← board

What a cross-unit define is called, and what it means

DECIDED by the user, 2026-08-19.

  1. Name: {$CLAIM}. {$DEFINEGLOBAL} is retired as a spelling — it named the wrong property. "I think that's fair."
  2. Set-once, never cleared. Not stated in as many words, but it follows directly from the semantics the user gave: "if not defined, I define this and craft this code, and claim the directive, so no other unit will do." A claim you can release is not a claim. Flagged as DERIVED rather than quoted — if the implementer finds a reason to want a release, that is a new question, not an implementation detail.
  3. Scope: whole compilation. Global, as recommended.
  4. NOT retroactive. "Apart retro-actively applying, I think, not." A unit already compiled does not see a later claim.

The rationale matters as much as the answers, because it settles what the order-dependence IS. The user: "that's pretty much how C works. and the whole purpose of this definition (was it already defined)."

So order-dependence is not a defect to be documented around — it is the feature. This is the #ifndef GUARD / #define GUARD pattern: the first unit to arrive claims the name, crafts its code, and every later unit sees the claim and stands down. The ticket worried that order-dependence conflicts with [[bug-p-uses-order-does-not-decide-which-unit-wins]], which worked to make resolution deterministic. It does not conflict: that bug was about order deciding an outcome the program did not ask for. {$CLAIM} is the program asking for it explicitly, at a spelling that says so. The name was the whole decision, exactly as the fork predicted.

Work re-filed into Track P — see below.

Split out of [[feature-p-defineglobal-a-define-that-crosses-unit-boundaries]] 2026-08-19, on frank2's triage recommendation. That ticket is genuine work, but it is blocked on judgement, not on engineering — it carries four design questions and no way for an engineer to settle them. Left as a feature it reads as buildable and gets picked up by someone who then has to guess.

Nothing is waiting on this. Its motivating case was closed as synthetic, so there is no deadline; the cost of leaving it open is zero and the cost of guessing is a dialect feature we cannot rename later.

The fork, in one line

The honest name is the decision. The mechanism is first-one-wins claim-and-skip, which is order-dependent by construction — the exact property that [[bug-p-uses-order-does-not-decide-which-unit-wins]] worked to eliminate. That is fine when a program deliberately asks for it and a bug when it happens by accident, so the spelling has to make the dependence obvious at the use site.

{$DEFINEGLOBAL} reads as "global" — i.e. as a property of the program — when it actually means "whoever gets here first claims it". The ticket itself floats {$CLAIM} as more honest. That is the question worth the user's attention; the other three follow from it.

The four questions, verbatim from the feature ticket

  1. Ordering. "First one wins" makes the answer depend on uses order. Acceptable when the program asked for claim-and-skip, unacceptable as an accident — so the name and docs must make the dependence obvious.
  2. Can it be undefined? A global {$UNDEF} reopens the same race. Ticket's lean: set-once, never cleared, which is also the cheapest to implement.
  3. Scope of "global". Whole compilation, presumably — rather than "all units compiled after this point in the uses graph", which is subtler and harder to reason about.
  4. Visibility to units compiled EARLIER. Does it survive into a used unit's own conditionals if that unit is re-entered? Ticket's lean: almost certainly no — and saying so is cheaper than discovering it.

Recommendation

Answer question 1 (the name) and questions 2-4 fall out with the leans already recorded. If the name says claim-and-skip, then set-once follows (a claim you can release is not a claim), whole-compilation scope follows, and no-retroactive-visibility follows.

Adjacent work, worth reading first: frank3's import/uses refactor landed 2026-08-19 and settled how a NilPy import names another language, including the quoted-path spelling and the as alias. That is neighbouring territory for how a program names and claims things across unit boundaries, and it may make one spelling read as more natural than the other.

What happens after

Once decided, re-file the work into the owning lane (Track P) and drop this ticket into decided/. A decided ticket that is never re-filed is invisible to ready/next and gets rediscovered — sometimes with a fix the decision already rejected.

Log