Configure engineering tools

Applies to SiliconForge 0.1.2 · Updated 2026-09-30. Check platform limits.

Before this task: Verify the installed runtime and inventory →

An installed application, a detected executable and a qualified engineering run are three different things. Check the actual authority and output before trusting a green status.

Match a tool to a question#

Use tools already present in your verified application inventory where available; otherwise use a supported external installation or another approved, verified authority for that platform. Published application packages include engineering tools; the package inventory identifies which ones are bundled on your platform. The Engineering Tool Pack is not offered as a separate download. Find source and notices for the exact application package; source availability is separate from whether a tool is ready to run. Do not download an arbitrary substitute pack, install unnecessary duplicates or bypass integrity checks.

Choose tools through the application#

1. Open Engineering tools… from the application menu, or Settings → Validation & tools → Choose engineering tools…. You can also reach it from Configure checks….
2. Read the separate Engineering tools and Verible lint tools states. Keep a working bundled installation unless a check identifies a missing requirement.
3. If an approved external installation is needed, choose Get approved archive…. This opens the exact upstream download; it is not an automatic installer or a separate SiliconForge Engineering Tool Pack. Extract it into a user-owned tools folder outside your project.
4. Use Browse… to select the extracted tool folder itself, not its parent download or extraction folder. The engineering suite and Linux Verible roots contain bin/. For Windows Verible, select the upstream extracted verible-…-win64 folder containing the .exe files directly; do not create a bin/ directory or move the executables. Choose Use selected tools… and confirm. SiliconForge checks the approved manifest, file integrity and actual tool versions. A filename or successful shell command alone is not approval.
5. Choose Refresh tool readiness, return to the project and reopen Configure checks…. Review the settings and choose Save check configuration before running a small check. A changed toolchain makes the previous setup stale. Inspect its output rather than assuming that selection is a passing engineering result.

The selection belongs to this application installation, not to untrusted project configuration. Reset selection… returns to the installed defaults after confirmation; it does not delete your external tool files. A changed, unsupported or incomplete installation remains unavailable instead of silently falling back to a random executable on your path.

If tool doctor reports a schema error#

If Refresh tool doctor reports SchemaError: verified tool doctor schema is invalid, the GUI could not interpret the core report. Older releases can disagree about the report schema. This is not proof that every installed tool failed and not a passing check. Preserve the message. For a configured source environment, python -m sf_core project-doctor reads the underlying report; see CLI prerequisites. Installed-app users who cannot run that supported diagnostic should send the release and redacted error to support rather than change a tool hash or install random replacements.

Ubuntu 24.04: enable isolated engineering checks#

Ubuntu protects unprivileged user namespaces by default. If tool readiness says the engineering sandbox is unavailable, an administrator must perform the supported one-time setup. Do not disable AppArmor, change the global user-namespace restriction, or run the application as root.

After verifying and extracting the application, open a terminal in its directory. With Ubuntu's bubblewrap and apparmor packages installed, replace YOUR_LOGIN with your existing non-root local desktop login:

sudo /usr/bin/python3 -I packaging/linux/setup_engineering_sandbox.py install --user YOUR_LOGIN
sudo /usr/bin/python3 -I packaging/linux/setup_engineering_sandbox.py check --user YOUR_LOGIN

The shipped docs/engineering/ubuntu-sandbox.md explains the supported platform, administrator review, update and removal. The helper creates a root-owned distro-identical executable at /opt/siliconforge/engineering-sandbox/bwrap, grants execution to the dedicated engineering group and loads only its exact-path AppArmor namespace permission. It does not download software or change global policy. Bubblewrap's namespace and mount recipe—not the permission profile alone—provides isolation.

The check runs as your normal user and verifies network/host-file isolation without calling AI. Log out and back in after first setup, then reopen SiliconForge and refresh tool readiness. Group changes do not apply to an already-running desktop. After an Ubuntu bubblewrap update, rerun these commands; changed or incomplete installations fail closed instead of trusting stale hashes.

Platform guidance: Ubuntu AppArmor documentation and Ubuntu 24.04 release notes.

Windows: set up the dedicated WSL worker#

The native Windows desktop can open and edit your project without a Linux guest. Isolated AI execution and fixed engineering checks use a separate WSL2 worker. Windows Home with working WSL2 is supported; no separate Windows guest ISO is required.

