Using Conan for Qt6

"Work in Progress"

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.5 or higher
• If you want to use Conan to build 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
  • Install required development libraries: https://doc.qt.io/qt-6/gettingstarted.html#platform-requirements
• ICU
  • There is work in progress to bring ICU as Conan package(s) as 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 system path where those can be found.
  • For example linux:
    • $ mkdir $HOME/icu_libs
    • $ cp $HOME/MyQtInstallation/6.2.0/gcc_64/lib/libicu* $HOME/icu_libs
    • export LD_LIBRARY_PATH=$HOME/icu_libs

Installing Conan

There are multiple options to install Conan package manager on your system:

• Official downloads: https://conan.io/downloads.html
• Qt Installer: https://download.qt.io/official_releases/online_installers/
  • Qt -> Tools -> Conan
• Python environment: $ pip install conan

Connecting to Conan remote

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

• Click on the "Get a new password" link. These are your personal credentials to Conan remote.
• Add 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.0@qt/everywhere
  

  qtdeclarative/6.2.0@qt/everywhere
  

  qtimageformats/6.2.0@qt/everywhere
  

  qtmultimedia/6.2.0@qt/everywhere
  

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

• Tome 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.0-alpha1, 6.2.0-beta2, 6.2.0-rc3

Build profiles

To tell Conan the build configuration you are interested about there are basically three ways (or four if you want to let Conan guess the default values).

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

• $ git clone "ssh://<user>@codereview.qt-project.org:29418/qt/qt5" && git checkout 6.2.0
  • coin/conan/profiles/<pick suitable build configuration profile file>
• $ conan config install "ssh://<user>@codereview.qt-project.org:29418/qt/qt5" --args="-b other_branch" --source-folder=coin/conan/profiles --target-folder=subdir
  • The --target-folder here points under your local Conan cache: $HOME/.conan/profiles/subdir
• At the time of writing this is still a work in progress but should be available shortly:
  • $ conan install qtbuildprofiles/6.2.0@qt/everywhere --build=missing --update -r qt
    • the profiles are installed to the current directory

Building

• Next to your project/app create a file that declares the Qt library dependencies as Conan packages:
  • conanfile.txt:  # filename can be anything
    • [requires] qtbase/6.2.0@qt/everywhere qtdeclarative/6.2.0@qt/everywhere # what ever your project/app may require qtcharts/6.2.0@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
        • 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
      • "--generator=virtualenv"
        • This will generate 'activate.sh'/'activate.ps1' 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
      • "--generator=qmake"
        • This will generate conanbuildinfo.pri file which you can include in your projects .pro 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.0@qt/everywhere --build=missing --profile=<profile> --update --install-folder=/home/<user>/Qt/6.2.0/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/
        • ...
    • Note! If you call $conan install <path>/conanfile.txt ... args ... --install-folder=/foo Conan will export binaries from cache to separate sub-directories per dependency
      • /foo/qtbase/lib|bin|include|...
      • /foo/qtdeclarative/lib|bin|include|...
      • /foo/qtcharts/lib|bin|include|...
  • Activate the 'activate.sh/activate.ps1' and compile your project
    • $ source activate.sh # on windows just call the activate.ps1
    • $ cd your_project_path && mkdir build && cd build
    • $ 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 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 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.0@qt/everywhere | grep headersclean  # grep if you want to narrow down the output
        • headersclean: ['yes', 'no', None]  # possible values headersclean: None  # default value
    • cmake_args_qtbase
      • Currently the only way to pass cmake arguments to qtbase build is via this Conan Option:
        • e.g. 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.0@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
      • 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
      • Example:
        • You want to install Qt6.2.0 binaries built by Qt using qt5.git:/coin/conan/profiles/linux-x86_64-gcc profile (used by Qt CI) but you notice that it has:
          • 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):
          • *: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=""

<nowiki/>

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