mbg-setup
Sets up this repository on a new machine — the Python environment, the GF180MCU PDK, the EDA tools (Magic, netgen, KLayout), the shell integration in $HOME/.mbg, and the OpenCode / Claude Code / Codex
SKILL.md.ai/skills/mbg-setup/SKILL.md
GitHubMBG Setup
Purpose
Get a clone working, then get it working from anywhere. One script,
./install.sh, does all of it in six stages. This is the skill to reach for on
a fresh machine, and the one Codex users invoke by name since Codex has no
slash commands.
When to Use
- A fresh clone, or a new machine.
import mbgfails, or a version error mentionsreferences,get_polygonsorfloat_.- The PDK, ngspice, Magic, netgen or KLayout cannot be found.
mbg checkis not a command, or$MBG_HOMEis unset in a new shell.- A
/mbg-*slash command is missing, stale, or only works inside the clone. - Someone asks how to install the skills for their agent.
When Not to Use
- Generating layout, running verification, or debugging a design.
- Adding a new skill or workflow — that is
mbg-extension-authoring.
Required Inputs
None. Every stage discovers the repository root itself. Nothing is hard-coded to a particular user or home directory.
Preconditions
- Linux. Debian/Ubuntu, Fedora/RHEL-like, Arch-like and openSUSE are detected.
- A Python 3.10–3.12 interpreter. gdsfactory 7 and numpy 1 have no wheels for
3.13+, and
install.shselects a supported one automatically. Pin one withMBG_PYTHON=/path/to/python3.11. - Roughly 2 GB of disk, most of it the GF180MCU PDK.
- No Docker and no root. Building Magic, netgen or KLayout from source needs a
C toolchain, Tcl/Tk, Cairo and X11 headers —
./install.sh --depsprints the exact package list for the detected distribution, and--deps --yesinstalls it. That is the only step that asks for sudo, and it is never silent.
The six stages
./install.sh with no arguments runs all of them in dependency order. Run one
at a time with --stage <name> when a fresh machine fails and you need to know
which layer broke.
| Stage | What it does |
|---|---|
python |
.venv, pinned dependencies, pip install -e . |
pdk |
GF180MCU via volare into $PDK_ROOT |
eda |
Magic, netgen and KLayout into $MBG_TOOLS_ROOT — only what is missing or incompatible |
shell |
$MBG_HOME/activate.sh, the mbg launchers, one ~/.bashrc line |
agents |
repo-scoped /mbg-* adapters + the Codex plugin (optional) |
global |
/mbg-* for the whole user account (optional) |
Where things land
Three directories, all overridable, none hard-coded:
| Variable | Default | Holds |
|---|---|---|
MBG_VENV |
<repo>/.venv |
the Python environment |
MBG_TOOLS_ROOT |
$HOME/.local/mbg-tools |
EDA builds |
MBG_HOME |
$HOME/.mbg |
activation script and launchers |
Nothing is written to /usr, /usr/local or the system package database
unless --deps --yes is used.
Workflow
Install
./install.sh # all six stages ./install.sh --list # show the stages and stop ./install.sh --check # full preflight, installs nothingPick up the environment
After the
shellstage, a new shell already has it — that stage writes$MBG_HOME/activate.shand adds one idempotent block to~/.bashrc(and~/.zshrcif present), between# >>> Microelectronic Block Generator >>>and# <<< Microelectronic Block Generator <<<. Re-running replaces the block, never appends.In the current shell, or when working inside the clone:
source scripts/activate_mbg.sh # delegates to $MBG_HOME/activate.shThat sets
MBG_HOME,MBG_ROOT,MBG_VENV, the four GF180 variables (PDK_ROOT,PDK,PDKPATH,STD_CELL_LIBRARY),MBG_TOOLS_ROOT, and pins each EDA tool by absolute path inMBG_MAGIC,MBG_NETGEN,MBG_KLAYOUTandMBG_NGSPICE. Every assignment defers to a value that is already exported, so a user's own setting wins.Pinning by absolute path is deliberate. Several distributions ship no
klayoutpackage at all, so the working binary often lives somewherePATHnever looks — and without it there is no foundry-deck DRC and no sign-off.The virtualenv is deliberately not activated. Activating it in a login file would change what
pythonandpipmean in every unrelated shell. Instead$MBG_HOME/bingoes onPATHwith launchers that name MBG's interpreter explicitly:mbg check # environment preflight — same report as ./install.sh --check mbg version mbg python x.py # run a script with MBG's interpreter mbg shell # interactive Python with mbg importable mbg-python -c ...Pass
--with-venvto theshellstage if the user would rather have the venv active everywhere.Agent integrations
./install.sh --stage agents # repo-scoped ./install.sh --stage global # the whole user accountagentsmakes/mbg-*work when the agent is started inside this checkout. OpenCode and Claude Code read.opencode/and.claude/straight from the clone and need no registration. Codex has no repo-scoped skills, so its plugin is registered once per machine; that writes to~/.codex/config.tomland asks first. Because Codex caches the plugin at install time, re-run this stage after any change under.ai/.globalinstalls for the current user, so/mbg-full-autoworks from any directory:Platform Installed to Claude Code ~/.claude/skills/mbg-*,~/.claude/commands/mbg-*.mdOpenCode ~/.config/opencode/skills/mbg-*,~/.config/opencode/commands/mbg-*.mdCodex the plugin registered by the agentsstageIt uses symlinks, so a
sync_agent_tools.pyrun reaches the global install immediately. A copied skill silently goes stale and the slash command ends up invoking last week's instructions. Use--copyonly when the setup cannot follow symlinks, and re-run after every sync. Onlymbg-*entries are created or removed; other projects' skills in those directories are never touched.Verify
./install.sh --check # or: mbg check python3 scripts/validate_agent_integrations.py python3 tests/test_all_designs.py--checkand--uninstallboth accept--stage, so a single layer can be inspected or undone:./install.sh --check --stage shell # exactly one rc block? tools pinned? ./install.sh --check --stage global # is the global install current? ./install.sh --uninstall --stage global # remove only the mbg-* entries
Outputs
.venv/withmbgimportable andmbg-sync/mbg-validateon PATH.$MBG_HOME/activate.sh,$MBG_HOME/bin/mbg,$MBG_HOME/bin/mbg-python, and one block in the user's rc file.- EDA tools under
$MBG_TOOLS_ROOT, each pinned by absolute path. - Registered agent integrations for whichever CLIs are installed, repo-scoped and optionally user-wide.
- A validator summary and a DRC/LVS result for the seven reference designs.
Failure Modes
- No supported interpreter. Install Python 3.10–3.12; do not force 3.13+, the wheels do not exist.
- PDK missing.
--stage pdkinstalls it with volare. Inside the IIC-OSIC-TOOLS container it is already atPDK_ROOT=/foss/pdks. - KLayout missing. DRC sign-off reports
CONFIGURATION_FAILURE, never PASS — a missing checker must not look like a clean run. Theklayoutpip package is not sufficient: it ships no executable and cannot run the GF180 deck's Ruby DSL. Point at a real binary withMBG_KLAYOUT=/path/to/klayout. mbgis not a command. Theshellstage has not run, or the shell predates it. Run./install.sh --stage shelland open a new shell./mbg-*works in the clone but not elsewhere. Theglobalstage has not run.- A
/mbg-*command runs stale instructions. The global install was made with--copy; re-run it, or reinstall without--copyso it symlinks. - Codex marketplace add fails with "local marketplace source must be a directory, not a file" — pass the repository root, not the manifest path.
- Optional stage did not complete.
agentsandglobalare optional: the install still succeeds, because MBG itself works without the agent layer. Report it asPARTIAL, not as failure.
Reporting Rules
Report what the script actually printed, including which stage failed. Never
describe a missing tool or a failed install as success, and use PASS /
FAIL / PARTIAL / NOT RUN / NOT AVAILABLE for status.