OpenWrt-RepoTool

Description

Tool for downloading OpenWrt repos to create a development workspace, by Daniel F. Dickinson. Inspired by Google's repo tool from AOSP, and began life as a 'post-sync' hook for that tool.

Motivation

It may be a bit of an edge case, but I work with multiple devices (with mostly different targets), SDK/IB snapshots (which change daily, so I want them updated regularly), I prefer to start with a clean build environment, and want to have additional configuration for things like linting and spell checking, that are not wanted in OpenWrt repos themselves. In order to do what I wanted, I was executing the same thing over, and over again to set up fresh workspaces.

Use case(s)

This is useful when at least some of the following are true:

• You are working in more than repo on regular basis (e.g. packages and luci)
• You are working with daily snapshot SDK and/or ImageBuilder, and
• You are starting with a clean build environment on a regular basis
• You are working with multiple targets
• DRY is a thing for you (Don't Repeat Yourself)
• You want your workspace to have tools outside the typical OpenWrt setup (e.g. linting/spell checking).
• You want the workspace setup to be consistent and correct each time

Requirements

• Built using Python 3.13.

• Depends on GitPython , requests, and zstandard (see requirements.txt)

• On Debian 13 (trixie) these can installed by executing:

  apt install python3-git python3-zstandard
  

Usage

• This tool is intended to be used on a POSIX-ish 'nix environment like Linux.
• It will likely NOT work on Windows natively (since neither will OpenWrt's build).
• It, like OpenWrt's build system, MAY work under WSL2.

Getting OpenWrt-RepoTool

pip install openwrt-repotool

• The current release will now be available as orepotool.
• See below for further usage.

Note: As there is not yet a true release this installs the most recent alpha release (rather than below which installs the work-in-progress -- development version -- for the next alpha release.

Option #2: Install devel version from package author's package repository

pip install --index-url https://forgejo.d-f-d.ca/api/packages/orepotool/pypi/simple/ openwrt-repotool

• It is now available as orepotool
• See below for further usage.

Option #3: Build development version

1. Clone this repository
2. Build the openwrt-repotool
3. Install it locally
4. It is now available as orepotool
5. See below for further usage.

git clone https://forgejo.d-f-d.ca/orepotool/openwrt-repotool.git
cd openwrt-repotool
pipx install build
pyproject-build
pipx install ./dist/openwrt_repotool-2026.1.0.dev0-py3-none-any.whl

Setup an OpenWrt workspace using an existing configuration

1. Create the root directory for the workspace
2. Change to that directory
3. Use orepotool with defaults to download Daniel F. Dickinson's workspace
4. If you use Visual Studio Code open the openwrt-repo.code-workspace now in the root of the the directory you are in.

mkdir ~/Build/snapshot-workspace
cd ~/Build/snapshot-workspace
orepotool -v
code openwrt-repo.code-workspace

You can omit the -v if you do not wish to see informational messages while the workspace is being cloned/downloaded and prepared.

The orepotool command line

The command line help

Output of orepotool -h

usage: orepotool [-h] [-c CONFIG] [-n CONFIG_NAME] [-r REPODIR] [--reset-branches] [-s] [--skip-external-archives] [--skip-link-copy] [--skip-repos] [-v | -q] [-V]

OpenWrt-RepoTool <version>: tool for downloading OpenWrt repos to create a development workspace

options:
  -h, --help            show this help message and exit
  -c, --config CONFIG   configuration file (default: ~/.config/openwrt-tools/config.json)
  -n, --config-name CONFIG_NAME
                        use configuration with specified name (default: default)
  -r, --repodir REPODIR
                        Repository dir override. Used instead of configured directory, or sets the configured directory, if none.
  --reset-branches      reset active branches to configured primary, but do not touch dirty or detached repos
  -s, --show-config-path
                        show the path the configuration file
  --skip-external-archives
                        skip downloading and extracting external archives
  --skip-link-copy      skip linking and/or copying files
  --skip-repos          skip extracting repos
  -v, --verbosity       display more messages during operation
  -q, --quiet           don't display any messages during operation (except fatal errors)
  -V, --version         version of openwrt-repotool

Licensed under the Apache 2.0 License. Copyright 2026 Daniel F. Dickinson.

Default operating configuration

By default on this is in $XDG_CONFIG_HOME/openwrt-repotool/config.json, which on most systems will be ~/.config/openwrt-repotool/config.json.

If you want to check the configuration file used, use the --show-config-path (or -s) command line option.

{
  "default": {
    "config_branch": "main",
    "config_dir": "openwrt-repotool-config",
    "config_repo": "https://gitlab.com/dfd-web/firmware/openwrt-mirrors/openwrt-repotool-config.git",
    "gnupghome": "gnupg",
    "gnupg_keyring": "openwrt.gpg",
    "openwrt_version": "snapshot",
    "quiet": false,
    "repodir": "/path/to/repo_topdir",
    "reset_branches": false,
    "skip_external_archives": false,
    "skip_link_copy": false,
    "skip_repos": false,
    "target": "mediatek-filogic",
    "verbose": false
  }
}

The --config-name (or -n) command line parameter allows you to use a named configuration object other the "default" one above.

OpenWrt Versions

Currently Daniel has configurations for:

1. snapshot
2. 25.12-snapshot
3. 25.12.0-rc5 (once it is released)
4. 24.10.5
5. 24.10-snapshot

Targets

Currently Daniel has configurations for:

1. bcm2xx-bcm2712
2. bcm2xx-bcm2709
3. mediatek/filogic

Creating and using alternate configurations

Basic outline of steps

1. Create a Git repo
2. Populate it with at least minimal configuration
3. Push to a location you can use with --configrepo command line options
4. Use orepotool to download/configure according to the configuration

mkdir some-dir
cd some-dir
git init
... (create configuration)
git add .
git remote add origin https://example.com/me/myconfigrepo.git
git push origin main
mkdir ~/Build/my-workspace
orepotool -r --configrepo https://example.com/me/myconfigrepo.git

Configuration required

common-configs/add-remotes.json

Remotes needed for a complete OpenWrt development environment using the proper official mirrors of the openwrt repositories:

{
  "luci": {
    "upstream": "https://github.com/openwrt/luci.git"
  },
  "openwrt": {
    "upstream": "https://git.openwrt.org/openwrt/openwrt.git"
  },
  "packages": {
    "upstream": "https://github.com/openwrt/packages.git"
  },
  "routing": {
    "upstream": "https://github.com/openwrt/routing.git"
  },
  "telephony": {
    "upstream": "https://github.com/openwrt/telephony.git"
  },
  "video": {
    "upstream": "https://github.com/openwrt/video.git"
  },
  "myconfigrepo": {
    "origin": "https://example.com/me/myconfigrepo.git"
  }
}

per-version-configs/repo-branches.json

{
  "25.12-snapshot": {
    "luci": {
      "primary": "upstream",
      "upstream": "openwrt-25.12"
    },
    "openwrt": {
      "primary": "upstream",
      "upstream": "openwrt-25.12"
    },
    "packages": {
      "primary": "upstream",
      "upstream": "openwrt-25.12"
    },
    "routing": {
      "primary": "upstream",
      "upstream": "openwrt-25.12"
    },
    "telephony": {
      "primary": "upstream",
      "upstream": "openwrt-25.12"
    },
    "video": {
      "primary": "upstream",
      "upstream": "openwrt-25.12"
    },
    "myconfigrepo": {
      "primary": "origin",
      "origin": "main"
    }
  },
  "snapshot": {
    "luci": {
      "primary": "upstream",
      "upstream": "master"
    },
    "openwrt": {
      "primary": "upstream",
      "upstream": "main"
    },
    "packages": {
      "primary": "upstream",
      "upstream": "master"
    },
    "routing": {
      "primary": "upstream",
      "upstream": "master"
    },
    "telephony": {
      "primary": "upstream",
      "upstream": "master"
    },
    "video": {
      "primary": "upstream",
      "upstream": "master"
    },
    "myconfigrepo": {
      "primary": "origin",
      "origin": "main"
    }
  }
}

per-version-configs/sdk-imagebuilder.json

{
  "common": {
    "common": [
      {
        "archive_type": "tar.zst",
        "build_os_arch": "Linux-x86_64",
        "checksum_filename": "sha256sums",
        "checksum_type": "sha256",
        "download_base": "https://downloads.openwrt.org/releases",
        "name": "common"
      },
      {
        "name": "openwrt-sdk"
      },
      {
        "name": "openwrt-imagebuilder"
      }
    ],
    "bcm27xx-bcm2709": [
      {
        "libc": "musl_eabi",
        "name": "openwrt-sdk"
      }
    ],
    "bcm27xx-bcm2712": [
      {
        "libc": "musl",
        "name": "openwrt-sdk"
      }
    ],
    "mediatek-filogic": [
      {
        "libc": "musl",
        "name": "openwrt-sdk"
      }
    ]
  },
  "24.10-snapshot": {
    "common": [
      {
        "name": "common",
        "version_name": "25.10-SNAPSHOT"
      },
      {
        "compiler_version": "gcc-13.3.0",
        "name": "openwrt-sdk"
      }
    ]
  },
  "25.12-snapshot": {
    "common": [
      {
        "name": "common",
        "version_name": "25.12-SNAPSHOT"
      },
      {
        "compiler_version": "gcc-14.3.0",
        "name": "openwrt-sdk"
      }
    ]
  },
  "24.10.6": {
    "common": [
      {
        "name": "common",
        "version_name": "24.10.6"
      },
      {
        "compiler_version": "13.3.0",
        "name": "openwrt-sdk",
      }
    ]
  },
  "25.12.2": {
    "common": [
      {
        "name": "common",
        "version_name": "25.12.2"
      },
      {
        "compiler_version": "gcc-14.3.0",
        "name": "openwrt-sdk"
      }
    ]
  },
  "snapshot": {
    "common": [
      {
        "download_base": "https://downloads.openwrt.org/snapshots",
        "name": "common",
        "version_name": ""
      },
      {
        "compiler_version": "gcc-14.3.0",
        "name": "openwrt-sdk"
      }
    ]
  }
}

per-version-configs/feeds.conf

src-link base ../../openwrt/package
src-link packages ../../packages
src-link luci ../../luci
src-link routing ../../routing
src-link telephony ../../telephony
src-link video ../../video

common-configs/repo-files.json

This wil create symlinks to (target) files in this repo name used ask the key myconfigrepo, below, from (link) the path rooted in repodir and listed in the configuration.

So, the below links feeds.conf from myconfigrepo's per-version-configs/feeds.conf to openwrt-sdk/feeds.conf in the repodir.

{
   "myconfigrepo": [
    {
      "openwrt_versions": [
        "25.12-snapshot",
        "snapshot"
      ],
      "symlinks": [
        {
          "target": "per-version-configs/feeds.conf",
          "link": "openwrt-sdk/feeds.conf"
        }
      ]
    }
  ]
}

per-version-configs/external-archives.json

• Currently an empty list

[]

Note: the checksum configurations are optional

Expected format:

[
  {
    "archive_type": "tar.zst",
    "checksum": {
      "gnupg_sig_url": "checksum-file-url.asc"
      "multi-file-checksum-file": true,
      "type": "sha256",
      "url": "checksum-file-url",
      "value": "<sha256sum-of-archive-if-not-using-url>"
    },
    "dest": "destination-directory-in-workspace",
    "name": "archive-filename",
    "sentinel_file": "file-in-dest-that-prevents-extraction",
    "url": "archive-url"
  }
]

Making this more useful

See https://forgejo.d-f-d.ca/orepotool/openwrt-repotool-config, especially the branches with the author's actual configurations, and https://forgejo.d-f-d.ca/orepotool/openwrt-repo-dev-configs for an examples of using this to setup a OpenWrt workspace that includes linting (in Visual Studio Code, or using standalone versions of cspell, eslint, ruff, shellcheck, and markdownlint-cli2).

License

Licensed under the Apache 2.0 License.

Copyright 2026 Daniel F. Dickinson dfdpublic@wildtechgarden.ca