svn commit: r44180 - head/en_US.ISO8859-1/books/porters-handbook/special

[Mathieu Arnold]

Author: mat (ports committer)
Date: Fri Mar  7 17:52:44 2014
New Revision: 44180
URL: http://svnweb.freebsd.org/changeset/doc/44180

Log:
  Update the special considerations chapter part one.
  
  Sponsored by:	Absolight

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

Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Fri Mar  7 17:10:44 2014	(r44179)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Fri Mar  7 17:52:44 2014	(r44180)
@@ -33,12 +33,22 @@
       (see <xref linkend="porting-prefix"/>).</para>
 
     <para>When a port still requires system-wide privileges in order
-      to run the <buildtarget>package</buildtarget> target, this
-      line must be added to the
+      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.  You can mostly avoid it 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>
+    </note>
+
     <para>Meta ports, or ports that do not install files themselves
       but only depend on other ports, should avoid needlessly
       extracting the &man.mtree.8; to the stage directory.  This is
@@ -125,9 +135,10 @@
     <para>When installing 32-bit libraries on 64-bit system, use
       <varname>USE_LDCONFIG32</varname> instead.</para>
 
-    <para>Try to keep shared library version numbers in the
-      <filename>libfoo.so.0</filename> format.  Our runtime linker
-      only cares for the major (first) number.</para>
+    <para>If the software you are porting uses <link
+	linkend="using-autotools">autotools</link>, and specifically
+      <command>libtool</command>, you should add <link
+	linkend="uses-libtool"><literal>USES=libtool</literal></link>.</para>
 
     <para>When the major library version number increments in the
       update to the new port version, all other ports that link to
@@ -815,16 +826,21 @@ CMAKE_SOURCE_PATH=	${WRKSRC}/subp
 
       <para>If your port requires <literal>gettext</literal>, set
 	<literal>USES= gettext</literal>, and your port will inherit
-	a dependency on
+	a dependency on <filename>libintl.so</filename> from
 	<package role="port">devel/gettext</package>.  Other
 	values for <literal>gettext</literal> usage are listed in
-	<xref linkend="uses-values"/>.</para>
+	<link
+	  linkend="uses-gettext"><literal>USES=gettext</literal></link>.</para>
 
       <para>A rather common case is a port using
 	<literal>gettext</literal> and <command>configure</command>.
 	Generally, GNU <command>configure</command> should be able
-	to locate <literal>gettext</literal> automatically.  If it
-	ever fails to, hints at the location of
+	to locate <literal>gettext</literal> automatically.</para>
+
+      <programlisting>USES=	gettext
+GNU_CONFIGURE=	yes</programlisting>
+
+      <para>If it ever fails to, hints at the location of
 	<literal>gettext</literal> can be passed in
 	<envar>CPPFLAGS</envar> and <envar>LDFLAGS</envar> as
 	follows:</para>
@@ -834,12 +850,6 @@ CPPFLAGS+=	-I${LOCALBASE}/include
 LDFLAGS+=	-L${LOCALBASE}/lib
 
 GNU_CONFIGURE=	yes</programlisting>
-
-      <para>Of course, the code can be more compact if there are no
-	more flags to pass to <command>configure</command>:</para>
-
-      <programlisting>USES=	gettext
-GNU_CONFIGURE=	yes</programlisting>
     </sect2>
 
     <sect2>
@@ -855,6 +865,20 @@ GNU_CONFIGURE=	yes</programlisting>
 
       <programlisting>GNU_CONFIGURE=		yes
 
+OPTIONS_DEFINE=		NLS
+OPTIONS_SUB=		yes
+
+NLS_USES=		gettext
+NKS_CONFIGURE_ENABLE=	nls
+
+.include <bsd.port.mk></programlisting>
+
+      <para>Or using the older way of using options:</para>
+
+      <programlisting>GNU_CONFIGURE=		yes
+
+OPTIONS_DEFINE=		NLS
+
 .include <bsd.port.options.mk>
 
 .if ${PORT_OPTIONS:MNLS}