svn commit: r46929 - in head/en_US.ISO8859-1/books/porters-handbook: makefiles special uses

[Mathieu Arnold]

Author: mat
Date: Mon Jul  6 09:39:45 2015
New Revision: 46929
URL: https://svnweb.freebsd.org/changeset/doc/46929

Log:
  Various small fixes.
  
  - Mention WRKSRC_SUBDIR.
  - Note that NO_WRKSUBDIR should not be used.
  - Mention USES=metaport.
  - NEED_ROOT is gone, mention USES=fakeroot.
  
  Approved by:	wblock (mentor)
  Differential Revision:	https://reviews.freebsd.org/D2941

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
  head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
  head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Mon Jul  6 09:26:34 2015	(r46928)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Mon Jul  6 09:39:45 2015	(r46929)
@@ -4692,6 +4692,16 @@ PORTVERSION=	1.0</programlisting>
       <programlisting>WRKSRC=	${WRKDIR}/${PORTNAME}</programlisting>
     </sect2>
 
+    <sect2 xml:id="makefile-wrksrc_subdir">
+      <title><varname>WRKSRC_SUBDIR</varname></title>
+
+      <para>If the source files needed for the port are in a
+	subdirectory of the extracted distribution file, set
+	<varname>WRKSRC_SUBDIR</varname> to that directory.</para>
+
+      <programlisting>WRKSRC_SUBDIR=	src</programlisting>
+    </sect2>
+
     <sect2 xml:id="makefile-no_wrksubdir">
       <title><varname>NO_WRKSUBDIR</varname></title>
 
@@ -4700,6 +4710,14 @@ PORTVERSION=	1.0</programlisting>
 	indicate that.</para>
 
       <programlisting>NO_WRKSUBDIR=	yes</programlisting>
+
+      <note>
+	<para>Because <varname>WRKDIR</varname> is the only directory
+	  that is supposed to be writable during the build, and is
+	  used to store many files recording the status of the build,
+	  it is always better to force extraction into a subdirectory
+	  anyway.</para>
+      </note>
     </sect2>
   </sect1>
 

Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Mon Jul  6 09:26:34 2015	(r46928)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Mon Jul  6 09:39:45 2015	(r46929)
@@ -31,21 +31,16 @@
       in &os;, <varname>DESTDIR</varname> has a different meaning
       (see <xref linkend="porting-prefix"/>).</para>
 
-    <para>When a port still requires system-wide privileges in order
-      to run the <buildtarget>stage</buildtarget> and
-      <buildtarget>package</buildtarget> targets, this line must be
-      added to the
-      <filename>Makefile</filename>:</para>
-
-    <programlisting>NEED_ROOT=	yes</programlisting>
-
     <note>
-      <para>The vast majority of ports do not <emphasis>really
-	  need</emphasis> to be root.  It can mostly be avoided by
-	using <link
-	  linkend="uses-uidfix"><literal>USES=uidfix</literal></link>,
-	and from time to time by slightly patching the port's
-	<filename>Makefiles</filename>.</para>
+      <para>No port <emphasis>really</emphasis> needs to be root.  It
+	can mostly be avoided by using <link
+	  linkend="uses-uidfix"><literal>USES=uidfix</literal></link>.
+	If the port still runs commands like &man.chown.8;,
+	&man.chgrp.1;, or forces owner or group with &man.install.1;
+	then use <link
+	  linkend="uses-fakeroot"><literal>USES=fakeroot</literal></link>
+	to fake those calls.  Sligh patching of the port's
+	<filename>Makefiles</filename> will be needed.</para>
     </note>
 
     <para>Meta ports, or ports that do not install files themselves
@@ -57,6 +52,13 @@
 
     <programlisting>NO_MTREE=	yes</programlisting>
 
+    <tip>
+      <para>Metaports should use <link
+	  linkend="uses-metaport"><literal>USES=metaport</literal></link>.
+	It sets up defaults for ports that do not fetch, build, or
+	install anything.</para>
+    </tip>
+
     <para>Staging is enabled by prepending
       <varname>STAGEDIR</varname> to paths used in the
       <buildtarget>pre-install</buildtarget>,

Modified: head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml	Mon Jul  6 09:26:34 2015	(r46928)
+++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml	Mon Jul  6 09:39:45 2015	(r46929)
@@ -407,7 +407,9 @@
 	  <entry>(none)</entry>
 
 	  <entry>Changes some default behaviour of build systems to
-	    allow installing as a user.</entry>
+	    allow installing as a user.  See <link
+	      xlink:href="http://fakeroot.alioth.debian.org/"/> for
+	    more information on <command>fakeroot</command>.</entry>
 	</row>
 
 	<row xml:id="uses-fam">