1zmk.Configure.5(PRM)                 LOCAL                zmk.Configure.5(PRM)
2

NAME

4     Configure — module providing build time configuration system
5

SYNOPSIS

7     include z.mk
8
9     $(eval $(call ZMK.Import,Configure))
10

DESCRIPTION

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

TARGETS

21     This module provides the following targets.
22
23   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
29   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
35   distclean
36     This phony target removes the configuration file config.$(NAME).mk.  In
37     maintainer mode, the configuration file is also removed.
38

VARIABLES

40     This module provides the following variables.
41
42   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
48     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
57   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
63     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
70   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
77   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
85   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
93     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
97   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
103   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
108   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
113   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
118   Configure.ProgramPrefix
119     This variable is set by the configure script when invoked with the
120     --program-prefix=... option.
121
122     The argument is the prefix added to installed name of all the programs
123     built with the Program and the Script templates.
124
125   Configure.ProgramSuffix
126     This variable is set by the configure script when invoked with the
127     --program-suffix=... option.
128
129     The argument is the suffix added to installed name of all the programs
130     built with the Program and the Script templates.
131
132   Configure.ProgramTransformName
133     This variable is set by the configure script when invoked with the
134     --program-transform-name=... option.
135
136     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
141   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
147   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

FILES

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
162   config.$(NAME).mk
163     Project specific configuration file generated by executing the configure
164     script.
165

EXAMPLES

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

HISTORY

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

BUGS

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

AUTHORS

185     Zygmunt Krynicki <me@zygoon.pl>
186
187zmk 0.5.1                        Dec 28, 2020                        zmk 0.5.1
Impressum