Using Conan for Qt6

"Work in Progress"

Conan package manager

Conan is often described as a "package manager for C and C++".

In addition to being a dependency manager it is both a source and binary package manager which means you can use it to build the packages from sources or

install pre-built binary packages from the server (if those exists for the selected build configuration).

The Conan packages are downloaded to your local Conan cache so there is no need to be connected to remote server all the time.

Please refer to official documentation for more details about Conan: https://conan.io/

Prerequisites

Conan depends on Python installed on your system. Although the Conan client may be standalone executable the Conan packages itself contain recipes that are written in Python.

• Python 3.6 or higher, make sure it is the default in your PATH
• If you want to use Conan to build Qt packages from sources
  • CMake (>= 3.16, >= 3.18.4 for Ninja Multi-Config, >= 3.21.1 for static Qt builds in Qt 6.2+)
  • Ninja
  • A working C++ compiler, supporting at least C++ 17
  • See the rest of needed tools from: Building Qt 6 from Git
• ICU (Linux and Windows)
  • There is work in progress to bring ICU as a Conan package (a dependency to Qt packages) so that it is taken care of automatically for the users (QTQAINFRA-4592). Until that one unfortunately needs to manually install ICU libs to a path where those can be found.
  • For example Linux:
    • $ mkdir $HOME/icu_libs
    • $ cp $HOME/MyQtSdkInstallation/6.2.2/gcc_64/lib/libicu* $HOME/icu_libs
    • export LD_LIBRARY_PATH=$HOME/icu_libs:$LD_LIBRARY_PATH

Installing Conan

There are multiple options to install Conan package manager on your system. You need at least version 1.39 or newer.

• Official downloads: https://conan.io/downloads.html
• Python environment: $ pip install conan --upgrade
• Test the installation: $ conan --version
• Important note!
  • If you had older version of the Conan installed and you upgraded it you will still have old version of the $HOME/.conan/settings.yml file. Qt Conan packages require the settings.yml file to be 1.39 or newer.
  • $ conan config init, or
    • Note! This may override your other Conan settings in $HOME/.conan/conan.conf
  • Download latest version from: https://docs.conan.io/en/latest/reference/config_files/settings.yml.html

Conan configuration

