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>
This commit is contained in:
171
doc/install/macos_source_install.md
Normal file
171
doc/install/macos_source_install.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# Klammertext source installation on macOS (Apple Silicon)
|
||||
|
||||
Companion to `linux_source_install.md`. Verified on an Apple-Silicon Mac
|
||||
(arm64, macOS 26 "Tahoe"). Klammertext's core (engine, SKS, HTML/LaTeX,
|
||||
`@image`) builds and runs natively with Apple Clang; the cross-platform build
|
||||
environment (`mac/env/makefile.env`) auto-detects the OS via `uname`.
|
||||
|
||||
## 1. Toolchain prerequisites
|
||||
|
||||
```sh
|
||||
xcode-select --install # Command Line Tools (clang, headers) — if not already present
|
||||
```
|
||||
|
||||
Then install Python with a linkable `libpython` and `python3-config`, using
|
||||
whichever package manager you have — **Homebrew** or **MacPorts**. Both work;
|
||||
only the install prefix differs, and the build auto-detects it.
|
||||
|
||||
```sh
|
||||
# Homebrew (https://brew.sh):
|
||||
brew install python
|
||||
brew install gcc # OPTIONAL: a second compiler for a standards check
|
||||
|
||||
# MacPorts (https://www.macports.org) — provisional, pending testing on a
|
||||
# MacPorts system:
|
||||
sudo port install python312
|
||||
sudo port select --set python3 python312 # so python3 / python3-config resolve
|
||||
sudo port install gcc14 # OPTIONAL: a second compiler for a standards check
|
||||
```
|
||||
|
||||
Notes:
|
||||
- The build embeds Python, which needs `python3-config` and a linkable
|
||||
`libpython`. Apple's `/usr/bin/python3` does **not** ship a usable
|
||||
`python3-config` and Apple discourages linking it — so a package-manager
|
||||
Python (Homebrew or MacPorts) is required. It coexists with Apple's;
|
||||
`python3-config` resolves to it when the manager's `bin` is early on `PATH`
|
||||
(`/opt/homebrew/bin` for Homebrew, `/opt/local/bin` for MacPorts — both set up
|
||||
by their installers). For MacPorts, `port select --set python3 python312`
|
||||
makes `python3` and `python3-config` resolve.
|
||||
- `makefile.env` gets all Python include/link flags from `python3-config` and
|
||||
auto-detects the package-manager prefix (`/opt/homebrew` or `/opt/local`, via
|
||||
`MACOS_PREFIX`), so either manager works without edits. Override with
|
||||
`make MACOS_PREFIX=...` if yours is installed elsewhere.
|
||||
|
||||
## 2. Image support (the `@image` klammer): OpenImageIO
|
||||
|
||||
```sh
|
||||
# Homebrew:
|
||||
/opt/homebrew/bin/pip3.<N> install --break-system-packages OpenImageIO
|
||||
# e.g. pip3.14 — match your Python's version
|
||||
|
||||
# MacPorts (matches the python312 installed above):
|
||||
sudo port install py312-openimageio
|
||||
```
|
||||
|
||||
This provides the OpenImageIO Python bindings the embedded interpreter uses.
|
||||
With pip, the self-contained PyPI wheel goes into that Python's site-packages;
|
||||
`--break-system-packages` is needed because the Python is PEP-668 "externally
|
||||
managed". (Homebrew alternative: `brew install openimageio`, heavier — it pulls
|
||||
ffmpeg/openexr/etc.)
|
||||
|
||||
## 3. Clone and configure the environment
|
||||
|
||||
```sh
|
||||
git clone https://git.andykopra.com/ack/klammertext.git ~/projects/klammertext
|
||||
# Set up the runtime environment (KLAMMERTEXT_HOME, PATH); add to ~/.zprofile:
|
||||
echo 'source "$HOME/projects/klammertext/mac/env/runtime.env"' >> ~/.zprofile
|
||||
```
|
||||
|
||||
The single self-configuring `runtime.env` self-locates `KLAMMERTEXT_HOME` from
|
||||
its own path. On macOS it sets no `LD_LIBRARY_PATH`/`DYLD_LIBRARY_PATH`
|
||||
(`libklammertext.so` is found via the binaries' `@loader_path` rpath, and
|
||||
`document.so` is dlopen'd by absolute path under `$KLAMMERTEXT_HOME`) and no
|
||||
`LSAN_OPTIONS` (LeakSanitizer is unsupported on macOS).
|
||||
|
||||
## 4. Build (Apple Clang)
|
||||
|
||||
Clang is the compiler you run on macOS, and it is the **default** here
|
||||
(`makefile.env` selects clang on Darwin), so no `COMPILER=` flag is needed.
|
||||
A single `make -C com` builds its prerequisites in `mac/` and `sks/` first,
|
||||
then the commands:
|
||||
|
||||
```sh
|
||||
cd "$KLAMMERTEXT_HOME"
|
||||
make -C com -j OPTIMIZE=1 # libklammertext.so + sks/*.so + bin/{ktext,kdesc,kdiag}
|
||||
ktext -s '@eval 1 + 1 @' -d # smoke test — prints 2
|
||||
```
|
||||
|
||||
For a document smoke test, create a small file and render it to HTML:
|
||||
|
||||
```sh
|
||||
cat > hello.kt <<'EOF'
|
||||
@document
|
||||
:structure article
|
||||
:title Hello
|
||||
:text
|
||||
@s1 Hello, Klammertext @
|
||||
|
||||
This document was built from source.
|
||||
@
|
||||
EOF
|
||||
ktext hello.kt -t html # writes hello/index.html
|
||||
```
|
||||
|
||||
(A PDF render needs TeX Live — see section 5.)
|
||||
|
||||
## 5. PDF target: TeX Live
|
||||
|
||||
Build a complete Klammertext TeX Live tree with the bundled script, into
|
||||
`~/external/texlive/<year>` — the location `runtime.env` auto-detects
|
||||
(`bin/universal-darwin`). macOS already has `curl`, `perl`, and `tar`, and
|
||||
`install-tl` self-provides `xz`, so nothing extra is needed:
|
||||
|
||||
```sh
|
||||
bash "$KLAMMERTEXT_HOME/doc/install/texlive_additional_packages.sh" ~/external/texlive/2026
|
||||
```
|
||||
|
||||
This installs `scheme-small` plus the SKS's additional packages and rebuilds all
|
||||
formats, fetching the `universal-darwin` binaries, and writes a
|
||||
`KLAMMERTEXT_BUILD_INFO.txt` provenance file into the tree. **This is the same
|
||||
command used on Linux**, so the TeX Live layout is identical across your
|
||||
machines. `runtime.env` then finds the tree automatically — open a new shell (or
|
||||
re-source it) and `xelatex` is on `PATH`; no manual `KLAMMERTEXT_TEXLIVE_BIN` is
|
||||
needed.
|
||||
|
||||
If you already run BasicTeX/MacTeX and prefer to reuse it, point `runtime.env`
|
||||
at its bin directory from the gitignored escape hatch instead (and install the
|
||||
SKS's extra packages into it yourself — the list is in the script). Set the
|
||||
variable **and** prepend it to `PATH`, since `runtime.env.local` is sourced
|
||||
after the main `PATH` is built:
|
||||
|
||||
```sh
|
||||
cat >> "$KLAMMERTEXT_HOME/mac/env/runtime.env.local" <<'EOF'
|
||||
export KLAMMERTEXT_TEXLIVE_BIN=/usr/local/texlive/2025basic/bin/universal-darwin
|
||||
export PATH="$KLAMMERTEXT_TEXLIVE_BIN:$PATH"
|
||||
EOF
|
||||
```
|
||||
|
||||
Verify and test (reusing `hello.kt` from section 4):
|
||||
|
||||
```sh
|
||||
xelatex --version
|
||||
ktext hello.kt -t pdf # writes hello.pdf
|
||||
```
|
||||
|
||||
## 6. Updating
|
||||
|
||||
To update an existing source installation to the latest version:
|
||||
|
||||
```sh
|
||||
cd "$KLAMMERTEXT_HOME"
|
||||
git pull
|
||||
make -C com -j OPTIMIZE=1 # rebuild library, SKS components, and commands
|
||||
```
|
||||
|
||||
Rebuild the TeX Live tree only if the SKS's package requirements changed (rare);
|
||||
re-run the script from section 5.
|
||||
|
||||
## Compiler notes (macOS)
|
||||
|
||||
- **Clang is the compiler you run, and the default here.** Apple Clang builds
|
||||
run correctly; `makefile.env` selects clang on Darwin automatically.
|
||||
- **Do not run gcc-built binaries on macOS.** GCC (Homebrew `g++-NN` or MacPorts
|
||||
`g++-mp-NN`) is useful only as an optional compile-time standards check
|
||||
(`make -C com COMPILER=gcc`); the resulting binaries **crash at runtime** on
|
||||
macOS because of a gcc/macOS codegen issue (for example `std::source_location`
|
||||
returning a bad pointer, so `Machine::Machine()` walks into `strlen` and
|
||||
SIGSEGVs). Always run the clang-built binary. (gcc-built binaries run fine on
|
||||
Linux.)
|
||||
- **Switching compilers requires a full clean** — `g++` and `clang++` objects
|
||||
must not be mixed (ABI). `make -C com redo` does a full clean rebuild across
|
||||
`mac`, `sks`, and `com`; a partial `make -C mac clean` does not.
|
||||
Reference in New Issue
Block a user