From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 93AB2138334 for ; Fri, 24 Aug 2018 00:23:15 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 7603AE08C2; Fri, 24 Aug 2018 00:23:14 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 30807E08C2 for ; Fri, 24 Aug 2018 00:23:13 +0000 (UTC) Received: from oystercatcher.gentoo.org (unknown [IPv6:2a01:4f8:202:4333:225:90ff:fed9:fc84]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id F139E335CA0 for ; Fri, 24 Aug 2018 00:23:11 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 08A723A4 for ; Fri, 24 Aug 2018 00:23:10 +0000 (UTC) From: "Sergei Trofimovich" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Sergei Trofimovich" Message-ID: <1535070167.153b36029749d2635a5b87d40e6cf8100b1340f2.slyfox@gentoo> Subject: [gentoo-commits] proj/gcc-config:master commit in: / X-VCS-Repository: proj/gcc-config X-VCS-Files: README X-VCS-Directories: / X-VCS-Committer: slyfox X-VCS-Committer-Name: Sergei Trofimovich X-VCS-Revision: 153b36029749d2635a5b87d40e6cf8100b1340f2 X-VCS-Branch: master Date: Fri, 24 Aug 2018 00:23:10 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: 5a74a434-0864-46fd-bbb6-96c565dd36bd X-Archives-Hash: 4e6cdfcfc5263b7b55b525c888d504b6 commit: 153b36029749d2635a5b87d40e6cf8100b1340f2 Author: Sergei Trofimovich gentoo org> AuthorDate: Fri Aug 24 00:22:47 2018 +0000 Commit: Sergei Trofimovich gentoo org> CommitDate: Fri Aug 24 00:22:47 2018 +0000 URL: https://gitweb.gentoo.org/proj/gcc-config.git/commit/?id=153b3602 README: add basic description of how gcc-config works Signed-off-by: Sergei Trofimovich gentoo.org> README | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/README b/README new file mode 100644 index 0000000..06bf8fe --- /dev/null +++ b/README @@ -0,0 +1,103 @@ +What is gcc-config? +------------------- + +Gentoo allows switching gcc as system runs via gcc-config: + $ gcc-config x86_64-pc-linux-gnu-8.1.0 + $ gcc-config x86_64-pc-linux-gnu-7.2.0 + +Ideally changes should be visible instantly and atomically +without shell restart. Practially see TODOs and BUGs on PATH/ROOTPATH. + +Files, variables, things. +------------------------- + +- Wrappers (copies of /usr/$(libexec)/gcc-config/wrapper) + /usr/bin/gcc + /usr/bin/g++ + /usr/bin/${CTARGET}-gcc + ... + (all files from /usr/${CTARGET}/gcc-bin/$GCC_VERSION/*) + + Wrapper reads env config and re-execs binary from `GCC_PATH`. + + See `gcc-config` script for wrapping details. + +- private gcc configs (provided by `toolchain.eclass`, gcc ebuilds) + + /etc/env.d/gcc/.NATIVE -> x86_64-pc-linux-gnu-8.1.0 (link to target config) + /etc/env.d/gcc/x86_64-pc-linux-gnu-8.1.0 + + Contains variables that describe tolchain layout: + + LDPATH="/usr/lib/gcc/x86_64-pc-linux-gnu/8.1.0" + MANPATH="/usr/share/gcc-data/x86_64-pc-linux-gnu/8.1.0/man" + INFOPATH="/usr/share/gcc-data/x86_64-pc-linux-gnu/8.1.0/info" + STDCXX_INCDIR="g++-v8" + CTARGET="x86_64-pc-linux-gnu" + GCC_SPECS="" + MULTIOSDIRS="../lib64" + GCC_PATH="/usr/x86_64-pc-linux-gnu/gcc-bin/8.1.0" + + Used by gcc-config to generate wrappers and 05gcc- env.d files. + Used by wrapper to extract GCC_PATH and re-exec(). + +- gcc env.d cross-compiler entries (provided by gcc-config) + + /etc/env.d/05gcc-${CTARGET} + + Populates paths for cross-compilers + + PATH="/usr/x86_64-pc-linux-gnu/powerpc64le-unknown-linux-gnu/gcc-bin/7.3.0" + ROOTPATH="/usr/x86_64-pc-linux-gnu/powerpc64le-unknown-linux-gnu/gcc-bin/7.3.0" + + Used by wrapper to extract PATH and re-exec(). + +How does gcc-config work? +------------------------- + +/usr/bin/gcc (or /usr/bin/) is a wrapper (wrapper.c). +gcc-config allows runtime gcc switch via level of indirection. + +Tool name is ${CTARGET}- or . TODO: doesn't it break +on ${CTARGET}--? Doesn't ${CTARGET} get misdetected? + +Today's resolution order is the following: + +1. Searches PATH for and reexecute if found. Some + target paths are ignored: + - itself (/usr/bin/) is ignored to avoid recursion + - */gcc-bin/* (/usr/${CHOST}/${CTARGET}/gcc-bin/7.3.0) is ignored + as those should precede in PATH to avoid wrapping entirely or be + selected via gcc-config. +2. If [1.] failed search for /etc/env.d/: /etc/env.d/gcc/.NATIVE (native compiler), + /etc/env.d/05gcc-${CTARGET} (cross-compiler). + + There GCC_PATH= (native) or PATH= (cross) directory entry is searched. + + Usually it's GCC_PATH="${EPREFIX}/usr/${CHOST}/gcc-bin/" (native) + or GCC_PATH="${EPREFIX}/usr/${CHOST}/${CTARGET}/gcc-bin/" (cross) + +3. If [2.] failed run 'ROOT= gcc-config --get-bin-path' and use it's output. + +4. Prepend path fetched from above to PATH environment variable and re-exec(). + +5. Done + +`gcc-config` script maintains binaries in `/usr/bin/` to make the above model work. + +To make compiler switchable in active shell `/usr/bin/` path must precede +'/usr/${CHOST}/gcc-bin/'. Otherwise wrapper is skipped. + +TODOs +----- + +- Write proper `gcc-config` manpage off this readme to be more discoverable. + +- Make /usr/bin/ a symlink of /usr/$(libexec)/gcc-config/wrapper, + not a file copy. This will make the fact that Gentoo uses wrappers more obvious. + It's essential to know for people using ccache cache or similar. + +- Move /etc/env.d/05gcc-${CTARGET} and /etc/env.d/04gcc-${CTARGET} after + /usr/bin PATH injection to restore gcc-config wrapping. + + See https://bugs.gentoo.org/255695 for some details.