ZMK.TOOLCHAIN(5)

🎀 NAME 🎀

Toolchain — a module that hands you all the info and configuration about your compiler toolchain. Yes bestie, this is zmk.Toolchain(5), section 5, LOCAL energy, and it's lowkey the backbone of everything compiler-related in here 💅

---

✨ SYNOPSIS ✨

include z.mk

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

Two lines. That's the whole entrance. Serve.

---

🦋 DESCRIPTION 🦋

The Toolchain module wraps up everything worth knowing about the C and C++ compilers you're using. Most of the time it's other modules and templates that are quietly eating this info behind the scenes, but you can absolutely use it directly to build your own custom rules. Main character module behavior, honestly 👑

---

🔥 TARGETS 🔥

Nope. None. Zero targets. This module does not provide any targets, and that's its whole vibe — it's a provider, not a doer 💀

---

💖 VARIABLES 💖

Okay so here's the tea: this module provides the following variables.

And before you go wild, please take note that make supports target-specific variables. That means a specific variable — say CFLAGS or LDLIBS — takes a particular value only while building a specific target, plus every target that it depends on. This scheme removes the need for extra variables that you'd otherwise have to manually customize for a specific target. It's giving "clean Makefiles, no notes" ✨

CC

The C compiler. Simple. Iconic.

CPP

The pre-processor, the one responsible for macros and include directives. It's the friend that handles the vibes before the compiler even shows up 🧚

CXX

The C++ compiler.

CFLAGS

Configuration options for the C compiler.

This is where you drop options like -Wall, -O2, or -fpic. Please refer to your compiler manual for details, bestie — I can't read the manual for you 💅

Now, real talk: this variable is often abused, mainly for simplicity, as a kitchen-sink that holds all of the compiler and linker options. That is discouraged. Not me calling you out, just the manpage calling everyone out 🙈

CPPFLAGS

Configuration options for the pre-processor.

Use this one to pass command line options that alter the include search path, like -I, or to define a pre-processor macro, like -D.

CXXFLAGS

Configuration options for the C++ compiler. This variable is the equivalent of CFLAGS for the C++ compiler. Same energy, different language 💜

OBJCFLAGS

Configuration options for the Objective C compiler. This variable is the equivalent of CFLAGS for the Objective C compiler.

ARFLAGS

Configuration options for the ar program.

TARGET_ARCH

Compiler options for performing architecture selection.

Heads up: this variable is not used by zmk. Cross compilation is supported by selecting a cross-compiling CC or CXX instead. So like… it exists, but it's not the move 🌸

LDLIBS

Additional libraries to link with.

Libraries are provided in the form -lfoo, where foo is the name of the library, without the prefix lib. Given the choice of static and dynamic libraries, the linker will prefer dynamic linking. You can link a specific library statically with the following option sequence: -Wl,-dn -lfoo -Wl,-dy. The first segment -Wl,-dn turns off dynamic linking, -lfoo links to the library libfoo.a, while the final -Wl,-dy turns dynamic linking back again. Note that using this sequence the final executable is not entirely statically linked. If libfoo.a has any additional dependences, those must be linked as well — either dynamically or statically. Fr fr, read that part twice 🔍

LDFLAGS

Configuration options for the linker.

This variable should be used to provide command line options that alter the linker search path, such as -L, or customize linker behavior. Note that the linker is not invoked directly, but through the compiler front-end. For example, when using gcc, one would typically pass -Wl,foo in order to pass the option foo to the linker.

exe

The suffix for executables. It is either empty, or it has the value .exe — if the image format of the resulting executable is either PE or MZ.

This variable is automatically used by zmk when building executables. No manual labor required, queen 🫶

Toolchain.SysRoot

Path of the root directory where the compiler looks for headers and libraries. A non-empty value causes --sysroot=$(Toolchain.SysRoot) to be passed to the compiler whenever it is used for compiling, linking or pre-processing.

The default value is $(Configure.SysRoot), namely the preference from the configuration system.

Toolchain.DependencyTracking

Expands to yes if compilation of C, C++ and Objective C source files will automatically generate dependency rules for Make.

The default value is $(Configure.DependencyTracking), namely the preference from the configuration system. Set it and forget it, that's the dream ⭐

Toolchain.ImageFormat

Identifier of the application image format generated by both the C compiler or the C++ compiler. If the two compilers produce different image formats — for example because one is a cross-compiler — the effective value is Mixed.

Toolchain.IsCross

Expands to yes if programs created by either the C compiler or the C++ compiler cannot be executed on the machine performing the build.

Toolchain.IsGcc

Expands to yes if both the C and C++ compilers are from the GNU Compiler Collection.

Toolchain.IsClang

Expands to yes if both the C and C++ compilers are from the clang project.

Toolchain.IsWatcom

Expands to yes if both the C and C++ compilers are from the Open Watcom compiler.

Toolchain.CC.IsAvaiable

Expands to yes if the C compiler is available.

Toolchain.CC.ImageFormat

Identifier of the application image format generated by the C compiler. Refer to the documentation of OS.ImageFormat for a description of known formats.

Unless cross-compiling, the default value is $(OS.ImageFormat).

Toolchain.CC.IsCross

Expands to yes if programs created by the C compiler cannot be executed on the machine performing the build.

Toolchain.CC.IsGcc

Expands to yes if the selected C compiler is the GNU Compiler Collection. This variable, as well as several others documented below, can be used to conditionally enable compiler specific options in a manner that does not break when another compiler is used. Conditional queen behavior 👑

Toolchain.CC.IsClang

Expands to yes if the selected C compiler is clang.

Toolchain.CC.IsWatcom

Expands to yes if the selected C compiler is the Open Watcom compiler.

Toolchain.CC.IsTcc

Expands to yes if the selected C compiler is the Tiny C Compiler.

Toolchain.CXX.IsAvaiable

Expands to yes if the C++ compiler is available.

Toolchain.CXX.ImageFormat

Identifier of the application image format generated by the C++ compiler.

Unless cross-compiling, the default value is $(OS.ImageFormat).

Toolchain.CXX.IsCross

Expands to yes if programs created by the C++ compiler cannot be executed on the machine performing the build.

Toolchain.CXX.IsGcc

Expands to yes if the selected C++ compiler is the GNU Compiler Collection.

Toolchain.CXX.IsClang

Expands to yes if the selected C++ compiler is clang.

Toolchain.CXX.IsWatcom

Expands to yes if the selected C++ compiler is the Open Watcom compiler.

---

🌈 EXAMPLES 🌈

(crickets) Yeah bestie, this section is just… empty. No examples in the original. Respect the silence 🙈

---

📜 HISTORY 📜

The Toolchain module first appeared in zmk 0.3. A legend from the start 💅

---

🌸 AUTHORS 🌸

Zygmunt Krynicki <me@zygoon.pl>

---

And that's the whole page, babe — this was zmk.Toolchain(5), straight outta zmk 0.5.1, dated May 3, 2020. Go compile something gorgeous 💖✨