Patching

Patching summary

The script supports automatic patching of all modules during build via a three-method priority system:

Priority	Method	Description
1 (highest)	Source directory	Files in patches/{module}/{version}/source/ are copied directly to the build tree, overwriting originals
2	Patch files	patch, url, *.patch, and *.diff files are merged in alphabetical order and applied via git apply or patch -p1
3 (fallback)	Remote patches	Downloaded from a GitHub repo via the GitHub API when local patches are absent

Here is an example local directory structure that the script will use to apply patches to libtorrent v1.2.19 and qBittorrent release-5.1.4:

• qbt-nox-static.bash
• Directoryqbt-build/

  • Directorypatches/

    • Directorylibtorrent/

      • Directoryv1.2.19/

        • patch # Primary patch file
        • url # URL to download remote patch
        • 01.patch # Additional patch file
        • 02.diff # Additional diff file
        • Directorysource/ # Source directory (highest priority)

          • Directoryinclude/

            • …
          • Directorysrc/

            • …
    • Directoryqbittorrent/

      • Directory5.1.4/

        • patch # Primary patch file
        • url # URL to download remote patch
        • custom.patch # Additional patch file
        • Directorysource/ # Source directory (highest priority)

          • Directorysrc/

            • Directorywebui/

              • webui.cpp # Modified source file

Tip

Use ./qbt.bash -h-pr to see patch-related help.

Note

The default remote patch repo userdocs/qbittorrent-nox-static contains only patches required for successful builds or security fixes — no optional customisations.

Bootstrapping

By default the script builds into a subdirectory relative to its location, so local patches need to be in the right place. Options:

• Option 1 (default): Bootstrap creates the directory structure; copy your patches in afterwards.

• Option 2: Clone the repo and copy patches into the build dir:

  git clone --depth 1 https://github.com/userdocs/qbittorrent-nox-static.git
  cd qbittorrent-nox-static
  mkdir -p qbt-build
  cp -r patches qbt-build/

• Option 3: Set the build dir to the repo root so the script finds patches automatically:

  export qbt_build_dir="."

• Option 4: Host patches in a remote GitHub repo and point the script at it via the -pr switch or qbt_patches_url env var.

• Option 5: Do nothing — the script falls back to userdocs/qbittorrent-nox-static for any required patches.

When bootstrapping the script will create the required directory structure using the current defaults and it will look like this:

qbt-build/patches/glibc/2.43
qbt-build/patches/zlib/1.3.2.1
qbt-build/patches/zlib_ng/1.3.1
qbt-build/patches/iconv/1.19
qbt-build/patches/icu/78.3
qbt-build/patches/openssl/3.6.1
qbt-build/patches/boost/1.90.0
qbt-build/patches/libtorrent/1.2.20
qbt-build/patches/libtorrent/2.0.12
qbt-build/patches/double_conversion/3.4.0
qbt-build/patches/qtbase/5.15.18
qbt-build/patches/qtbase/6.11.0
qbt-build/patches/qttools/5.15.18
qbt-build/patches/qttools/6.11.0
qbt-build/patches/qbittorrent/5.1.4

Local patching examples

Method 1: Source directory

Copy modified source files directly into the patch directory — no patch file required.

Note

All examples assume you are in the directory containing qbt-nox-static.bash.

Step 1: Bootstrap the patches directory

./qbt.bash -bs-p

Step 2: Clone the target repo at the required version

git clone --branch release-5.1.4 --depth 1 https://github.com/qbittorrent/qBittorrent.git

Step 3: Copy the source tree into the patch directory

cp -r qBittorrent/* qbt-build/patches/qbittorrent/5.1.4/source/

Step 4: Edit files directly in the source directory

nano qbt-build/patches/qbittorrent/5.1.4/source/src/webui/webui.cpp

Step 5: Build

./qbt.bash all

The script detects the source/ directory and copies all files into the build tree, overwriting the originals.

Method 2: Patch file (git diff)

Use this for targeted changes where creating a patch file is more efficient than copying a full source tree.

Step 1: Bootstrap and clone

./qbt.bash -bs-p
git clone --branch release-5.1.4 --depth 1 https://github.com/qbittorrent/qBittorrent.git

Step 2: Edit the file(s) you want to modify inside the cloned repo

Step 3: Generate the patch with git diff

cd qBittorrent
git diff > ../qbt-build/patches/qbittorrent/5.1.4/01-my-changes.patch

All staged and unstaged changes across all modified files are captured in the single patch.

Step 4: Build

./qbt.bash all

Method 3: Multiple patch files

Drop multiple *.patch / *.diff files into the version directory. The script merges them alphabetically into a single patch before applying.

# Example: two independent changes applied in order
git diff -- src/base/bittorrent/session.cpp > qbt-build/patches/qbittorrent/5.1.4/01-session-defaults.patch
git diff -- src/webui/webui.cpp             > qbt-build/patches/qbittorrent/5.1.4/02-webui-tweaks.patch

Method 4: URL-based patches

Create a url file containing one URL per line. The script downloads each URL and merges them into the final patch.

echo "https://github.com/qbittorrent/qBittorrent/pull/18271.patch" > qbt-build/patches/qbittorrent/5.1.4/url

To get a patch URL from a GitHub pull request or commit, append .patch to the PR or commit URL:

https://github.com/qbittorrent/qBittorrent/pull/18271.patch
https://github.com/qbittorrent/qBittorrent/commit/c924904308e806db6e1b321da18c1f91c4e8f8bf.patch

Caution

Use PR patches from the same branch you are building against. For release-5.1.4 that means the v5_1_x branch. Check available branches at https://github.com/qbittorrent/qBittorrent/branches

Custom tags

Some modules accept alternative tags via switches or env vars. The script uses the defaults if none are set.

# Via switches
./qbt.bash -qt master -lt RC_2_0 -bs

# Via env vars (persist between script invocations)
export qbt_qbittorrent_tag=master
export qbt_libtorrent_tag=RC_2_0

Bootstrap creates version-named directories matching the tags:

qbt-build/patches/qbittorrent/master/
qbt-build/patches/libtorrent/RC_2_0/

Caution

Pass the same tags when building, or the patches won’t match the downloaded source. Env vars persist automatically; switches must be repeated.

./qbt.bash -qt master -lt RC_2_0 all

Remote GitHub-based patching

Use -pr or qbt_patches_url to pull patches from a GitHub repository. The script uses the GitHub API to recursively download the full patches/ directory tree, including source/ subdirectories.

Repository structure

qbittorrent

patches/qbittorrent/master/patch
patches/qbittorrent/master/url
patches/qbittorrent/master/01-custom.patch
patches/qbittorrent/master/source/src/webui/webui.cpp
patches/qbittorrent/4.5.0/patch
patches/qbittorrent/4.5.0/source/

libtorrent

patches/libtorrent/RC_2_0/patch
patches/libtorrent/RC_2_0/source/include/
patches/libtorrent/RC_1_2/patch
patches/libtorrent/v1.2.12/url

Usage

# Command line
./qbt.bash all -pr username/repository

# Environment variable
export qbt_patches_url="username/repository"
./qbt.bash all