From 1f724200fe3493e4571b034ed81477d2a5ce1aad Mon Sep 17 00:00:00 2001 From: _ov4 Date: Wed, 21 Oct 2026 12:45:37 +0000 Subject: docs(agents): dedupe library units and move macOS CI caching into NIGHTLY Co-Authored-By: Claude Sonnet 5.5 --- AGENTS/ARCH.md | 19 +++++++++++-------- AGENTS/ARCH/LIBRARY_UNITS.md | 5 ----- AGENTS/ARCH/LINKING.md | 16 +++------------- AGENTS/ARCH/NIGHTLY.md | 22 +++++++++++++++++++--- AGENTS/SUBSYSTEMS/STDLIB.md | 8 +++++--- 5 files changed, 38 insertions(+), 32 deletions(-) delete mode 100644 AGENTS/ARCH/LIBRARY_UNITS.md (limited to 'AGENTS') diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md index d77dd8f..b9805c8 100644 --- a/AGENTS/ARCH.md +++ b/AGENTS/ARCH.md @@ -10,18 +10,21 @@ This file is an index; the detail lives in `AGENTS/ARCH/`. | [DEPENDENCIES.md](ARCH/DEPENDENCIES.md) | Local/system dependency lookup, compiler selection, MSYS2 notes, LLVM 23 pin | | [DRIVER.md](ARCH/DRIVER.md) | `tools/driver/main.cc`: options, multi-file inputs, entry points, output and exit-code rules, PATH/NONE modes | | [EMBEDDED_RUNNER.md](ARCH/EMBEDDED_RUNNER.md) | EMBEDDED LLJIT/JITLink runner, MinGW COFF/SEH support, archive loading | -| [LINKING.md](ARCH/LINKING.md) | Static LLVM/LLD linking, `NativeCompiler`, macOS static LLD helper and its CI caching | +| [LINKING.md](ARCH/LINKING.md) | Static LLVM/LLD linking, `NativeCompiler`, macOS static LLD helper | | [INSTALL.md](ARCH/INSTALL.md) | `install.sh`/`install.ps1`, manual generation, release packaging | -| [NIGHTLY.md](ARCH/NIGHTLY.md) | `nightly-build.yml` jobs, Bundle packages, publish rules, package naming | +| [NIGHTLY.md](ARCH/NIGHTLY.md) | `nightly-build.yml` jobs, Bundle packages, macOS LLD/Rust caching, publish rules, package naming | | [LAYOUT.md](ARCH/LAYOUT.md) | Source file map (lexer, parser, codegen, CMake, installers), AST conventions | -| [LIBRARY_UNITS.md](ARCH/LIBRARY_UNITS.md) | `#LIB` library units and the embedded standard library | + +`#LIB` library units are described in [CONVENTIONS/EXCEPTIONS_AND_UNITS.md](CONVENTIONS/EXCEPTIONS_AND_UNITS.md); +the embedded standard library in [SUBSYSTEMS/STDLIB.md](SUBSYSTEMS/STDLIB.md). ## Detail docs | File | Read it when | |---|---| -| `AGENTS/CONVENTIONS.md` | Before writing any code — cross-module invariants whose violation breaks code you didn't touch | -| `AGENTS/EXTENDING.md` | Adding a statement, builtin, operator, type, runtime check, or libc dependency — exact recipes | -| `AGENTS/SUBSYSTEMS.md` | Working on arrays, functions/procedures, or runtime checks | -| `AGENTS/PITFALLS.md` | Verified sharp edges (they *will* bite) and the list of unimplemented 9618 features | -| `AGENTS/MAN.md` | Editing man Markdown, language manual layout, generation and installation | +| [CONVENTIONS.md](CONVENTIONS.md) | Before writing any code — cross-module invariants whose violation breaks code you didn't touch | +| [EXTENDING.md](EXTENDING.md) | Adding a statement, builtin, operator, type, runtime check, or libc dependency — exact recipes | +| [SUBSYSTEMS.md](SUBSYSTEMS.md) | Working on a CodeGen helper subsystem: arrays, functions/operators, EXTERN, user types, classes, runtime checks/exceptions, files, memory, standard library, templates | +| [PITFALLS.md](PITFALLS.md) | Verified sharp edges (they *will* bite) and the list of unimplemented 9618 features | +| [MAN.md](MAN.md) | Editing man Markdown, language manual layout, generation and installation | +| [TESTING.md](TESTING.md) | Writing or running compiler tests in `tests/` (case layout, manifests, Perl runner, generators) | diff --git a/AGENTS/ARCH/LIBRARY_UNITS.md b/AGENTS/ARCH/LIBRARY_UNITS.md deleted file mode 100644 index 4a0c6d2..0000000 --- a/AGENTS/ARCH/LIBRARY_UNITS.md +++ /dev/null @@ -1,5 +0,0 @@ -# Library units and standard library - -**Library units.** Line-leading `#LIB` marks SourceUnit::IsLibrary. RuntimeCheck uses the externally visible i32 `__cps_user_line`; FunctionGen’s shared call hook updates it only on non-library to library calls. Runtime helper line arguments use RuntimeCheck::lineValue too. Compiler diagnostics retain the owning file location. - -**Standard library.** Build-time embedding includes pseudocode-lib/std.cps, its imported string.cps and the matching string.o. StandardLibrary extracts these for parsing and linking; user units import std.cps by default. -no-std disables automatic loading/linking. STRING is an ordinary class; StringValueGen bridges literals, C_STRING conversions and I/O. String functions, concatenation and comparisons use normal function/operator resolution. Installed/released cpsc needs no separate library directory; manually linking saved IR still requires the matching string.o and C++ runtime. diff --git a/AGENTS/ARCH/LINKING.md b/AGENTS/ARCH/LINKING.md index f240ba4..d0efe81 100644 --- a/AGENTS/ARCH/LINKING.md +++ b/AGENTS/ARCH/LINKING.md @@ -6,7 +6,7 @@ builds link the C++ runtime statically; MinGW uses `-static`. The tested Debian LLVM 23 executable has only libc, libm and the system loader as dynamic dependencies. macOS links with `-dead_strip_dylibs` to omit unused dylibs inherited from LLVM's support interface, including Homebrew's Z3. Keep the nightly package's -non-system dependency check; required dylibs are not removed by this option. +non-system dependency check ([NIGHTLY.md](NIGHTLY.md)); required dylibs are not removed by this option. On MinGW, `LLVMWindowsManifest` explicitly uses static libxml2, iconv and zlib plus the system bcrypt library. XML definitions are loaded with `--whole-archive` to satisfy dllimport references in the prebuilt LLVM archive. `-static` alone @@ -28,19 +28,9 @@ with the selected LLVM prefix and cpsc build directory before configuring on mac It builds matching LLD sources, installs static archives and tools into the build prefix, and leaves LLVM itself installed. Source and build caches are versioned; the resulting local `lib/cmake/lld` takes precedence over shared system packages. -The macOS nightly job caches the helper's versioned source/build directory and still -runs the helper to configure, build incrementally and install after restoring it. -Exact cache keys include the runner image, SDK identity, LLVM package version and -compiler/library content, workspace path and helper script hash. No fallback key -restores a build from a different toolchain. Homebrew updates and the LLVM archive -symbol check still run before cache lookup. Windows and macOS desktop jobs cache -compiled Rust dependencies after selecting the toolchain, including on failure; -project crates rebuild with the current compiler payload. Rust release optimization -and archive compression settings are unchanged. The helper's build-time linker can use the installed LLVM dylib; cpsc still links the LLD archives and static LLVM components. Both macOS configurations explicitly select the SDK with `CMAKE_OSX_SYSROOT` before compiler detection, so imported SDK include paths do not precede libc++. -The macOS job updates Homebrew and upgrades LLVM 23 before building LLD. It checks -that clangDriver defines `AMDGPU::setArchNameInTriple` to reject older bottles -corrupted by Homebrew's duplicate-member LTO conversion (homebrew-core #301252). +The nightly macOS job's helper caching and LLVM bottle checks are described in +[NIGHTLY.md](NIGHTLY.md#macos-lld-helper-and-desktop-caches). diff --git a/AGENTS/ARCH/NIGHTLY.md b/AGENTS/ARCH/NIGHTLY.md index 4ea645d..8afb53e 100644 --- a/AGENTS/ARCH/NIGHTLY.md +++ b/AGENTS/ARCH/NIGHTLY.md @@ -18,14 +18,15 @@ Native runner tests check prefilled input, EOF, diagnostics, output before exit, stopping and restart. Portable packages are checked for the desktop executable, compiler and notices, then run with toolchain directories removed from PATH. The publish job requires both Bundle packages alongside the original four packages. -See `bundle/AGENTS/DEVELOPMENT.md` for the shared editor and build details. +See [`bundle/AGENTS/DEVELOPMENT.md`](../../bundle/AGENTS/DEVELOPMENT.md) for the shared editor and build details. The Linux compiler and plugin jobs use Ubuntu 24.04 x86_64; the macOS compiler job uses a macOS 15 arm64 runner, and Windows uses Windows Server 2025 x86_64. All four check out the push SHA and run independently. All three compiler jobs use LLVM/Clang/LLD 23, Perl (build-time), Release and EMBEDDED settings, Pandoc, and the existing `release` target. Linux obtains its toolchain from apt.llvm.org; macOS -uses Homebrew's LLVM 23 and builds matching static LLD with the helper above. Windows uses `msys2/setup-msys2@v2` with MINGW64, +uses Homebrew's LLVM 23 and builds matching static LLD with the helper described in +[LINKING.md](LINKING.md). Windows uses `msys2/setup-msys2@v2` with MINGW64, MSYS2 LLVM/Clang packages, explicit native compiler and LLVM paths, and the MinGW Makefiles generator. It downloads the official Pandoc 3.12.1 Windows x86_64 ZIP into `build/deps/packages/` for CMake to extract. Each compiler job @@ -39,7 +40,7 @@ as a separate Actions artifact for one day, failing if the package is missing. Compiler jobs enable BUILD_TESTING and run all CTest cases with the push SHA as seed before their package smoke checks and uploads. Failed tests retain inputs and logs as -Actions artifacts for 14 days; test summaries appear even on failure. See TESTING.md. +Actions artifacts for 14 days; test summaries appear even on failure. See [TESTING.md](../TESTING.md). The publish job downloads only the current run's `nightly-*` artifacts and checks that exactly one nonempty package exists for each build before any release API calls. It then checks main's current SHA to avoid modifying nightly for a @@ -50,3 +51,18 @@ The VSIX internal version is `YYYYMMDD.HHMMSS.0+commit`, with leading zeros removed from the numeric time component. Before committing workflow changes, run actionlint, simulate release API calls, and smoke-test the packages locally; do not modify the real release for local verification. + +## macOS LLD helper and desktop caches + +The macOS job updates Homebrew and upgrades LLVM 23 before building LLD. It checks +that clangDriver defines `AMDGPU::setArchNameInTriple` to reject older bottles +corrupted by Homebrew's duplicate-member LTO conversion (homebrew-core #301252). +The macOS nightly job caches the helper's versioned source/build directory and still +runs the helper to configure, build incrementally and install after restoring it. +Exact cache keys include the runner image, SDK identity, LLVM package version and +compiler/library content, workspace path and helper script hash. No fallback key +restores a build from a different toolchain. Homebrew updates and the LLVM archive +symbol check still run before cache lookup. Windows and macOS desktop jobs cache +compiled Rust dependencies after selecting the toolchain, including on failure; +project crates rebuild with the current compiler payload. Rust release optimization +and archive compression settings are unchanged. diff --git a/AGENTS/SUBSYSTEMS/STDLIB.md b/AGENTS/SUBSYSTEMS/STDLIB.md index 5518f3e..a4e260a 100644 --- a/AGENTS/SUBSYSTEMS/STDLIB.md +++ b/AGENTS/SUBSYSTEMS/STDLIB.md @@ -1,6 +1,7 @@ # Standard library -Part of the [subsystem notes](../SUBSYSTEMS.md). +Part of the [subsystem notes](../SUBSYSTEMS.md). `#LIB` library units and default +import rules: [CONVENTIONS/EXCEPTIONS_AND_UNITS.md](../CONVENTIONS/EXCEPTIONS_AND_UNITS.md). **Standard library** (`pseudocode-lib/`) @@ -11,8 +12,9 @@ Part of the [subsystem notes](../SUBSYSTEMS.md). in cpsc. - StandardLibrary extracts the resources through linking/execution; the driver implicitly imports std.cps unless -no-std is set. std.cps imports string.cps. -- Source/object resources are embedded in installed/released cpsc; saved IR requires the - object when manually linked. +- Source/object resources are embedded in installed/released cpsc, which needs no + separate library directory; manually linking saved IR still requires the matching + string.o and the C++ runtime. ## STRING and I/O bridging -- cgit v1.3.1-4-g156e