os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Rewrite symlink handling.

Browse source 
Reviewed by:	bapt
This commit is contained in:
Mathieu Arnold 2020-09-23 15:13:21 +00:00
parent d7737f3cf0
commit ca3acc91d4
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=54516
1 changed files with 14 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
View file

@ -81,56 +81,31 @@
<sect2 xml:id="staging-symlink">
<title>Handling Symbolic Links</title>
<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>When creating a symbolic link, relative ones are strongly
recommended. Use <command>${RLN}</command> to create relative
symbolic links. It uses &man.install.1; under the hood to
automatically figure out the relative link to create.</para>
<example xml:id="staging-ex1">
<title>Inside <filename>${PREFIX}</filename>, Create Relative
Symbolic Links</title>
<title>Create Relative Symbolic Links Automatically</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>
<programlisting>${RLN} ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable>
${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/<replaceable>bar</replaceable> ${STAGEDIR}${PREFIX}/bin/<replaceable>bar</replaceable>
${RLN} ${STAGEDIR}<replaceable>/var/cache/foo</replaceable> ${STAGEDIR}${PREFIX}/share/<replaceable>foo</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>
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*
&prompt.user; <userinput>ls -lF ${STAGEDIR}${PREFIX}/bin</userinput>
lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 bar@ -> ../libexec/foo/bar
&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>