Patching

Patching summary

The script supports the automatic patching of all modules when building, providing the prerequisite conditions are met. In summary it works like this:

• The script will look for a patch file, url file or sources directory in the patches sub directory of the build directory.
• If none are found, then the script will check the default online patch directory userdocs/qbittorrent-nox-static for a patch or url file to apply (ignoring source files)
• It will compare tag versions of the activated modules and if a match is found it will use an existing local patch or download and apply the patch.
• Order of priorities:
  • local - patch file
  • local - patch url
  • local - sources directory
  • remote - patch file
  • remote - patch url

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

• qbittorrent-nox-static.sh
• Directoryqbt-build

  • Directorypatches

    • Directorylibtorrent/

      • Directoryv1.2.19

        • patch
        • Jamfile
        • Directorysources/

          • …
    • Directoryqbittorrent/

      • Directory5.0.3

        • patch
        • sources/src/webui/webui.cpp

Tip

Use the help command to get more information

./qbittorrent-nox-static.sh -h-pr

Note

The default remote patch repo if userdocs/qbittorrent-nox-static will only store critical patches required to build successfully or apply security fixes.

There are no customisations or additional patches stored in the default repo. If it applies a remote patch consider that patch essnetial.

Boot strapping

By default the script installs to a build directory that is a sub directory relative to the script location. This means that if you clone the git repo and run the script it won’t find the local patches. There are few ways to handle this.

• Option 1: Default, the script assumes you will prepare the environment before building by using the bootstrapping feature. This will create the required directory structure, then you copy the patch files to the correct location as needed.

• Option 2: Clone the repo and copy the patches to the correct location

  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: You can set the build dir to the root of the github repo and the script will find the patches

  export qbt_build_dir="."

• Option 4: Upload the patches to a remote github repo with the patches dir in the repo root and use the pr switch or qbt_patches_url env to specify the repo URL. The script will download the patches from the remote location and apply them.

• Option 5: Do nothing and the script will use the default remote patch repo userdocs/qbittorrent-nox-static to apply patches

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

qbt-build/patches/zlib/1.3.1
qbt-build/patches/iconv/1.18
qbt-build/patches/icu/76-1
qbt-build/patches/openssl/3.4.0
qbt-build/patches/boost/1.87.0
qbt-build/patches/libtorrent/2.0.10
qbt-build/patches/double_conversion/3.3.0
qbt-build/patches/qtbase/6.8.1
qbt-build/patches/qttools/6.8.1
qbt-build/patches/qbittorrent/5.0.3

Local patching via example

In this example we will apply a real patch that can be used with this script from this pinned issue: https://github.com/userdocs/qbittorrent-nox-static/issues/149

Note

We will assume you are in folder with the qbittorrent-nox-static.sh script.

Step 1: Boot strap the patches directory

qbittorrent-nox-static.sh -bs-p

Step 2: Clone the qBittorrent repo targeting the specific tag we want to patch - --branch release-5.0.3

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

Step 3: Copy the file that we need to edit to our home directory.

cp qBittorrent/src/webui/webui.cpp webui.cpp

Step 4: Now edit the ~/webui.cpp as per this example of the applied patch

Step 5: Once you have finished making your changes you can create a patch file using this command

diff -Naru qBittorrent/src/webui/webui.cpp webui.cpp > ~/patch

You will now have a patch file that looks like this: qbittorrent/5.0.3/patch

Step 6:

The directory structure that will be created will look like this:

Place your patch file named patch inside the relevant directories. So it would look something like this:

qbt-build/patches/qbittorrent/5.0.3/patch

Then the patch file will be automatically matched to the tag used by the script and loaded.

Using custom github tags

Some modules like libtorrent and qbittorrent have multiple tags that can be used and they can be passed to the script as variables or switches. The script will use the default tags if none are provided.

Using the -qt and -lt switches here:

~/qbittorrent-nox-static.sh -qt master -lt RC_2_0 -bs

or

export qbt_qbittorrent_tag=master
export qbt_libtorrent_tag=RC_2_0

The bootstrapped directory structure would look like this instead:

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

Caution

Remember to provide the same tags via switches when using the build command or the patches won’t match the defaults.

Only the env variables will persist between uses of the script.

qbittorrent-nox-static.sh -qt master -lt RC_2_0 all

Git based patching

Instead of a local patch you can use github hosted patch files. Your patches need to be hosted in the root of the repo like this:

qbittorrent

patches/qbittorrent/master/patch
patches/qbittorrent/4.5.0/patch

libtorrent

patches/libtorrent/RC_2_0/patch
patches/libtorrent/RC_1_2/patch
patches/libtorrent/v1.2.12/patch

The all you do is use the pr switch when using the script. The repo URL is abbreviated to your username and repo:

bash ~/qbittorrent-nox-static.sh all -pr username/repo

Then the patch file will be automatically matched to the tag used by the script and loaded.

How to make a patch

Using qbittorrent as an example we will edit the src/base/bittorrent/session.cpp to apply some session defaults.

Download the relevant git repo:

git clone --no-tags --single-branch --branch release-4.5.0 --shallow-submodules --recurse-submodules --depth 1 https://github.com/qbittorrent/qBittorrent.git

Copy the file that we need to edit to our home directory.

cp qBittorrent/src/base/bittorrent/session.cpp ~/session.cpp

Now edit the ~/session.cpp. Once you have finished making your changes you can create a patch file using this command

diff -Naru qBittorrent/src/base/bittorrent/session.cpp ~/session.cpp > ~/patch

Then you place that patch file in the matching tag directory.

patches/qbittorrent/4.3.4.1/patch

Using a Github pull request or commit

First, it’s sensible to make sure the patch that we want to use is from a pull request on the same branch that we are building against. So when using release-4.5.0 we should use https://github.com/qbittorrent/qBittorrent/tree/v4_5_x

You can see the branches for qBittorrent here - https://github.com/qbittorrent/qBittorrent/branches

When you are on a commit or pull request you simply add .patch to the end of the url.

So here we take the pull request or commit URL

https://github.com/qbittorrent/qBittorrent/pull/18271

https://github.com/qbittorrent/qBittorrent/commit/c924904308e806db6e1b321da18c1f91c4e8f8bf

and add .patch to it so it becomes this

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

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

You can download these using curl or wget and use these as patches in custom builds.

Cache folder based patching

The cache folder system is essentially an offline dependency system that allows you to store source files for modules that you want to patch.

This allows the cached folder system to serve as a way patch modules. Source folders are stored in the cache folder and they are copied over to the build directory when the script is run.

This means you can edit the source files in the cache folder and they will be copied over to the build directory when the script is run.

This method is similar to the source directory method but it is more flexible and allows you to store multiple versions of the source files via checking out a specific tag or branch.