PERFORCE change 101467 for review

[Gabor Kovesdan]

http://perforce.freebsd.org/chv.cgi?CH=101467

Change 101467 by gabor at gabor_spitfire on 2006/07/13 14:06:30

	Add some explanation what DESTDIR is for and how to write
	DESTDIR-compliant ports.

Affected files ...

.. //depot/projects/soc2006/gabor_docs/porters-handbook/book.sgml#3 edit

Differences ...

==== //depot/projects/soc2006/gabor_docs/porters-handbook/book.sgml#3 (text+ko) ====

@@ -4757,7 +4757,7 @@
 	    <row>
 	      <entry><makevar>USE_X_PREFIX</makevar></entry>
 
-	      <entry>The port installs in <makevar>X11BASE</makevar>, not
+	      <entry>The port installs in <makevar>X11BASE_REL</makevar>, not
 		<makevar>PREFIX</makevar>.</entry>
 	    </row>
 
@@ -6778,17 +6778,33 @@
       </sect1>
 
       <sect1 id="porting-prefix">
-	<title><makevar>PREFIX</makevar></title>
+	<title><makevar>PREFIX</makevar> and <makevar>DESTDIR</makevar></title>
 
+	<para>Firstly, you should completely unerstand what these two
+	  variables are for.  <makevar>PREFIX</makevar> determines the
+	  location where all ports should install in the current environemt.
+	  This is usually <filename>/usr/local</filename>, or
+	  <filename>/opt</filename> in other operating systems.   You
+	  can set <makevar>PREFIX</makevar> to everything you want, See the
+	  <a href="http://www.pathname.com/fhs/2.2/>Filesystem Hierarchy
+	  Standard</a> for making a good decision.  <makevar>DESTDIR</makevar>
+	  determines the whole environment you want to use the package from.
+	  This environment can be a jail, or an installed system mounted
+	  elsewhere than <filename>/</filename>.  This means a port will
+	  actually install to <makevar>DESTDIR</makevar>/<makevar>PREFIX</makevar>,
+	  and registered in the package database of the given environment.
+	  It is very important that you write such ports that respect this,
+	  thus you can find some guidelines below to do so.</para>
+	 
 	<para>Do try to make your port install relative to
 	  <makevar>PREFIX</makevar>.  The value of this variable will be set
-	  to <makevar>LOCALBASE</makevar> (default
+	  to <makevar>LOCALBASE_REL</makevar> (default
 	  <filename>/usr/local</filename>).  If
 	  <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is
-	  set, <makevar>PREFIX</makevar> will be <makevar>X11BASE</makevar> (default
+	  set, <makevar>PREFIX</makevar> will be <makevar>X11BASE_REL</makevar> (default
 	  <filename>/usr/X11R6</filename>).  If
 	  <makevar>USE_LINUX_PREFIX</makevar> is set, <makevar>PREFIX</makevar>
-	  will be <makevar>LINUXBASE</makevar> (default
+	  will be <makevar>LINUXBASE_REL</makevar> (default
 	  <filename>/compat/linux</filename>).</para>
 
 	<para>Avoiding the hard-coding of <filename>/usr/local</filename> or
@@ -6839,6 +6855,40 @@
 	  <literal>-DPAGER=\"/usr/local/bin/less\"</literal>. This way it will
 	  have a better chance of working if the system administrator has
 	  moved the whole <filename>/usr/local</filename> tree somewhere else.</para>
+
+	<para>For writing <makevar>DESTDIR</makevar>-compliant ports, note that
+	  <makevar>LOCALBASE</makevar>, <makevar>LINUXBASE</makevar>,
+	  <makevar>X11BASE</makevar>, <makevar>DOCSDIR</makevar>,
+	  <makevar>EXAMPLESDIR</makevar>, <makevar>DESKTOPDIR</makevar>
+	  variables already contain <makevar>DESTDIR</makevar>, so
+	  <makevar>DESTDIR</makevar>/<makevar>LOCALBASE</makevar> is
+	  definitely wrong, but you can use <makevar>LOCALBASE_REL</makevar> if
+	  you need a variable relative to <makevar>DESTDIR</makevar>.
+	  Similarly, you can use <makevar>LINUXBASE_REL</makevar> and
+	  <makevar>X11BASE_REL</makevar> variables as well.</para>
+
+	<para>You have to use these variables correctly
+	  in your ports <filename>Makefile</filename>, esepecially in
+	  custom targets, to ensure each files are installed to the
+	  corect place.  For dependencies, using <makevar>LOCALBASE</makevar>
+	  is still correct, since we want to check for dependencies
+	  in <makevar>DESTDIR</makevar>.  If everything is correct, set
+	  <makevar>DESTDIR_READY</makevar> to indicate that your port
+	  is ready to be used with <makevar>DESTDIR</makevar>.</para>
+
+	<para>In packing lists, or in <filename>pkg-*</filename> scripts you
+	  can still use <literal>%%LOCALBASE%%</literal>,
+	  <literal>%%LINUXBASE%%</literal> and <literal>%%X11BASE%%</literal>
+	  expansions, since they represent relative paths here.  This ambiguity
+	  can be frustrating at first, but this actually simplifies the process
+	  of writing <makevar>DESTDIR</makevar>-compliant ports.  We did not use to
+	  have <makevar>DESTDIR</makevar> support by our ports infrastructure,
+	  and one of the major goals was to avoid modifying a tons of ports,
+	  so we just changed <makevar>LOCALBASE</makevar> in the
+	  infrastructure instead of changing that in tons of individual ports.
+	  With a little workaround, <makevar>LOCALBASE</makevar>,
+	  <makevar>LINUXBASE</makevar> and <makevar>X11BASE</makevar>
+	  are still overrideable, though.</para>
       </sect1>
   </chapter>