zmk.Configure.5(PRM)

NAME
Configure - module providing build time configuration system

SYNOPSIS

    include z.mk
    $(eval $(call ZMK.Import,Configure))

DESCRIPTION
The Configure module provides two sides of the build-time configuration system. On one hand side it provides the familiar configure script, which can be used to set up various settings, prepare a directory for out-of-tree build, and integrate with project specific configuration settings. On the other hand it exposes the collected information as a set of variables, allowing the rest of the build system to modify its behavior accordingly.

TARGETS
This module provides the following targets.

  configure
This target generates the configuration script. The script is also automatically placed inside the source archive, so that the recipient does not need to have a local installation of zmk to build a project from source.

  config.$(NAME).mk
This target is named after the configuration file created by the configure script. The rules are such, that if the configure script is newer than the configuration file, then the script is re-executed to generate a possibly updated configuration file.

  distclean
This phony target removes the configuration file config.$(NAME).mk. In maintainer mode, the configuration file is also removed.

VARIABLES
This module provides the following variables.

  Configure.HostArchTriplet
This variable is set by the configure script when invoked with the --host=... option. It represents the triplet describing the system which will eventually execute the compiled binaries. This is in contrast to the system that is preforming the build.

Unlike in autoconf this variable is not set automatically. It is usually provided by Linux distribution packaging which follows the up-to-date conventions on architecture triplet names. The triplet contains three components, separated by dashes, the CPU architecture, Kernel name and Operating System name. Popular values include x86_64-linux-gnu, aarch64-linux-gnu and riscv64-linux-gnu. Note that there is a lot of variability in the architecture name and special cases related to the ARM architecture.

  Configure.BuildArchTriplet
This variable is set by the configure script when invoked with the --build=... option. It represents the triplet describing the system which is performing the build process. This is in contrast to the system that will execute the built binaries.

When both Configure.HostArchTriplet and Configure.BuildArchTriplet are set and their values differ and when CC and CXX are not overridden, then zmk automatically selects a cross-compiler from the GNU Compiler Collection named $(Configure.HostArchTriplet)-gcc and $(Configure.HostArchTriplet)-g++ for the C and C++ compilers, respectively.

  Configure.TargetArchTriplet
This variable is set by the configure script when invoked with the --target=... option. It represents the triplet describing the system for which any generated code will be made. This variable is needed infrequently, usually by tools such as compilers, to prepare them for creating binary code for a given architecture.

  Configure.SysRoot
This variable is set by the configure script when invoked with the --with-libtool-sysroot=... option. It represents the explicit root directory of the file system where the compiler should look for libraries and headers. It is typically used during cross-compilation, to isolate the build process from whatever headers and libraries are installed natively on the system.

  Configure.DependencyTracking
This variable is controlled by the configure script options --enable-dependency-tracking (default) and --disable-dependency-tracking. When enabled it expands to yes and causes compatible compilers to generate dependency information when compiling source files, that is subsequently used by Make to understand relationship between all the source files and object files.

When performing pristine builds in a scratch environment that does not contain any old object files, this setting can be disabled to speed up the build a little.

  Configure.MaintainerMode
This variable is controlled by the configure script options --enable-maintainer-mode (default) and --disable-maintainer-mode. When enabled it expands to yes and impacts the configure and config.$(NAME).mk targets as described earlier.

  Configure.SilentRules
This variable is controlled by the configure script options --enable-silent-rules and --disable-silent-rules (default). When enabled it expands to yes and silences make rules defined by zmk.

  Configure.StaticLibraries
This variable is controlled by the configure script options --enable-static (default) and --disable-static. When static libraries are disabled the template Library.A becomes inactive.

  Configure.DynamicLibraries
This variable is controlled by the configure script options --enable-dynamic (default) and --disable-dynamic. When dynamic libraries are disabled the templates Library.So and Library.DyLib become inactive.

  Configure.ProgramPrefix
This variable is set by the configure script when invoked with the --program-prefix=... option.

The argument is the prefix added to installed name of all the programs built with the Program and the Script templates.

  Configure.ProgramSuffix
This variable is set by the configure script when invoked with the --program-suffix=... option.

The argument is the suffix added to installed name of all the programs built with the Program and the Script templates.

  Configure.ProgramTransformName
This variable is set by the configure script when invoked with the --program-transform-name=... option.

The argument is a sed expression used to transform the installed name of all the programs built with the Program and the Script templates. The transformation affects the entire name, together with any prefix or suffix defined by their options.

  Configure.Configured
This variable expands to yes when the configure script was used to customize the build process. It can be used to offer default behaviors that are appropriate to a given project, without interacting with customizations performed by distribution packaging.

  Configure.Options
This variable expands to the command line arguments passed to the configure script. It is used for automatic re-configuration supported by maintainer mode. It can be also provided to the pre-processor to embed the information about build-time configuration into the application or library binary.

FILES

  configure
Automatically generated POSIX shell script mimicking the appearance and behavior of a similar file provided by GNU autoconf. This script should not be committed to version control systems. This script is added to release archives, as it allows one to compile a project from source without additionally depending on zmk libraries.

  config.$(NAME).mk
Project specific configuration file generated by executing the configure script.

EXAMPLES
The Configure module is automatically imported and is implicitly available when templates such as Program or Script are used. It does not require any additional input files. All customization is available directly from the project makefile.

HISTORY
The Configure module first appeared in zmk 0.3. Starting with version 0.4 the configuration module provides the configure script and configuration persistence only to projects which define their Configure NAME .

BUGS
Versions prior to 0.4 used a fixed name for the configuration file created by running the configure script, namely GNUmakefile.configured.mk. This caused issues with make's PATH traversal when searching for include candidates that was resolved by using configuration files specific to a given project, called config.$(NAME).mk.

AUTHORS
Zygmunt Krynicki <me@zygoon.pl>