Building

Github actions

On every commit, there is a github action that rebuilds the documentation website on each commit.

In addition to the documentation, on tag commits, the python wheel will be:

• Built
• Uploaded to PyPi & TestPyPi
• Signed and added to a new Github release

Note that the Windows build is not automatically created. This is currently a manual process.

Manual build

Required packages

uv is used to build the packages and Innosetup is used to build the Windows installer.

Required binaries (Windows builds only)

The installers use uv to run the tool in its own virtual environment and the only non-Python runtime dependency is ffmpeg.

Settings things up

The following assumes building on Windows so that the Windows installer can be created in addition to the multi-platform wheel. If you are building on mac / linux, you can skip steps 3 and 4.

1. Set the version number in pyproject.toml
2. Set the version number in install/gogadget_windows.iss
3. [Windows only] Make sure that uv and innosetup are installed and in path. (innosetup isn't by default, you will need to add the root innosetup directory that is located in program files)
4. [Windows only] Download latest windows builds of ffmpeg and uv and put the binaries directly in install/bin/

Build commands (Windows)

These commands are for Bash on Windows, you will need to convert them to whatever shell / platform you are using.

#!/bin/bash

# Clear out any wheels and existing installers that we have
rm -f dist/* && rm -f install/bin/*.whl

# uv lock to create a record of the dependencies
uv lock

# Build new wheel and copy to bin folder
uv build
cp dist/*.whl install/bin/

# Build windows installer and move to dist folder
iscc install/gogadget_windows.iss

Documentation

mkdocs-material

The documentation uses mkdocs-material and related plugins. It also uses typer to generate the command reference page. The required packages are installed by running:

uv sync

A test server can then be run with:

uv run mkdocs serve -f docs/mkdocs.yml

Generating command reference page

The command reference page can automatically be regenerated with:

uv run typer gogadget.main utils docs --name gogadget --output docs/pages/reference/command_reference.md

Generating list of python dependencies

The list of licenses for python dependencies can be generated with the following. The documentation site automatically references the generated file.

uv sync
source .venv/bin/activate
pip-licenses --format=markdown --with-authors --no-version --with-urls --with-system --order=license --output-file=src/gogadget/3rd-party-licences/license_listing_for_python_dependencies.md

Running from source

Generic

Firstly, please note the package requirements at the top of this document. You can then run:

#!/bin/bash

# Download the repo and enter it
git clone https://github.com/jonathanfox5/gogadget
cd gogadget

# Create the virtual environment and install packages
uv sync

# Run the tool
uv run gogadget

# Alternatively, you can enter the venv and then run the tool in any directory you like
source .venv/bin/activate
gogadget

On a clean install of Ubuntu Server 24.04 LTS

#!/bin/bash

# Update system and install binary requirements
sudo apt update -y && sudo apt install -y
sudo apt install ffmpeg build-essential python3-dev git tree -y

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Build python package
git clone https://github.com/jonathanfox5/gogadget
uv build gogadget

# Find the wheel and install it
whl_file=$(ls gogadget/dist/*.whl | head -n 1)

if [ -z "$whl_file" ]; then
    echo "No .whl file found in the dist directory."
    exit 1
fi

# Python 3.10 is used due to certain dependencies having 
# compatibility issues with linux ARM on newer versions
uv tool install "$whl_file" --python 3.10