1z.mk(5) Programmer's Manual z.mk(5)
2
4 z.mk — library for writing featureful Makefiles
5
7 # Define name and version of the project.
8 Project.Name=foo
9 Project.Version=1.2
10 # Include the configuration file generated by the configure script, if one
12 # exists. This enables a multitude of configuration options to be used.
13 -include config.foo.mk
14 # Assume the source code is in the current directory. This variable is always
16 # defined by the generated configuration file, enabling support for out-of-tree
17 # builds.
18 ZMK.SrcDir ?= .
19 # Include z.mk by searching include directories. If zmk is not globally
21 # installed then ZMK.Version expands to nothing. As a last resort, assume that
22 # zmk was bundled into the release archive.
23 include z.mk
24 ifeq ($(value ZMK.Version),)
25 include $(ZMK.SrcDir)/z.mk
26 endif
27 # ZMK is now ready. Import additional modules or expand templates as necessary.
29
31 z.mk, also known as ZMK, is a library of GNU-make compatible makefiles
32 providing an opinionated module and template system. The library comes
33 with a collection of modules for common C/C++ software projects: compil‐
34 ing programs, creating libraries, installing development headers, data
35 files, testing, etc. In addition the library offers specialized modules
36 for constructing new modules that reuse specific behavior, such as par‐
37 ticipating in targets such as all, clean, install or uninstall.
38 Naming Convention
40 ZMK comes with a convention for development of Make libraries. This is an
41 informal convention aimed at reducing friction in a untyped language de‐
42 void of any encapsulation system, such as that of Make itself.
43 Almost all variables and functions use a naming convention prefixing all
45 names with the name of the module followed by a dot. In addition, each
46 name is either public, meant to be used by others and offering some API
47 stability guarantees, or private, being a part of the implementation and
48 not the interface one should rely on, even though nothing in make itself
49 prevents this. Public names are capitalized, private names start with a
50 lower case character.
51 For example ZMK.Version is a public symbol containing the version of the
53 ZMK library while ZMK.z.mk is a private symbol containing, at the time of
54 this writing, the full path of the loaded z.mk library.
55 Modules
57 ZMK comes with a module system, which builds on the make include system.
58 A module is a makefile installed to a zmk-specific directory. Typically
59 each module defines some variables, one of which can be a template. A
60 module which defines a template is simply called a template and is dis‐
61 cussed below. To import a module use the following expression:
62 $(eval $(call ZMK.Import,ModuleName))
64 Modules encapsulate a piece of functionality or knowledge. For example,
65 there is a module which handles well-known UNIX directories. Importing
66 that module defines variables expanding to each of such directories. In
67 addition, that module depends on a template handling creation of a direc‐
68 tory, expanding that template many times, ensuring that make knows about
69 all the directories, contains no duplicate rules and that conventions
70 such as the DESTDIR variable are respected.
71 Not all modules contain literal make rules. As another example, the
73 Toolchain module knows how to detect and interrogate the compiler
74 toolchain, offering information useful for other modules. For a full
75 listing of modules built into zmk see MODULES below.
76
78 ZMK provides the following importable modules.
79 AllClean
81 This template interacts with the common targets all and clean.
82 Configure
84 This module provides a configuration facility and access to interactive
85 configure script.
86 Coverity
88 This unstable module provides support for the Coverity static analyzer.
89 Directories
91 This module provides rules for configurable directories such as $(libdir)
92 or $(bindir).
93 Directory
95 This template provides rules for creating a single directory. It's more
96 involved than it seems.
97 GitVersion
99 This module allows augmenting project version with information from the
100 Git version control system.
101 Header
103 This template provides targets for installation of public development
104 headers.
105 InstallUninstall
107 This template provides rules for installing and uninstalling files.
108 Library.A
110 This template provides rules for preparing static libraries.
111 Library.DyLib
113 This template provides rules for preparing Mach-O dynamic libraries.
114 Library.So
116 This template provides rules for preparing ELF dynamic libraries.
117 ManPage
119 This template provides rules for checking and installing manual pages.
120 OS
122 This module provides information about the operating system.
123 ObjectGroup
125 This template provides rules for compiling a group of object files.
126 PVS
128 This module provides rules for working with the PVS static analyzer.
129 Program.Test
131 This template provides rules for compiling and executing test programs as
132 well as for computing code coverage analysis.
133 Program
135 This template provides rules for compiling, installing and uninstalling
136 executable programs.
137 Script
139 This template provides rules checking, installing and uninstalling exe‐
140 cutable scripts.
141 Symlink
143 This template provides rules for creating symbolic links.
144 Tarball.Src
146 This template provides rules for creating release archives. It offers
147 utility targets such as distcheck, which performs a level of validation
148 of the produced archive.
149 Tarball
151 This template provides rules for constructing arbitrary tarballs. It han‐
152 dles differences between GNU and BSD tar utilities.
153 Toolchain
155 This module provides information about the configured toolchain. ZMK of‐
156 fers support for gcc, clang and several less commonly used compilers.
157
159 ZMK provides the following make goals.
160 all
162 This goal builds everything that can be compiled or otherwise built.
163 clean
165 This goal removes all the files that were built.
166 coverage
168 This goal provides information about test coverage.
169 fmt
171 This goal re-formats source code according to the selected standard.
172 static-check
174 This goal runs static check analysis programs.
175 check
177 This goal runs unit test programs.
178 install
180 This goal installs everything that is installable.
181 uninstall
183 This goal removes everything that is installable.
184 dist
186 This goal produces a release archive, or archives.
187 distclean
189 This goal is a superset of clean, removing some files that require a ZMK
190 installation to recreate.
191 distcheck
193 This goal is a superset of dist which produces and tests the release ar‐
194 chive.
195
197 ZMK provides several variables out of the box, even without importing any
198 additional modules. Those are listed below.
199 Project.Name
201 Name of the software distribution project. This value is typically used
202 for release archives but it shows up in several other places.
203 Project.Version
205 Version of the project. The value is sometimes interpolated into gener‐
206 ated files. It is also used for release archives. It can be modified pro‐
207 grammatically by the GitVersion module.
208 NAME
210 Compatibility alias for Project.Name
211 VERSION
213 Compatibility alias for Project.Version
214 ZMK.Version
216 Version of the included zmk library.
217 ZMK.Path
219 Path of the included zmk library. This is used to locate modules to im‐
220 port.
221 ZMK.DistFiles
223 List of files to place into release archives so that the recipient need
224 not install zmk on their system to build the project from source.
225 ZMK.SrcDir
227 Location of the source tree, when building out-of-tree. This is rarely
228 needed as out-of-tree builds are supported by all the modules bundled
229 with zmk.
230 ZMK.IsOutOfTreeBuild
232 If building out-of-tree, a non-empty word indicating truth. This is
233 rarely required but may be of use in specific circumstances. One such ex‐
234 ample is the makefile of zmk itself, where certain directories that are
235 present in the version control system need to be created and removed when
236 building out-of-tree.
237 ZMK.OutOfTreeSourcePath
239 When building out-of-tree, the full path, including the trailing slash,
240 of the source directory. This may be a relative path.
241 ZMK.ImportedModules
243 The set of modules imported so far. This can be used for diagnostic pur‐
244 poses. Please import modules by calling
245 ZMK.BugFixes
247 A list of bug identifiers representing the set of bugs that are resolved
248 in zmk. Membership test can be used to conditionally enable hot-fixes
249 that patch a part of ZMK in a given project, when upgrading zmk itself is
250 not feasible. ZMK.Import.
251 VPATH
253 When building out-of-tree, ZMK sets VPATH to the out-of-tree source path.
254 This allows make implicit and built-in rules to find the source code
255 without modification.
256
258 ZMK.z.mk
259 Path of the entry point of the zmk library.
260 ZMK.comma
262 Variable expanding to a comma.
263 ZMK.newline
265 Variable expanding to a newline.
266 ZMK.hash
268 Variable expanding to a hash-or-pound symbol.
269
271 The primary interface of zmk was first documented zmk 0.4
272
274 Zygmunt Krynicki <me@zygoon.pl>
275zmk 0.5.1 Oct 26, 2020 zmk 0.5.1