1 files changed, 84 insertions, 0 deletions
diff --git a/sofort/ccenv/ccenv.usage b/sofort/ccenv/ccenv.usage
new file mode 100644
index 0000000..44e5f05
--- /dev/null
+++ b/sofort/ccenv/ccenv.usage
@@ -0,0 +1,84 @@
+A few words on sofort's tool-finding logic
+==========================================
+
+# the goals of sofort's tool-finding logic are:
+- follow a clear, transparent, and consistent logic
+- allow users to easily specify per-build preferences
+- allow distros to easily and cleanly use site-wide settings
+
+
+# three-way terminology:
+- native machine: where make(1) will be running.
+- host machine:   where the package's program or libraries will execute.
+- target machine: where code generated by the host package will execute.
+
+! NOTE, however, that the host/target distinction is only relevant
+  when building a code-generating utility (e.g. a compiler), and that
+  the two are otherwise rather synonymous. Moreover, in practice it
+  is much more common to see configure scripts being invoked with a
+  --target=<machine> argument specifying the host, than with a
+  --host=<machine> argument.
+
+
+# invocation and names of binary tools:
+- agnostic names (ar, nm, objdump, ...)
+- branded names (llvm-ar, llvm-nm, llvm-objdump, ...)
+- machine-prefixed agnostic names (x86_64-nt64-midipix-ar, ...)
+- machine-prefixed branded names (x86_64-linux-gnu-gcc-ar, ...)
+- machine-specifying branded tools, as in
+  llvm-ar --target=x86_64-linux.
+
+
+# cross-compilation: default search order:
+- machine-prefixed agnostic tools
+- machine-prefixed branded tools, starting with the prefix
+  most commonly associated with the selected compiler (that is,
+  ``gcc'' when using gcc, and ``llvm'' when using clang)
+- (machine-specifying) agnostic tools
+- (machine-speficying) branded tools, starting once again with the
+  prefix most commonly associated with the selected compiler
+
+
+# native builds: default search order:
+- agnostic tools
+- machine-prefixed agnostic tools
+- machine-prefixed branded tools
+- branded tools
+
+
+# using an alternate search order:
+- --toolchain=<prefix> (e.g. --toolchain=llvm) --> search for tools
+  that begin with <prefix> before searching for agnostic tools
+
+
+# restricting which tools may be searched:
+- --zealous          --> only search for agnostic tools
+- --zealous=<prefix> --> only search for <prefix>-branded tools
+
+
+# per-tool overrides, by example of the ``ar'' tool:
+- AR=ar          --> set AR to $(command -v ar)
+- AR=/path/to/ar --> set AR to the specified absolute path
+
+
+# consistency:
+- in the above case of AR=ar, using $(command -v ar) ensures
+  that the same tool is used throughout the lifetime of the
+  build project.
+
+
+# host generated config file and variable names:
+- ccenv/host.mk
+- AR, NM, OBJDUMP, ...
+
+
+# native generated config file and variable names:
+- ccenv/native.mk
+- NATIVE_AR, NATIVE_NM, NATIVE_OBJDUMP, ...
+
+
+# distro: site-wide preferences
+- --ccenv=/path/to/site-specific/ccenv
+- use the above to create ccenv as a symlink to
+  /path/to/site-specific/ccenv, and to accordingly
+  skip configure's tool-finding step.