How to properly tell Bob about host dependencies
Bob closely tracks the input of all packages. This includes all checked out sources and the dependencies to other packages. If something is changed Bob can accurately determine which packages have to be rebuilt. This information is also used to find matching binary artifacts. If a recipe depends on resources that are outside of the declared recipes the situation changes, though. Bob cannot infer what external resources are actually used and how these influence the build result.
To make these external resources visible to Bob a fingerprintScript
must be
used. The script is executed and the output is taken as fingerprint for the
external resource. This way Bob can detect if the external resource has been
changed and if a binary artifact is suitable on other machines. See
Host dependency fingerprinting for more details.
Generally speaking fingerprint scripts should only be evaluated in case of a host-build. For cross-compiling the resources are usually provided by other recipes. The exception would be a recipe that uses some host resources during cross compilation, e.g. an IDL compiler that ships a target library too.
Fingerprinting the C/C++ compiler
The most common fingerprinting application is the host compiler. Usually a project should define a stub host compiler recipe that just represents the host compiler. The following example is stripped down for clarity:
provideTools:
toolchain:
path: .
environment:
CC: cc
CXX: c++
fingerprintIf: true
fingerprintScript: |
bob-libc-version
bob-libstdc++-version
host-toolchain:
path: .
By convention the tool name for the C/C++-Toolchain is just called
toolchain
. The fingerprintIf
of it will unconditionally enable
fingerprinting of whatever package is using this tool. The
fingerprintScript
will be added to these packages. In these scripts the
libc and libstdc++ versions are checked via the built-in helpers.
Note that there is a separate host-toolchain
tool that is basically the
same as toolchain
but without the fingerprintScript
and
fingerprintIf
. This special tool is used in recipes that always need the
host compiler even if they are cross-compiled with a different toolchain. The
Linux kernel is a notable example. The fingerprintScript
is not needed
there because the result of such packages do not depend on the actual host
compiler.
Using external libraries
Using a library from the host adds another dependency that must be declared to Bob. The example below assumes that the compiler is already fingerprinted as described in the previous chapter. Generally speaking the fingerprint script should properly detect the version of the library on the host.
Using pkg-config libraries
If your recipe uses an external library that ships a proper .pc
file it
is usually as simple as calling pkg-config
in the fingerprintScript
:
fingerprintScript: |
pkg-config --modversion <external-dependency>
Note the absence of a fingerprintIf
in the example. This is left out
deliberately because the recipe should typically not know if it is compiled on
the host or cross-compiled. The toolchain is supposed to enable fingerprinting
if the recipe is compiled for the host. For cross-builds the used
toolchain/SDK is normally provided by another recipe and thus fully known to
Bob. In contrast to that the host toolchain is just a stub recipe but it will
enable the fingerprinting if you follow the suggestion of the first section.
Using a library without meta information
If the library you are using does not provide any form of meta information it must be assumed that it is already in the search path of the linker. Bob provides a small helper that links a dummy executable to find the actual library that the linker was using:
fingerprintScript: |
bob-hash-libraries ffi
This will let the linker search the library. The result of the fingerprint is the hash sum of all used libraries, including transitive dependencies. While this may be more pessimistic than using a version number it is on the other hand guaranteed to detect different host configurations regarding this library.