Build Help

Once the script has successfully configured the platform you can execute the help switch to see how it works and what options you have available to you.

./qbt.bash -h

Order of preference

The script will use the following order of preference when configuring the build environment:

1. Command line flags provided to the script
2. .qbt_env file in the same directory as the script
3. Exported env variables, these will overridden by .qbt_env

Tip

There are two flags related to bootstrapping the .qbt_env

The first can be run at anytime regardless of the missing dependencies. It creates .qbt_env with empty values

./qbt.bash -bs-e or --bootstrap-env

The second can be run once test dependencies are installed. It creates a .qbt_env with values populated by defaults or flag settings.

./qbt.bash -bs-ef or --bootstrap-env-full

ENV settings

The script has some env settings that can trigger certain behavior without the need to pass flags to the script.

Tip

export the variables listed below when you use them in your local env.

You can export these before you run the script to set them. The can be used for docker builds or local builds and work in the .qbt_env file.

View: Basic Advanced

Note

This view shows the most important settings for most users' needs.
Switch to Advanced to see and all env options.

Caution

You don't need to configure most of these. The defaults are correct and should probably be left alone.
This view shows all the script env settings and you only need to modify them if you understand what it does.

Build variable	Default if unset	Options	example usage
qbt_zlib_type	zlib	zlib zlib-ng	qbt_zlib_type="zlib"
qbt_skip_icu	yes	yes no	qbt_skip_icu="yes"
qbt_boost_tag	boost-1.89.0	Any valid git tag	qbt_boost_tag="boost-1.89.0"
qbt_libtorrent_version	2.0	1.2 2.0	qbt_libtorrent_version="2.0"
qbt_libtorrent_tag	v2.0.11	Any valid git tag	qbt_libtorrent_tag="v2.0.11"
qbt_libtorrent_master_jamfile	no	yes no	qbt_libtorrent_master_jamfile="no"
qbt_qt_version	6	5.12 5.15 6.3 6.3.1	qbt_qt_version="6"
qbt_qt_tag	v6.9.1	Any valid git tag	qbt_qt_tag="v6.9.1"
qbt_qbittorrent_tag	release-5.1.2	Any valid git tag	qbt_qbittorrent_tag="release-5.1.2"
qbt_build_dir	qbt-build	qbt-build	qbt_build_dir="~/custom"
qbt_build_tool	cmake	cmake qmake	qbt_build_tool="cmake"
qbt_cross_name	default (default to OS gcc)	See Cross arch options below	qbt_cross_name="aarch64"
qbt_mcm_url	userdocs/qbt-musl-cross-make	n/a for general use	qbt_mcm_url="userdocs/qbt-musl-cross-make"
qbt_patches_url	userdocs/qbittorrent-nox-static	n/a for general use	qbt_patches_url="userdocs/qbittorrent-nox-static"
qbt_workflow_files	no	yes no	qbt_workflow_files="no"
qbt_cache_dir	empty = unset	relative folder name or full path path	qbt_cache_dir="cache"
qbt_optimise_strip	yes	yes no	qbt_optimise_strip="yes"
qbt_build_debug	no	yes no	qbt_build_debug="no"
qbt_standard	20	14 17 20 23	qbt_standard="20"
qbt_static_ish	no	yes no	qbt_static_ish="no"
qbt_optimise	no	yes no	qbt_optimise="yes"
qbt_with_qemu	yes	yes no	qbt_with_qemu="yes"
qbt_host_deps	yes	yes no	qbt_host_deps="no"
qbt_host_deps_repo	userdocs/qbt-host-deps	n/a for general use	qbt_host_deps_repo=userdocs/qbt-host-deps
qbt_legacy_mode	yes	yes no	qbt_legacy_mode="no"
qbt_advanced_view	yes	yes no	qbt_advanced_view="no"

Build flags

Note

Using the qbt_optimise will only add -march=native to the build flags, when not cross compiling.

The script build is already optimised but if you really want to experiment you can use the following flags in the host env or .qbt_env and they will be appended to the current build flags:

export CFLAGS=""
export CPPFLAGS=""
export CXXFLAGS=""
export LDFLAGS=""

Tip

The build script is configured to use the following hardening flags by default via the _custom_flags function: https://best.openssf.org/Compiler-Hardening-Guides/Compiler-Options-Hardening-Guide-for-C-and-C++.html#tldr-what-compiler-options-should-i-use

See the _custom_flags function in the script for more information.

Cross arch options

