Attachment 69100 Details for Bug 101365 – porters-handbook.diff

[patch] porters-handbook.diff

porters-handbook.diff (text/plain), 5.67 KB, created by Gabor Kovesdan on 2006-08-04 18:00:26 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Gabor Kovesdan

Created: 2006-08-04 18:00:26 UTC

Size: 5.67 KB

patch

obsolete

>Index: book.sgml
>===================================================================
>RCS file: /usr/cvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
>retrieving revision 1.740
>diff -u -r1.740 book.sgml
>--- book.sgml	3 Aug 2006 19:01:34 -0000	1.740
>+++ book.sgml	4 Aug 2006 16:49:21 -0000
>@@ -3942,6 +3942,18 @@
>       <para>There are some more things you have to take into account when you
> 	create a port.  This section explains the most common of those.</para>
> 
>+      <sect1 id="building-in-jails">
>+        <title>Building in jails</title>
>+
>+	<para>Note, that the behavior of <makevar>OSVERSION</makevar> has been
>+	  changed recently.  Now, it gets the <link
>+	   linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>
>+	  from the userland, since it makes more sense for the ports, than the
>+	  kernel.  You can still override it, if you really have to get it from
>+	  the kernel.</para>
>+
>+      </sect1>
>+
>       <sect1 id="porting-shlibs">
> 	<title>Shared Libraries</title>
> 
>@@ -4758,7 +4770,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>
> 
>@@ -6779,17 +6791,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
>@@ -6840,6 +6868,43 @@
> 	  <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>DATADIR</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.
>+	  <makevar>PREFIX</makevar> is an absolute path. but relative
>+	  to <makewar>DESTDIR</makevar>.  If you want to refer to the
>+	  fully qualified destination you can use <makevar>TARGETDIR</makevar>,
>+	  which resolves to <makevar>DESTDIR</makevar>/<makevar>PREFIX</makevar>.</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>.</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 there.  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>

Actions: View | Diff

Attachments on bug 101365: 69100