Initial commit: Klammertext source distribution

Curated source subset assembled by klammertext-dev's doc/make_dist.sh: the Klammermachine (mac), the Standard Klammer Set (sks), the commands (com), editor plugins and install guides (doc), a test subset (tst), and lib/bin placeholders. Builds with 'make -C com'.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

mac/env/lsan.supp

@@ -0,0 +1,12 @@
+# LeakSanitizer suppressions for Klammertext debug builds.
+#
+# Suppress unactionable leaks from the embedded Python interpreter and
+# OpenImageIO module initialization — one-time-init allocations that
+# libraries conventionally leave for the OS to reclaim at exit. Real
+# leaks in Klammertext's own C++ code are still reported.
+#
+# Each "leak:<pattern>" line suppresses any leak whose stack trace has
+# a frame matching the substring (in a function name or library path).
+
+leak:libpython
+leak:OpenImageIO

mac/env/makefile.env

@@ -0,0 +1,68 @@
+# mac/env/makefile.env — single cross-platform build environment for Klammertext.
+#
+# Included identically by every component Makefile:
+#     include $(KLAMMERTEXT_HOME)/mac/env/makefile.env
+#
+# The platform is auto-detected with uname; the compiler is chosen with
+#     make COMPILER=gcc      (default)
+#     make COMPILER=clang
+# There is no per-host/per-OS file and no DESKTOP_SESSION/HOST/SITE selector.
+
+ifndef KLAMMERTEXT_HOME
+$(error KLAMMERTEXT_HOME is not set -- source mac/env/runtime.env first)
+endif
+
+include $(KLAMMERTEXT_HOME)/mac/env/optimize.env
+
+UNAME_S     := $(shell uname -s)
+CPP_VERSION := c++20
+# Default compiler: clang on macOS, gcc elsewhere. gcc-built Klammertext
+# binaries crash at runtime on macOS (a documented gcc/macOS codegen issue), so
+# gcc there is only a compile-time conformance check (via `./dbg/rebuild.sh
+# gcc`, which compiles under g++ then rebuilds with clang). Override with
+# `make COMPILER=...`.
+ifeq ($(UNAME_S),Darwin)
+COMPILER    ?= clang               # gcc | clang
+else
+COMPILER    ?= gcc                 # gcc | clang
+endif
+
+# Python: version- and platform-agnostic, no hardcoded paths.
+PYTHON_INC := $(shell python3-config --includes)
+PYTHON_LIB := $(shell python3-config --ldflags --embed)
+
+# Flags common to all platforms.
+CPPFLAGS = -I$(KLAMMERTEXT_HOME)/mac $(PYTHON_INC)
+CXXFLAGS = -Wall -Wextra -Weffc++ -Wshadow -std=$(CPP_VERSION) -fPIC $(OPTIMIZE) $(SANITIZE)
+
+ifeq ($(UNAME_S),Darwin)
+# ---------- macOS (Apple Silicon) ----------
+# Package-manager prefix, auto-detected: Homebrew (/opt/homebrew) or MacPorts
+# (/opt/local). Override with `make MACOS_PREFIX=...`. Only the prefix differs
+# between the two: the compiler is Apple Clang either way, and all Python flags
+# come from python3-config (prefix-agnostic), so nothing else is PM-specific.
+MACOS_PREFIX   ?= $(shell test -d /opt/homebrew && echo /opt/homebrew || (test -d /opt/local && echo /opt/local || echo /opt/homebrew))
+# Newest optional gcc (conformance check only): Homebrew g++-NN or MacPorts g++-mp-NN.
+GCC            := $(shell g=$$(ls $(MACOS_PREFIX)/bin/g++-[0-9]* $(MACOS_PREFIX)/bin/g++-mp-[0-9]* 2>/dev/null | sort -V | tail -1); echo $${g:-g++})
+CLANG          := clang++                         # Apple clang (or brew/port llvm)
+CPPFLAGS       += -I$(MACOS_PREFIX)/include
+LDFLAGS         = -L$(MACOS_PREFIX)/lib
+LDLIBS          = $(if $(NOPYTHON),,$(PYTHON_LIB))
+SHARED          = -dynamiclib
+SONAME          = -install_name @rpath/$(notdir $@)
+ORIGIN         := @loader_path
+EXPORT_DYNAMIC  = -Wl,-export_dynamic
+else
+# ---------- Linux ----------
+GCC            := /usr/bin/g++
+CLANG          := $(shell command -v clang++-18 2>/dev/null || command -v clang++ 2>/dev/null)
+LDFLAGS         = -L/usr/lib/x86_64-linux-gnu
+LDLIBS          = -ldl $(if $(NOPYTHON),,$(PYTHON_LIB))
+SHARED          = -shared
+SONAME          = -Wl,-soname,$(notdir $@)
+ORIGIN         := $$ORIGIN
+EXPORT_DYNAMIC  = -rdynamic
+endif
+
+# Resolve the compiler choice (gcc by default; clang with COMPILER=clang).
+CXX := $(if $(filter clang,$(COMPILER)),$(CLANG),$(GCC))

