Nuitka build (LSP + CLI)

Nuitka build (LSP + CLI)

Abstract

Both the Language Server and the Click CLI can run as pure Python or as Nuitka-compiled onefile binaries for offline distribution. Compilation freezes the entry module and followed imports into artifacts under dist/.

Primary tools: scripts/build/compile.py (local) and scripts/build/ci_build.py (CI/Cloud Build). Both accept --target lsp|cli|all.

Conceptual model

Rendering…

Interface surface

Commands

# Prerequisites
pip install nuitka cryptography

# Full LSP onefile build (default path via Make)
make build
# ≡ python scripts/build/compile.py --target lsp --jobs=4

# CLI onefile binary
make build-cli
# ≡ python scripts/build/compile.py --target cli --jobs=4

# Fast import check only (~30s) — both targets
make build-check
# ≡ python scripts/build/compile.py --target all --check

# Explicit modes
python scripts/build/compile.py --target cli --standalone
python scripts/build/compile.py --target all --jobs 8
python scripts/build/ci_build.py --target cli --jobs=4 --skip-metadata --skip-vsix

Build modes (approx. wall time)

Expected layout

dist/
├── lsp/
│   └── pynescript-lsp          # onefile (path may vary by script)
├── vsix/
│   └── pynescript-lsp.vsix     # optional bundle
└── pynescript-lsp              # ci_build final move target (script-dependent)

Also see scripts/build/README.md.

Internals

Key Nuitka flags (compile.py)

• --static-libpython=no — default; critical for many Linux/Anaconda envs
• --python-flag=no_site,no_docstrings
• --include-data-dir=…/providers=pynescript/langserver/providers
• --lto=auto, --jobs=N
• --onefile or --standalone
• --follow-imports on local compile path

Entry module

Compilation targets src/pynescript/langserver (package entry), product name pynescript-lsp.

Metadata stage

Before compile, scripts may:

1. Run scripts/generate_builtin_metadata.py if plaintext metadata missing
2. Fernet-encrypt to builtin_metadata.json.enc
3. Write truncated SHA256 sidecar
4. Write scripts/build/.metadata.key (gitignored) or consume CRYPTO_KEY env in CI

Anaconda

If static libpython is unavailable:

conda install libpython-static
# or rely on --static-libpython=no (already the default in compile.py)

Invariants & edge cases

1. C compiler required (gcc/clang/MSVC). Containers need build-essential or equivalent if compiling inside Docker.
2. Python 3.10+; release workflow pins 3.11 with nuitka>=2.5.1,<2.8. Local/Cloud Build sketches often use 3.12.
3. Providers data dir must ship — completion/hover collapse without metadata.
4. Onefile startup cost includes extract-to-temp; standalone is snappier for local soak tests.
5. Do not commit scripts/build/.metadata.key.

Worked examples

Local onefile with explicit jobs

python scripts/build/compile.py --jobs "$(nproc)"
find dist -name 'pynescript-lsp*' -type f

CI-shaped build

export CRYPTO_KEY="$METADATA_KEY_STABLE"
python scripts/build/ci_build.py --jobs=4

Verify without compile

python scripts/build/compile.py --check

Failure modes

See also

• Metadata crypto
• Release
• LSP builtin metadata