Date: Fri, 4 Aug 2006 18:52:02 +0200 (CEST) From: Gabor Kovesdan <gabor@FreeBSD.org> To: FreeBSD-gnats-submit@FreeBSD.org Cc: Gabor Kovesdan <gabor@FreeBSD.org> Subject: docs/101365: [patch] Document DESTDIR support in porters-handbook Message-ID: <20060804165202.AB8F628A0C3@catv-50635cb6.catv.broadband.hu> Resent-Message-ID: <200608041700.k74H0VoA035829@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 101365
>Category: docs
>Synopsis: [patch] Document DESTDIR support in porters-handbook
>Confidential: no
>Severity: non-critical
>Priority: medium
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: update
>Submitter-Id: current-users
>Arrival-Date: Fri Aug 04 17:00:26 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator: Gabor Kovesdan
>Release: FreeBSD 6.1-STABLE i386
>Organization:
n/a
>Environment:
System: FreeBSD spitfire 6.1-STABLE FreeBSD 6.1-STABLE #0: Sat Jul 29 18:31:18 CEST 2006 gabor@spitfire:/usr/src/sys/i386/compile/SPITFIRE i386
>Description:
Document the recently added DESTDIR support.
>How-To-Repeat:
>Fix:
--- porters-handbook.diff begins here ---
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>
--- porters-handbook.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060804165202.AB8F628A0C3>