• Enable Conan revisions so that your conan(.exe) client works against the Conan remote server (What revisions? https://docs.conan.io/en/latest/versioning/revisions.html).
  • Set revisions_enabled=1 in the [general] section of your $HOME/.conan/conan.conf file (preferred)
  • Alternatively export in your env: CONAN_REVISIONS_ENABLED=1
• Windows: Enable short paths
  • Set use_always_short_paths = True in the [general] section of your $HOME/.conan/conan.conf file (preferred)
  • Alternatively export in your env: CONAN_USE_ALWAYS_SHORT_PATHS=1
• Set CMake generator as Ninja (which is required by Qt6)
  • Add cmake_generator=Ninja in the [general] section of your $HOME/.conan/conan.conf file (preferred)
  • Alternatively export in your env: CONAN_CMAKE_GENERATOR=Ninja
• Conan 1.39 or newer is required (more specifically the $HOME/.conan/settings.yml file)
  • (the Qt CI / build configuration reference values from settings.yml which needs to be up-to-date on client side as well)

Connecting to Conan remote

First you need credentials to Qt Conan server. Login to your Qt Account and click on the "Conan Package Manager" link.

• Note! The default Conan installation will include Opensource conan-center remote configured in your settings. At the time of writing this the certificate was expired which will make the conan(.exe) client to throw an error when it searches for remote packages. You can disable ssl verification temporarily by editing $HOME/.conan/remotes.json
  •   {    "name": "conancenter",    "url": "https://center.conan.io",    "verify_ssl": false   }
• Click on the "Get a new password" link. These are your personal credentials to Conan remote.
• Add the Qt Conan remote to your environment
  • $ conan remote add qt https://qtpkgtest.jfrog.io/artifactory/api/conan/qt
    • You can choose the alias name for the remote name
    • This will add it into $HOME/.conan/remotes.json
      • $ conan remote list
• Authenticate to the server
  • $ conan user USERNAME -p PASSWORD -r qt
• Run a search command to verify that your credentials and the remote were ok
  • $ conan search -r qt
    

Qt Conan packages

To get an idea what Qt Conan packages are available run the following command

• $ conan search -r qt

Existing package recipes:

qtbase/6.2.2@qt/everywhere

qtdeclarative/6.2.2@qt/everywhere

qtimageformats/6.2.2@qt/everywhere

qtmultimedia/6.2.2@qt/everywhere

The generic pattern for package naming is: <module name>/<version>-<pre-release segment>@qt/everywhere

• Some Qt .git repositories may yield multiple Conan packages like qtscxml.git -> qscxml, qtscxmlqml, qtscmlstatemachine and qtscxmlstatemachineqml
• The optional pre-release segment may contain e.g. 6.2.2-alpha1, 6.2.2-beta2, 6.2.2-rc3

Build profiles

The profile files collect all the Settings and Options for the build ($ conan install) i.e. the build configuration.

You can pass each setting and option separately from command line or pass a build profile which should be a more convenient way.

• $ conan install qtbuildprofiles/6.2.2@qt/everywhere --update -r qt
  • The profiles are installed to the current directory (choose a suitable directory for you)
  • These are the build profiles used by the Qt CI to produce the Qt Conan binary packages.
    • Note, these can be edited but see the Q/A below about Settings and Options on this page

Building

• Next to your project/app create a file that declares the Qt library dependencies as Conan packages:
  • conanfile.txt:  # filename can be anything, declare what ever your project/app may require

    • [requires]
      qtbase/6.2.2@qt/everywhere
      qtdeclarative/6.2.2@qt/everywhere
      qtcharts/6.2.2@qt/everywhere
      

• Call Conan to install the requirements for you (Linux example):
  • $ conan install <path>/conanfile.txt --build=missing --profile=<profiles installation folder>/linux-x86_64-gcc --update --generator=virtualenv -r qt
    • --build
      • "--build" will force a complete build from sources including transitive dependencies
      • "--build=never" will attempt to install pre-built binaries (from local cache or from given server) if those should exist for the given build configuration i.e. --profile. If the requested build configuration is not found (local cache or server) Conan will bail out with an error.
      • "--build=missing" Conan will attempt to build those missing packages/dependencies for the requested build configuration which are missing
      • https://docs.conan.io/en/latest/mastering/policies.html
    • --profile
      • This specifies the build configuration i.e. Conan settings (os, os version, compiler, arch, ...) and Options (shared, release, headersclean, ..)
        • Edit if needed, see the Q/A section below for more details
        • Settings and Options in profile file can be overridden from command line by:
          • -s compiler.version=9.3 -s compiler.libcxx=libstdc++11 -o release=no -o shared=no ...
    • --update
      • Forces Conan to check if the given server (-r, --remote) contains a newer version of the package(s) and downloads those if found. This option should be always preferred
    • --generator
      • multiple can be given (if you want to dive into details: https://docs.conan.io/en/latest/reference/generators.html)
      • "--generator=virtualenv" (the recommended way for consuming Qt Conan packages)
        • This will generate 'activate.sh'/'activate.bat' which you can call
          • $ source activate.sh  # on windows do not use 'source' -command
        • Now all the Qt packages are in your PATH/env which were declared in the conaninfo.txt file
    • -r, --remote
      • Ask Conan to install the package(s) from the given remote server to your local Conan cache
    • Note! If you want to export the binaries out from the Conan cache to given directory you need to call conan install a bit differently
      • $ conan install qtdeclarative/6.2.2@qt/everywhere --build=missing --profile=<profile> --update -r qt --install-folder=/some/path/here/Qt/6.2.2/gcc
        • You should have the binaries of the required package and all of its transitive dependencies installed to the given directory with the usual directory layout:
          • lib/
          • bin/
          • include/
          • ...
  • Activate the 'activate.sh/activate.bat' and compile your project
    • $ source activate.sh # on windows just call the activate.bat
    • $ cd your_project_path
    • $ cmake CMakeLists.txt
    • $ cmake --build .
    • Launch your app

Q/A:

• What Conan Settings?
  • All the packages in the dependency chain will get the same Settings for binary compatibility (os, os version, arch, compiler, compiler version, ...)
  • $HOME/.conan/settings.yml
    • This defines the project/organization level super-set of the supported settings
      • https://docs.conan.io/en/latest/reference/config_files/settings.yml.html
      • The Conan package build recipes usually reference the attributes from this file for various reasons
      • This can be forked/edited but may then cause incompatibility between Qt Conan packages and packages created by 3rd parties
        • Current understanding is that we should try to stick with the upstream version of this file so our Qt packages are "compatible" with Conan packages e.g. in Conan Center Index (CCI)
• What Conan Options? Where these are defined and what about Qt's configure options and features and leaf module features?
  • qtbase:
    • All configure options and features are mapped as Conan Options in the qtbase Conan package:
      • $ conan inspect qtbase/6.2.2@qt/everywhere | grep headersclean  # grep if you want to narrow down the output
        • headersclean: ['yes', 'no', None]  # possible values
        • headersclean: None  # default value, configure(.bat) will find out the default value automatically for you
    • cmake_args_qtbase
      • Currently the only way to pass cmake arguments to qtbase build is via this Conan Option:
        • See e.g. in profile files: qtbase:cmake_args_qtbase="-DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++"
  • leaf modules:
    • leaf module specific options are mapped as Conan Options per leaf module Conan package
      • $ conan inspect qtdeclarative/6.2.2@qt/everywhere
    • cmake_args_leaf_module
      • Currently the only way to pass cmake arguments to leaf modules is via this Conan Option
• I edited the profile file and tried to install pre-built Qt binaries but it fails/starts to compile from sources, why?
  • Conan calculates a package_id checksum for each build configuration/binary package
    • All the used Settings attribute values are included
    • All the used Options attribute values are included
    • Check sums from all dependencies and transitive dependencies are included
  • If you change the build profile or override the values from command line it will result in different package_id checksum -> Conan will interpret that such binaries are not available and tries to build from source (depending on used build policy)
    • Note! The following Options are explicitly excluded from package_id checksum calculation in Qt Conan package build recipes as these should not affect binary compatibility:
      • qtbase configure options:
        • sdk
        • android_sdk
        • android_ndk
        • android_ndk_platform
        • android_abis
        • android_javac_target
        • android_javac_source
        • qpa, translationsdir
        • headersclean
        • TODO: Should more options be added?
      • cmake arguments:
        • CMAKE_CXX_COMPILER_LAUNCHER
        • CMAKE_C_COMPILER_LAUNCHER
        • QT_BUILD_EXAMPLES
        • WARNINGS_ARE_ERRORS
        • FEATURE_headersclean
        • PostgreSQL_ROOT
        • OPENSSL_ROOT_DIR
        • LLVM_INSTALL_DIR
        • TODO: Should more argments be added?
      • Example:
        • You want to install Qt6.2.2 binaries built by Qt using linux-x86_64-gcc profile (used by Qt CI):
          • qtbase:cmake_args_qtbase="-DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DOpenGL_GL_PREFERENCE=LEGACY -DFEATURE_system_harfbuzz=OFF -DOPENSSL_ROOT_DIR=$OPENSSL_ANDROID_HOME -DCMAKE_C_COMPILER_LAUNCHER=sccache -DCMAKE_CXX_COMPILER_LAUNCHER=sccache" *:cmake_args_leaf_module="-DCMAKE_C_COMPILER_LAUNCHER=sccache -DCMAKE_CXX_COMPILER_LAUNCHER=sccache"
        • You notice that is has certain options that would not work on your system. You can edit/remove the listed ones without affecting the package_id (binary compatibility) and still install the pre-built binaries from server.
          • *:cmake_args_qtbase="-DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DOpenGL_GL_PREFERENCE=LEGACY -DFEATURE_system_harfbuzz=OFF -DOPENSSL_ROOT_DIR=/my/openssl/dir " *:cmake_args_leaf_module=""

Further notes

• Ninja is the recommended CMake generator and should be used. E.g. on Windows you may get compilation time errors if using VS generator