docs: add libVCT public specification set (000-015)
This commit is contained in:
@@ -0,0 +1,159 @@
|
||||
# 015 — Open Questions
|
||||
|
||||
- **Status:** Draft
|
||||
- **Normative language:** `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, and `MAY` are to be
|
||||
interpreted as described in RFC 2119.
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This file records the capabilities that v1 deliberately defers. Each item is stated as an open
|
||||
question with the reason for deferral and the work needed to resolve it. The purpose is to
|
||||
separate "not yet designed" from "required and specified", so that readers and implementors do
|
||||
not mistake a gap for a guarantee.
|
||||
|
||||
## 2. Scope and conformance status
|
||||
|
||||
Everything in this file is **out of scope for v1**. These items are **not** conformance
|
||||
requirements, and they add no behavior an implementation must provide.
|
||||
|
||||
1. An implementation **MUST NOT** be judged non-conforming for omitting any item in this file.
|
||||
2. An implementation **MAY** implement any item here. Doing so **MUST NOT** change the behavior
|
||||
required by the stage files for the features that are in scope.
|
||||
3. The absence statements already in [000 — Overview](000-overview.md), such as the absence of
|
||||
LLVM debug metadata on the LLVM path, describe the v1 scope. They **MUST NOT** be read as
|
||||
forbidding a future extension.
|
||||
4. When an item is resolved, it **MUST** be promoted into a stage file with its own normative
|
||||
requirements; it **MUST NOT** remain only here.
|
||||
|
||||
## 3. Summary
|
||||
|
||||
| ID | Open question | v1 status | Would touch |
|
||||
|---|---|---|---|
|
||||
| OQ1 | LLVM debug info (`!llvm.dbg`) | Deferred | [009 — LLVM Backend](009-llvm-backend.md) |
|
||||
| OQ2 | Windows and MSVC support | Out of scope | [008 — C Backend](008-c-backend.md), [010 — Driver & CLI](010-driver-cli.md) |
|
||||
| OQ3 | LLVM bitcode emission | Deferred | [009 — LLVM Backend](009-llvm-backend.md) |
|
||||
| OQ4 | Incremental and cached compilation | Out of scope | [010 — Driver & CLI](010-driver-cli.md), [013 — Build & Packaging](013-build-packaging.md) |
|
||||
| OQ5 | Cross-compilation beyond passthrough | Future work | [009 — LLVM Backend](009-llvm-backend.md), [010 — Driver & CLI](010-driver-cli.md) |
|
||||
|
||||
## 4. OQ1: LLVM debug information
|
||||
|
||||
**Question.** Should the LLVM backend emit `!llvm.dbg` metadata so that debuggers can map machine
|
||||
state back to frontend source?
|
||||
|
||||
**v1 behavior.** No. The LLVM backend emits no debug metadata. Debug mapping exists only on the C
|
||||
path, through `#line` directives (see [008 — C Backend](008-c-backend.md)).
|
||||
|
||||
**Why deferred.** The C path already provides source mapping for the v1 target, and LLVM debug
|
||||
metadata is a large, version-sensitive surface. Emitting it correctly needs `DICompileUnit`,
|
||||
`DIFile`, `DISubprogram`, `DILocation`, and scope chain construction, plus a verifier pass that
|
||||
checks the metadata graph. That is a subsystem of its own, and getting it half-right produces
|
||||
misleading debuggers, which is worse than no debug info.
|
||||
|
||||
**What resolution requires.**
|
||||
|
||||
- Define how VIR source locations resolve through the `LoweringMap` and the registered source
|
||||
map (see [011 — Diagnostics](011-diagnostics.md)).
|
||||
- Lower those locations to LLVM metadata on the LLVM 18+ schema, including lexical block scopes.
|
||||
- Add a verification step over the metadata graph, and test it with `llvm-dwarfdump` and a
|
||||
debugger round-trip in CI.
|
||||
- Decide whether debug metadata is emitted only under `-g` and how it interacts with the
|
||||
determinism guarantee.
|
||||
|
||||
## 5. OQ2: Windows and MSVC support
|
||||
|
||||
**Question.** Should libVCT support Windows as a host or target, and MSVC as the C compiler?
|
||||
|
||||
**v1 behavior.** No. v1 is Linux/POSIX-first and supports GCC and Clang only (see
|
||||
[000 — Overview](000-overview.md)).
|
||||
|
||||
**Why deferred.** The C backend leans on GCC and Clang constructs: `__builtin_expect`,
|
||||
`__builtin_assume_aligned`, `__builtin_assume`, `__asm__` fences, `#[[]]` attributes, and
|
||||
`#pragma` loop hints. MSVC lacks most of these and spells the rest differently. Beyond the C
|
||||
surface, the driver's compiler discovery, response-file handling, path rules, and ABI
|
||||
(`dllexport`/`dllimport`, COFF) all differ. Cosmopolitan mode covers a subset of Windows
|
||||
execution but not MSVC as a backend compiler.
|
||||
|
||||
**What resolution requires.**
|
||||
|
||||
- Define an MSVC dialect layer: per-construct mappings for hints, attributes, fences, and
|
||||
pragmas, with a portable fallback where no equivalent exists.
|
||||
- Extend the driver with `cl.exe` discovery, argument syntax, and error parsing.
|
||||
- Specify the Windows ABI surface, including exported symbol decoration and the C runtime.
|
||||
- Add a Windows CI matrix, which also forces decisions about the xmake build on Windows.
|
||||
|
||||
## 6. OQ3: LLVM bitcode emission
|
||||
|
||||
**Question.** Should the LLVM backend be able to emit bitcode (`.bc`) directly instead of
|
||||
textual `.ll`?
|
||||
|
||||
**v1 behavior.** No. The backend emits textual `.ll` only, and the caller runs `llvm-as` (see
|
||||
[009 — LLVM Backend](009-llvm-backend.md)). libVCT never links LLVM.
|
||||
|
||||
**Why deferred.** The two obvious routes both carry cost or conflict. Linking LLVM would add a
|
||||
large native dependency and contradict the zero-runtime-dependency rule (see
|
||||
[013 — Build & Packaging](013-build-packaging.md)). Emitting the LLVM bitstream by hand would
|
||||
require implementing and version-tracking the bitstream container format, which is stable but
|
||||
large and not the intended value of the project. Textual output keeps the backend a pure
|
||||
translator.
|
||||
|
||||
**What resolution requires.**
|
||||
|
||||
- Choose a route: an optional LLVM-linked build, a bundled bitstream writer, or a supported
|
||||
external `llvm-as` invocation driven by the library.
|
||||
- If the library invokes `llvm-as`, specify discovery and failure handling the way the C compiler
|
||||
is handled in [010 — Driver & CLI](010-driver-cli.md).
|
||||
- Keep textual emission available, since it is the format the round-trip and FileCheck tests use
|
||||
(see [012 — Testing](012-testing.md)).
|
||||
|
||||
## 7. OQ4: Incremental and cached compilation
|
||||
|
||||
**Question.** Should libVCT cache compiled objects keyed by a content hash so that repeated
|
||||
compilations skip work?
|
||||
|
||||
**v1 behavior.** No. Content-hash `.o` caching is out of scope. Every invocation of the pipeline
|
||||
compiles from the input it is given.
|
||||
|
||||
**Why deferred.** Caching is only safe when the cache key captures everything that affects
|
||||
output. The deterministic-output guarantee makes caching feasible, but it also raises the bar:
|
||||
a stale hit would silently violate determinism. The key must cover the input, the full `Config`,
|
||||
the library version, the trait vocabulary version, the textual IR format version, and the chosen
|
||||
C compiler and its version. The storage, eviction, and concurrency design is a separate feature.
|
||||
|
||||
**What resolution requires.**
|
||||
|
||||
- Specify the cache key and prove that no input affecting output is omitted.
|
||||
- Specify cache storage, invalidation, and locking, including concurrent invocations.
|
||||
- Expose the feature through the CLI and the API without making it the default.
|
||||
- Test that a cache hit and a cache miss produce byte-identical output.
|
||||
|
||||
## 8. OQ5: Cross-compilation
|
||||
|
||||
**Question.** Should libVCT support cross-compilation to targets other than the host?
|
||||
|
||||
**v1 behavior.** Partial. `-target <triple>` passes through to the toolchain, and `-mangled`
|
||||
mode produces an Actually Portable Executable, but there is no general cross-compilation support.
|
||||
Compiler discovery is host-oriented, and there is no sysroot or header management.
|
||||
|
||||
**Why deferred.** Real cross-compilation needs a target model, not just a flag: target data
|
||||
layout for the LLVM backend, an ABI definition for the C backend, discovery of a target C
|
||||
compiler, and a sysroot with target headers and libraries. The v1 pipeline assumes a host
|
||||
compiler that already knows its target.
|
||||
|
||||
**What resolution requires.**
|
||||
|
||||
- Define the supported target matrix and the meaning of a target triple in `Config`.
|
||||
- Derive the LLVM target data layout and triple, and validate the module against it.
|
||||
- Specify cross C compiler discovery, sysroot layout, and header resolution.
|
||||
- Define the target ABI surface for the C backend and test it on at least one non-host target.
|
||||
|
||||
## 9. Cross-references
|
||||
|
||||
- [000 — Overview](000-overview.md) for the v1 non-goals these questions extend.
|
||||
- [008 — C Backend](008-c-backend.md) for the GCC and Clang constructs behind OQ2 and OQ5.
|
||||
- [009 — LLVM Backend](009-llvm-backend.md) for the emission surface behind OQ1, OQ3, and OQ5.
|
||||
- [010 — Driver & CLI](010-driver-cli.md) for compiler discovery behind OQ2, OQ3, OQ4, and OQ5.
|
||||
- [011 — Diagnostics](011-diagnostics.md) for source maps behind OQ1.
|
||||
- [012 — Testing](012-testing.md) for the regression and determinism obligations new features
|
||||
must inherit.
|
||||
- [013 — Build & Packaging](013-build-packaging.md) for the dependency and versioning rules
|
||||
these features must respect.
|
||||
Reference in New Issue
Block a user