README-DEV

1. TODO upon upstream upgrade

1.1. Upgrade the version in the package manifests.

1.2. Run the generate script.

1.3. Check whether any locally patched bugs have been resolved

Remove patched files from downstream/ where appropriate. (Bugs awaiting
resolution should be recorded in this file somewhere.)

1.4. Check whether the upstream versions of files in downstream/ have changed.

Print all files under downstream/ that have changed upstream since the
last revision we had checked out:

  $ ./find-outdated-patches 98c727f2
  qtbase/src/tools/moc/generator.cpp
  qtbase/src/tools/moc/main.cpp
  qtbase/src/corelib/thread/qmutex.cpp
  qtbase/src/corelib/compat/removed_api.cpp
  qtbase/src/corelib/serialization/qcborstreamreader.cpp

Then make use of something like `git add --patch` to merge the new upstream
changes and our downstream patches:

  $ cp {upstream,downstream}/qtbase/src/tools/moc/generator.cpp
  $ git add --patch downstream/qtbase/src/tools/moc/generator.cpp

1.5. Ensure resource collection files (.qrc) have not changed.

Currently only libQt5Gui/QtGui/painting/qmake_webgradients.qrc needs to be
checked because all the rest are static (that is, not generated by the
upstream build) and are therefore symlinks into upstream/, whereas our
qmake_webgradients.qrc is a copy of the one generated by the upstream build.

It's probably easiest to simply check its parameters of interest (file list,
prefix, etc.) in upstream/qtbase/src/gui/painting/painting.pri (the rest of
the file is unlikely to change).

Otherwise, to generate the upstream version:

  - Configure the upstream build (see above for instructions)
  - CD to the build directory
  - Run `make sub-src-qmake_all`
  - Find the generated file at `src/gui/.rcc/qmake_webgradients.qrc`.

1.6. Check version scripts

Ensure that our copied version scripts still match the upstream-generated
ones.

Currently the only one is
libQt5Gui/QtGuiPlugins/platforms/xcb/QtXcbQpa.version. Although it is very
simple (it does nothing but put all symbols inside the Qt_5_PRIVATE_API
version node -- that is, it does not restrict the visibility of any symbols --
it is generated by the upstream build so it's best to check that nothing has
changed in upstream/qtbase/mkspecs/features/qt_module.prf, which currently
does the work as follows (QtXcbQpa is an internal module):

    internal_module {
        verscript_content = "Qt_$${QT_MAJOR_VERSION}_PRIVATE_API { *; };"
    } else {
      ...

2. Licensing

2.1. Qt Core

License choices:

  a) Qt Commercial License

  b) GPL v2-only or GPL v3-only

  c) LGPL v3-only

2.2. Meta-Object Compiler (MOC)

License choices:

  a) Qt Commercial License

  b) GPL v3-only with exceptions granted by Qt
     (upstream/qtbase/LICENSE.GPL3-EXCEPT). These exceptions relax the
     GPLv3. For example, it allows a work that contains, but does not output
     itself, MOC output (such as a program compiled with MOC-generated source
     files) to be distributed under any terms.

3. Qt mailing lists

They're listed on qt-project.org which is a fact not easy to discover starting
from https://qt.io/ but see https://wiki.qt.io/Online_Communities.

4. Build system notes

Configure/build system: https://wiki.qt.io/Qt5_Build_System

QMake manual: https://doc.qt.io/qt-5.5/qmake-manual.html

4.1 Running the upstream build

- Configure

  $ Qt5/upstream/qtbase/configure -v \
    -opensource -nomake examples -nomake tests -no-dbus

- Build

  $ make

4.2 Platform-specific code

In qmake, platform-specific code is wrapped in a "platform scope" which looks
like this:

  win32 {...}
  linux-g++ {...}
  freebsd-clang {...}

The full set of "toplevel" platform names like `win32`, `linux`, or `mingw`
can be found out by grepping for all occurrences of "QMAKE_PLATFORM" in *.conf
under upstream/qtbase/mkspecs/, while the more specific platform names like
`linux-g++`, `freebsd-clang`, or `win32-clang-msvc` each have a directory
under upstream/qtbase/mkspecs/.

4.3 Qt module configuration

In general, the qt<module>-config.h header defines the macros for public/user
features, while the qt<module>-config_p.h header defines macros for
private/internal features. Users can only enable or disable public features,
not the private ones.

In the Qt source code the features (QT_FEATURE_foo macros) are checked using
the QT_CONFIG(foo) macro (defined in qglobal.h) which will not compile unless
the macro is defined and has a value of 1 or -1.

If QT_FEATURE_foo is defined to -1 then it may also be necessary to define
QT_NO_FOO (always in the public header).

NOTE: to find usage instances, grep in upstream/qtbase/ for
      '(qtConfig|QT_CONFIG)\(<feature-name>\)'

