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

[Mathieu Arnold]

Author: mat
Date: Fri Aug  4 10:23:55 2017
New Revision: 50627
URL: https://svnweb.freebsd.org/changeset/doc/50627

Log:
  Rewrite the symlink bits and introduce RLN.
  
  Reviewed by:	bcr
  Sponsored by:	Absolight, The FreeBSD Foundation
  Differential Revision:	https://reviews.freebsd.org/D11839

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 Aug  4 01:11:29 2017	(r50626)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Fri Aug  4 10:23:55 2017	(r50627)
@@ -72,23 +72,67 @@
       <buildtarget>post-install</buildtarget> target.  Avoid using
       absolute paths whenever possible.</para>
 
-    <para>When creating a symlink, <varname>STAGEDIR</varname>
-      is prepended to the target path only.  For
-      example:</para>
+    <tip>
+      <para>Ports that install kernel modules must prepend
+	<varname>STAGEDIR</varname> to their destination, by default
+	<filename>/boot/modules</filename>.</para>
+    </tip>
 
-    <programlisting>${LN} -sf <replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable></programlisting>
+    <sect2 xml:id="staging-symlink">
+      <title>Handling Symbolic Links</title>
 
-    <para>The source path
-      <filename>${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable></filename>
-      looks fine but could, in fact, be incorrect.  Absolute paths can
-      point to a wrong location, like when a remote file system has
-      been mounted with <acronym>NFS</acronym> under a non-root mount
-      point.  Relative paths are less fragile, and often much
-      shorter.</para>
+      <para>When creating a symlink, there are two cases, either the
+	source and target are both within
+	<filename>${PREFIX}</filename>.  In that case, use
+	<command>${RLN}</command>.  In the other case, if one or both
+	of the paths are outside of <filename>${PREFIX}</filename>
+	use <command>${LN} -s</command> and only prepend
+	<filename>${STAGEDIR}</filename> to the target's path.</para>
 
-    <para>Ports that install kernel modules must prepend
-      <varname>STAGEDIR</varname> to their destination, by default
-      <filename>/boot/modules</filename>.</para>
+      <example xml:id="staging-ex1">
+	<title>Inside <filename>${PREFIX}</filename>, Create Relative
+	  Symbolic Links</title>
+
+	<para><command>${RLN}</command> uses &man.install.1;'s
+	  relative symbolic feature which frees the porter of
+	  computing the relative path.</para>
+
+	<programlisting>${RLN} ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable></programlisting>
+
+	<para>Will generate:</para>
+
+	<screen>&prompt.user; <userinput>ls -lF ${STAGEDIR}${PREFIX}/lib</userinput>
+  lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 libfoo.so@ -> libfoo.so.42
+  -rwxr-xr-x  1 nobody  nobody     15 Aug  3 11:24 libfoo.so.42*</screen>
+
+	<para>When used with paths not in the same directory:</para>
+
+	<programlisting>${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/<replaceable>bar</replaceable> ${STAGEDIR}${PREFIX}/bin/<replaceable>bar</replaceable></programlisting>
+
+	<para>Will automatically generate the relative symbolic
+	  links:</para>
+
+	<screen>&prompt.user; <userinput>ls -lF ${STAGEDIR}${PREFIX}/bin</userinput>
+  lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 bar@ -> ../libexec/foo/bar</screen>
+      </example>
+
+      <example xml:id="staging-ex2">
+	<title>Outside <filename>${PREFIX}</filename>, Create Absolute
+	  Symbolic Links</title>
+
+	<para>When creating a symbolic link outside of
+	  <filename>${PREFIX}</filename>, the source must not contain
+	  <filename>${STAGEDIR}</filename>, the target, however,
+	  must:</para>
+
+	<programlisting>${LN} -sf <replaceable>/var/cache/${PORTNAME}</replaceable> ${STAGEDIR}${PREFIX}/share/<replaceable>${PORTNAME}</replaceable></programlisting>
+
+	<para>Will generate:</para>
+
+	<screen>&prompt.user; <userinput>ls -lF ${STAGEDIRDIR}${PREFIX}/share</userinput>
+  lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 foo@ -> /var/cache/foo</screen>
+      </example>
+    </sect2>
   </sect1>
 
   <sect1 xml:id="bundled-libs">