mirror of
https://github.com/diodeinc/pcb.git
synced 2026-09-14 20:17:19 +08:00
Akhil Velagapudi
2bc8ca73f6
Amp-Thread-ID: https://ampcode.com/threads/T-01a07c7f-dbdd-70ef-b61e-694d08c325e1
145 lines
5.0 KiB
Plaintext
145 lines
5.0 KiB
Plaintext
---
|
||
title: "Getting Started"
|
||
description: "Get started with the `pcb` CLI"
|
||
---
|
||
|
||
Use this guide to install `pcb`, create a board repository, validate its Zener
|
||
source, and generate a KiCad layout.
|
||
|
||
## Requirements
|
||
|
||
- macOS or Linux. Windows support is experimental; use WSL2 for the most
|
||
stable Windows environment.
|
||
- Git, which `pcb new board` uses to initialize a repository.
|
||
- KiCad 10.x for layout generation and editing. `pcb build` does not require
|
||
KiCad.
|
||
|
||
## 1. Install `pcb`
|
||
|
||
Run the installer for your platform:
|
||
|
||
<CodeGroup>
|
||
|
||
```bash bash
|
||
curl -fsSL https://raw.githubusercontent.com/diodeinc/pcb/main/install.sh | bash
|
||
```
|
||
|
||
```powershell powershell
|
||
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/diodeinc/pcb/main/install.ps1 | iex"
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
Default install directories are `$HOME/.local/bin` on Unix and
|
||
`%USERPROFILE%\.pcb\bin` on Windows; override with `PCB_INSTALL_DIR`.
|
||
|
||
The installer adds `pcb` to your user `PATH` when necessary. Verify installation:
|
||
|
||
```bash
|
||
pcb --version
|
||
```
|
||
|
||
For source builds, see the [repository README](https://github.com/diodeinc/pcb#developing-from-source).
|
||
|
||
## 2. Create a board repository
|
||
|
||
Replace the example repository URL with the project repository URL:
|
||
|
||
```bash
|
||
pcb new board Blinky github.com/your-org/blinky
|
||
cd Blinky
|
||
```
|
||
|
||
The generated design is empty but valid. See [Packages](/pages/packages#repository-structure)
|
||
for repository structure.
|
||
|
||
## 3. Build the board
|
||
|
||
Validate the board source and generate its netlist:
|
||
|
||
```bash
|
||
pcb build Blinky.zen
|
||
```
|
||
|
||
## 4. Generate the layout
|
||
|
||
Generate the KiCad files without opening KiCad:
|
||
|
||
```bash
|
||
pcb layout --no-open Blinky.zen
|
||
```
|
||
|
||
This command writes the generated board under `layout/`.
|
||
|
||
## Toolchains
|
||
|
||
`pcb` manages the compiler, stdlib, and sidecars as one toolchain. Workspace
|
||
commands use `pcb-version`; `pcb auth` uses latest stable instead. An explicit
|
||
`pcb +<version> <command>` overrides either selection.
|
||
|
||
```bash
|
||
pcb toolchain show # Active and available versions; --offline avoids network
|
||
pcb toolchain install latest # Also accepts nightly, a lane (0.4), or an exact version
|
||
pcb toolchain repair latest # Validate and restore a toolchain
|
||
pcb toolchain prune --dry-run # Preview cleanup; omit --dry-run to remove files
|
||
pcb self update # Update the shim and managed channels
|
||
```
|
||
|
||
Pruning removes downloads and superseded patches, preserving the newest patch
|
||
per lane, the active version, prereleases, nightly, and local toolchains.
|
||
|
||
## Service accounts and CI
|
||
|
||
Run `pcb auth login --service-account` interactively, or import JSON containing
|
||
`client_id` and `client_secret`:
|
||
|
||
```bash
|
||
pcb auth login --service-account --stdin < credentials.json
|
||
```
|
||
|
||
For CI, supply `DIODE_API_URL`, `DIODE_CLIENT_ID`, and `DIODE_CLIENT_SECRET`
|
||
through the CI secret store. PCB renews access tokens automatically.
|
||
|
||
## Geometry accuracy
|
||
|
||
Use the global `--accuracy-um` option before or after a built-in subcommand to
|
||
set the accumulated geometry approximation budget in whole micrometres:
|
||
|
||
```bash
|
||
pcb --accuracy-um 30 ipc2581 gerber board.xml --output gerbers
|
||
pcb gerber normalize top.gbr --accuracy-um 5 --output top-normalized.gbr
|
||
```
|
||
|
||
The default is **10 µm**. The accepted range is **1–100 µm**: the lower bound
|
||
avoids zero and sub-micrometre subdivision costs; the upper bound limits coarse
|
||
approximation to 0.1 mm rather than millimetres. Smaller budgets can require more
|
||
time and larger files. This is an approximation bound, not a guarantee that a
|
||
coarse budget preserves every small feature. Geometry operations still fail if
|
||
they cannot meet the requested budget.
|
||
|
||
The option applies to IPC-2581 geometry preparation (info, assembly, CPL, ICT, rendering,
|
||
HTML, outline/DXF, warpage, board arrays, fabrication panels, and manufacturing
|
||
export), Gerber normalize/compare/render, and the HTML generated by board
|
||
releases. It does **not** change feature-significance or Gerber comparison
|
||
tolerances. Exceptions:
|
||
|
||
- `pcb dfm` and `pcb ipc2581 dfm` always use **10 µm** to keep findings stable.
|
||
- Copper balancing always uses its **50 µm** profile budget; surrounding panel
|
||
geometry uses the requested budget.
|
||
- KiCad exports, interposer generation, and external commands are not controlled
|
||
by this option. Release Gerbers are KiCad exports; only release HTML uses it.
|
||
- The WebAssembly API keeps its existing defaults; this is a CLI option only.
|
||
|
||
## Troubleshooting
|
||
|
||
- If the shell cannot find `pcb` after installation, restart the shell or
|
||
source the environment file printed by the installer.
|
||
- If `pcb layout` cannot find KiCad, install `kicad-cli` and `pcbnew`. Set
|
||
`KICAD_CLI` or `KICAD_PCBNEW` if either executable is outside its default
|
||
platform path.
|
||
- Installers register `diode://` links for opening registry layouts in KiCad.
|
||
If opening fails, check `~/.pcb/pcb-launcher.log` (Windows:
|
||
`%USERPROFILE%\.pcb\pcb-launcher.log`). `./install.sh --local` registers the
|
||
local toolchain; release installation or `pcb self update` restores `latest`.
|
||
- Run `pcb help` or `pcb help <command>` for the complete CLI reference.
|