kami
6c92f85d10
Bring the Nexus/Praxis/Hexis integration in line with MAVEN_ECOSYSTEM_ARCHITECTURE.md: - Praxis over HTTP: drop the in-process praxis.db open (praxisstore/ praxistools) and call praxisd's /api/v1/tools/* API via a new praxisClient. Honors the "no component reads another's DB" invariant (AC#12). PraxisConfig.DBPath -> URL. - Hexis confirmation gate: mutating capabilities (ReadOnly=false) now park a bound pendingHexis confirmation and require a spoken "да" before executing; read-only run immediately (AC#7, no auto attention->action). - Capability safety: >1 verb match is ambiguous -> ask instead of firing the first; ambiguous Nexus resolution asks for clarification (AC#2). - Correlation IDs on Hexis execute, recorded in the cross-service trace. - Bug: importance arrives as JSON float64 over HTTP, not int. - Tests: confirm-gate, decline, read-only, and ambiguity paths. Build: vendor/ bakes in the hexis client (replace-directed at a sibling repo outside the Docker context); Dockerfile builds from vendor and no longer `go mod download`s the unreachable replace paths. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
57 lines
2.9 KiB
Markdown
57 lines
2.9 KiB
Markdown
# GEMINI.md
|
|
|
|
This file provides guidance for the Gemini AI assistant when working with the `modernc.org/libc` repository.
|
|
|
|
## Overview
|
|
`modernc.org/libc` is a partial reimplementation of C libc in pure Go. It acts as the runtime for C programs transpiled to Go by the `modernc.org/ccgo` transpiler (used notably by `modernc.org/sqlite`). It is not intended as a general-purpose standalone library.
|
|
|
|
**Key Rule:** The API tracks the needs of `ccgo`-generated code. Callers must use the libc version matching their generated code. Do not bump the libc version of downstream consumers without re-translating their C sources.
|
|
|
|
## Architecture
|
|
The codebase is split into two completely separate code paths, selected by build constraints:
|
|
|
|
1. **musl-derived (Linux)**
|
|
- Targeted via: `//go:build linux && (amd64 || arm64 || loong64 || ppc64le || s390x || riscv64 || 386 || arm)`
|
|
- Generated files: `ccgo_linux_*.go` (~4MB each), per-arch `musl_*.go`, and assembly stubs `abi0_linux_amd64.{go,s}`. **Do not hand-edit generated files**.
|
|
- Hand-written glue files: `libc_musl.go`, `etc_musl.go`, `mem_brk_musl.go`, `mem_musl.go`, `memgrind_musl.go`, `pthread_musl.go`, `syscall_musl.go`, `aliases.go`, `atomic.go`, `atomic{32,64}.go`, `builtin{32,64}.go`, `libc_linux_statfs.go`.
|
|
|
|
2. **Hand-written (non-Linux / mips64le)**
|
|
- Targeted via negated constraints.
|
|
- Main files: `libc.go`, `libc_unix.go`, `libc_<goos>.go`, `libc_windows*.go`, `pthread.go`, `mem.go`.
|
|
- These platforms use handwritten implementations combined with some older `ccgo/v3`-generated `musl_<goos>_<goarch>.go` pieces.
|
|
|
|
**Important:** When making a change, you usually need to update *both* code paths (the musl path and the hand-written path).
|
|
|
|
## Common Commands
|
|
- **Build/Lint**:
|
|
- `go build ./...`
|
|
- `make editor` (fast iteration)
|
|
- `make build_all_targets` (full cross-compile, required before submitting)
|
|
- **Tests**:
|
|
- `make short-test`
|
|
- `make test` (full test)
|
|
- `make libc-test` (musl libc-test suite)
|
|
- `go test -v -run <TestName>`
|
|
- **Generate** (Linux only):
|
|
- `make generate` (downloads musl, translates via `ccgo`, rebuilds, and tests)
|
|
|
|
## Build Tags
|
|
- `libc.membrk`: Sbrk-style allocator for detecting use-after-free.
|
|
- `libc.memgrind`: Allocator audit table for leak detection.
|
|
- `libc.dmesg`: Per-pid logging to `/tmp/libc.log`.
|
|
- `libc.strace`: Traces C function entries.
|
|
- *Note: `libc.membrk` and `libc.memgrind` are mutually exclusive.*
|
|
|
|
## Symbol Naming Conventions
|
|
- `Xfoo`: Externally visible C function `foo`.
|
|
- `Yfoo`: abi0-wrapped entry to `Xfoo` (linux/amd64).
|
|
- `Tfoo_t`: Typedef'd C type `foo_t`.
|
|
- `Sfoo` / `Ufoo`: Struct / Union tags.
|
|
- `Ffield`: Struct field.
|
|
|
|
If you add a new `Xfoo` symbol in hand-written files, ensure it is added to the relevant `capi_<goos>_<goarch>.go` files.
|
|
|
|
## Thread Local State (TLS)
|
|
- `*TLS` represents a C "thread". It is passed as the first argument to every `Xfoo` function.
|
|
- `TLS` is **not safe for concurrent use**. Use one goroutine per TLS.
|