Naming Convention¶

ZMK comes with a convention for development of Make libraries. This is an informal convention aimed at reducing friction in a untyped language devoid of any encapsulation system, such as that of Make itself.

Almost all variables and functions use a naming convention prefixing all names with the name of the module followed by a dot. In addition, each name is either public, meant to be used by others and offering some API stability guarantees, or private, being a part of the implementation and not the interface one should rely on, even though nothing in make itself prevents this. Public names are capitalized, private names start with a lower case character.

For example ZMK.Version is a public symbol containing the version of the ZMK library while ZMK.z.mk is a private symbol containing, at the time of this writing, the full path of the loaded z.mk library.

Modules¶

ZMK comes with a module system, which builds on the make include system. A module is a makefile installed to a zmk-specific directory. Typically each module defines some variables, one of which can be a template. A module which defines a template is simply called a template and is discussed below. To import a module use the following expression:

$(eval $(call ZMK.Import,ModuleName))

Not all modules contain literal make rules. As another example, the Toolchain module knows how to detect and interrogate the compiler toolchain, offering information useful for other modules. For a full listing of modules built into zmk see MODULES below.

AllClean¶

This template interacts with the common targets all and clean.

Configure¶

This module provides a configuration facility and access to interactive configure script.

Coverity¶

This unstable module provides support for the Coverity static analyzer.

Directories¶

This module provides rules for configurable directories such as $(libdir) or $(bindir).

Directory¶

This template provides rules for creating a single directory. It's more involved than it seems.

GitVersion¶

This module allows augmenting project version with information from the Git version control system.

Header¶

This template provides targets for installation of public development headers.

InstallUninstall¶

This template provides rules for installing and uninstalling files.

Library.A¶

This template provides rules for preparing static libraries.

Library.DyLib¶

This template provides rules for preparing Mach-O dynamic libraries.

Library.So¶

This template provides rules for preparing ELF dynamic libraries.

ManPage¶

This template provides rules for checking and installing manual pages.

OS¶

This module provides information about the operating system.

ObjectGroup¶

This template provides rules for compiling a group of object files.

PVS¶

This module provides rules for working with the PVS static analyzer.

Program.Test¶

This template provides rules for compiling and executing test programs as well as for computing code coverage analysis.

Program¶

This template provides rules for compiling, installing and uninstalling executable programs.

Script¶

This template provides rules checking, installing and uninstalling executable scripts.

Symlink¶

This template provides rules for creating symbolic links.

Tarball.Src¶

This template provides rules for creating release archives. It offers utility targets such as distcheck, which performs a level of validation of the produced archive.

Tarball¶

This template provides rules for constructing arbitrary tarballs. It handles differences between GNU and BSD tar utilities.

Toolchain¶

This module provides information about the configured toolchain. ZMK offers support for gcc, clang and several less commonly used compilers.

all¶

This goal builds everything that can be compiled or otherwise built.

clean¶

This goal removes all the files that were built.

coverage¶

This goal provides information about test coverage.

fmt¶

This goal re-formats source code according to the selected standard.

static-check¶

This goal runs static check analysis programs.

check¶

This goal runs unit test programs.

install¶

This goal installs everything that is installable.

uninstall¶

This goal removes everything that is installable.

dist¶

This goal produces a release archive, or archives.

distclean¶

This goal is a superset of clean, removing some files that require a ZMK installation to recreate.

distcheck¶

This goal is a superset of dist which produces and tests the release archive.

Project.Name¶

Name of the software distribution project. This value is typically used for release archives but it shows up in several other places.

Project.Version¶

Version of the project. The value is sometimes interpolated into generated files. It is also used for release archives. It can be modified programmatically by the GitVersion module.

NAME¶

Compatibility alias for Project.Name

VERSION¶

Compatibility alias for Project.Version

ZMK.Version¶

Version of the included zmk library.

ZMK.Path¶

Path of the included zmk library. This is used to locate modules to import.

ZMK.DistFiles¶

List of files to place into release archives so that the recipient need not install zmk on their system to build the project from source.

ZMK.SrcDir¶

Location of the source tree, when building out-of-tree. This is rarely needed as out-of-tree builds are supported by all the modules bundled with zmk.

ZMK.IsOutOfTreeBuild¶

If building out-of-tree, a non-empty word indicating truth. This is rarely required but may be of use in specific circumstances. One such example is the makefile of zmk itself, where certain directories that are present in the version control system need to be created and removed when building out-of-tree.

ZMK.OutOfTreeSourcePath¶

When building out-of-tree, the full path, including the trailing slash, of the source directory. This may be a relative path.

ZMK.ImportedModules¶

The set of modules imported so far. This can be used for diagnostic purposes. Please import modules by calling

ZMK.BugFixes¶

A list of bug identifiers representing the set of bugs that are resolved in zmk. Membership test can be used to conditionally enable hot-fixes that patch a part of ZMK in a given project, when upgrading zmk itself is not feasible. ZMK.Import.

VPATH¶

When building out-of-tree, ZMK sets VPATH to the out-of-tree source path. This allows make implicit and built-in rules to find the source code without modification.

ZMK.z.mk¶

Path of the entry point of the zmk library.

ZMK.comma¶

Variable expanding to a comma.

ZMK.newline¶

Variable expanding to a newline.

ZMK.hash¶

Variable expanding to a hash-or-pound symbol.