armel armhf armv7 aarch64

x86 x86_64

s390x

powerpc ppc64el

mips mipsel mips64 mips64el

loongarch64

riscv64

Tip

If you see more variables in the script but they are not listed here they are Github Action specific configured by workflows and you should ignore them

Note

If you set qbt_build_tool=qmake and qbt_qt_version=5 you can build qBittorrent v4 or earlier using Qt5.

Switches and flags summarised

All switches and flags have a supporting help option that will provide dynamic content where applicable.

Note

The --bootstrap-release and --bootstrap-multi-arch options are specific to GitHub actions but if you read --help-bootstrap-release you can see how to trigger aarch64|armv7 builds on your local system using Alpine/Debian/Ubuntu via docker.

Script Help Options

Script Help Options

 Here are a list of available options

 Use: -b     or --build-directory       Help: -h-b     or --help-build-directory
 Use: -bt    or --boost-tag             Help: -h-bt    or --help-boost-version
 Use: -c     or --cmake                 Help: -h-c     or --help-cmake
 Use: -cd    or --cache-directory       Help: -h-cd    or --help-cache-directory
 Use: -d     or --debug                 Help: -h-d     or --help-debug
 Use: -bs-e  or --bootstrap-env         Help: -h-bs-e  or --help-bootstrap-env
 Use: -bs-ef or --bootstrap-env-full    Help: -h-bs-ef or --help-bootstrap-env-full
 Use: -bs-p  or --bootstrap-patches     Help: -h-bs-p  or --help-bootstrap-patches
 Use: -bs-c  or --bootstrap-cmake       Help: -h-bs-c  or --help-bootstrap-cmake
 Use: -bs-r  or --bootstrap-release     Help: -h-bs-r  or --help-bootstrap-release
 Use: -bs-ma or --bootstrap-multi-arch  Help: -h-bs-ma or --help-bootstrap-multi-arch
 Use: -bs-a  or --bootstrap-all         Help: -h-bs-a  or --help-bootstrap-all
 Use: -i     or --icu                   Help: -h-i     or --help-icu
 Use: -lm    or --libtorrent-master     Help: -h-lm    or --help-libtorrent-master
 Use: -lt    or --libtorrent-tag        Help: -h-lt    or --help-libtorrent-tag
 Use: -m     or --master                Help: -h-m     or --help-master
 Use: -ma    or --multi-arch            Help: -h-ma    or --help-multi-arch
 Use: -n     or --no-delete             Help: -h-n     or --help-no-delete
 Use: -o     or --optimise              Help: -h-o     or --help-optimise
 Use: -p     or --proxy                 Help: -h-p     or --help-proxy
 Use: -pr    or --patch-repo            Help: -h-pr    or --help-patch-repo
 Use: -q     or --qmake                 Help: -h-q     or --help-qmake
 Use: -qm    or --qbittorrent-master    Help: -h-qm    or --help-qbittorrent-master
 Use: -qt    or --qbittorrent-tag       Help: -h-qt    or --help-qbittorrent-tag
 Use: -qtt   or --qt-tag                Help: -h-qtt   or --help-qtt-tag
 Use: -sdu   or --script-debug-urls     Help: -h-sdu   or --help-script-debug-urls
 Use: -si    or --static-ish            Help: -h-s     or --help-strip
 Use: -s     or --strip                 Help: -h-s     or --help-strip
 Use: -wf    or --workflow              Help: -h-wf    or --help-workflow

 Module specific help - flags are used with the modules listed here.

 Use: all or module-name          Usage: ~/qbt.bash all -i

 all ---------------- optional Recommended method to install all modules
 install ------------ optional Install the ~/qbt-build/completed/qbittorrent-nox binary
 zlib --------------- required Build zlib locally
 iconv -------------- required Build iconv locally
 icu ---------------- optional Build ICU locally
 openssl ------------ required Build openssl locally
 boost -------------- required Download, extract and build the boost library files
 libtorrent --------- required Build libtorrent locally
 qtbase ------------- required Build qtbase locally
 qttools ------------ required Build qttools locally
 qbittorrent -------- required Build qbittorrent locally

 env help - supported exportable environment variables

 export qbt_build_dir="" ----------------- options path - a valid path
 export qbt_libtorrent_version="" -------- options 1.2 | 2.0
 export qbt_qt_version="" ---------------- options 5 | 5.15 | 6 | 6.2 | 6.3 and so on
 export qbt_build_tool="" ---------------- options qmake | cmake - The default if empty is cmake
 export qbt_cross_name="" ---------------- options x86_64 | aarch64 | armv7 | armhf
 export qbt_patches_url="" --------------- options userdocs/qbittorrent-nox-static
 export qbt_libtorrent_tag="" ------------ options Takes a valid git tag or branch for libtorrent
 export qbt_qbittorrent_tag="" ----------- options Takes a valid git tag or branch for qbittorrent
 export qbt_boost_tag="" ----------------- options Takes a valid git tag or branch for boost
 export qbt_qt_tag="" -------------------- options Takes a valid git tag or branch for Qt
 export qbt_workflow_files="" ------------ options yes | no - use qbt-workflow-files for dependencies
 export qbt_cache_dir="" ----------------- options path | empty - provide a path to a cache directory
 export qbt_libtorrent_master_jamfile="" - options yes | no - use RC branch instead of release jamfile
 export qbt_optimise_strip="" ------------ options yes | no - strip binaries - cannot be used with debug
 export qbt_build_debug="" --------------- options yes | no - debug build - cannot be used with strip
 export qbt_standard="" ------------------ options 14 | 17 | 20 | 23 - c standard for gcc - OS dependent
 export qbt_static_ish="" ---------------- options yes | no - libc linking - link dynamically to host libc

 ⬤ Default env settings

   qbt_zlib_type="zlib"
   qbt_skip_icu="yes"
   qbt_boost_tag="boost-1.88.0"
   qbt_libtorrent_version="2.0"
   qbt_libtorrent_tag="v2.0.11"
   qbt_libtorrent_master_jamfile="no"
   qbt_qt_version="6"
   qbt_qt_tag="v6.9.1"
   qbt_qbittorrent_tag="release-5.1.2"
   qbt_build_dir="qbt-build"
   qbt_build_tool="cmake"
   qbt_cross_name="default"
   qbt_mcm_url="userdocs/qbt-musl-cross-make"
   qbt_patches_url="userdocs/qbittorrent-nox-static"
   qbt_workflow_files="no"
   qbt_cache_dir=""
   qbt_optimise_strip="yes"
   qbt_build_debug="no"
   qbt_standard="20"
   qbt_static_ish="no"
   qbt_optimise="no"
   qbt_with_qemu="yes"
   qbt_host_deps="no"
   qbt_host_deps_repo="userdocs/qbt-host-deps"