mac/env/makefile.env.hollis.DISABLED

@@ -0,0 +1,46 @@
+KLAMMERTEXT_HOME = /home/ack/projects/klammertext/K
+
+include $(KLAMMERTEXT_HOME)/mac/env/optimize.env
+
+CPP_VERSION = c++20
+
+#GCC_LIB = /usr/lib/gcc/x86_64-linux-gnu/7.4.0
+CXX = /usr/bin/g++
+
+#IMPORT = -fmodules -fsearch-include-path bits/std.cc
+IMPORT = 
+
+# Hack for now; to be generalized:
+ifneq ("$(wildcard /usr/include/python3.14)","")
+    PYTHON = python3.14
+else ifneq ("$(wildcard /usr/include/python3.13)","")
+    PYTHON = python3.13
+else
+    PYTHON = python3.12
+endif
+
+# -no-pie?
+CXXFLAGS =  -Wall -Wextra -Weffc++ -fPIC $(PROFILE) -std=$(CPP_VERSION) $(IMPORT) $(OPTIMIZE) \
+-I$(KLAMMERTEXT_HOME)/mac \
+-I/usr/include \
+-I/usr/include/$(PYTHON)
+
+# -L$(GCC_LIB) \
+
+LDFLAGS = \
+-L/usr/lib/x86_64-linux-gnu
+
+LDLIBS = \
+-ldl
+
+ifndef NOPYTHON
+LDLIBS += -l$(PYTHON)
+endif
+
+#GCC_ROOT = /h/dev/pkg/gcc-$(GCC_VERSION)
+#GCC_LIB = $(GCC_ROOT)/$(GCC_DIR)/lib/gcc/$(GCC_DIR)/$(GCC_VERSION)
+#$(GCC_LIB)
+
+LD_LIBRARY_PATH=\
+/usr/lib64\
+:/usr/lib/x86_64-linux-gnu

mac/env/makefile.env.jatke.DISABLED

@@ -0,0 +1,33 @@
+KLAMMERTEXT_HOME = /home/ack/projects/klammertext/K
+
+include $(KLAMMERTEXT_HOME)/mac/env/optimize.env
+
+CPP_VERSION = c++20
+
+CXX = /usr/bin/g++
+
+# Hack for now; to be generalized:
+ifneq ("$(wildcard /usr/include/python3.14)","")
+    PYTHON = python3.14
+else ifneq ("$(wildcard /usr/include/python3.13)","")
+    PYTHON = python3.13
+else
+    PYTHON = python3.12
+endif
+
+CPPFLAGS = \
+-I$(KLAMMERTEXT_HOME)/mac \
+-I/usr/include \
+-I/usr/include/$(PYTHON)
+
+CXXFLAGS = -Wall -Wextra -Weffc++ -Wshadow -std=$(CPP_VERSION) -fPIC $(OPTIMIZE) $(SANITIZE)
+
+LDFLAGS = \
+-L/usr/lib/x86_64-linux-gnu
+
+LDLIBS = \
+-ldl
+
+ifndef NOPYTHON
+LDLIBS += -l$(PYTHON)
+endif

mac/env/makefile.env.pop.DISABLED

