[gentoo-commits] proj/gcc-config:master commit in: /

["Sergei Trofimovich" <slyfox@gentoo.org>]

commit:     153b36029749d2635a5b87d40e6cf8100b1340f2
Author:     Sergei Trofimovich <slyfox <AT> gentoo <DOT> org>
AuthorDate: Fri Aug 24 00:22:47 2018 +0000
Commit:     Sergei Trofimovich <slyfox <AT> gentoo <DOT> 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 <slyfox <AT> 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/<tool>) is a wrapper (wrapper.c).
+gcc-config allows runtime gcc switch via level of indirection.
+
+Tool name is ${CTARGET}-<tool> or <tool>. TODO: doesn't it break
+on ${CTARGET}-<tool>-<version>? Doesn't ${CTARGET} get misdetected?
+
+Today's resolution order is the following:
+
+1. Searches PATH for <tool> and reexecute if found. Some
+   target paths are ignored:
+   - itself (/usr/bin/<tool>) 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/<gcc-version>" (native)
+   or GCC_PATH="${EPREFIX}/usr/${CHOST}/${CTARGET}/gcc-bin/<gcc-version>" (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/<gcc-version>'. Otherwise wrapper is skipped.
+
+TODOs
+-----
+
+- Write proper `gcc-config` manpage off this readme to be more discoverable.
+
+- Make /usr/bin/<tool> 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.