Apio CLI Developer Environment¶

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

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

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

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

Fork the Apio CLI repository¶

The first step in developing for Apio CLI is to fork the Apio CLI 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 CLI repository and cloned it locally on your computer.

Install the 'Invoke' tool¶

Apio CLI 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

HINT: You can use the shortcut inv instead of invoke.

Install your cloned Apio CLI¶

The easiest way to develop Apio CLI 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 CLI source code as the Pip apio package, run these command in the root directory of the Apio CLI 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 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

Clean the Apio CLI project¶

The apio directory tree may contain temporary artifacts and caches that were generated by the various command. Use this command to safely clearing them and starting at a clean well define starting point.

# Clean project artifacts and caches.
invoke clean
invoke c    # 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.

The test coverage is also published online at the Test Coverage Report each time a new commit is checked in.

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 main branch, so if you worked on your own branch, merge it with main 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 CLI 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 CLI 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 CLI.
From the command line, run the Apio CLI command that invokes the Scons subprocess (e.g., apio build).
In the VSC debugger, start the target Attach remote debugger.

Apio CLI remote config during testing¶

Apio CLI 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. ```