CMake Port

This is an overview on the port of Qt from qmake to CMake.

Quick Links

• Key initiative: Transition to CMake in JIRA
• #qt-cmake channel on freenode/IRC
• wip/cmake branch in qtbase
• cmake/README.md

Overview

The current port of qtbase can be found in the wip/cmake branch of qt/qtbase.git. See also cmake/README.md in the sources.

This port was announced and discussed on the qt-development mailing list: "Build system for Qt 6" thread on development@qt-project.org

Development Status

• Development Notes by date: the summary of the development progress.

Sub-pages

• CMake Port/Configure System
• CMake Port/Development Notes
• CMake Port/Enabling repo in the CI
• CMake Port/Porting Guide
• CMake Port/Qt Creator
• CMake Port/Workshop 2019 11

Non-technical issues

Open Questions

• Qt development workflows:
  • Documentation and knowledge transfer:
  • Where will the CMake workflow differ from the current qmake one?
• Document the differences and explain why they exist to reduce friction of devs
  • building Qt with CMake
• How can we spread the knowledge? In the end everybody needs to work with cmake, so how do we train our devs and contributors to write/update the build system?
• What is the process to get fixes from Qt 5 into Qt 6? We will need to do that for a long time after all
• 3rd party code:
  • How do we get external libraries into place -- now that we are getting rid of src/3rdparty? VCPKG? Can we get that decided and into place?
• Projects *using* Qt
  • How can we ease the transition of current CMake based Qt 5 projects to Qt6 with CMake? Can we introduce changes to Qt 5 right now to make switching between Qt 5/Qt 6 easier?
  • Idea:
    • For Qt5:
      • Status quo: `find_package(Qt5 ...), results in targets: Qt5::Core.
      • In future, also export targets named: Qt::Core (for Qt6 compat)
    • Qt6:
      • Should: `find_package(Qt6 ...)`, results in targets: Qt::Core
• How can we ease the transition of current qmake based Qt 5 projects to Qt6 with CMake?
  • Idea: Tobias has porting scripts, but they are very Qt specific
    • Probably not useful for the average Qt developer

• QMake support in Qt6?
  • Customer still need to build QMake projects
  • Idea: Make QMake build outside qtbase.git
    • Do a verbatim copy of mkspecs for Qt6
    • Let CMake generate the QMake module .pri files (via ECM's CMake modules)

• Qt Community:
  • How do we communicate the progress to our community and get a community decision on the build system for Qt 6?
  • We'll put this document on the wiki, work on it, later turn it into a QUIP

Technical issues

• Do we need more changes in cmake? We want a released cmake with everything we need in time for the Qt 6 release, so we need to push this through review upstream ASAP!
• Work on finding all the 3rd-party code we need. E.g. I got a patch for OpenGL in gerrit that needs some work in the find_packages department.
• Cross compilation:
  • Requires that the target sysroot contains all third-party libraries that we use, including things like double-conversion, harfuzz, etc.
    • The use of vcpkg in combination with yocto is tricky as yocto's environment setup strictly tells cmake to not look anywhere else for libraries/files/packages. So it's best to not combine them but make sure that your yocto SDK has everything you need. Simplest workaround: Create a simple arm-linux triplet, build pcre2, double-conversion with vcpkg from within a shell that's been through yocto's environment-setup-* and copy the resulting artifacts into the sysroot (from $vcpkg_root/installed/$yourtriplet to $sysroot/usr)
  • Requires a separate host build of Qt (that's installed), and then pass -DHOST_QT_TOOLS_DIRECTORY=/path/to/where/host/build/is/installed/bin (the bin is important!)
  • The plan is to replace the HOST_QT_TOOLS_DIRECTORY with a more fine-grained and extensible tools selection by having per-Qt module tools packages (Qt6CoreTools, Qt6QuickTools, Qt63dTools)
• CI: What needs to be done to make our CI build cmake projects? Can we get that sorted to get wider test coverage (and an idea how the switch will effect build times:-).
  • More passing tests in Qt base
  • Better testing of MacOS and Windows.
• Add one more Qt module and see how that works -- building it stand-alone against an already installed QtBase and from a master build directory.
  • Idea: Test building qtsvg
  • Create a wip/cmake branch on Gerrit (but not necessarily)
• Creator integration
  • Currently QtCreator needs `qmake -query` to identify Qt kits
  • Needs something similar in the CMake world, basically a Qt description file format (CMake? JSON?)
• Qt build compiler flags
  • Qt configure's -developer-build builds with warnings-as-errors, how to do it in CMake?
  • Idea: Use ECM code for inspiration? -- will probably still need to enable warnings-as-errors manually
• Library naming: Qt library names are missing SOVERSION, etc. pp.

Porting Notes

• Process of getting new CMakeLists.txt files, ideally:
  • Run the conversion script pro2cmake.py
  • Edit the places which fail by hand, add a comment "# special case" next to the manual changes, this helps with future git diffs when re-running the script.
  • When the conversion script was fixed, and it is re-run:
    • Either the code next to the comment is fixed automatically
    • Or the hand-edited version needs to be kept

Technical decisions

• Why use AUTOMOC instead of a custom scanner + custom build rules?

Initially we did use a custom scanner, but we encountered a big issue and decided to go with AUTOMOC.

Headers and cpp files need to be scanned ONLY after all sources are set for the target, so the safest way to do it would be after all directories and targets are processed. The problem is that it's not possible to associate additional sources (the generated moc.cpp files) to a target outside the directory where the target was defined.

Another proposed approach was to scan and associate the additional sources just before the directory scope is left, by abusing CMake's variable_watch on the CMAKE_CURRENT_SOURCE_DIR variable, but the maintainers of CMake claimed that it is an implementation detail that is liable to change, so it would not be safe to use.