===============
Getting Started
===============

This page gets a fresh machine (tested on Ubuntu 24.04) ready to run the
Flow A pipeline described in :doc:`flow-a-overview`. It condenses the setup
steps from the repository's top-level ``README.md``; see that file for the
full troubleshooting table.

Every tool below lives in its own environment (venv or sourced shell
script) and **must be (re-)activated in every new terminal session** before
use.

1. FuseSoC
==========

FuseSoC is the package/build manager that reads a design's ``.core`` file
and dispatches simulation/synthesis to the right backend (Edalize).

.. code-block:: sh

   sudo apt install python3-pip python3-venv iverilog

   python3 -m venv ~/fusesoc-venv
   source ~/fusesoc-venv/bin/activate

   pip install --upgrade fusesoc
   fusesoc --version

If ``fusesoc tool list`` fails with
``ImportError: cannot import name 'walk_tool_packages' from 'edalize.edatool'``,
the auto-installed Edalize is out of sync with FuseSoC — fix with
``pip install --upgrade edalize``.

Validate the install with FuseSoC's own "blinky" example (the "hello
world" of this pipeline — it doesn't test a real design, it just proves
core file → FuseSoC → simulator → result works):

.. code-block:: sh

   git clone https://github.com/olofk/fusesoc.git
   cd fusesoc/tests/userguide/blinky
   fusesoc --cores-root . run --target=sim fusesoc:examples:blinky

All 10 "Pulse N/10 OK!" lines passing confirms the toolchain works
end-to-end.

2. oss-cad-suite (Yosys, Icarus, Verilator, GTKWave, nextpnr, ...)
===================================================================

.. code-block:: sh

   wget https://github.com/YosysHQ/oss-cad-suite-build/releases/download/<date>/oss-cad-suite-linux-x64-<date>.tgz
   tar xzf oss-cad-suite-linux-x64-<date>.tgz
   source oss-cad-suite/environment
   yosys -V

``source oss-cad-suite/environment`` must be re-run every new terminal
session, same as the FuseSoC venv.

3. OpenROAD
===========

Build from source (a Bazel build, ~installs to ``../install/OpenROAD``):

.. code-block:: sh

   git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD.git
   cd OpenROAD
   sudo ./etc/DependencyInstaller.sh -base
   ./etc/DependencyInstaller.sh -common -local
   ./etc/Build.sh

   echo 'export PATH="$HOME/thesis/tools/install/OpenROAD/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   openroad -version

4. KLayout
==========

.. code-block:: sh

   wget https://www.klayout.org/downloads/Ubuntu-22/klayout_<version>-1_amd64.deb
   sudo apt install ./klayout_<version>-1_amd64.deb
   klayout -v

5. PDK (Sky130, via ciel)
==========================

``ciel`` is the PDK version manager used to fetch and pin a specific
``open_pdks``-built revision of the PDK. It is what LibreLane and
Edalize's ASIC backend expect ``PDK_ROOT``/``PDK`` to point at.

.. code-block:: sh

   python3 -m venv ~/pdk-venv
   source ~/pdk-venv/bin/activate
   pip install --upgrade ciel

   export PDK_ROOT="$HOME/thesis/tools/pdk"
   mkdir -p "$PDK_ROOT"
   echo 'export PDK_ROOT="$HOME/thesis/tools/pdk"' >> ~/.bashrc

   ciel ls-remote --pdk-family sky130
   ciel enable --pdk-family sky130 <commit-hash>

   export PDK=sky130A
   echo 'export PDK=sky130A' >> ~/.bashrc

This creates ``$PDK_ROOT/sky130A`` containing ``libs.ref`` (Liberty, LEF,
GDS, SPICE, Verilog views per standard-cell library) and ``libs.tech``
(per-tool tech setup: ``klayout/``, ``magic/``, ``librelane/``,
``ngspice/``) — the layout every stage of the flow expects. See
:doc:`pdk-portability` for what to do when this PDK is **not** Sky130
(e.g. a closed 55 nm node for Flow B).

6. Bender (multi-file / multi-module designs)
================================================

Bender is a dependency/file-list manager. ``myfir`` (a single RTL file)
never needed it, but any design with more than one source file does —
see :doc:`running-your-own-design`. Bender needs a Rust toolchain:

.. code-block:: sh

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source ~/.cargo/env

   cargo install bender
   bender --version

7. Verify the ``read_slang`` SystemVerilog frontend
======================================================

Synthesis (:doc:`running-your-own-design`) uses Yosys's ``read_slang``
command (also known as yosys-slang / sv-elab) to parse SystemVerilog
directly, including multi-file/multi-package designs. It is **not**
guaranteed to be bundled in every oss-cad-suite release — verify it
explicitly rather than assuming:

.. code-block:: sh

   yosys -p 'plugin -i slang; help read_slang' | tee /tmp/slang_check.log
   echo "exit code: ${PIPESTATUS[0]}"

Expect the full ``read_slang`` option list to print and exit code
``0``. Do **not** pipe this through ``head`` or run it with Yosys's
``-qq`` flag "to check quickly" — both suppress the error text that
would distinguish a real plugin-load failure from a genuine success,
making the two look identical. If it fails, this oss-cad-suite build
doesn't bundle the plugin — see https://github.com/povik/sv-elab for a
from-source build before continuing.

Environment checklist
======================

Before running anything, every new terminal needs:

.. code-block:: sh

   source ~/fusesoc-venv/bin/activate
   source ~/thesis/tools/oss-cad-suite/environment
   echo "$PDK_ROOT"; echo "$PDK"
   which openroad; which yosys; which iverilog; which klayout; which bender

If any of these come back empty, re-source the relevant environment
script or re-check ``~/.bashrc``.