Imported from cyril0124/verilua (AGENTS.md). Install upstream with npx skills add cyril0124/verilua. Copyright stays with the author.

AGENTS.md

Project Map

• Project name: Verilua.
• ./DEVELOPMENT.md contains extra background for generated-code workflows and broader testing guidance.
• ./xmake.lua is the top-level build entry. Many subprojects under ./src also have their own xmake.lua.
• ./docs contains MDX documentation sources. ./docs-website contains the Docusaurus site.

Where To Start

• Lua runtime and public scripting APIs: ./src/lua/verilua
• Rust VPI core and simulator-specific shared libraries: ./libverilua
• Turso FFI database backend: ./src/turso_ffi
• Rust big-integer backend for StrBitsUtils: ./src/bigint_ffi
• Verilator main program and LightSSS support: ./src/verilator
• Waveform backend binaries and readers: ./src/wave_vpi
• No-simulation analysis backend: ./src/nosim
• SystemVerilog lint tool (slang-backed): ./src/sv_lint
• Code generators for schedulers and CHDL access: ./src/gen
• Testbench generator: ./src/testbench_gen
• SignalDB generator and shared library: ./src/signal_db_gen
• VPI shim over generated DPI accessors: ./src/dummy_vpi
• DPI code generator for dummy_vpi: ./src/dpi_exporter
• Coverage instrumentation and export generator: ./src/cov_exporter
• Common C/C++ headers: ./src/include
• Examples and tutorials: ./examples
• Xmake rules, plugins, and simulator toolchains: ./scripts/xmake
• Verilua's xmake rule implementation: ./scripts/xmake/rules/verilua/xmake.lua
• Conan packaging helpers: ./scripts/conan
• Simulator wrapper commands: ./tools
• Documentation content: ./docs
• Docusaurus site sources: ./docs-website
• Tests: ./tests

Generated Code

• Generated-code workflows are documented in ./DEVELOPMENT.md; keep the detailed source-to-generated file mapping there to avoid duplication.
• For scheduler changes, edit ./src/gen/scheduler_template.lua and regenerate from ./src/gen.
• For CHDL access changes, edit ./src/gen/gen_chdl_access.py and regenerate from ./src/gen.
• For generated Rust changes, edit ./libverilua/src/gen/gen.lua and regenerate from ./libverilua/src/gen.

Code Style

• Lua code must include LuaCATS type annotations written for EmmyLuaLs: https://github.com/EmmyLuaLs/emmylua-analyzer-rust.
• Annotation reference: https://github.com/EmmyLuaLs/emmylua-analyzer-rust/tree/main/docs/emmylua_doc/annotations_EN
• When modifying Lua function signatures, return types, or data structures, update the corresponding LuaCATS annotations so they stay in sync with the implementation.
• When adding or renaming set_values / add_values keys handled by Verilua xmake rules (especially verilua.* flags in ./scripts/xmake/rules/verilua/xmake.lua), also update the verilua.xmake.set_add_values.cmd alias list in ./src/lua/meta.lua so EmmyLua completion and type checks stay in sync.
• Lua code must follow LuaJIT best practices and account for JIT performance characteristics.
• Follow the best practices already used in the existing codebase.
• Add concise English comments for important or non-obvious code blocks when they improve readability.
• After modifying Lua files, run xmake r format-lua (uses scripts/emmylua_format.py; F can select a file/dir).
• After modifying C or C++ files, run xmake r format-cpp.

Environment Variable Naming

• Prefer documenting user-facing env vars in ./docs/reference/special_env_variables.mdx.
• Naming by audience / lifecycle:
  • VL_* — Verilua runtime (read by src/lua / libverilua; e.g. VL_DEBUG, VL_CFG_FILE, VL_DUT_TOP).
  • VL_XMK_* — xmake rule / test-matrix knobs (read by ./scripts/xmake/rules/verilua/xmake.lua and/or test main.lua; e.g. VL_XMK_USE_INERTIAL_PUT, VL_XMK_NO_INTERNAL_CLOCK, VL_XMK_USE_NATIVE_CLOCK). Prefer set_values("verilua.*", ...) when a permanent project setting is enough; use VL_XMK_* for CI/one-shot overrides.
  • VERILUA_HOME — install root only. Do not invent new VERILUA_* env vars.
  • Unprefixed freeze list (do not grow): SIM, SEED, PRJ_DIR, PRJ_TOP.
• Do not add new unprefixed env vars. New runtime knobs → VL_*; new xmake-rule-only knobs → VL_XMK_*.

Code Quality Checks

• After modifying any Lua file, including standalone Lua test files such as test_idpool.lua, always run:

# F is a Lua file or directory. Relative paths are resolved from the project root.
F=path/to/<lua file> xmake r lsp-check-lua

# Examples
F=src/lua/verilua/LuaUtils.lua xmake r lsp-check-lua
F=/abs/path/to/LuaUtils.lua xmake r lsp-check-lua

• lsp-check-lua runs scripts/emmylua_ls_check.py (emmylua_ls over stdio LSP). Without F, it checks src/lua.
• Make sure the output contains no errors or warnings.
• After modifying any Rust code, run cargo fmt and then cargo clippy --all-targets --all-features -- -D warnings; fix all warnings.

TDD Workflow

