If you want to run the bootcamp locally, follow the instructions below for your platform. If something fails, docs/troubleshooting.md has the errors seen so far and their fixes.
Note: Java 17 or later is recommended (Java 11 also works). If you have multiple Java versions installed, select the appropriate version before running jupyter notebook:
- On Windows: https://gist.github.com/rwunsch/d157d5fe09e9f7cdc858cec58c8462d6
- On macOS: https://stackoverflow.com/questions/21964709/how-to-set-or-change-the-default-java-jdk-version-on-os-x
Make sure you have Docker installed on your system, or alternatively nerdctl for a Docker-compatible CLI.
The sysprog21/chisel-bootcamp image supports both x86-64 and Arm64 architectures. It bundles:
- Alpine Linux 3.22 with OpenJDK 17
- Scala 2.13.18 with Almond 0.14.5 kernel
- Chisel 7.16.0 and CIRCT firtool 1.160.0 (preinstalled, so the image also works offline)
- Verilator and a C++ toolchain, used by ChiselSim to simulate designs
- sbt 1.13.1 with the dependencies of the
riscv/project preloaded (see below) - Jupyter Lab
- Graphviz for circuit visualization
Run the container:
Using Docker:
docker run -it --rm -p 8888:8888 sysprog21/chisel-bootcampUsing nerdctl:
nerdctl run -it --rm -p 8888:8888 sysprog21/chisel-bootcampThe container starts Jupyter Lab (not classic Jupyter Notebook). Look for output like:
To access the server, open this file in a browser:
file:///home/bootcamp/.local/share/jupyter/runtime/jpserver-7-open.html
Or copy and paste one of these URLs:
http://d77238b933b7:8888/lab?token=TOKEN_HERE
http://127.0.0.1:8888/lab?token=TOKEN_HERE
Copy the last URL (starting with http://127.0.0.1:8888/lab) into your browser to access the bootcamp.
This bootcamp uses Jupyter notebooks. Jupyter notebooks allow you to interactively run code in your browser. It supports multiple programming languages. For this bootcamp, we'll install jupyter first and then the Scala-specific jupyter backend (now called almond).
On Ubuntu 24.04 or newer, tools/install.sh (run from a clone of the repository) does every step of
this section; the rest describes them by hand, for other systems.
First install Jupyter.
Dependencies: curl, openssh-client, openjdk-17-jre (-headless OK), ca-certificates-java, Verilator 5.026 or newer, a C++ compiler (g++ or clang++) and make
Install Jupyter with pip (see Jupyter installation docs), in a Python virtual environment where the system's Python refuses packages installed with pip (as on Ubuntu 24.04):
python3 -m venv ~/.local/share/chisel-bootcamp/venv && source ~/.local/share/chisel-bootcamp/venv/bin/activate
pip install --upgrade pip
pip install jupyter
(To reinstall jupyter later for whatever reason, you can use --no-deps to avoid re-installing all the dependencies.)
The jupyter package includes JupyterLab, the newer interface developed by Project Jupyter, which
can also run a terminal emulator in your browser.
If you experience errors or issues with this section, try running rm -rf ~/.local/share/jupyter/kernels/scala/ first.
Download coursier and use it to install Almond (see Almond installation docs for details):
curl -L -o coursier https://github.com/coursier/coursier/releases/download/v2.1.24/coursier
echo "7aa975f12469726d6bb87852107afe0b8d6f3c82b12a49ef43cc6647c4e057ca coursier" | sha256sum -c -
# without sha256sum (as on macOS), end the line above with `| shasum -a 256 -c -` instead
chmod +x coursierChisel 7 needs Scala 2.13, so ask for that Scala version explicitly (the notebooks use Scala 2.13.18):
./coursier bootstrap -r jitpack sh.almond:scala-kernel_2.13.18:0.14.5 --default=true -o almond
./almond --installYou can delete the coursier and almond files afterward if desired.
Chisel simulates designs with ChiselSim (documentation), which runs Verilator and compiles the result with a C++ compiler.
Use Verilator 5.026 or newer: older 5.x releases intermittently abort with "attempted to destroy locked Thread Pool" while ChiselSim compiles a design. On macOS, brew install verilator is new enough; Ubuntu 24.04's package (5.020) is not, and tools/install.sh builds a newer one there.
Check with verilator --version.
Chisel also needs CIRCT's firtool to generate SystemVerilog. You don't have to install it: Chisel downloads the matching version on first use (this needs Internet access once).
You can also point the CHISEL_FIRTOOL_PATH environment variable at a directory that contains firtool 1.160.0.
On Linux/Arm64 (outside Docker) there is no firtool for Chisel to download: Maven Central has firtool
for Linux x86-64, macOS and Windows only. tools/install.sh sets up the x86-64 one under qemu-user,
as the Docker image does (firtool is slower there), and points CHISEL_FIRTOOL_PATH at it.
Module 5.9 proves a property with Yosys, run as yosys. The Docker
image installs YoWASP's build (Yosys compiled to WebAssembly); locally, install either your
system's yosys (for example sudo apt install yosys or brew install yosys) or the same build
with pip install yowasp-yosys (riscv.Formal runs yosys, or else yowasp-yosys). Without
it, the formal-check cells of 5.9 print that Yosys is not installed, and its other cells still run.
Graphviz is required to show visualizations of Chisel modules, such as in the demo page. However, visualizations are optional as the other Chisel and Scala features will work without it.
Now clone the bootcamp repo and install the customization script. If you already have one, append this script to it.
git clone https://github.com/sysprog21/chisel-bootcamp.git
cd chisel-bootcamp
mkdir -p ~/.jupyter/custom
cp source/custom.js ~/.jupyter/custom/custom.js
And to start the bootcamp on your local machine:
jupyter notebook
If you installed Jupyter Lab, run jupyter-lab instead.
These instructions cover Windows 10 and later. Running the command prompt in Administrator Mode is recommended for installation steps.
Ensure Java 17 or later is installed. Test by typing java -version in a command prompt. If not found, install from Adoptium.
Jupyter recommends using the Anaconda distribution, here is the Windows download.
Near the end of the Jupyter installation is a question about whether to add Jupyter to the PATH. Windows does not recommend this, but I do. It will make it easier to run using the command prompt.
If you did not elect to add Jupyter to the PATH, start a prompt using the "Anaconda Prompt (Anaconda3)" shortcut from the Start Menu.
Download Coursier from GitHub releases.
Navigate to your download folder and run:
java -jar coursier bootstrap -r jitpack sh.almond:scala-kernel_2.13.18:0.14.5 --default=true -o almond
java -jar almond --installChisel's simulations need Verilator, which is not available natively on Windows. Install and use the bootcamp inside WSL 2 (follow the Linux instructions there) or use the Docker image.
Graphviz is required to show visualizations of Chisel modules, such as in the demo page. However, visualizations are optional as the other Chisel and Scala features will work without it.
Download the chisel-bootcamp as a zip file (or use a Windows git client) and unpack it in a directory you have access to. Ideally, you should put it in a path that has no spaces.
Install the customization script by moving chisel-bootcamp/source/custom.js to
%HOMEDRIVE%%HOMEPATH%\.jupyter\custom\custom.js.
If you already have a custom.js file, append this script to it.
In the directory containing the unpacked chisel-bootcamp repo, from a new command window type:
jupyter notebookThis should start the bootcamp server and open a top page bootcamp menu in your default browser. If it does not look for the something like the following in the command window and copy and paste the link you see into a browser window.
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://localhost:8888/?token=9c503729c379fcb3c7a17087f05462c733c1733eb8b31d07If you require a proxy, try uncommenting and changing the relevant lines at the start of source/load-ivy.sc.
Module 5 builds a RISC-V processor in an sbt project under riscv/. In the Docker image, sbt and
everything the project needs are preinstalled, so it works offline. Open a terminal in Jupyter Lab
(or docker exec -it <container> bash) and run:
cd riscv
sbt test # compile and run every test (ChiselSim tests need Verilator)
sbt "testOnly riscv.IsaSpec"
sbt "testOnly riscv.MemorySpec -- -DemitVcd=1" # also dump each simulation's waveform (VCD) under build/
# assemble a test program into the memory image that the processors load
sbt "runMain riscv.Asm programs/src/fib.S programs/hex/fib.hex"The programs are RV32I assembly, assembled by the project's own assembler (riscv.Asm); no RISC-V
compiler is needed (see riscv/DESIGN.md).
Outside Docker, install sbt (any 1.x launcher; the project
pins its sbt version in riscv/project/build.properties), Java 17 or later (a runtime is enough: the project has no Java sources, and the image has only
the Java 17 runtime),
and Verilator 5.026 or newer as described above (tools/install.sh installs all of them on Ubuntu, in its Python environment: activate it before running sbt); the first sbt run downloads the dependencies.
The image has no network access to fetch more: changing scalaVersion or adding a dependency to
riscv/build.sbt makes the offline sbt fail. Run such builds with network access.
Good Luck!