DOCSEARCHbyAlgolia
Submit Docs

aqtinstall Documentation

repository·master·Indexed 23 days ago

https://github.com/miurahr/aqtinstall

aqtinstall is a command-line utility and headless alternative to the official graphical Qt installer, designed to automatically download and install prebuilt Qt binaries, documents, and sources. It is ideal for CI/CD environments and provides commands to list and install Qt versions, modules, architectures, source code, documentation, examples, and auxiliary tools like CMake, Conan, and MinGW across Linux, Windows, and macOS.

Tokens
10.3K
Snippets
27
Records
70
Agent score
79%

What's inside aqtinstall

  1. Post-installation environment configuration

    master

    After aqtinstall completes, it automatically updates configuration files like bin/qt.conf and bin/qconfig.pri to ensure the installation works within its directory.

    Important: aqtinstall does not manage your system environment variables. You are responsible for manually setting variables such as PATH, QT_PLUGIN_PATH, QML_IMPORT_PATH, and QML2_IMPORT_PATH to point to your installation to avoid conflicts between multiple Qt versions.

  2. Authenticate with the Official Qt Installer

    master

    The install-qt-official and list-qt-official commands require authentication for both commercial and open-source Qt versions. Authentication follows this priority order:

    1. qtaccount.ini file: The CLI looks for this file in your OS-specific application data folder:
      • Windows: C:\Users\<username>\AppData\Roaming\Qt\qtaccount.ini
      • Linux: /home/<username>/.local/share/Qt/qtaccount.ini
      • MacOS: /Users/<username>/Library/Application Support/Qt/qtaccount.ini Note: You can copy this file from a local machine to a CI server to reuse your session. Treat it as a password.
    2. QT_INSTALLER_JWT_TOKEN environment variable: If provided, this token is used for authentication.
    3. Command-line flags: If no file or token is found, you must provide --email <email> and --pw <password>. Providing these flags will supersede any existing qtaccount.ini or JWT token. If used, the CLI will automatically generate a new qtaccount.ini in the appropriate OS folder.

    Important: You can only install Qt for the OS currently running the CLI.

  3. How the --archives flag interacts with modules and debug_info

    master

    The --archives flag has specific behavior regarding how it selects files from different sources:

    1. Base Installation: If you specify an archive name (e.g., qtbase), aqt pulls it from the base installation.
    2. Modules: If you specify a module via --modules, aqt installs the module's archives.
    3. debug_info Module: This module contains archives that correspond to almost every other archive. There is a name collision by design (e.g., a qtbase archive exists in the base installation AND a qtbase archive exists in the debug_info module).

    Example of complex selection: If you run: aqt install-qt linux desktop --modules qtcharts debug_info --archives qtcharts qtbase qtdeclarative

    It installs:

    • 3 archives from the debug_info module (qtcharts, qtbase, qtdeclarative).
    • 1 archive from the qtcharts module (qtcharts).
    • 2 archives from the base installation (qtbase, qtdeclarative).

    Constraint: You cannot install a debug_info archive without also installing its corresponding archive from the base Qt installation.

  5. Use Override Mode for the Official Qt Installer

    master

    The --override flag allows you to pass arguments directly to the underlying Qt installer CLI. When using override mode:

    • All standard aqt command options are ignored.
    • Arguments are passed directly to the Qt installer.
    • The --email and --pw flags are still used for authentication and must be provided.

    Usage Patterns:

    aqt install-qt-official --override [installer_args... --email email --pw password]
aqt install-qt-official --email email --pw password --override [installer_args...]
    aqt install-qt-official --override install qt.qt6.680.gcc_64 --email user@example.com --pw pass

  6. Configure MSYS2/Mingw64 environment for aqtinstall

    master

    When using aqtinstall in an MSYS2/Mingw64 environment, you must set the following environment variable to prevent setuptools from raising a VC6.0 is not supported error:

    export SETUPTOOLS_USE_DISTUTILS=stdlib

  7. Install Qt Documentation

    master

    Use aqt install-doc to download and install Qt documentation archives.

    • List archives: aqt list-doc <host> <version> shows the standard documentation archives (e.g., qdoc, qtcore, qtwidgets). Running aqt install-doc without flags installs all listed archives.
    • List additional modules: Use the --modules flag with list-doc to see extra documentation modules (e.g., qt3d, qtcharts).
    • Selective installation: Use --archives to pick specific standard archives and --modules to pick specific extra modules.

    Command Syntax: aqt install-doc <host> <version> [--archives <archive_names>] [--modules <module_names>]

  8. Install Qt for Android

    master

    To install Qt for Android, first list the available versions, architectures, and modules using aqt list-qt.

    Important: For Qt 6 and above, installing Android or iOS versions requires a corresponding desktop version of Qt to be functional. You can automate this by using the --autodesktop flag.

    Note: Do not use --extensions or --extension flags; these were required in versions older than 3.1.0 but are no longer necessary for Qt 6+.

    Workflow:

    1. List versions: aqt list-qt <host> android
    2. List architectures: aqt list-qt <host> android --arch <version>
    3. List modules: aqt list-qt <host> android --modules <version> <arch>
    4. Install: aqt install-qt <host> android <version> <arch> -m <modules> [--autodesktop]

  9. Configure aqtinstall using a configuration file

    master

    You can configure aqtinstall using a configuration file (INI format). By default, the configuration is stored in aqt/settings.ini.

    To use a custom configuration file, you can either:

    1. Set the AQT_CONFIG environment variable to the path of your file.
    2. Use the -c or --config command line option when running aqt.

    A sample configuration structure is provided below.

    [DEFAULTS]

[aqt]
concurrency: 4
baseurl: https://download.qt.io
7zcmd: 7z
print_stacktrace_on_error: False
always_keep_archives: False
archive_download_location: .
min_module_size: 41

[requests]
connection_timeout: 3.5
response_timeout: 30
max_retries_on_connection_error: 5
retry_backoff: 0.1
max_retries_on_checksum_error: 5
max_retries_to_retrieve_hash: 5
hash_algorithm: sha256
INSECURE_NOT_FOR_PRODUCTION_ignore_hash: False

[mirrors]
trusted_mirrors:
    https://download.qt.io
blacklist:
    http://mirrors.ustc.edu.cn
    http://mirrors.tuna.tsinghua.edu.cn
    http://mirrors.geekpie.club
fallbacks:
    https://mirrors.ocf.berkeley.edu/qt
    https://ftp.jaist.ac.jp/pub/qtproject
    https://ftp.nluug.nl/languages/qt
    https://mirrors.dotsrc.org/qtproject

[kde_patches]
patches:
    0001-toolchain.prf-Use-vswhere-to-obtain-VS-installation-.patch

  10. Install aqtinstall via pip

    master

    You can install aqtinstall using pip. It is recommended to update pip before installation to ensure all dependencies (including precompiled packages for various platforms) are handled correctly.

    pip install -U pip
pip install aqtinstall

  12. Reduce Qt installation footprint using --archives

    master

    By default, aqt install-qt installs a large number of archives (often ~27 for the base installation), which can consume significant disk space. You can use the --archives flag to specify exactly which .7z archives to download and install.

    Warning: This is an Advanced feature. Misusing this flag can result in a broken Qt installation missing required components or dependencies.

    Key Concepts:

    • Archives: Individual .7z compressed bundles.
    • Modules: Groups of archives (e.g., qtcharts).
    • the base Qt installation: A special module containing 20-30 archives that is installed by default. It cannot be specified via --modules but can be controlled via --archives.