From owner-svn-doc-head@freebsd.org Fri Aug 4 10:23:56 2017 Return-Path: Delivered-To: svn-doc-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 794D6DD1D09; Fri, 4 Aug 2017 10:23:56 +0000 (UTC) (envelope-from mat@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4D3BC3332; Fri, 4 Aug 2017 10:23:56 +0000 (UTC) (envelope-from mat@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v74ANtI0068707; Fri, 4 Aug 2017 10:23:55 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v74ANtV8068706; Fri, 4 Aug 2017 10:23:55 GMT (envelope-from mat@FreeBSD.org) Message-Id: <201708041023.v74ANtV8068706@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Fri, 4 Aug 2017 10:23:55 +0000 (UTC) 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 X-SVN-Group: doc-head X-SVN-Commit-Author: mat X-SVN-Commit-Paths: head/en_US.ISO8859-1/books/porters-handbook/special X-SVN-Commit-Revision: 50627 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 04 Aug 2017 10:23:56 -0000 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 @@ post-install target. Avoid using absolute paths whenever possible. - When creating a symlink, STAGEDIR - is prepended to the target path only. For - example: + + Ports that install kernel modules must prepend + STAGEDIR to their destination, by default + /boot/modules. + - ${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so + + Handling Symbolic Links - The source path - ${PREFIX}/lib/libfoo.so.42 - 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 NFS under a non-root mount - point. Relative paths are less fragile, and often much - shorter. + When creating a symlink, there are two cases, either the + source and target are both within + ${PREFIX}. In that case, use + ${RLN}. In the other case, if one or both + of the paths are outside of ${PREFIX} + use ${LN} -s and only prepend + ${STAGEDIR} to the target's path. - Ports that install kernel modules must prepend - STAGEDIR to their destination, by default - /boot/modules. + + Inside <filename>${PREFIX}</filename>, Create Relative + Symbolic Links + + ${RLN} uses &man.install.1;'s + relative symbolic feature which frees the porter of + computing the relative path. + + ${RLN} ${STAGEDIR}${PREFIX}/lib/libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so + + Will generate: + + &prompt.user; ls -lF ${STAGEDIR}${PREFIX}/lib + 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* + + When used with paths not in the same directory: + + ${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/bar ${STAGEDIR}${PREFIX}/bin/bar + + Will automatically generate the relative symbolic + links: + + &prompt.user; ls -lF ${STAGEDIR}${PREFIX}/bin + lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 bar@ -> ../libexec/foo/bar + + + + Outside <filename>${PREFIX}</filename>, Create Absolute + Symbolic Links + + When creating a symbolic link outside of + ${PREFIX}, the source must not contain + ${STAGEDIR}, the target, however, + must: + + ${LN} -sf /var/cache/${PORTNAME} ${STAGEDIR}${PREFIX}/share/${PORTNAME} + + Will generate: + + &prompt.user; ls -lF ${STAGEDIRDIR}${PREFIX}/share + lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 foo@ -> /var/cache/foo + +