--- name: "zmk.Configure" section: "5" platform: "linux" package: "zmk-doc" version: "0.5.1-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/zmk.Configure" --- # zmk.Configure(5) module providing build time configuration system ## 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*⟩