Apio Developer Environment¶

This page explains how to set up the Apio development environment. If you just want to quickly test the latest development version of Apio, install Python and run the following command:

pip install --force-reinstall -U git+https://github.com/FPGAwars/apio.git@develop

For a specific commit, replace develop with the commit's SHA.

The rest of the page describes the settings for the Apio development environment.

Fork the Apio repository¶

The first step in developing for Apio is to fork the Apio repository. This will allow you to run the GitHub test workflow before submitting your pull request. In the rest of this document, we assume that you have forked the Apio repository and cloned it locally on your computer.

Install the 'Invoke' tool¶

Apio development tasks are defined in the file tasks.py which is executed by the invoke command. To install the invoke command run

pip install invoke

Test it by listing the available tasks

invoke --list

Install your cloned Apio¶

The easiest way to develop Apio is to install its source code from your local repo as the Pip apio package. This will allow you to test your edited code by running apio from the command line.

To install the Apio source code as the Pip apio package, run these command in the root directory of the Apio repository:

invoke install-apio

From this point on, when you run apio, it will run the source code in your cloned repo, including any changes you may have.

Test your changes locally¶

Before creating a commit, test your code locally by running this in the repo root directory:

invoke test
invoke t   # Shortcut, same as above.

During debugging, it is sometimes useful to run quick partial tests before running invoke check. Here are some examples:

# Run linters only
invoke lint
invoke l   # Shortcut, same as above.

# Run the fast tests only and skip the rest. Note that even in fast mode,
# the first test may require to fill in the packages cache which may take
# a minute or two.
invoke test-fast
invoke tf   # Shortcut, same as above.

# Run a single test file with verbose info
pytest -vv -s test/managers/test_project.py

# Run a single test with verbose info
pytest -vv -s test/managers/test_project.py::test_first_env_is_default

Clearing the pytest cache¶

The Apio pytest use a shared cache for the downloaded apio packages to speed up the tests, otherwise, almost each test would require to download the packages from scratch. The cache is persisted across test invocations to minimize the tests initialization time. To start a test session from scratch, clear the pytest cache using the following command:

# Clear the pytest test cache. This is seldom requires.
invoke clear-cache
invoke cc   # Shortcut, same as above.

Generate a test coverage report.¶

You can generate a report with the line by line coverage of the tests by running

invoke coverage-report
invoke cr   # Shortcut, same as above.

This will update the page _pytest-coverage/index.html with the latest coverage information.

The directory _pytest-coverage is ignored by git and is not checked in with apio.

Confirm that the test workflow passes¶

Once you are ready to send a pull request from your forked repository, make sure that the test workflow completed successfully. You can find it in the Actions tab of your forked repo.

The test workflow tests the develop branch, so if you worked on your own branch, merge it with develop first.

Using `APIO_DEBUG` to print verbose debug information¶

Debug information can be printed by defining the env var APIO_DEBUG with an int value in the range 1 (minimal debug info) to 10 (verbose debug info).

# Linux and Mac OSX
export APIO_DEBUG=1   # Minimal debug info
export APIO_DEBUG=3   # More debug info

# Windows
set APIO_DEBUG=1
set APIO_DEBUG=3

Debugging with Visual Studio Code¶

The file .vscode/launch.json contains debugging targets for the Visual Studio Code (VSC) debugger. To use them, make sure that you open the Apio project at its root directory and select the desired VSC debugging target. To customize the targets for your specific needs, click on the Settings icon (wheel) near the debugging target and edit its definition in launch.json (do not submit changes to launch.json unless they will benefit other developers).

Since Apio launches Scons as a subprocess, debugging the Scons code requires a different approach using these steps:

Set the environment variable APIO_SCONS_DEBUGGER to cause Scons to wait for the debugger (in apio/scons/SConstruct).
Set your desired breakpoints in the Scons part of Apio.
From the command line, run the Apio command that invokes the Scons subprocess (e.g., apio build).
In the VSC debugger, start the target Attach remote debugger.

Apio remote config during testing¶

Apio retrieves its package information from a remote config .jsonc file whose URL is stored in apio/resources/config.jsonc. During automated testing it is overridden to point to the local copy of the config file in case it was modified in the local repository. ```