Skip to content

install.md

Latest commit

 

History

History
214 lines (155 loc) · 5.01 KB

install.md

File metadata and controls

214 lines (155 loc) · 5.01 KB

CCT Installation Guide

Scope

This guide defines the supported installation and validation paths for the current CCT toolchain, including the historical host-compiler installation flow, the promoted self-hosted wrapper model, and the validated release-facing baseline through FASE 40.

Prerequisites

  • POSIX shell environment
  • C compiler (gcc or clang)
  • make

Platform note:

  • Linux and macOS are the supported validation targets for the current toolchain.
  • The current repository baseline is working and tested on Linux.
  • Native Windows usage is not fully addressed and should be treated as experimental.
  • Known Windows issues remain in shell/process behavior, path semantics, packaging, and some runtime-backed workflows.
  • If you need a stable installation path, use Linux, macOS, or WSL2 rather than native Windows.

Current release note:

  • validated baseline: FASE 40
  • immediate publication target: v0.40

1. Build

make

Expected result: ./cct binary available in project root.

2. Run Full Regression (Recommended)

make test

Expected result: all tests pass.

3. Build Relocatable Distribution Bundle

make dist

Expected layout:

dist/cct/
├── bin/
│   ├── cct
│   └── cct.bin
├── lib/
│   └── cct/
├── docs/
└── examples/

dist/cct/bin/cct is a wrapper that sets CCT_STDLIB_DIR to the bundle-local stdlib path by default.

4. Smoke Test the Bundle

./dist/cct/bin/cct --version
./dist/cct/bin/cct --check tests/integration/stdlib_resolution_basic_11a.cct
./dist/cct/bin/cct tests/integration/showcase_string_11g.cct && ./tests/integration/showcase_string_11g

5. System Installation (Optional)

Install under default prefix (/usr/local):

make install

Install under custom prefix:

make install PREFIX="$HOME/.local"

This installs:

  • wrapper: <prefix>/bin/cct
  • binary: <prefix>/bin/cct.bin
  • stdlib: <prefix>/lib/cct/

6. Uninstall

make uninstall

Or with custom prefix:

make uninstall PREFIX="$HOME/.local"

7. Environment Override

If needed, stdlib resolution can be overridden explicitly:

export CCT_STDLIB_DIR=/path/to/lib/cct
./cct --check file.cct

Resolver order:

  1. CCT_STDLIB_DIR environment variable (if set)
  2. build-time canonical stdlib path

8. Troubleshooting

  • ADVOCARE target not found in Bibliotheca Canonica:
    • check CCT_STDLIB_DIR
    • verify <stdlib>/cct/<module>.cct exists
  • Input file must have .cct extension:
    • ensure positional file ends with .cct
  • packaging smoke fails:
    • rebuild with make then make dist
  • Windows-specific failures:
    • do not assume parity with Linux/macOS
    • prefer WSL2 first
    • if native Windows is required, expect unsupported gaps and partial failures in some workflows

9. Bootstrap and Self-Host Validation Targets

Additional repository-level validation targets now exist beyond the historical baseline:

make test-legacy-full
make test-legacy-rebased
make test-all-0-30
make test-all-0-31
make test-bootstrap
make test-bootstrap-selfhost
make test-phase30-final
make test-phase31-final

For publication or release validation, use:

make test-all-0-31

10. Multi-Stage Self-Host Build Targets

The repository also exposes explicit self-host stages:

make bootstrap-stage0
make bootstrap-stage1
make bootstrap-stage2
make bootstrap-stage-identity

These targets remain part of the supported operational toolchain after bootstrap closure and compiler promotion.

11. FASE 31 First-Run Verification

After a fresh build, verify the wrapper state explicitly:

./cct --which-compiler
./cct-host --which-compiler
./cct-selfhost --which-compiler

Current repository baseline:

  • ./cct is the default user-facing compiler entrypoint
  • ./cct-host is the explicit host fallback
  • ./cct-selfhost is the explicit self-hosted entrypoint
  • the repository baseline is validated through FASE 40
  • Linux is part of the tested baseline

If you want to force the default wrapper mode explicitly after install:

make bootstrap-promote
# or
make bootstrap-demote

12. Bundle and Installed Wrapper Roles

In bundled or installed layouts, the user should still call cct first. FASE 31 changes the compiler mode behind that wrapper, not the top-level command name users are expected to memorize.

Wrapper roles in installed layouts:

  • cct: default operational wrapper
  • cct-host: explicit host path where installed or packaged
  • cct-selfhost: explicit self-host path where installed or packaged

13. Recommended Validation After Installation

Daily validation after installation:

./cct --which-compiler
make bootstrap-stage-identity
make test

Release-oriented validation after installation:

make test-host-legacy
make test-all-0-31
make test-phase30-final
make test-phase31-final

For the current release baseline, interpret this sequence as the minimum public-release validation path before publishing v0.40.