ZMK.PROGRAM(5)

💖 zmk.Program(5) — the vibe guide to compiling your lil C/C++/ObjC babies 💖

okay so bestie, welcome to zmk.Program, a manual page in the zmk family of manuals. it's a template for compiling C/C++/ObjC programs, and honestly? it's giving "build system but make it cute". let's get into it. 🎀

---

✨ NAME ✨

Program — the template for compiling C/C++/ObjC programs. that's it, that's the whole name, no notes. 👑

---

✨ SYNOPSIS ✨

include z.mk
# programName is any valid identifier.
programName.Sources = hello.c
$(eval $(call ZMK.Expand,Program,programName))

so like. programName is any valid identifier, okay? you pick it. it's your moment. 🌟

---

✨ DESCRIPTION ✨

okay so once you expand the Program template with a program name, it literally creates rules for compiling, cleaning, installing, and removing one single program written in C, C++, or Objective C. one program. one vibe. ✨

here's the tea on source files: they get compiled into object files that are prefixed with $(programName)-. why?? because that way a single source file can be compiled separately with distinct preprocessor, compiler, and linker options. slay. it's the same file, different settings, no drama, no collisions. 💅

and when you're cross-compiling for Windows or DOS, the $(exe) variable expands to .exe. periodt. 🪟

---

🎯 TARGETS 🎯

this module provides the following targets, bestie. memorize them, they're your besties too.

• $(programName)$(exe) — this target represents the program executable. the main character, literally. 👑
• all — a phony target that depends on $(programName)$(exe). it's the "do the thing" button. 🫶
• clean — phony, and it removes $(programName)$(exe) plus all the constituent object files and dependency files. it's giving spring cleaning. 🧹
• install — phony. copies $(programName) to $(programName.InstallDir), using the name $(programName.InstallName) and mode $(programName.InstallMode). and guess what, the target directory gets automatically created if it's required, so you don't have to lift a finger. 💅
  • also!! the variables Configure.ProgramPrefix, Configure.ProgramSuffix, and Configure.ProgramTransformName automatically impact the installed names of all the programs. no cap. all of them.
• uninstall — phony, removes $(programName)$(exe) as installed by the install target. the reverse uno card. 🃏

---

🧚 VARIABLES 🧚

this module provides the following variables. sit down, hydrate, here we go. 🍓

• $(programName).Sources — list of source files to compile.
  • there is no default value. this variable must be set before expanding the template. like, it's not optional, bestie, it's the whole point. 😭
• $(programName).Objects — list of object files to link.
  • the default value is all the elements of $(programName).Sources with the added prefix $(programName)- and with the extension replaced by .o.
• $(programName).Linker — the linker required to link object files together.
  • the default value depends on the type of source files used, ensuring that C++ sources are linked with the C++ linker. it just knows. 🔥
• $(programName).InstallDir — the directory $(programName)$(exe) is installed to.
  • the default value is $(bindir), but $(sbindir) or $(libexecdir) are commonly used as well. the special value noinst disables the rules related to installation and uninstallation. so if you don't want it installed, say noinst and it goes away. ghosted. 👻
• $(programName).InstallName — the name of the program after installation.
  • the default value is $(programName).
• $(programName).InstallMode — the UNIX mode $(programName)$(exe) is installed with.
  • the default value is 0755. iconic permissions, honestly. 🎀
• DESTDIR — path added to all installation targets.
  • this variable is normally set externally, to install a compiled program into a staging area during construction of a compiled binary package. you usually don't touch this one, it's set for you. 🫶
• CFLAGS, CXXFLAGS, OBJCFLAGS — options for the C, C++ and the Objective C compiler, respectively. one for each language, no favoritism. 🌈
• CPPFLAGS — options for the preprocessor.

---

🔧 IMPLEMENTATION NOTES 🔧

Program uses InstallUninstall to handle installation and removal. also, the exe variable is automatically set to .exe where appropriate. so you don't gotta do that yourself, it's already handled. 💜

---

🌸 EXAMPLES 🌸

okay so picture this. you've got yourself a true_false.c file that looks like:

#include <stdlib.h>

int main(void) {
    return EXIT_CODE;
}

and now the following Makefile builds the classic programs true and false. yes, THE classic programs. we love a throwback. 👑

include z.mk

true.Sources = true_false.c
$(eval $(call ZMK.Expand,Program,true))
true$(exe): CPPFLAGS += -DEXIT_CODE=EXIT_SUCCESS

false.Sources = true_false.c
$(eval $(call ZMK.Expand,Program,false))
false$(exe): CPPFLAGS += -DEXIT_CODE=EXIT_FAILURE

same source file, two whole programs, two different exit codes. the way that CPPFLAGS gets appended per-target?? obsessed. 🔥

---

📜 HISTORY 📜

the Program template first appeared in zmk 0.1. a true OG. ✨

---

💖 AUTHORS 💖

Zygmunt Krynicki <me@zygoon.pl> — thank you for your service, king. 🫡👑

---

and that's the whole page, bestie!! this was zmk 0.5.1, dated May 3, 2020 — go forth and compile something iconic. mwah. 💅✨🎀