From d02ab4b7b6165a6acb22926f65e59bef5bf5874f Mon Sep 17 00:00:00 2001
From: huntedbytheirs <huntedbyth3irs@gmail.com>
Date: Tue, 4 Aug 2026 13:19:59 -0400
Subject: [PATCH] docs: update examples with += env operator and env usage docs

- foo.kap: document all three env operators (=, ?=, +=) in header,
  demonstrate += in env block with comments

- postgres.kap: demonstrate += for appending security hardening flags

- config.kap: demonstrate system-level += for inherited flags
---
 examples/config.kap   |  2 ++
 examples/foo.kap      | 15 +++++++++++++++
 examples/postgres.kap |  2 ++
 3 files changed, 19 insertions(+)

diff --git a/examples/config.kap b/examples/config.kap
index de9b668..1a6ace0 100644
--- a/examples/config.kap
+++ b/examples/config.kap
@@ -67,6 +67,8 @@ system {
 
     env {
         CFLAGS    = "-O2 -march=native"
+        // packages inherit this appended flag
+        CFLAGS   += "-pipe"
         LDFLAGS   = "-Wl,--as-needed"
         MAKEFLAGS = "-j8"
     }
diff --git a/examples/foo.kap b/examples/foo.kap
index d602780..04db029 100644
--- a/examples/foo.kap
+++ b/examples/foo.kap
@@ -46,6 +46,17 @@
  *
  * The backend generators handle all translation.  Package authors only
  * need to pick the semantic type that describes their daemon's behaviour.
+ *
+ *
+ * ENV OPERATORS
+ * =============
+ *   key = "val"     hard set — overwrites any existing value
+ *   key ?= "val"    soft set — only applied if key is not already set
+ *   key += "val"    append   — adds to existing value with a space separator
+ *
+ * Order matters.  Subsequent entries in the same env block can append to
+ * earlier ones.  System-level env (from config.kap) is applied before
+ * package env, so packages can += to flags set globally.
  */
 package "foo" {
     const version = "1.2.3"
@@ -101,8 +112,12 @@ package "foo" {
     }
 
     env {
+        // hard set — overwrites any existing CFLAGS
         CFLAGS   = "-O2 -march=native"
+        // append  — now CFLAGS is "-O2 -march=native -pipe"
+        CFLAGS  += "-pipe"
         LDFLAGS  = "-Wl,--as-needed"
+        // soft set — only added if CFLAGS isn't already defined
         CFLAGS  ?= "-g"
     }
 
diff --git a/examples/postgres.kap b/examples/postgres.kap
index 333d230..62f5f3e 100644
--- a/examples/postgres.kap
+++ b/examples/postgres.kap
@@ -77,6 +77,8 @@ package "postgresql" {
 
     env {
         CFLAGS  = "-O2"
+        // append security hardening flags
+        CFLAGS += "-D_FORTIFY_SOURCE=2"
         LDFLAGS = "-Wl,--as-needed"
     }