From owner-svn-doc-all@freebsd.org Wed Sep 23 15:13:22 2020 Return-Path: Delivered-To: svn-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 112D23FCB35; Wed, 23 Sep 2020 15:13:22 +0000 (UTC) (envelope-from mat@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4BxMBT565Cz3VJv; Wed, 23 Sep 2020 15:13:21 +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 mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 926791233D; Wed, 23 Sep 2020 15:13:21 +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 08NFDLOb084732; Wed, 23 Sep 2020 15:13:21 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id 08NFDLDQ084731; Wed, 23 Sep 2020 15:13:21 GMT (envelope-from mat@FreeBSD.org) Message-Id: <202009231513.08NFDLDQ084731@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Wed, 23 Sep 2020 15:13:21 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r54516 - 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: 54516 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.33 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 23 Sep 2020 15:13:22 -0000 Author: mat Date: Wed Sep 23 15:13:21 2020 New Revision: 54516 URL: https://svnweb.freebsd.org/changeset/doc/54516 Log: Rewrite symlink handling. Reviewed by: bapt 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 Wed Sep 23 06:48:38 2020 (r54515) +++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Wed Sep 23 15:13:21 2020 (r54516) @@ -81,56 +81,31 @@ Handling Symbolic Links - 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. + When creating a symbolic link, relative ones are strongly + recommended. Use ${RLN} to create relative + symbolic links. It uses &man.install.1; under the hood to + automatically figure out the relative link to create. - Inside <filename>${PREFIX}</filename>, Create Relative - Symbolic Links + Create Relative Symbolic Links Automatically ${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 + ${RLN} ${STAGEDIR}${PREFIX}/lib/libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so +${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/bar ${STAGEDIR}${PREFIX}/bin/bar +${RLN} ${STAGEDIR}/var/cache/foo ${STAGEDIR}${PREFIX}/share/foo 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 +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; ls -lF ${STAGEDIR}${PREFIX}/bin +lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 bar@ -> ../libexec/foo/bar +&prompt.user; ls -lF ${STAGEDIRDIR}${PREFIX}/share +lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 foo@ -> ../../../var/cache/foo