Getting Started

Setting up a Build Environment

This guide highlights the installation / setup process for the LUNA gateware library. It focuses on getting the Python module (and prerequisites) up and running.


  • Python 3.8, or later.

  • A working FPGA toolchain. We only officially support a toolchain composed of the Project Trellis ECP5 tools, the yosys synthesis suite, and the NextPNR place-and-route tool. You can obtain the latest binary distribution of this software from the oss-cad-suite-build project.

  • A working installation of Amaranth HDL.


Currently, the LUNA library is considered a “work-in-progress”; and thus it’s assumed you’ll want to use a local copy of LUNA for development.

# clone the LUNA repository
git clone

The easiest way to set this up is to install the distribution in your working environment. From the root of the repository:

# Install a copy of our local tools.
pip install .

# Alternatively: install all dependencies,
# including optional development packages (required for running applets and examples).
pip install .[dev]

If you want to install LUNA to your machine globally (not recommended), you can do so using the following single command:

# Create a LUNA package, and install it.
pip install . --user


The easiest way to test your installation is to build one of the test applets. These applets are just Python scripts that construct and program gateware using Amaranth HDL; so they can be run like any other script:

# With GSG or self-built Cynthion hardware connected; we can test both our
# installation and the attached hardware.
python applets/

# Without hardware connected, we'll only build the applet, to exercise
# our toolchain.
python applets/ --dry-run