host, target and runtime
~~~~~~~~~~~~~~~~~~~~~~~~

Scconfig supports crosscompiling by separating tests done for the host
platform and for the target platform. The host platform is the one that
hosts compilation while the target platform is where the final binaries
produced by the project embedding scconfig will run.

The property tree is divided up to 3 root directories: /host/, /target/
and /runtime/. If scconfig is not running in cross mode
so target is the same as host, then /target/ is a symlink to /host/ and
/runtime/ is a symlink to /host/.

1. host

In any case, there are tests done for the host system first. These are
the tests needed for the compile infrastructure of the project to work.
For example if the project needs to compile tools that are used during
compilation, these tools will run on the host computer, whatever the
target computer is. Any utility (including the compiler) that is needed to
get those tools compiled and run must be detected for the host. If the
compilation process needs to create directories e.g. for object files,
it needs a host mkdir.

Typical examples: code and documentation generators that are executed on
host, generating files before any cross compilation is done. Another good
example is a host-only native C compiler, in case those generators are
written in C.

2. target

Scconfig will first run tests for the host system (calling user
provided callback hook_detect_host()) and then tests for the target
system (using hook_detect_target()). The /target/ subtree will contain
the cross compilation tools: software that runs on the host system to
produce files to be used on the target system. When working for the target
system, scconfig will use the specified emulator to run the test programs or
if no emulator is available it will simply assume the test programs
worked if they compiled. This no-execute setup is called "blind cross".

Typical examples of target detection are a cross compiling CC, the linker
from the same cross compiler. Even ranlib or ar is affected if it needs
to read the object files.

If the host system is the target system, some tests may overlap. As example
for the local tools, cc/cc is needed on the host and for the final compilation
cc/cc is needed for the target. In short, this means both /host/cc/cc and
/target/cc/cc are needed. If scconfig is running in non-cross mode, that means
/target is linked to /host, thus the two cc/cc nodes are the same. When
cc/cc detection for host runs, it will find the C compiler and will store it
in the tree and next when the same test would run for target, the result is
already there so the test is skipped. This way overlapping requirements on
host and target systems won't result in duplicate tests in case we
are not doing cross compilation.

3. runtime

The third root, /runtime/, is for software that will run on the target system
only. Typical examples are commands that will be embedded in scripts that
are generated during compilation but intended to be ran by the application
on the target system only, independently of what the host system was.

4. summary


Host: the system used for compilation
Target: the system where the compiled software will run on

                  +--------------------------+
                  | where the output is used |
                  |-------------+------------+
                  |   Host      |   Target   |
+------+----------+-------------+------------+
| where| Host     | /host/      | /target/   |
| it   +----------+-------------+------------+
| runs | Target   |             | /runtime/  |
+------+----------+-------------+------------+