Naja

What is Naja?

Naja is an open source EDA framework for loading, elaborating, analyzing, optimizing, and transforming hardware designs from RTL SystemVerilog through structural netlists. It is usable from Python or C++.

• SV/Verilog frontend — parse Verilog and elaborate SystemVerilog RTL into a browsable design model
• Netlist analysis — hierarchy, connectivity, equipotentials
• Logic optimization — dead logic elimination, constant propagation
• ECO transformations — direct netlist editing
• Serialization — SNL interchange format (Cap'n Proto) and Verilog output

Get Started

The best entry point is the najaeda Python package:

pip install najaeda

Full documentation: najaeda.readthedocs.io

For AI-assisted design exploration, naja-scope is a najaeda-based MCP server that gives MCP-compatible assistants a precise, structured view of elaborated SystemVerilog designs. Instead of pasting large RTL files into chat, agents can ask targeted questions — what drives a signal, what is inside a module, where a net comes from — and get small, exact answers with file-and-line references.

Tutorials

Six hands-on notebooks — open any of them in Colab with no local install needed:

#	Topic	Colab
1	Getting started — load Verilog, navigate hierarchy, visualize
2	Liberty primitives — load a synthesised design with standard cells
3	Editing a netlist — rename, disconnect, reconnect, delete
4	SystemVerilog elaboration — load and browse an elaborated SV design
5	ibex RISC-V core — explore a real-world SV core, collect stats
6	Fanout analysis — compute fanout for every net, trace drivers, export to pandas

naja_edit — Netlist CLI

naja_edit is a command-line tool for optimizing and translating netlists.

📺 Presented at ORConf 2024.

# Translate Verilog → SNL
naja_edit -f verilog -t snl -i input.v -o output.snl

# Parse SystemVerilog with explicit top
naja_edit -f systemverilog -t verilog -i input.sv -o output.v --sv_top top

# Dead logic elimination
naja_edit -f snl -t snl -i input.snl -o output.snl -a dle

# Chain optimizations with Python scripts
naja_edit -f snl -t snl -i input.snl -o output.snl -a dle -e pre.py -z post.py

Available optimizations (-a): all (DLE + constant propagation + primitives), dle.

Python script examples: src/apps/naja_edit/examples
Regression suite: naja-regress

Building from Source

CMake is Naja's primary build, test, and install workflow. Bazel is maintained as a build-and-test smoke path; it does not replace the CMake install and packaging workflows.

CMake

Dependencies

Ubuntu:

sudo apt-get update
sudo apt-get install build-essential cmake git libboost-dev python3-dev \
  capnproto libcapnp-dev libtbb-dev pkg-config bison flex

macOS (Homebrew):

brew install cmake capnp tbb bison flex boost
export PATH="/opt/homebrew/opt/flex/bin:/opt/homebrew/opt/bison/bin:$PATH"

Nix:

nix-shell -p cmake gnumake boost python3 capnproto bison flex pkg-config tbb_2021_8

Build, test, and install

git clone --recurse-submodules https://github.com/najaeda/naja.git
cd naja
export NAJA_INSTALL="$PWD/install"
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$NAJA_INSTALL"
cmake --build build --parallel
ctest --test-dir build --output-on-failure
cmake --install build

# Add the installed Python package to your environment.
export PYTHONPATH="${PYTHONPATH:+$PYTHONPATH:}$NAJA_INSTALL/lib/python"

Bazel smoke build

The Bazel build covers the repository's build and test targets on Ubuntu and macOS. The version is pinned in .bazelversion; using Bazelisk as the bazel command automatically selects it.

Bazel fetches its own pinned copies of the shared source dependencies, so a Bazel-only checkout does not need Git submodules. It still uses system toolchains and libraries for parts of the build.

Ubuntu:

sudo apt-get update
sudo apt-get install build-essential cmake libboost-dev libfl-dev libtbb-dev \
  bison flex m4 pkg-config python3-dev git

macOS (Homebrew):

Install the Xcode Command Line Tools, then:

brew install cmake capnp tbb bison flex boost fmt tomlplusplus pkg-config
export PATH="$(brew --prefix flex)/bin:$(brew --prefix bison)/bin:$PATH"

Build and test from the repository root:

git clone https://github.com/najaeda/naja.git
cd naja
bazel build //... --jobs=auto
bazel test //... --test_output=errors --jobs=auto

These are the same smoke commands used by ubuntu-bazel.yml and macos-bazel.yml. There is no Bazel install target; use the CMake workflow above when you need an installed library, Python package, or packaged artifact.

When changing a shared dependency pin, keep the Git submodule and MODULE.bazel entries synchronized, then run:

python3 ci/check_submodule_bazel_sync.py

C++ API

Naja exposes two complementary APIs:

• SNL (Structured Netlist) — full read/write netlist representation
• DNL (Dissolved Netlist) — fast, read-only flattened view for parallel analysis

Extended documentation: naja.readthedocs.io
C++ snippet: NLUniverseSnippet.cpp
App template (copy to start a new tool): src/app_snippet

Community

• Chat: Matrix #naja:fossi-chat.org
• Bugs / features: GitHub Issues
• Contact: contact@keplertech.io

⭐ If you find Naja useful, starring the repo helps spread the word.

Acknowledgement

Supported by NLNet through the NGI0 Entrust Fund.