Skip to content

README.md

Latest commit

 

History

History
168 lines (117 loc) · 5.45 KB

README.md

File metadata and controls

168 lines (117 loc) · 5.45 KB
Raw

Dev tooling

This directory contains scripts for running LLGo locally and inside reusable Linux dev containers.

Prerequisites

  • Docker installed and running
  • Docker Compose v2 (docker compose, not docker-compose)

1) Start a Linux container, then run dev/llgo.sh / dev/llgo_wasm.sh

Start an interactive shell (pick one):

./dev/docker.sh amd64
./dev/docker.sh arm64
./dev/docker.sh i386

Notes:

  • amd64 uses the pydeps image target (includes extra Python demo deps like numpy/torch).
  • arm64 and i386 use the smaller base target (no extra Python ML deps).

Inside the container, run tests/builds using the repo scripts:

./dev/llgo.sh test ./...
./dev/llgo.sh test ./test

# WASI/WASM (wasip1/wasm)
./dev/llgo_wasm.sh build ./...

Notes:

  • dev/docker.sh starts in the same repo subdirectory you launched it from.
  • dev/llgo.sh and dev/llgo_wasm.sh must be run from within LLGO_ROOT (the repo) and will error otherwise.

2) Start a Linux container, run one command, then exit

./dev/docker.sh amd64 bash -lc './dev/llgo.sh test ./test'

3) Run on the host (no container)

From anywhere inside the repo:

./dev/llgo.sh test ./test
./dev/llgo_wasm.sh build ./...

4) Run local CI (covers most checks)

./dev/local_ci.sh

This script creates a temporary workspace, runs formatting/build/tests, runs llgo test, and then runs demo checks. You can control demo parallelism via LLGO_DEMO_JOBS (defaults to up to 4 jobs).

5) dev/docker.sh (composition-friendly)

dev/docker.sh is a thin wrapper around docker compose:

./dev/docker.sh <arch> [command...]
  • <arch> must be amd64, arm64, or i386.
  • If [command...] is omitted, it starts an interactive bash.
  • If [command...] is provided, it runs that command and exits.
  • You must run it from within the repo (within LLGO_ROOT), and it will start in the matching repo subdirectory inside the container.

6) Refresh test goldens

LLGo currently has two different golden-test refresh flows:

  • gentests for directory-based golden files such as out.ll and expect.txt
  • litgen for the curated set of 40 source-embedded, autogenerated // LITTEST FileCheck snapshots

gentests

Run:

go run ./chore/gentests

Behavior:

  • Refreshes out.ll for the built-in test suites under cl/_testlibc, cl/_testlibgo, cl/_testrt, cl/_testgo, cl/_testpy, and cl/_testdata.
  • Refreshes expect.txt for the same directories using the existing runtime execution flow.
  • Preserves the existing skip convention where out.ll or expect.txt containing only ; means "do not refresh".
  • New behavior: if a test case directory contains a non-test Go source file whose first line is exactly // LITTEST, gentests skips llgen for that directory and does not regenerate out.ll there.

Use gentests when the test still stores LLVM IR in out.ll.

litgen

Autogenerated checks stay in the Go source file. A test opts in with an autogenerated note immediately after // LITTEST; the note also records the arguments required to reproduce the checks:

// LITTEST
// NOTE: Assertions have been autogenerated by chore/litgen UTC_ARGS: --function=run --check-globals=smart

Create or replace an autogenerated region explicitly:

go run ./chore/litgen --function=run --check-globals=smart path/to/in.go

Refresh existing autogenerated tests recursively, using the arguments recorded in each source file:

go run ./chore/litgen -u cl

Check that committed autogenerated checks are current without modifying files:

go run ./chore/litgen -u --check cl

Behavior:

  • Accepts one or more paths.
  • If the path is a .go file, it refreshes only that file. The file must start with // LITTEST.
  • If the path is a directory, it walks that directory recursively and processes marked source files in a stable order.
  • -u/--update-only updates only tests that already carry the autogenerated note. Handwritten checks are never silently replaced.
  • --check reports stale autogenerated checks and does not write files.
  • --function is repeatable and selects functions by regular expression. Use --all-functions only when the entire generated module is genuinely the test contract.
  • --check-globals=none|smart|all controls global checks. smart keeps globals referenced by selected functions.
  • Generated checks abstract numeric LLVM SSA values, block suffixes, numeric globals, and generated cgo symbol hashes to reduce irrelevant churn.
  • Does not update expect.txt and does not write out.ll.

Use litgen only when a test intentionally checks a broad IR shape. Prefer short, handwritten FileCheck assertions for a single lowering or ABI property. Runtime output does not replace focused IR checks; it only removes the need for a second full-output snapshot.

Use 100 FileCheck directive lines as an audit threshold rather than a size cap. For a larger handwritten fixture, every group should correspond to an explicit semantic contract. Convert long contiguous IR-shape checks to an opted-in litgen snapshot instead.

Marker convention

Source-embedded IR checks are enabled by putting this marker on the first line of the source file:

// LITTEST

The generated directives are consumed by the existing littest/FileCheck path in the compiler tests.

Example: