vj 0.3.0

//! vj CLI: `vj run <file.sv>` -- Task S7's end-to-end pipeline
//! (`docs/superpowers/plans/2026-09-26-wave-A2-slice.md`; ledger CG-125).
//! `vj build-aot <file.sv>... -o <out.so>` / `vj run-aot <out.so>` --
//! the AOT path (see `vj::aot`'s own module doc comment).
//! Any other/no subcommand prints usage to stderr and exits `2`, per Task
//! S7's own "Public names/types introduced" spec.
use std::io::Write;
use std::path::{Path, PathBuf};

use vj::aot::{RUNTIME_LIB_NAME, build_aot_design, build_aot_exe, find_runtime_lib};
use vj::aot_loader::run_aot;
use vj::cli::{RunArgs, parse_build_aot_args, parse_run_args};
use vj::dpi;
use vj::run::run_sources_with_options;
use vj::vpi;

/// Task 11 (AB-006): a manual/diagnostic smoke path proving the AOT-static
/// build embeds the fixture kernel directly (ordinary linked-symbol calls,
/// no `libloading`, no `dlopen`). Only compiled when this crate's own
/// `static-test-kernel` Cargo feature is enabled -- the default `vj`
/// build never references this module at all. Not exercised by any
/// `#[test]` in this crate (the automated coverage lives in
/// `tests/static_link.rs`, which does its own independent `include!` of the
/// same `build.rs`-generated shim); this exists so a human (`cargo run -p
/// vj --features static-test-kernel -- __static_test_kernel_smoke__`)
/// can observe the static path work from the real CLI binary too.
#[cfg(feature = "static-test-kernel")]
mod static_test_kernel_smoke {
    include!(concat!(env!("OUT_DIR"), "/kernel_shim.rs"));

    pub fn run() {
        // SAFETY: sim_abi_version/sim_init are the statically-linked
        // fixture kernel's real ABI-conformant exports -- build.rs compiled
        // and archived them, and wired the archive into this very binary's
        // own link line (`cargo:rustc-link-arg-bins`, see build.rs's own
        // doc comment for why). Calling them with their declared signatures
        // (design_id: u32) -> *mut c_void, matching
        // tests/fixtures/test_kernel.rs's own real signatures, is exactly
        // what they're for.
        unsafe {
            let version = sim_abi_version();
            let handle = sim_init(0);
            println!(
                "static-test-kernel smoke: sim_abi_version={version} sim_init_handle={handle:p}"
            );
        }
    }
}

/// A `--vpi`/`+vpi=` entry as a library path: a C/C++ source is compiled
/// against the bundled headers first (exiting with status 1 on failure), a
/// library path is used as given, and a bare `NAME` means `NAME.so`.
fn vpi_library(arg: &str) -> PathBuf {
    let path = Path::new(arg);
    if dpi::is_c_source(path) {
        match dpi::compile_sources(&[path.to_path_buf()]) {
            Ok(lib) => lib,
            Err(e) => {
                eprintln!("error: {e}");
                std::process::exit(1);
            }
        }
    } else {
        dpi::sv_lib_path(arg)
    }
}

/// `vj run --aot` (AB-012): elaborate -> codegen -> AOT compile+link into a
/// private temporary library -> load and run it, returning the exit code.
/// The temporary directory is removed before returning. A timing option is
/// refused by name (it is a build-time choice of `build-aot`; pass the same
/// flags to `build-aot` and `run-aot`).
#[allow(clippy::too_many_arguments)]
fn run_aot_in_one_invocation(
    sources: &vj::sources::SourceSet,
    timing: vj::timing_options::TimingOptions,
    driver_options: Vec<String>,
    x_initial_zero: bool,
    coverage: bool,
    seed: Option<u64>,
    plusargs: &[String],
    libs: &[PathBuf],
    vpi_libs: &[PathBuf],
) -> i32 {
    if timing != Default::default() {
        eprintln!("error: `run --aot` does not take timing options; use `build-aot` and `run-aot`");
        return 2;
    }
    let Some(runtime_lib) = find_runtime_lib() else {
        eprintln!(
            "error: cannot find {RUNTIME_LIB_NAME}; build it with `cargo xtask \
             build-aot-runtime` or set VJ_AOT_RT"
        );
        return 1;
    };
    // `design.so` is loaded from here: an owner-only directory with an
    // unpredictable name, never a pre-existing one (see `private_dir`).
    let dir = match vj::private_dir::create("vj-run-aot") {
        Ok(d) => d,
        Err(e) => {
            eprintln!("error: cannot create a private scratch directory: {e}");
            return 1;
        }
    };
    let so = dir.join("design.so");
    vj_runtime::codecov::set_enabled(coverage);
    vj_codegen::frontend::set_driver_options(driver_options);
    vj::run::set_x_initial_zero(x_initial_zero);
    dpi::set_pending_libraries(libs.to_vec());
    vpi::loader::set_pending_libraries(vpi_libs.to_vec());
    let code = match build_aot_design(sources, timing, &runtime_lib, &so) {
        Err(e) => {
            eprintln!("error: {e}");
            1
        }
        Ok(_) => {
            let mut run_args: Vec<String> = plusargs.to_vec();
            for l in libs {
                run_args.push("--sv-lib".into());
                run_args.push(l.display().to_string());
            }
            for l in vpi_libs {
                run_args.push("--vpi".into());
                run_args.push(l.display().to_string());
            }
            if x_initial_zero {
                run_args.extend(["--x-initial".into(), "zero".into()]);
            }
            if coverage {
                run_args.push("--coverage".into());
            }
            if let Some(s) = seed {
                run_args.extend(["--seed".into(), s.to_string()]);
            }
            match run_aot(&so, &run_args) {
                Ok(code) => code,
                Err(e) => {
                    eprintln!("error: {e}");
                    1
                }
            }
        }
    };
    let _ = std::fs::remove_dir_all(&dir);
    code
}

fn main() {
    let args: Vec<String> = std::env::args().collect();

    #[cfg(feature = "static-test-kernel")]
    if args.len() == 2 && args[1] == "__static_test_kernel_smoke__" {
        static_test_kernel_smoke::run();
        return;
    }

    match args.get(1).map(String::as_str) {
        // RT-077: `vj run <file.sv> [+PLUSARG]... [DPI...]` -- every
        // trailing token that starts with `+` is a plusarg, handed, in
        // order, to `run_design_with_options` (which reaches
        // `vj_runtime::plusargs_sink::set_plusargs_for_run` before
        // simulation starts). DPI-C code: a C/C++ source is compiled into a
        // shared library, and `--sv-lib LIB` / `-sv_lib LIB` / a `.so`
        // path is loaded, before the design is compiled (`vj::dpi`).
        // Several files, `-I`/`+incdir+`, `-D`/`+define+`, `--top` and `-f`
        // list files are read by `vj::cli`.
        Some("run") if args.len() >= 3 => {
            // AB-012: `--aot` selects the other half of the pipeline
            // (elaborate -> codegen -> AOT compile+link -> run) in a single
            // invocation: `build-aot` into a private temporary library, then
            // `run-aot` it, then delete it.
            let aot = args[2..].iter().any(|a| a == "--aot");
            // `--parse-only`: preprocess and parse the sources, no
            // elaboration and no simulation (exit 0 when they parse).
            let parse_only = args[2..].iter().any(|a| a == "--parse-only");
            let run_tokens: Vec<String> = args[2..]
                .iter()
                .filter(|a| *a != "--aot" && *a != "--parse-only")
                .cloned()
                .collect();
            let parsed = match parse_run_args(&run_tokens) {
                Ok(p) => p,
                Err(e) => {
                    eprintln!("error: {e}");
                    std::process::exit(2);
                }
            };
            let RunArgs {
                sources: source_set,
                plusargs,
                mut libs,
                c_sources,
                timing,
                vpi_libs,
                driver_options,
                x_initial_zero,
                coverage,
                seed,
            } = parsed;
            if parse_only {
                match vj::sources::parse_only(&source_set) {
                    Ok(()) => std::process::exit(0),
                    Err(e) => {
                        eprintln!("error: {e}");
                        std::process::exit(1);
                    }
                }
            }
            let vpi_libs: Vec<PathBuf> = vpi_libs.iter().map(|l| vpi_library(l)).collect();
            if !c_sources.is_empty() {
                match dpi::compile_sources(&c_sources) {
                    Ok(lib) => libs.push(lib),
                    Err(e) => {
                        eprintln!("error: {e}");
                        std::process::exit(1);
                    }
                }
            }
            if aot {
                std::process::exit(run_aot_in_one_invocation(
                    &source_set,
                    timing,
                    driver_options,
                    x_initial_zero,
                    coverage,
                    seed,
                    &plusargs,
                    &libs,
                    &vpi_libs,
                ));
            }
            vj_codegen::frontend::set_driver_options(driver_options);
            vj::run::set_x_initial_zero(x_initial_zero);
            vj_runtime::codecov::set_enabled(coverage);
            vj::run::set_seed(seed);
            dpi::set_pending_libraries(libs);
            vpi::loader::set_pending_libraries(vpi_libs);
            vpi::api::set_pending_command_line(args.clone());
            let mut stdout = std::io::stdout();
            match run_sources_with_options(&source_set, &plusargs, timing, &mut stdout) {
                Ok(code) => {
                    let _ = stdout.flush();
                    std::process::exit(code);
                }
                Err(e) => {
                    eprintln!("error: {e}");
                    std::process::exit(1);
                }
            }
        }
        // `cc -I "$(vj --vpi-include-dir)" -shared -fPIC my_vpi.c`.
        Some("--vpi-include-dir") if args.len() == 2 => match vpi::include_dir() {
            Ok(dir) => println!("{}", dir.display()),
            Err(e) => {
                eprintln!("error: {e}");
                std::process::exit(1);
            }
        },
        // `vj build-aot FILE... [source options] -o OUT.so [--runtime-lib LIB]`:
        // the design of `run`, compiled into a shared library (see
        // `vj::aot`). A construct the library cannot carry is refused
        // by name.
        Some("build-aot") if args.len() >= 3 => {
            let parsed = match parse_build_aot_args(&args[2..]) {
                Ok(p) => p,
                Err(e) => {
                    eprintln!("error: {e}");
                    std::process::exit(2);
                }
            };
            let RunArgs {
                sources: source_set,
                mut libs,
                c_sources,
                timing,
                vpi_libs,
                driver_options,
                x_initial_zero,
                coverage,
                ..
            } = parsed.run;
            // Statement probes are code, so they are a build choice
            // (`build-aot --coverage`); toggle and assertion coverage are not.
            vj_runtime::codecov::set_enabled(coverage);
            let runtime_lib = match parsed.runtime_lib.or_else(find_runtime_lib) {
                Some(l) => l,
                None => {
                    eprintln!(
                        "error: cannot find {RUNTIME_LIB_NAME}; build it with `cargo xtask \
                         build-aot-runtime` and pass --runtime-lib or set VJ_AOT_RT"
                    );
                    std::process::exit(1);
                }
            };
            // Libraries only matter to be refused: DPI and VPI run host code.
            let vpi_libs: Vec<PathBuf> = vpi_libs.iter().map(|l| vpi_library(l)).collect();
            if !c_sources.is_empty() {
                match dpi::compile_sources(&c_sources) {
                    Ok(lib) => libs.push(lib),
                    Err(e) => {
                        eprintln!("error: {e}");
                        std::process::exit(1);
                    }
                }
            }
            vj_codegen::frontend::set_driver_options(driver_options);
            vj::run::set_x_initial_zero(x_initial_zero);
            dpi::set_pending_libraries(libs);
            vpi::loader::set_pending_libraries(vpi_libs);
            if parsed.exe {
                match build_aot_exe(&source_set, timing, &runtime_lib, &parsed.out) {
                    Ok(()) => println!("linked {} (standalone executable)", parsed.out.display()),
                    Err(e) => {
                        eprintln!("error: {e}");
                        std::process::exit(1);
                    }
                }
            } else {
                match build_aot_design(&source_set, timing, &runtime_lib, &parsed.out) {
                    Ok(handle) => {
                        println!(
                            "linked {} (abi_version={}, process_count={})",
                            parsed.out.display(),
                            handle.abi_version,
                            handle.process_count
                        );
                    }
                    Err(e) => {
                        eprintln!("error: {e}");
                        std::process::exit(1);
                    }
                }
            }
        }
        // `vj run-aot OUT.so [+plusarg]... [--seed N] [--x-initial zero|x]
        //  [timing options]`: a timing option (same flags as `run`/`build-aot`,
        // M5) is checked against what the library was built with, never
        // forwarded to the design -- a disagreement is refused by name.
        Some("run-aot") if args.len() >= 3 => {
            let code = match run_aot(Path::new(&args[2]), &args[3..]) {
                Ok(code) => code,
                Err(e) => {
                    eprintln!("error: {e}");
                    1
                }
            };
            std::process::exit(code);
        }
        _ => {
            eprintln!(
                "usage: vj run <file.sv>... [source options] [+plusarg]... [dpi.c | lib.so | --sv-lib LIB]... \
                 [--vpi LIB | +vpi=LIB[,LIB]]... [-GNAME=VALUE]... [compat options] [timing options]"
            );
            eprintln!("  source options:");
            eprintln!(
                "    -I DIR | +incdir+DIR[+DIR]...       `include search directories (after the including file's own)"
            );
            eprintln!(
                "    -D NAME[=VALUE] | +define+NAME[=VALUE]...   predefined macros (NAME alone is 1)"
            );
            eprintln!(
                "    --top MODULE | -top MODULE          elaborate MODULE as a top (repeatable; default: every uninstantiated module)"
            );
            eprintln!(
                "    -f LIST | -F LIST                   read arguments from a list file (-F: paths relative to the list file)"
            );
            eprintln!(
                "    --timescale UNIT/PRECISION          time scale of design elements that declare none (e.g. 1ns/1ps)"
            );
            eprintln!("  compat options (non-LRM; each relaxes or overrides an IEEE 1800 rule):");
            eprintln!(
                "    --allow-use-before-declare          a name used before its declaration resolves to it"
            );
            eprintln!(
                "    --relax-enum-conversions            implicit integral-to-enum conversions (LRM 6.19.3)"
            );
            eprintln!(
                "    --allow-hierarchical-const          hierarchical references in constant expressions"
            );
            eprintln!(
                "    --compat vcs|all                    slang's bundles of the relaxations above"
            );
            eprintln!(
                "    --x-initial zero                    uninitialized variables and memories start at 0, not X"
            );
            eprintln!(
                "    --parse-only                        (run) preprocess and parse the sources, then stop"
            );
            eprintln!(
                "    --seed N                            base seed of the $random/$urandom generators (default: a fixed constant)"
            );
            eprintln!("  timing options:");
            eprintln!(
                "    --timing-check-per-bit              per-bit expansion of vector timing checks (LRM 31.8)"
            );
            eprintln!(
                "    --enable-negative-timing-checks     negative $setuphold/$recrem limits (LRM 31.9.4)"
            );
            eprintln!(
                "    --timing-reject-limit-pct=N         default pulse reject limit, 0..100 percent of the delay (LRM 30.7.2, 32.7)"
            );
            eprintln!(
                "    --timing-error-limit-pct=N          default pulse error limit, 0..100 percent of the delay (LRM 30.7.2, 32.7)"
            );
            eprintln!(
                "    --pulse-style=on-event|on-detect    pulse style, overrides declarations (LRM 30.7.4.1)"
            );
            eprintln!(
                "    --showcancelled | --noshowcancelled showcancelled mode, overrides declarations (LRM 30.7.4.2)"
            );
            eprintln!(
                "    --sdf-mtm=minimum|typical|maximum   what $sdf_annotate's TOOL_CONTROL selects (LRM Table 32-5)"
            );
            eprintln!(
                "       vj build-aot <file.sv>... [source options] -o <out.so> [--runtime-lib libvj_aot.a] [--exe]"
            );
            eprintln!(
                "         --exe                              link <out.so> as a standalone executable (no vj run-aot needed)"
            );
            eprintln!(
                "       vj run-aot <out.so> [+plusarg]... [--seed N] [--x-initial zero|x] [--vpi LIB]... [timing options]"
            );
            eprintln!("       vj --vpi-include-dir");
            std::process::exit(2);
        }
    }
}