Development Guide

Installation for Development Use

Just as for normal use, you need to install all packages into the Poetry environment:

poetry install

Tip

Consider setting your Poetry cache directory somewhere else than the default if you have limited space!

We recommend sourcing the environment. Usually, its location can be found by running poetry env info. If you have issues here, please check out the Poetry documentation.

Now that the environment is sourced:

1. In your IDE of choice (e.g., VS Code), select the interpreter from the environment for your workspace
2. This ensures you get the correct hints and autocompletes

If you need to edit another package as part of your development, change the package to editable in the pyproject.toml. Further information is found in the Poetry documentation.

Before running FINN+ for the first time, we recommend running:

finn config create .

This creates a template config in your cloned FINN+ repository. In this configuration, set:

FINN_DEPS: ./deps

This places all dependencies local to your FINN+ repository, enabling you to work on multiple FINN versions simultaneously. If you don't plan on changing dependencies, you can leave this to the default value to maintain a single shared dependency directory.

If you want your temporary build files to stay local to your repository as well, add the absolute path to your settings.yaml:

FINN_BUILD_DIR: <path>

For more information about configuration, check the Settings wiki page.

You can now start finn using:

finn run build.py

# or

finn build cfg.yaml model.onnx

Prerequisites

Before starting to do development on FINN it is a good idea to start with understanding the basics as a user. Going through all of the Tutorials is strongly recommended if you haven’t already done so. Additionally, please review the documentation available on Internals.

Repository structure

The figure above gives a description of the repositories used by the FINN project, and how they are interrelated.

Branching model

All of the FINN repositories mentioned above use a variant of the GitHub flow from https://guides.github.com/introduction/flow as further detailed below:

• The master or main branch contains the latest released version, with a version tag.
• The dev branch is where new feature branches get merged after testing. dev is “almost ready to release” at any time, and is tested with nightly Jenkins builds – including all unit tests and end-to-end tests.
• New features or fixes are developed in branches that split from dev and are named similar to feature/name_of_feature. Single-commit fixes may be made without feature branches.
• New features must come with unit tests and docstrings. If applicable, it must also be tested as part of an end-to-end flow, preferably with a new standalone test. Make sure the existing test suite (including end-to-end tests) still pass. When in doubt, consult with the FINN+ maintainers.
• When a new feature is ready, a pull request (PR) can be opened targeting the dev branch, with a brief description of what the PR changes or introduces.
• Larger features must be broken down into several, smaller PRs. If your PRs have dependencies on each other please state in which order they should be reviewed and merged.

Linting

We use a pre-commit hook to auto-format Python code and check for issues. See https://pre-commit.com/ for installation. Once you have pre-commit, you can install the hooks into your local clone of the FINN+ repo:

pre-commit install

Every time you commit some code, the pre-commit hooks will first run, performing various checks and fixes. In some cases pre-commit won’t be able to fix the issues and you may have to fix it manually, then run git commit once again. The checks are configured in .pre-commit-config.yaml under the repo root.

Debugging FINN+

To enable debug mode for the FINN+ command line interface:

FINN_DEBUG=1 finn <your-command>

When building custom steps and transformations:

• Use the debug environment variable for basic output
• For more detailed logging, enable the verbose flag in the DataflowBuildConfig

FINN+ Execution Flow

When you run the finn command, the system performs several initialization steps:

1. Entry point: src/finn/interface/run_finn.py initializes the execution
2. Configuration: System reads settings.yaml files (local and global)
3. Dependencies resolution:
   • Poetry dependencies (from pyproject.toml)
   • External dependencies (configured in src/finn/interface/manage_deps.py)
4. Environment setup:
   • FINN_DEPS: Points to dependency location
   • FINN_BUILD_DIR: Specifies where generated files are stored

After initialization, the system:

1. Creates a DataflowBuildConfig object
2. Starts the build flow

Warning

During testing, finn is not called directly. See the VS Code Integration section for testing-specific setup.

VS Code Integration

Environment Setup

Create an .env file with the following variables:

FINN_ROOT             # Your repository path
FINN_BUILD_DIR        # Temporary files location (e.g., /tmp/FINN_TEST_BUILD_DIR)
FINN_DEPS             # Dependency location
NUM_DEFAULT_WORKERS   # Number of parallel transformation workers
VIVADO_PATH           # Path to Vivado (e.g., .../Vivado/2023.1)
VITIS_PATH            # Path to Vitis
HLS_PATH              # Path to Vitis HLS

Tip

See the Settings wiki page for detailed information about these variables.

Important

Run finn deps update at least once manually before testing, as the test setup doesn't automatically fetch dependencies.

Important

FINN_BUILD_DIR determines where test-generated files are placed. Consider the resolution order.

Debugging Configuration

Configure VS Code's debugger by adding this to .vscode/launch.json:

{
    "name": "Python Debugger: Run FINN",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/src/finn/interface/run_finn.py",
    "console": "integratedTerminal",
    "args": "${command:pickArgs}",
    "subProcess": true
}

Testing Configuration

Tests are vital to keep FINN+ running. All the FINN+ tests can be found in the test folder. These tests can be roughly grouped into three categories:

• Unit tests: targeting unit functionality, e.g. a single transformation. Example: tests/transformation/streamline/test_sign_to_thres.py tests the expected behavior of the ConvertSignToThres transformation pass.
• Small-scale integration tests: targeting a group of related classes or functions that to test how they behave together. Example: tests/fpgadataflow/test_convert_to_hls_conv_layer.py sets up variants of ONNX Conv nodes that are first lowered and then converted to FINN HLS layers.
• End-to-end tests: testing a typical ‘end-to-end’ compilation flow in FINN, where one end is a trained QNN and the other end is a hardware implementation. These tests can be quite large and are typically broken into several steps that depend on prior ones. Examples: tests/end2end

Additionally, qonnx, brevitas and finn-hlslib also include their own test suites.

Configure VS Code to use pytest by adding this to .vscode/settings.json:

"python.testing.pytestArgs": [
    "tests",
    "src/finn/transformation/fpgadataflow",
    "-n",
    "10",
    "--doctest-modules"
],
"python.testing.unittestEnabled": false,
"python.testing.pytestEnabled": true,

Important

Settings in .vscode/settings.json override your pyproject.toml testing settings. Update both when changing test configurations.

Test Environment Variables

Control test execution with these environment variables:

• FINN_TESTS_ISOLATE_BUILD_DIRS (default: 1)

  • When set to 1, creates a separate directory for each test
  • Example: /tmp/FINN_TESTS/test_operator_a, /tmp/FINN_TESTS/test_operator_b, etc.
  • During the test, FINN_BUILD_DIR points to the test-specific directory

• FINN_TESTS_CLEANUP_BUILD_DIRS (default: 0)

  • When set to 1, removes the test build directory after execution
  • Requires FINN_TESTS_ISOLATE_BUILD_DIRS=1
  • Set to 0 by default to allow post-test debugging