13. Development Infrastructure

13.1. Packaging and distribution of PEAT

13.1.1. Linux

13.1.1.1. Portable Linux Executable

PyInstaller is used to create a portable executable version of PEAT. The package is portable across distribution versions, e.g. a package built on Ubuntu 18.10 will work on Ubuntu 14.04. This is accomplished by using StaticX to include the system libraries in the package. NOTE: this does NOT work with Pythons installed using pyenv or compiled manually. It must be a system Python, e.g. included in distro or installed with apt or yum.

13.1.1.1.1. Building the executable
# Ensure PDM has initialized venv
pdm install -d

# make sure you have the following dependencies if you run into build issues
sudo apt install -qyf python3-dev patchelf binutils scons libpq-dev libpq5

# Build Linux executable
# This runs staticx to include system libraries and be fully portable.
# This WILL NOT work on Windows, and probably won't work with Mac.
pdm run build-linux-exe

# Test
./dist/peat --version
./dist/peat --help

13.1.2. Windows

13.1.2.1. Windows Portable Executable using PyInstaller

The Windows version of PEAT that’s distributed to end users is a bundled executable file created by PyInstaller. PyInstaller uses a number of files, depending on the options used:

  • peat.spec: Describes the install configuration for PyInstaller

  • file_version_info.txt: File metadata for the resulting .exe

  • tbird.ico: Icon for the resulting .exe

13.1.2.2. Building the Windows EXE on a Windows system

  1. Install a version of Python supported by PEAT: python.org

  2. Install Microsoft Visual C++ 2015 Redistributable Update 3 RC (which provides VCRuntime140.dll)

  3. Open PowerShell and run the build script:

    pdm install -d
pdm run build-exe
.\dist\peat.exe --version

If you wish to build manually step by step, open the build script in a text editor and run the commands individually.

13.1.2.3. Setting up a Windows development environment

How to setup a local Python environment if you will be developing PEAT and need to edit and test the code.

  1. Install Python 3.11 or newer (download from python.org). During install, ensure the option “Add Python to environment variables” or “Add Python to system PATH” is checked (you may need to click “Next” to see this option).

  2. Install Npcap 0.99 or newer (Skip this step if Wireshark, Nmap, or Winpcap is already installed)

  3. Open a PowerShell or Command Prompt window

  4. Run py -3 -V, and verify it is 3.11 or newer.

  5. Install PDM

  6. Run the following commands to setup a development environment:

# Clone the PEAT Git repository
git clone https://github.com/sandialabs/peat.git
cd peat

# Install dependencies and create environment
pdm install -d

13.1.3. Docker

NOTE: the GitHub Actions CI pipeline automatically builds and pushes containers if all the tests pass in the main branch. Build locally to test changes, but you cannot push to GitHub.

bash distribution/build-docker.sh
docker run -it ghcr.io/sandialabs/peat --help

13.1.4. General build guidance

# make sure you have the following dependencies (linux) if you run into build issues
sudo apt install -qyf python3-dev patchelf binutils scons libpq-dev libpq5 graphviz

# Build Windows executable with PyInstaller
pdm run build-exe

# Build Linux executable
# This runs staticx to include system libraries and be fully portable.
# This WILL NOT work on Windows, and probably won't work with Mac.
# Also, you may need to install some tools:
# sudo apt install -qyf python3-dev patchelf binutils scons libpq-dev libpq5
pdm run build-linux-exe

# Sneakypeat (Windows and Linux)
pdm run build-sneakypeat
pdm run build-linux-sneakypeat

# Build Python packages
pdm build
ls -lAht ./dist/
# View files in the package
pdm run wheel-files

# Build docker
pdm run build-docker

# Update dependencies, but don't bump as many versions (pdm.lock)
pdm lock --update-reuse -d
pdm sync -d

# Update dependencies and versions
pdm lock -d
pdm sync -d

13.2. Test documentation

Regressions are a menance, and especially so for PEAT due to it’s complexity. Our goal is to cover the major features with a minimal amount of effort to ensure future changes don’t cause major breakages (e.g. a change in the parsing logic breaks scanning).

There are three forms of testing:

  • Quality: linting and code quality checks

  • Unit tests: uses pytest to test the CLI interface and individual functions and methods in the code. There are also unit tests that only run against live devices in CI, these are marked with @pytest.mark.gitlab_ci_only.

  • Live tests: run the PEAT executable against live devices and Elasticsearch server in the GitLab Continuous Integration (CI) pipeline. This validates the “end to end” user experience. However, it won’t catch logic failures (e.g. bad output or missing files) and failures are more time consuming to debug than with unit tests. NOTE: these tests are not run on GitHub.

13.2.1. Running the tests

NOTE: you must be in the root directory of the repository (“PEAT”).

# Ensure environment is up to date
pdm install -d

# Linting
pdm run lint

# Run just pytest. This is fast, but not comprehensive.
pdm run pytest

# Run unit tests
pdm run test

# Run unit tests, including slow tests
# This takes significantly longer, but is more comprehensive
pdm run test-full

# Run tests for a specific version of Python
# For example, Python 3.12
pdm use -f 3.12
pdm install -d
pdm run test

# pytest can be configured via arguments at runtime
pdm run pytest -h  # Available pytest arguments
pdm run pytest --durations=10

# Run specific tests
pdm run pytest -k "test_some_code"

# Increase output (-vv shows detailed diff on failures)
pdm run pytest -v
pdm run pytest -vv

# Stop after failures
pdm run pytest -x           # stop after first failure
pdm run pytest --maxfail=2  # stop after two failures
pdm run pytest --lf         # rerun only the tests that failed at the last run
pdm run pytest --ff         # run all tests, but run the last failures first

# Run any test marked as "slow" with the decorator "@pytest.mark.slow"
# This includes the CLI, SEL parsing, and a few other tests
pdm run pytest -v --run-slow
pdm run pytest -k "test_some_code" -vv --run-slow

13.2.2. Testing tools

  • pytest is used for composing and running the Python unit tests. It is an robust and powerful framework that makes writing Python tests easier and at times enjoyable. There are a lot of things pytest makes easy that are difficult, onerous, or even impossible to accomplish with unittest.

  • pyenv is used to download, compile, and manage multiple versions of Python on the same system without affecting the system Pythons. Installation is easy, just follow the guide on the pyenv-installer page.

13.2.3. Organization of tests

tests/
    conftest.py -> Configuration of pytest
    test_module_manager.py -> Unit tests for peat/module_manager.py
    test_utils.py -> Unit tests for peat/utils.py
    api/
       data_files/
       ...
    data_files/  -> Files used by tests at the current directory level (e.g. test_utils.py)
    modules/
        <vendor>/
            data_files/
            test_<device>.py
            ...
        ...
    protocols/
        data_files/
        test_<protocol>.py
        ...