• Use TDD by default for bug fixes and feature work.
• Start with a failing test that reproduces the bug or captures the expected behavior before changing production code.
• Prefer the smallest relevant test first: run one Lua test file with cd tests && luajit test_xxx.lua --stop-on-fail --no-quiet, or run one focused integration target with xmake build -P tests/<case> and xmake run -P tests/<case>.
• Make the minimum code change needed to turn the test green, then refactor with the test still passing.
• Before finishing, rerun the targeted test(s) you added or changed and then run the required format and static checks for the files you touched.

Running Tests

• Run only the smallest relevant build or test commands for the files you changed. Do not run a full-project build such as xmake b.
• When adding or changing features, include relevant tests.
• To run the broader regression suite, use xmake run test.
• To run the full regression suite in one command, use ./test-all.sh (sets VL_TEST_JOBS to nproc/2 automatically). Extra env vars such as STOP_ON_FAIL=1 or VL_TEST_FILTER=<token> can be prepended as usual.
• To control parallelism for xmake run test, set VL_TEST_JOBS=<n>. The default is 4.
  • Use VL_TEST_FILTER=<token1,token2> to run only matching test jobs.
  • Use VL_TEST_LIST=1 to list matched test jobs without running them.
  • Use STOP_ON_FAIL=1 to stop scheduling new jobs after the first failure.
  • Use VL_TEST_KEEP_WORKDIR=1 to keep the test log directory under .xmake/test even when all jobs pass.
  • Use VERBOSE=1 or V=1 for verbose output and failed-job log dumping.
• To run Lua unit tests, use cd tests && xmake run -P . test-all-lua.
• To run one Lua test file, use cd tests && luajit test_lua_utils.lua --stop-on-fail --no-quiet.
• ./tests/test_*.lua files can be executed directly with luajit.
• For integration-style test directories such as ./tests/test_*/, enter the directory and usually run xmake b -P . && xmake r -P ..
• You can also run a specific integration test from the repo root with xmake build -P tests/test_basic_signal and xmake run -P tests/test_basic_signal.
• Tests that rely on xmake support the SIM environment variable to select the simulator. Supported values include verilator, vcs, and iverilog.
• Example: SIM=vcs xmake b -P . && SIM=vcs xmake r -P .
• Example from the repo root: SIM=iverilog xmake run -P tests/test_basic_signal
• If SIM is not specified, the default simulator is typically verilator.

Component Builds

• If you modify libverilua, rebuild it with xmake run build_libverilua.
• If the libverilua change is simulator-specific, use the matching command:
  • SIM=verilator xmake run build_libverilua
  • SIM=vcs xmake run build_libverilua
  • SIM=iverilog xmake run build_libverilua
  • SIM=xcelium xmake run build_libverilua
  • SIM=wave_vpi xmake run build_libverilua
• If you modify wave_vpi, run xmake b wave_vpi_main.
• Run xmake b wave_vpi_main_fsdb only on Linux with verdi available in PATH.
• If you modify testbench_gen, run xmake b testbench_gen.
• If you modify signal_db_gen, run xmake b signal_db_gen and xmake b libsignal_db_gen.
• If you modify dpi_exporter, run xmake b dpi_exporter.
• If you modify cov_exporter, run xmake b cov_exporter.
• If you modify nosim, run xmake b nosim.
• If you modify sv_lint, run xmake b sv_lint.
• If you modify src/turso_ffi, run xmake b turso_ffi.
• If you modify src/bigint_ffi, run xmake b bigint_ffi.
• If building wave_vpi_main fails, build wave_vpi_wellen_impl first with xmake b wave_vpi_wellen_impl.
• If you modify Rust code in wellen_impl, build wave_vpi_wellen_impl first with xmake b wave_vpi_wellen_impl.

Docs Style

• Prefer concise, example-driven docs. Avoid restating what code already shows.
• Collapse repetitive entries; group symmetric APIs into one item.

Docs Sync

• If you change user-facing behavior, commands, configuration, or workflows, update ./docs as needed.
• When adding or updating documentation pages, ensure the new or changed entries are registered in ./docs-website/sidebars.ts so they appear in the site sidebar.
• If you modify ./docs-website, use Node.js >=18 and run npm run build in ./docs-website.

Feature Delivery Completeness

• When implementing a new feature or fixing a bug, complete the full delivery in one pass without waiting for user reminders:
  1. Implementation code
  2. Tests (unit and/or integration)
  3. Documentation updates (./docs if user-facing behavior changes)
  4. CHANGELOG.md entry under ## Unreleased (skip pure doc-only changes like typos/formatting, and anything not user-visible: internal tooling, agent rules, private scripts, CI-only, etc.)
  5. If new or renamed xmake verilua.* / rule config flags were introduced, update ./src/lua/meta.lua (verilua.xmake.set_add_values.cmd)
  6. Format checks (xmake r format-lua / xmake r format-cpp)
  7. Static checks (xmake r lsp-check-lua / cargo clippy)

Pull Requests

• Before creating a PR, show the full PR title and description to the user and wait for explicit approval. Do not create or update the PR until it is approved.
• Write the PR body with one line per paragraph or bullet, without hard wrapping. GitHub renders a single newline in a PR body as a line break, so wrapped text breaks mid-sentence.

Release Versioning

• Before creating or pushing a release tag, update the root VERSION file in the same release commit and verify that it exactly matches the tag, including the leading v.

Reference Code

• If you are unsure about a Slang API, inspect the Slang source repository first: https://github.com/MikePopoloski/slang.git. Many parts of Verilua depend on Slang.
• For Verilua's Slang helper layer used by multiple generators, inspect src/slang_common/.
• If something is still unclear, online research is allowed.