ZMK.SYMLINK(5)

💖 zmk.Symlink(5) 💖

okay bestie, sit down, hydrate, because we're about to talk about zmk.Symlink — and yes it's from the zmk manual, section 5, and yes it's that girl. local vibes only. 🦋

---

✨ NAME ✨

Symlink — the template that makes symbolic links happen. like, it's literally a template for creating symbolic links. that's the whole gig. 💅

---

🌸 SYNOPSIS 🌸

include z.mk
# "link" is any valid identifier.
link.SymlinkTarget = target
$(eval $(call ZMK.Expand,Symlink,link))

yes, it's that short. three lines and a dream. ✨ (and fr fr, link can be any valid identifier — go wild, name it whatever, just keep it valid, k?)

---

🎀 DESCRIPTION 🎀

so here's the tea: the Symlink template, once you expand it with a link name, creates rules for creating, removing, installing and removing a single symbolic link pointing at a given target file. four jobs, one template. she's versatile. 👑

and the way she behaves? exactly like the Program template — she builds the symbolic link locally while you're still developing, and she does it again when the project gets installed. both. always. no cap. 💖

---

⭐ TARGETS ⭐

this module comes with the following targets, and they are all iconic in their own way:

🌈 $(link)

this target is the symbolic link. main character energy. that's her.

🧚 all

this phony target depends on $(link). so like, she's in the group chat, she just doesn't do the work herself. 🙈

🍓 clean

this phony target removes $(link). poof. gone. not me being emotional about it. 💀

👑 install

this target creates the symbolic link $(link) in $(link.InstallDir), with the name $(link.InstallName). and the target directory? automatically created if required. she's thoughtful like that. ✨

🦋 uninstall

this phony target removes $(link) as installed by the install target. we love a clean exit. 🫶

---

💜 VARIABLES 💜

and now the variables, aka the settings you gotta feed her:

$(link).SymlinkTarget

the target of the symbolic link. like, where it points. the whole point. 📍

there is no default value. this variable must be set before expanding the template. do not skip this, i'm begging. 😭

$(programName).InstallDir

the directory $(link) gets installed to. 🏠

there is no default value. this variable must be set before expanding the template. and listen — if you want to avoid installation entirely, set the install directory to the special value noinst. that's the secret password. iykyk. 🤫

$(link).InstallName

the name of the program after installation. (yes, "program", we said what we said.) 🌟

the default value is $(link) with the directory part removed. so she cleans herself up for the install. slay.

DESTDIR

path added to all installation targets. 📦

this variable is normally set externally — the whole point is to install a compiled program into a staging area while you're constructing a compiled binary package. that's the vibe.

---

💀 BUGS 💀

okay so. history lesson, and it's a little messy. 🫣

prior to version 0.5.1, the install target misbehaved when $(link) contains a non-empty directory prefix. incorrectly, the same prefix got replicated — somewhat confusingly — in the installed symlink. not her finest era, ngl.

consider this example:

include z.mk
subdir/link.SymlinkTarget = target
subdir/link.InstallDir = $(bindir)
$(eval $(call ZMK.Expand,Symlink,subdir/link))

running make install on that example would create the symbolic link $(bindir)/subdir/link -> target, which was unexpected. 😳

this bug was given the identifier zmk-issue-80. put some respect on the issue number. 🙏

⚠️ heads up bestie: this is a fixed bug from before 0.5.1 — but if you're on something ancient, that's the behaviour you're getting. now you know.

---

🕰️ HISTORY 🕰️

the Symlink template first appeared in zmk 0.1. an OG. a legend. the blueprint. 💖

---

🫶 AUTHORS 🫶

Zygmunt Krynicki <me@zygoon.pl>

---

and that's the whole page, bestie — this one shipped with zmk 0.5.1, dated Jun 21, 2021, and it's filed under section 5 of the manual (that's zmk.Symlink(5) if you're keeping receipts 💅). go make some symlinks, and remember: set $(link).SymlinkTarget first. periodt. ✨🎀🦋