Metadata-Version: 2.4
Name: openwrt-repotool
Version: 2026.0.7.0a1
Summary: Tool for downloading OpenWrt repos to create a development workspace
Author-email: "Daniel F. Dickinson" <dfdpublic@wildtechgarden.ca>
License-Expression: Apache-2.0
Project-URL: Homepage, https://gitlab.com/dfd-web/firmware/openwrt-mirrors/openwrt-repotool
Project-URL: Repository, https://gitlab.com/dfd-web/firmware/openwrt-mirrors/openwrt-repotool.git
Project-URL: Issues, https://gitlab.com/dfd-web/firmware/openwrt-mirrors/openwrt-repotool/-/issues
Keywords: openwrt,buildroot,development,tools,git,repo
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: GitPython>=3.1
Requires-Dist: zstandard>=0.23
Requires-Dist: requests
Dynamic: license-file

# 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](https://gitlab.com/dfd-web/firmware/openwrt-mirrors/openwrt-repotool/-/blob/main/requirements.txt))
* On Debian 13 (trixie) these can installed by executing:

   ```bash
   apt install python3-git python3-zstandard
   ```

## Usage

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

### Getting tool

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.

```bash
git clone https://gitlab.com/dfd-web/firmware/openwrt-mirrors/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.

```bash
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`

```auto
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 system 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.

```json
{
  "default": {
    "config_branch": "main",
    "config_dir": "openwrt-repotool-config",
    "config_repo": "https://gitlab.com/dfd-web/firmware/openwrt-mirrors/openwrt-repotool-config.git",
    "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

```bash
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 official
`codeberg` mirrors of the openwrt repositories:

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

##### `per-version-configs/repo-branches.json`

```json
{
  "25.12-snapshot": {
    "luci": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "openwrt-25.12"
    },
    "openwrt": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "openwrt-25.12"
    },
    "packages": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "openwrt-25.12"
    },
    "routing": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "openwrt-25.12"
    },
    "telephony": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "openwrt-25.12"
    },
    "video": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "openwrt-25.12"
    }
  },
  "snapshot": {
    "luci": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "master"
    },
    "openwrt": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "master"
    },
    "packages": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "master"
    },
    "routing": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "master"
    },
    "telephony": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "master"
    },
    "video": {
      "primary": "upstream-codeberg",
      "upstream-codeberg": "master"
    }
  }
}
```

##### `per-version-configs/sdk-imagebuilder.json`

```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.5": {
    "common": [
      {
        "name": "common",
        "version_name": "24.10.5"
      },
      {
        "compiler_version": "13.3.0",
        "name": "openwrt-sdk",
      }
    ]
  },
  "25.12.0-rc5": {
    "common": [
      {
        "name": "common",
        "version_name": "25.12.0-rc5"
      },
      {
        "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`

```plaintext
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`.

```json
{
   "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

```json
[]
```

**Note:** the checksum configurations are optional

Expected format:

```json
[
  {
    "archive_type": "tar.zst",
    "checksum": {
      "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://gitlab.com/dfd-web/firmware/openwrt-mirrors/openwrt-repotool-config.git>
and <https://gitlab.com/dfd-web/firmware/openwrt-mirrors/openwrt-repo-dev-configs>
for an example 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](LICENSE).

Copyright 2026 Daniel F. Dickinson <dfdpublic@wildtechgarden.ca>