4.3.1 Module configuration headers

(See https://wiki.qt.io/Qt5_Build_System and the "Downstream module
configuration headers" section in Qt6's README-DEV, most of which also applies
here.)

Every module has a public and private configuration header:

Global:    qconfig.h           qconfig_p.h (found in the QtCore module)
QtCore:    qtcore-config.h     qtcore-config_p.h
QtGui:     qtgui-config.h      qtgui-config_p.h
QtWidgets: qtwidgets-config.h  qtwidgets-config_p.h

Upstream, each module's config headers are generated by
qtbase/mkspecs/features/qt_configure.prf from its configure.json:

Global:    qtbase/configure.json
QtCore:    qtbase/src/corelib/configure.json
QtGui:     qtbase/src/gui/configure.json
QtWidgets: qtbase/src/widgets/configure.json

configure.json

Where a feature is defined is controlled by the "output" option under each
feature in the "features" array. The options and their effects that are of
interest to us are:

"publicFeature": define QT_FEATURE_foo in the public module config header.

"privateFeature": define QT_FEATURE_foo in the private module config header.

"feature": define QT_NO_FOO in the public module config header if this feature
           is disabled.

"type": "define": define a feature-associated macro in the public module
                  config header.

Entries in the `features` array in configure.json files correspond to .prf
files under upstream/qtbase/mkspecs/features/.

5. Platform/compiler support issues

Mac OS with GCC is not supported because certain system headers make use of
Objective-C blocks
(https://en.wikipedia.org/wiki/Blocks_(C_language_extension)) which are not
supported by GNU gcc/g++. There is an open issue to add support
(https://gcc.gnu.org/bugzilla/show_bug.cgi?id=78352) but it's stalled for what
looks like licensing reasons (see comment 16).

libQt5Gui and libQt5Widgets are not supported on FreeBSD because those CI VMs
do not have the X Window System installed.

6. Locally-patched bugs

https://invent.kde.org/qt/backports-tracker/-/issues/2449 (missing include of
qt_windows.h causing errors on min()/max() due to NOMINMAX not being defined).

7. Qt build

7.1 Shared vs. static

The upstream build defaults to shared; static libraries are not built by
default.

7.2 Symbol export

The general convention seems to be that the definition of
QT_BUILD_<library>_LIB causes <library>/qt<library>global.h to define
Q_<LIBRARY>_EXPORT to Q_DECL_EXPORT, or to Q_DECL_IMPORT if
QT_BUILD_<library>_LIB is not defined. (The upstream build automatically
defines QT_<library>_LIB in the import/consumption case but it seems to only
be used in their tests.)

Under MSVC, Q_DECL_EXPORT is defined (in corelib/global/qcompilerdetection.h)
to __declspec(dllexport) and Q_DECL_IMPORT to __declspec(dllimport). Under GCC
and Clang both are defined to __attribute__((visibility("default"))) (that is,
export the symbol).

Note that as a result of the above QT_BUILD_<library>_LIB only actually
affects symbol export under MSVC. Under GCC and Clang all symbols are exported
by default and therefore additional mechanisms such as the -fvisibility=hidden
and -fvisibility-inlines-hidden command-line options and/or linker version
scripts are used in order to restrict symbol exports.

7.3 How to identify sources to be moc'd

grep -REl 'Q_OBJ|Q_GADGET|Q_NAMESPACE' upstream/qtbase/src/<module>

This will include headers and source files (C++ and Objective-C++). The
transformations are as follows:

  `moc foo.hpp` produces moc_foo.cpp
  `moc foo.cpp` produces foo.moc (a C++ source file)
  `moc foo.mm`  produces foo.moc (note: also a C++ source file)

Most moc outputs are included, but some are compiled.

- Find included header moc outputs:

    grep -REh 'include.+moc_.+\.cpp' upstream/qtbase/src/<module>

- Find included source file moc outputs:

    grep -REh 'include.+\.moc' upstream/qtbase/src/<module>

7. Upstream repository

We use the KDE Qt5 Patch Collection because Qt stopped providing support to
non-commercial customers after Qt version 5.15.2.

Information: https://community.kde.org/Qt5PatchCollection
Repository:  https://invent.kde.org/qt/qt/qtbase (kde/5.15 branch)

That repository is regularly synced with the Qt upstream so also contains
Qt6. The KDE Patch Collection refers to the kde/5.15 branch which diverged
from the upstream Qt 5.15 branch after version 5.15.2.

The commits in the kde/5.15 branch are changes (fixes only -- no new features)
cherry-picked from the upstream dev branch (note: Qt6). Some (most?) of the
back-ported changes are made by KDE Patch Collection developers but presumably
they also back-port changes by Qt developers.

There are no releases. Because the commits are mere fixes which have been
applied to the upstream Qt6 dev branch they should be quite stable so assume
that any point along the kde/5.15 branch is stable.