| zmk.Configure.5(PRM) | PRM | zmk.Configure.5(PRM) |
Configure — module
providing build time configuration system
include z.mk $(eval $(call ZMK.Import,Configure))
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.
This module provides the following targets.
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.
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.
This
phony
target removes the configuration file
config.$(NAME).mk. In maintainer
mode, the configuration file is also removed.
This module provides the following variables.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Project specific configuration file generated by executing the
configure script.
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.
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 .
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.
Zygmunt Krynicki <me@zygoon.pl>
| December 28, 2020 | zmk 0.5.1 |