Before setup, close SiliconForge and active worker sessions. You need a verified Windows x64 installation, an administrator PowerShell terminal, working WSL2, internet access for the reviewed upstream downloads, and at least 20 GiB free for a new dedicated distribution. Worker staging also checks for 8 GiB free inside Linux. Downloads are approximately 1.2 GB; extracted tools need more space.

1. Set the actual application directory containing SiliconForge.exe below. Use that installation's interpreter and helper together; do not run a project checkout as administrator.
2. List and download the exact reviewed Ubuntu image, engineering tools, Verible and complete Codex package. The helper verifies archive sizes/digests and reports progress; do not continue after a failure. Engineering launchers are transformed by the same reviewed, deterministic recipe used by the release producer; upstream internal file links are materialized inside the verified tool root. Normalized executable and runtime hashes remain pinned; no hash is weakened to accept a raw wrapper.
3. Create a new SiliconForge distribution in a new directory. The helper does not export, reuse or modify your personal Ubuntu distro.
4. Install the worker, pass the Linux and native Windows source-bound canaries, then reopen Settings → Tool installations and refresh readiness before running a small project check.

$Install = "$env:LOCALAPPDATA\Programs\SiliconForge\current"
$Python = Join-Path $Install 'runtime\python.exe'
$Setup = Join-Path $Install 'app\packaging\windows\setup_wsl_worker.py'
$Downloads = "$env:USERPROFILE\Downloads\SiliconForge-WSL"
$Data = "$env:LOCALAPPDATA\SiliconForge-WSL"
& $Python -I -B $Setup downloads
& $Python -I -B $Setup download --downloads $Downloads
& $Python -I -B $Setup create --downloads $Downloads --directory $Data
& $Python -I -B $Setup install --downloads $Downloads
& $Python -I -B $Setup check

The administrator helper creates a locked unprivileged sf-agent account, root-owned source/tools, and a dedicated policy with Windows drive automounting and Windows executable interoperability disabled. It restarts only the newly created distribution to activate that policy. It never unregisters a distribution, changes your WSL default, automatically elevates itself, executes npm hooks or calls a model. Provider login and a commercial subscription remain separate.

Update and recover the worker#

After an application update, close the app and use the updated installation's helper to repeat download, install and check. Its packaged source must match the Linux worker exactly. Failed qualification restores the prior worker generations. For an application rollback, restore the earlier verified application first, then use that version's helper with rollback and check. A source mismatch fails closed; never edit an inventory to accept unknown bytes.

remove disables the active managed worker and clears its matching selection, but retains source history, archives, tools, the distribution and user data. It does not reclaim all disk space or delete your personal distro. The full procedure, prerequisites, cancellation and power-loss limits are shipped with the app in docs/engineering/windows-wsl.md. If creation fails, preserve the incomplete dedicated distribution and failure stage for support; it is not silently deleted or adopted.

WSL missing? Follow Microsoft's WSL installation instructions and complete any requested restart first. Reviewed media comes from Ubuntu's official release files. Never expose host drives or disable system-wide protections to bypass an isolation failure.

Platform boundaries#

Do not copy a Linux tool directory onto Windows or an AMD64 directory onto ARM64. Application availability does not imply identical simulator, formal-engine or native-helper coverage on every platform. Windows launch and AI isolation have their own rules; Linux runtime overrides are not a Windows setup recipe. Check the current doctor result and supported release metadata for the particular tool, not just the application download card.

Example: diagnose a missing simulation#

1. Open the first-project example and keep its RTL/testbench unchanged.
2. Check whether the required simulator is actually available. If not, record the missing tool and install it using its reviewed, platform-appropriate instructions.
3. Run the documented standalone example or a supported application check. Standalone shell results are useful diagnostics, but do not automatically become core-custodied Verify evidence.
4. Inspect the exit status and expected PASS marker; preserve compile errors instead of labelling a skipped run successful.

Failure and recovery#

If a path change appears ignored, check environment overrides and whether the job began before settings were saved. If the doctor reports a version/hash mismatch, obtain the exact reviewed tool build or matching authorized manifest; do not edit a hash to bless unknown bytes. Check the source and license records for the exact package you obtained. An external upstream archive has its own records; it is not interchangeable with the tools recorded for another SiliconForge release.

Tool documentation#

• Verilator
• cocotb
• Yosys
• SymbiYosys

Next: run interpretation, simulation and waves, synthesis and formal.

Need help? Report an issue. Include your application version; never include credentials.