From 44cc709e29a67c8c6d361157c05916fee235ec7a Mon Sep 17 00:00:00 2001 From: John Ericson Date: Fri, 1 Sep 2017 15:33:59 -0400 Subject: [PATCH] doc: Document Binutils Wrapper Shrunk the CC Wrapper documentation so as not to be repetative. --- doc/stdenv.xml | 60 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 18 deletions(-) diff --git a/doc/stdenv.xml b/doc/stdenv.xml index dac53bc2b800..5d6d9f595097 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -1,4 +1,3 @@ - @@ -1342,33 +1341,58 @@ someVar=$(stripHash $name) + + Binutils Wrapper + + + Binutils Wrapper wraps the binary utilities for a bunch of miscellaneous purposes. + Specifically, GNU Binutils (for Linux, but a mix of cctools and GNU Binutils for Darwin), and a C standard library (glibc or Darwin's libSystem, just for the dynamic loader) are all fed in, and dependency finding, hardening (see below), and purity checks for each are handled by Binutils Wrapper. + Packages typically depend on CC Wrapper, which in turn (at run time) depends on binutils-wrapper. + + + Binutils Wrapper was only just recently split off from CC Wrapper, so the division of labor is still being worked out. + For example, it shouldn't care about about the C standard library, but just take a derivation with the dynamic loader (which happens to be the glibc on linux). + Dependency finding however is a task both wrappers will continue to need to share, and probably the most important to understand. + It is currently accomplished by collecting directories of host-platform dependencies (i.e. buildInputs and nativeBuildInputs) in environment variables. + Binutils Wrapper's setup hook causes any lib and lib64 subdirectories to NIX_LDFLAGS. + Sine CC Wrapper and Binutils Wrapper use the same strategy, most of the Binutils Wrapper code is sparsely commented and refers to CC Wrapper. + But CC Wrapper's code, by contrast, has quite lengthy comments. + Binutils Wrapper merely cites those, rather than repeating them, to avoid falling out of sync. + + + A final task of the setup hook is defining a number of standard environment variables to tell build systems which executables full-fill which purpose. + They are defined to just be the base name of the tools, under the assumption that Binutils Wrapper's binaries will be on the path. + Firstly, this helps poorly-written packages, e.g. ones that look for just gcc when CC isn't defined yet clang is to be used. + Secondly, this helps packages not get confused when cross-compiling, in which case multiple Binutils Wrappers may be simultaneous in use (targeting different platforms). + BUILD_- and TARGET_-prefixed versions of the normal environment variable are defined for the additional Binutils Wrappers, properly disambiguating them. + + + A problem with this final task is that Binutils Wrapper is honest and defines LD as ld. + Most packages, however, firstly use the C compiler for linking, secondly use LD anyways, defining it as the C compiler, and thirdly, only so define LD when it is undefined as a fallback. + This triple-threat means Binutils Wrapper will break those packages, as LD is already defined as the actually linker which the package won't override yet doesn't want to use. + The workaround is to define, just for the problematic package, LD as the C compiler. + A good way to do this would be preConfigure = "LD=$CC". + + + + CC Wrapper CC Wrapper wraps a C toolchain for a bunch of miscellaneous purposes. - Specifically, a C compiler (GCC or Clang), Binutils (or the CCTools + binutils mashup when targetting Darwin), and a C standard library (glibc or Darwin's libSystem) are all fed in, and dependency finding, hardening (see below), and purity checks for each are handled by CC Wrapper. - Packages typically depend on only CC Wrapper, instead of those 3 inputs directly. + Specifically, a C compiler (GCC or Clang), Binutils (or the CCTools + binutils mashup when targetting Darwin), and a C standard library (glibc or Darwin's libSystem, just for the dynamic loader) are all fed in, and dependency finding, hardening (see below), and purity checks for each are handled by Binutils Wrapper. + Packages typically depend on CC Wrapper, which in turn (at run time) depends on Binutils Wrapper. - Dependency finding is undoubtedly the main task of CC wrapper. - It is currently accomplished by collecting directories of host-platform dependencies (i.e. buildInputs and nativeBuildInputs) in environment variables. - CC wrapper's setup hook causes any include subdirectory of such a dependency to be added to NIX_CFLAGS_COMPILE, and any lib and lib64 subdirectories to NIX_LDFLAGS. + Dependency finding is undoubtedly the main task of CC Wrapper. + This works just like Binutils Wrapper, except the any include subdirectory of any relevant dependency is added to NIX_CFLAGS_COMPILE. The setup hook itself contains some lengthy comments describing the exact convoluted mechanism by which this is accomplished. - A final task of the setup hook is defining a number of standard environment variables to tell build systems which executables full-fill which purpose. - They are defined to just be the base name of the tools, under the assumption that CC Wrapper's binaries will be on the path. - Firstly, this helps poorly-written packages, e.g. ones that look for just gcc when CC isn't defined yet clang is to be used. - Secondly, this helps packages not get confused when cross-compiling, in which case multiple CC wrappers may be simultaneous in use (targeting different platforms). - BUILD_- and TARGET_-prefixed versions of the normal environment variable are defined for the additional CC Wrappers, properly disambiguating them. - - - A problem with this final task is that CC Wrapper is honest and defines LD as ld. - Most packages, however, firstly use the C compiler for linking, secondly use LD anyways, defining it as the C compiler, and thirdly, only so define LD when it is undefined as a fallback. - This triple-threat means CC Wrapper will break those packages, as LD is already defined as the actually linker which the package won't override yet doesn't want to use. - The workaround is to define, just for the problematic package, LD as the C compiler. - A good way to do this would be preConfigure = "LD=$CC". + CC Wrapper also like Binutils Wrapper defines standard environment variables with the names of the tools it wraps, for the same reasons described above. + Importantly, while it includes a cc symlink to the c compiler for portability, the CC will be defined using the compiler's "real name" (i.e. gcc or clang). + This helps lousy build systems that inspect on the name of the compiler rather than run it.