@@ -0,0 +1,33 @@
+KLAMMERTEXT_HOME = /home/ack/projects/klammertext/K
+
+include $(KLAMMERTEXT_HOME)/mac/env/optimize.env
+
+CPP_VERSION = c++20
+
+CXX = /usr/bin/g++
+
+# Hack for now; to be generalized:
+ifneq ("$(wildcard /usr/include/python3.14)","")
+    PYTHON = python3.14
+else ifneq ("$(wildcard /usr/include/python3.13)","")
+    PYTHON = python3.13
+else
+    PYTHON = python3.12
+endif
+
+CPPFLAGS = \
+-I$(KLAMMERTEXT_HOME)/mac \
+-I/usr/include \
+-I/usr/include/$(PYTHON)
+
+CXXFLAGS = -Wall -Wextra -Weffc++ -Wshadow -std=$(CPP_VERSION) -fPIC $(OPTIMIZE) $(SANITIZE)
+
+LDFLAGS = \
+-L/usr/lib/x86_64-linux-gnu
+
+LDLIBS = \
+-ldl
+
+ifndef NOPYTHON
+LDLIBS += -l$(PYTHON)
+endif

mac/env/makefile.env.ubuntu.DISABLED

@@ -0,0 +1,33 @@
+KLAMMERTEXT_HOME = /home/ack/projects/klammertext/K
+
+include $(KLAMMERTEXT_HOME)/mac/env/optimize.env
+
+CPP_VERSION = c++20
+
+CXX = /usr/bin/g++
+
+# Hack for now; to be generalized:
+ifneq ("$(wildcard /usr/include/python3.14)","")
+    PYTHON = python3.14
+else ifneq ("$(wildcard /usr/include/python3.13)","")
+    PYTHON = python3.13
+else
+    PYTHON = python3.12
+endif
+
+CPPFLAGS = \
+-I$(KLAMMERTEXT_HOME)/mac \
+-I/usr/include \
+-I/usr/include/$(PYTHON)
+
+CXXFLAGS = -Wall -Wextra -Weffc++ -Wshadow -std=$(CPP_VERSION) -fPIC $(OPTIMIZE) $(SANITIZE)
+
+LDFLAGS = \
+-L/usr/lib/x86_64-linux-gnu
+
+LDLIBS = \
+-ldl
+
+ifndef NOPYTHON
+LDLIBS += -l$(PYTHON)
+endif

mac/env/optimize.env

@@ -0,0 +1,16 @@
+
+ifdef OPTIMIZE
+# Performance build: make OPTIMIZE=1
+# `override` so a command-line `make OPTIMIZE=1` is remapped to -O3 too;
+# without it, a command-line assignment wins over this `:=` and the literal
+# `1` leaks into CXXFLAGS (g++ then treats `1` as an input file).
+override OPTIMIZE := -O3
+SANITIZE :=
+else ifdef NOPYTHON
+OPTIMIZE := -O0 -g -DNOPYTHON
+SANITIZE :=
+else
+# Debug build (default): includes AddressSanitizer
+OPTIMIZE := -O0 -g
+SANITIZE := -fsanitize=address -fno-omit-frame-pointer
+endif

mac/env/runtime.env

