1zmk.Configure.5(PRM) LOCAL zmk.Configure.5(PRM)
2
4 Configure — module providing build time configuration system
5
7 include z.mk
8 $(eval $(call ZMK.Import,Configure))
10
12 The Configure module provides two sides of the build-time configuration
13 system. On one hand side it provides the familiar configure script, which
14 can be used to set up various settings, prepare a directory for
15 out-of-tree build, and integrate with project specific configuration set‐
16 tings. On the other hand it exposes the collected information as a set of
17 variables, allowing the rest of the build system to modify its behavior
18 accordingly.
19
21 This module provides the following targets.
22 configure
24 This target generates the configuration script. The script is also auto‐
25 matically placed inside the source archive, so that the recipient does
26 not need to have a local installation of zmk to build a project from
27 source.
28 config.$(NAME).mk
30 This target is named after the configuration file created by the
31 configure script. The rules are such, that if the configure script is
32 newer than the configuration file, then the script is re-executed to gen‐
33 erate a possibly updated configuration file.
34 distclean
36 This phony target removes the configuration file config.$(NAME).mk. In
37 maintainer mode, the configuration file is also removed.
38
40 This module provides the following variables.
41 Configure.HostArchTriplet
43 This variable is set by the configure script when invoked with the
44 --host=... option. It represents the triplet describing the system which
45 will eventually execute the compiled binaries. This is in contrast to the
46 system that is preforming the build.
47 Unlike in autoconf this variable is not set automatically. It is usually
49 provided by Linux distribution packaging which follows the up-to-date
50 conventions on architecture triplet names. The triplet contains three
51 components, separated by dashes, the CPU architecture, Kernel name and
52 Operating System name. Popular values include x86_64-linux-gnu,
53 aarch64-linux-gnu and riscv64-linux-gnu. Note that there is a lot of
54 variability in the architecture name and special cases related to the ARM
55 architecture.
56 Configure.BuildArchTriplet
58 This variable is set by the configure script when invoked with the
59 --build=... option. It represents the triplet describing the system which
60 is performing the build process. This is in contrast to the system that
61 will execute the built binaries.
62 When both Configure.HostArchTriplet and Configure.BuildArchTriplet are
64 set and their values differ and when CC and CXX are not overridden, then
65 zmk automatically selects a cross-compiler from the GNU Compiler
66 Collection named $(Configure.HostArchTriplet)-gcc and
67 $(Configure.HostArchTriplet)-g++ for the C and C++ compilers, respec‐
68 tively.
69 Configure.TargetArchTriplet
71 This variable is set by the configure script when invoked with the
72 --target=... option. It represents the triplet describing the system for
73 which any generated code will be made. This variable is needed infre‐
74 quently, usually by tools such as compilers, to prepare them for creating
75 binary code for a given architecture.
76 Configure.SysRoot
78 This variable is set by the configure script when invoked with the
79 --with-libtool-sysroot=... option. It represents the explicit root direc‐
80 tory of the file system where the compiler should look for libraries and
81 headers. It is typically used during cross-compilation, to isolate the
82 build process from whatever headers and libraries are installed natively
83 on the system.
84 Configure.DependencyTracking
86 This variable is controlled by the configure script options
87 --enable-dependency-tracking (default) and --disable-dependency-tracking.
88 When enabled it expands to yes and causes compatible compilers to gener‐
89 ate dependency information when compiling source files, that is subse‐
90 quently used by Make to understand relationship between all the source
91 files and object files.
92 When performing pristine builds in a scratch environment that does not
94 contain any old object files, this setting can be disabled to speed up
95 the build a little.
96 Configure.MaintainerMode
98 This variable is controlled by the configure script options
99 --enable-maintainer-mode (default) and --disable-maintainer-mode. When
100 enabled it expands to yes and impacts the configure and config.$(NAME).mk
101 targets as described earlier.
102 Configure.SilentRules
104 This variable is controlled by the configure script options
105 --enable-silent-rules and --disable-silent-rules (default). When enabled
106 it expands to yes and silences make rules defined by zmk.
107 Configure.StaticLibraries
109 This variable is controlled by the configure script options
110 --enable-static (default) and --disable-static. When static libraries
111 are disabled the template Library.A becomes inactive.
112 Configure.DynamicLibraries
114 This variable is controlled by the configure script options
115 --enable-dynamic (default) and --disable-dynamic. When dynamic libraries
116 are disabled the templates Library.So and Library.DyLib become inactive.
117 Configure.ProgramPrefix
119 This variable is set by the configure script when invoked with the
120 --program-prefix=... option.
121 The argument is the prefix added to installed name of all the programs
123 built with the Program and the Script templates.
124 Configure.ProgramSuffix
126 This variable is set by the configure script when invoked with the
127 --program-suffix=... option.
128 The argument is the suffix added to installed name of all the programs
130 built with the Program and the Script templates.
131 Configure.ProgramTransformName
133 This variable is set by the configure script when invoked with the
134 --program-transform-name=... option.
135 The argument is a sed expression used to transform the installed name of
137 all the programs built with the Program and the Script templates. The
138 transformation affects the entire name, together with any prefix or suf‐
139 fix defined by their options.
140 Configure.Configured
142 This variable expands to yes when the configure script was used to cus‐
143 tomize the build process. It can be used to offer default behaviors that
144 are appropriate to a given project, without interacting with customiza‐
145 tions performed by distribution packaging.
146 Configure.Options
148 This variable expands to the command line arguments passed to the
149 configure script. It is used for automatic re-configuration supported by
150 maintainer mode. It can be also provided to the pre-processor to embed
151 the information about build-time configuration into the application or
152 library binary.
153
155 configure
156 Automatically generated POSIX shell script mimicking the appearance and
157 behavior of a similar file provided by GNU autoconf. This script should
158 not be committed to version control systems. This script is added to re‐
159 lease archives, as it allows one to compile a project from source without
160 additionally depending on zmk libraries.
161 config.$(NAME).mk
163 Project specific configuration file generated by executing the configure
164 script.
165
167 The Configure module is automatically imported and is implicitly avail‐
168 able when templates such as Program or Script are used. It does not re‐
169 quire any additional input files. All customization is available directly
170 from the project makefile.
171
173 The Configure module first appeared in zmk 0.3. Starting with version 0.4
174 the configuration module provides the configure script and configuration
175 persistence only to projects which define their Configure NAME .
176
178 Versions prior to 0.4 used a fixed name for the configuration file cre‐
179 ated by running the configure script, namely GNUmakefile.configured.mk.
180 This caused issues with make's PATH traversal when searching for include
181 candidates that was resolved by using configuration files specific to a
182 given project, called config.$(NAME).mk.
183
185 Zygmunt Krynicki <me@zygoon.pl>
186zmk 0.5.1 Dec 28, 2020 zmk 0.5.1