Date: Fri, 4 Aug 2017 10:23:55 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50627 - head/en_US.ISO8859-1/books/porters-handbook/special Message-ID: <201708041023.v74ANtV8068706@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201708041023.v74ANtV8068706>