# Developer Guide

## Python virtual environment

The minimum supported version of Python is 3.10, as stated in the
[user guide](user-guide.md#dependencies--installation).

We suggest creating a Python virtual environment to install the dependencies
for development.

- To create a Python virtual environment:
```sh
$ python3 -m venv .venv
```
 - Once it is created, you can activate it:
```sh
$ source .venv/bin/activate
```
 - pip version 25.1 or later is required to install development tool
   dependencies, if needed, update it:
```sh
(.venv) $ pip install --upgrade pip
```

## Documentation generation

The documentation sources are in `docs`. To build them using Sphinx, run
the following commands:

 - First create a [Python virtual environment](#python-virtual-environment)
   and update pip.
 - Install the dependencies to generate this documentation in your Python
   virtual env:
```sh
(.venv) $ cd sbom-cve-check
(.venv) $ pip install --group docs
```
 - You can now build the docs in HTML, from the `docs` directory:
```sh
(.venv) $ cd sbom-cve-check/docs
(.venv) $ make html
```
 - The generated documentation will be available under
   `docs/_build/html/index.html`.


The command below, executed from the `docs` directory, could be used to watch
for any file changes under the `docs` directory and rebuild the documentation
automatically:

```sh
while sleep 1 ; do make clean; find -name '*.md' | entr -d make html ; done
```

## Tool installation for development

For normal use of the tool, it should be installed as described in the
[user guide](user-guide.md#dependencies--installation).

As an alternative, only the dependencies could be installed, and we could use
the `src/sbom-cve-check.py` executable. But for development purposes, it is
instead highly recommended to "install" the tool using the `--editable` flag:
```sh
(.venv) $ pip install -e .
```

For development purposes, to "install" it with all optional dependencies, run:
```sh
(.venv) $ pip install -e .[extra]
```

## Linter and static analysis

First create a [Python virtual environment](#python-virtual-environment),
if not already done, and update *pip*.

Then, to install the tools, run:
```sh
(.venv) $ pip install --group lint
```

It may be necessary to install the various dependencies, for example using:
```sh
(.venv) $ pip install -e .[extra]
(.venv) $ pip install --group test
```

### Ruff

This project uses the [Ruff](https://docs.astral.sh/ruff/) linter.

### mypy

This project uses [mypy](https://mypy.readthedocs.io/en/stable/) for static
type checking.

## Tests

First create a [Python virtual environment](#python-virtual-environment),
if not already done, and update *pip*.

Then, install the tool with all optional dependencies if this is not already
the case. For example run:
```sh
(.venv) $ pip install -e .[extra]
```

Then, to install the test tools, run:
```sh
(.venv) $ pip install --group test
```

To execute the test, run the following command from the `tests` directory:
```sh
pytest -v .
```

To execute the test with the coverage, run the following command from the
`tests` directory:
```sh
pytest -v --run-slow --cov=sbom_cve_check --cov-config=../pyproject.toml .
```
Then, to generate the HTML report, execute:
```sh
coverage html
```

For test troubleshooting, is it possible to define the
`SBOM_CVE_CHECK_TEST_KEEP_TMP` environment variable to `1`. The temporary
directories generated during the tests will not be deleted. Note: to use this
environment variable, at least Python 3.12 is required.

## Roadmap & planned developments

The following features are intended to be developed in the medium term:

- Add support of Ubuntu CVE tracker repository
  - Automatically detect if a patch was backported
- Add CycloneDX (CDX) SBOM support as input.
- Add more export formats, like, for example, OpenVEX.

The following features are intended to be developed in the very long term:

- Allow to generate an SBOM (CDX or SPDX 3.0) as output even if the SBOM
  specified as input is in another format.