Module 0: Installation & Environment Setup¶

Module Objective

Establish a fully reproducible ASIC physical design environment and verify end-to-end toolchain functionality before beginning the design flow.

Table of Contents¶

Overview
Installing Nix
- 2.1 Installation Guides by OS
- 2.2 Why Nix?
Invoking the Environment
Verification & Smoke Test
- 4.1 Version Check
- 4.2 Running the Smoke Test
Cloning the Project Repositories

1. Overview¶

This module walks you through the complete setup of your ASIC development environment. You will install the necessary dependencies for hardening the AES-128 core, configure the LibreLane toolchain, and verify the environment is fully operational before proceeding to the design modules.

By the end of this module, you will have:

A working Nix-managed ASIC toolchain (Yosys, OpenROAD, Magic, KLayout, Netgen).
The SkyWater 130nm PDK downloaded and verified.
Both workshop repositories cloned and accessible on your machine.

2. Installing Nix¶

Warning

Do not install Nix using apt. The version distributed via apt is outdated and will cause compatibility failures with the LibreLane environment. Always use the official installer described below.

Nix requires curl to download the installer. Install it first:

$ sudo apt-get install -y curl

Then install Nix using the official Determinate Systems installer:

$ curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install \
    --prefer-upstream-nix \
    --no-confirm \
    --extra-conf "
        extra-substituters = https://nix-cache.fossi-foundation.org
        extra-trusted-public-keys = nix-cache.fossi-foundation.org:3+K59iFwXqKsL7BNu6Guy0v+uTlwsxYQxjspXzqLYQs=
    "

Enter your system password if prompted. The installation typically takes a few minutes.

Required Action After Installation

Close all open terminal windows and open a new one before continuing. Nix modifies your shell configuration, and the changes only take effect in a fresh session.

2.1 Installation Guides by OS¶

Select the guide corresponding to your operating system:

Operating System	Guide
Ubuntu / Linux	Installation on Ubuntu/Linux
Windows 10+ (WSL2)	Installation on Windows via WSL2
macOS 11+	Installation on macOS

2.2 Why Nix?¶

Reproducibility is a foundational requirement in ASIC design flows. Nix creates an isolated and deterministic development environment where every tool is pinned to a fixed, verified version.

This ensures the entire flow — from RTL synthesis with Yosys through layout generation with Magic — executes identically on every machine, eliminating the common failure mode where a design passes on one workstation but breaks on another due to differing tool versions.

Note

The Nix shell does not modify your global system. All tools are contained within the managed environment and disappear when you type exit. Your system remains clean.

3. Invoking the Environment¶

Once Nix is installed, you will work inside a Nix shell — an isolated virtual environment containing all specialized ASIC tools without polluting your global system installation.

Before cloning the required repositories, ensure Git is installed on your system:

$ sudo apt install git

Step 3.1 — Clone the LibreLane Repository¶

Clone the LibreLane infrastructure into your home directory:

$ git clone https://github.com/librelane/librelane/ ~/librelane

Step 3.2 — Initialize the Nix Shell¶

Load all LibreLane packages into your current terminal session:

$ nix-shell --pure ~/librelane/shell.nix

First-Run Download

On the first execution only, Nix will download approximately 3 GB of tool packages. Ensure you have a stable internet connection before proceeding. Subsequent shell launches will use the local cache and start in seconds.

Once the download completes, your terminal prompt will change to confirm you are inside the managed environment:

[nix-shell:~]$

All librelane commands in subsequent modules must be run from within this shell.

4. Verification and Smoke Test¶

With the Nix shell active, verify the toolchain installation and download the SkyWater 130nm PDK.

Step 4.1 — Version Check¶

Confirm the environment is correctly loaded by querying the LibreLane version:

[nix-shell:~]$ librelane --version

A version string should be printed to the terminal. If this command fails, do not proceed — revisit Section 3.3.

Step 4.2 — Running the Smoke Test¶

The smoke test performs a minimal end-to-end flow run and simultaneously downloads the SkyWater 130nm PDK to your local cache.

[nix-shell:~]$ librelane --log-level ERROR --condensed --show-progress-bar --smoke-test

After completing the smoke test — or any work session with the ASIC tools — exit the Nix environment and return to your standard terminal by running:

[nix-shell:~]$ exit

This cleanly releases the managed environment. Your system is unchanged.

Expected Outcome

A successful smoke test will print a short summary report with no errors. The Sky130 PDK is now cached locally and will be available for all subsequent runs without re-downloading.

5. Cloning the Project Repositories¶

clone both repositories required for this workshop.

Step 1 — Clone the Silicon-Sprint-AUC Project¶

This repository contains the Carvel user project template pre-configured for the LibreLane flow:

$ git clone https://github.com/basemhesham/Silicon-Sprint-AUC ~/Silicon-Sprint-AUC

Step 2 — Clone the AES Source Code¶

This repository contains the AES-128 RTL implementation that will be hardened during the workshop:

$ git clone https://github.com/secworks/aes ~/secworks_aes

Step 3 — Verify the Directory Structure¶

Confirm that both repositories were cloned successfully:

$ ls -d ~/Silicon-Sprint-AUC ~/secworks_aes

Expected output:

/home/<user>/Silicon-Sprint-AUC
/home/<user>/secworks_aes

Module Complete

Both repositories are now present on your machine. Your environment is fully configured and ready for Module 1: RTL Integration & ASIC Flow.

Proceed to the next module only after confirming:

✅ librelane --version returns a version string inside the Nix shell.
✅ The smoke test completed without errors.
✅ Both repository directories exist in your home folder.

PDK¶: Process Design Kit. A collection of files provided by a semiconductor foundry (in this case, SkyWater) that describes the electrical and physical properties of the manufacturing process, including standard cell libraries, design rules, and SPICE models.