For example, taking the -h-bs switch as an example, it will show different results based on the preceding switches provided:

-h-bs

Here is the help description for this flag:

Creates dirs in this structure: ~/qbt-build/patches/APPNAME/TAG/patch

Add your patches there, for example.

~/qbt-build/patches/libtorrent/1.2.18/patch

~/qbt-build/patches/qbittorrent/4.5.0/patch

-qm -lm -h-bs

Here is the help description for this flag:

Creates dirs in this structure: ~/qbt-build/patches/APPNAME/TAG/patch

Add your patches there, for example.

~/qbt-build/patches/libtorrent/RC_1_2/patch

~/qbt-build/patches/qbittorrent/master/patch

-qt release-4.2.5 -lt v2.0.3 -h-bs

Here is the help description for this flag:

Creates dirs in this structure: ~/qbt-build/patches/APPNAME/TAG/patch

Add your patches there, for example.

~/qbt-build/patches/libtorrent/2.0.3/patch

~/qbt-build/patches/qbittorrent/4.2.5/patch

Build - default profile

Install all default modules (ICU is skipped) and build qbittorrent-nox to the default build directory qbt-build/completed.

./qbt.bash all

Build - modules (optional and mostly for debugging and testing)

You can build modules individually, subject to this warning.

Caution

It’s best to consider all individual modules listed below as being dependent on the previous modules being built for that module to build successfully.

./qbt.bash module

Here are the list of supported modules:

glibc (Debian based only)
zlib (default)
iconv (default libtorrent v1.2 only)
icu (optional)
openssl (default)
boost (default)
qtbase (default)
qttools (default)
libtorrent (default)
qbittorrent (default)

Build - paths

By default the script will built to a hard coded path defined by the scripts $install_dir variable as to avoid installing files to a server and causing conflicts.

Note

This path is relative to the scripts location.

qbt-build

You can modify this dynamically with the -b argument

Caution

The -b must be used in all commands provided to the script or default qbt-build will be used instead.

Tip

The -b flag accepts both full /opt and relative opt paths.

./qbt.bash all -b "/opt"