@@ -0,0 +1,72 @@
+# mac/env/runtime.env — single self-configuring runtime environment for Klammertext.
+#
+# Source this from your shell profile (~/.bashrc etc.):
+#     source /path/to/klammertext/K/mac/env/runtime.env
+#
+# This is the runtime counterpart of the shared mac/env/makefile.env: one file
+# for every machine, with all machine-specific values AUTO-DETECTED. There is no
+# per-host runtime.env.<host> file and no HOST/OS/SITE selector.
+#   - KLAMMERTEXT_HOME     : derived from this file's own location (self-locating)
+#   - KLAMMERTEXT_TEXLIVE_BIN : newest ~/external/texlive/<year>/bin/<arch>
+# Machine-unique, non-committable additions (extra library paths such as NVIDIA
+# iray, local tools, etc.) go in an optional, gitignored mac/env/runtime.env.local
+# sourced at the end -- NOT in this shared file, so one machine's bundled
+# libraries can't shadow another's system libraries.
+
+# --- KLAMMERTEXT_HOME: self-locate (bash sets BASH_SOURCE; zsh sets $0) --------
+# This file lives at $KLAMMERTEXT_HOME/mac/env/runtime.env, so go up two levels.
+_kt_self="${BASH_SOURCE[0]:-$0}"
+export KLAMMERTEXT_HOME="$(cd "$(dirname "$_kt_self")/../.." && pwd)"
+unset _kt_self
+
+_kt_uname="$(uname -s)"
+
+# --- KLAMMERTEXT_TEXLIVE_BIN: newest installed TeX Live under ~/external -------
+# Klammertext's TeX Live installs are named by 4-digit year (2024, 2025, 2026).
+# Match only those so unrelated dirs (e.g. a "texlive-2022-min" system install)
+# are never selected; sort -V then picks the newest year.
+if [ "$_kt_uname" = "Darwin" ]; then
+    _kt_arch="universal-darwin"
+else
+    _kt_arch="$(uname -m)-linux"          # e.g. x86_64-linux
+fi
+# Use `find` with a -path pattern, NOT a shell glob: on macOS/zsh an unmatched
+# glob (no texlive installed) is a hard "no matches found" error, whereas find
+# just returns nothing. The -path pattern keeps the 4-digit-year restriction.
+_kt_tl="$(find "$HOME/external/texlive" -maxdepth 3 -type d \
+             -path "*/[0-9][0-9][0-9][0-9]/bin/$_kt_arch" 2>/dev/null \
+         | sort -V | tail -1)"
+[ -n "$_kt_tl" ] && export KLAMMERTEXT_TEXLIVE_BIN="$_kt_tl"
+unset _kt_tl _kt_arch
+
+# --- PATH (TeX Live appended only if one was found) ---------------------------
+export PATH="$KLAMMERTEXT_HOME/bin:$KLAMMERTEXT_HOME/tst${KLAMMERTEXT_TEXLIVE_BIN:+:$KLAMMERTEXT_TEXLIVE_BIN}:$PATH"
+
+# --- Per-platform: LSan suppressions + shared library search path -------------
+# The shared library path deliberately includes ONLY Klammertext's own .so dirs,
+# NOT third-party bundled-library dirs. In particular NVIDIA iray's platforms/
+# ships its own libfreetype.so and Qt6; if added here they shadow the system
+# libraries, and iray's freetype drags in unversioned libharfbuzz.so/libbz2.so
+# (absent without -dev packages), which breaks `import OpenImageIO` (SKS @image).
+# Machine-specific library paths (iray included) go in runtime.env.local.
+if [ "$_kt_uname" = "Darwin" ]; then
+    # macOS: no LD/DYLD_LIBRARY_PATH needed — libklammertext.so is found via the
+    # binaries' @loader_path rpath and document.so is dlopen'd by absolute path.
+    # LeakSanitizer is unsupported on macOS, so LSAN_OPTIONS does not apply.
+    :
+else
+    # LSan suppressions for unactionable libpython/OpenImageIO leaks (see
+    # lsan.supp). Real leaks in Klammertext code are still reported; no effect
+    # in performance builds (OPTIMIZE=1, which disables ASan).
+    export LSAN_OPTIONS="suppressions=$KLAMMERTEXT_HOME/mac/env/lsan.supp:print_suppressions=0"
+    export LD_LIBRARY_PATH="$KLAMMERTEXT_HOME/mac:$KLAMMERTEXT_HOME/sks/kutil:$KLAMMERTEXT_HOME/sks/document:$KLAMMERTEXT_HOME/doc/handbook${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+fi
+unset _kt_uname
+
+# --- Optional per-machine escape hatch (gitignored, absent by default) ---------
+# Use an if-block (not `[ -f ] && .`) so that when the local file is absent this
+# file's final exit status is 0 -- otherwise `source runtime.env` returns
+# non-zero, breaking `source runtime.env && ...` and `set -e` callers.
+if [ -f "$KLAMMERTEXT_HOME/mac/env/runtime.env.local" ]; then
+    . "$KLAMMERTEXT_HOME/mac/env/runtime.env.local"
+fi