6.12. Using Qt

6.12.1. Ports That Require Qt

The Ports Collection provides support for Qt 4 and Qt 5 frameworks with USES+=qt:x, where x is 4 or 5. Set USE_QT to the list of required Qt components (libraries, tools, plugins). The Qt 4 and Qt 5 frameworks are quite similar. The main difference is the set of supported components.

The Qt framework exports a number of variables which can be used by ports, some of them listed below:

Table 6.11. Variables Provided to Ports That Use Qt
QMAKEFull path to qmake binary.
LRELEASEFull path to lrelease utility.
MOCFull path to moc.
RCCFull path to rcc.
UICFull path to uic.
QT_INCDIRQt include directory.
QT_LIBDIRQt libraries path.
QT_PLUGINDIRQt plugins path.

6.12.2. Component Selection

Individual Qt tool and library dependencies must be specified in USE_QT. Every component can be suffixed with _build or _run, the suffix indicating whether the dependency on the component is at buildtime or runtime. If unsuffixed, the component will be depended on at both build- and runtime. Usually, library components are specified unsuffixed, tool components are mostly specified with the _build suffix and plugin components are specified with the _run suffix. The most commonly used components are listed below (all available components are listed in _USE_QT_ALL, _USE_QT4_ONLY, and _USE_QT5_ONLY in /usr/ports/Mk/Uses/qt.mk):

Table 6.12. Available Qt Library Components
NameDescription
corecore library (Qt 5 only)
corelibcore library (Qt 4 only)
dbusQt DBus library
guigraphical user interface library
networknetwork library
openglQt OpenGL library
scriptscript library
sqlSQL library
testlibunit testing library
webkitQt WebKit library
xmlQt XML library

To determine the libraries an application depends on, run ldd on the main executable after a successful compilation.

Table 6.13. Available Qt Tool Components
NameDescription
qmakeMakefile generator/build utility
buildtoolsbuild tools (moc, rcc), needed for almost every Qt application (Qt 5 only)
linguisttoolslocalization tools: lrelease, lupdate (Qt 5 only)
linguistlocalization tools: lrelease, lupdate (Qt 4 only)
mocmeta object compiler, needed for almost every Qt application at buildtime (Qt 4 only)
rccresource compiler, needed if the application comes with *.rc or *.qrc files (Qt 4 only)
uicuser interface compiler, needed if the application comes with *.ui files, in practice, every Qt application with a GUI (Qt 4 only)

Table 6.14. Available Qt Plugin Components
NameDescription
iconenginesSVG icon engine plugin, needed if the application ships SVG icons (Qt 4 only)
imageformatsplugins for TGA, TIFF, and MNG image formats

Example 6.15. Selecting Qt 4 Components

In this example, the ported application uses the Qt 4 graphical user interface library, the Qt 4 core library, all of the Qt 4 code generation tools and Qt 4's Makefile generator. Since the gui library implies a dependency on the core library, corelib does not need to be specified. The Qt 4 code generation tools moc, uic and rcc, as well as the Makefile generator qmake are only needed at buildtime, thus they are specified with the _build suffix:

USES=	qt:4
USE_QT=	gui moc_build qmake_build rcc_build uic_build

6.12.3. Using qmake

If the application provides a qmake project file (*.pro), define USES= qmake along with USE_QT. USES= qmake already implies a build dependency on qmake, therefore the qmake component can be omitted from USE_QT. Similar to CMake, qmake supports out-of-source builds, which can be enabled by specifying the outsource argument (see USES= qmake example). Also see Table 6.15, “Possible Arguments for USES= qmake.

Table 6.15. Possible Arguments for USES= qmake
VariableDescription
no_configureDo not add the configure target. This is implied by HAS_CONFIGURE=yes and GNU_CONFIGURE=yes. It is required when the build only needs the environment setup from USES= qmake, but otherwise runs qmake on its own.
no_envSuppress modification of the configure and make environments. It is only required when qmake is used to configure the software and the build fails to understand the environment setup by USES= qmake.
norecursiveDo not pass the -recursive argument to qmake.
outsourcePerform an out-of-source build.

Table 6.16. Variables for Ports That Use qmake
VariableDescription
QMAKE_ARGSPort specific qmake flags to be passed to the qmake binary.
QMAKE_ENVEnvironment variables to be set for the qmake binary. The default is ${CONFIGURE_ENV}.
QMAKE_SOURCE_PATHPath to qmake project files (.pro). The default is ${WRKSRC} if an out-of-source build is requested, empty otherwise.

When using USES= qmake, these settings are deployed:

CONFIGURE_ARGS+=	--with-qt-includes=${QT_INCDIR} \
			--with-qt-libraries=${QT_LIBDIR} \
			--with-extra-libs=${LOCALBASE}/lib \
			--with-extra-includes=${LOCALBASE}/include

CONFIGURE_ENV+=	QTDIR="${QT_PREFIX}" QMAKE="${QMAKE}" \
		MOC="${MOC}" RCC="${RCC}" UIC="${UIC}" \
		QMAKESPEC="${QMAKESPEC}"

PLIST_SUB+=	QT_INCDIR=${QT_INCDIR_REL} \
		QT_LIBDIR=${QT_LIBDIR_REL} \
		QT_PLUGINDIR=${QT_PLUGINDIR_REL}

Some configure scripts do not support the arguments above. To suppress modification of CONFIGURE_ENV and CONFIGURE_ARGS, set USES= qmake:no_env.

Example 6.16. USES= qmake Example

This snippet demonstrates the use of qmake for a Qt 4 port:

USES=	qmake:outsource qt:4
USE_QT=	moc_build

For a Qt 5 port:

USES=	qmake:outsource qt:5
USE_QT=	buildtools_build

Qt applications are often written to be cross-platform and often X11/Unix is not the platform they are developed on, which in turn leads to certain loose ends, like:

  • Missing additional include paths. Many applications come with system tray icon support, but neglect to look for includes and/or libraries in the X11 directories. To add directories to qmake's include and library search paths via the command line, use:

    QMAKE_ARGS+=	INCLUDEPATH+=${LOCALBASE}/include \
    		LIBS+=-L${LOCALBASE}/lib
  • Bogus installation paths. Sometimes data such as icons or .desktop files are by default installed into directories which are not scanned by XDG-compatible applications. editors/texmaker is an example for this - look at patch-texmaker.pro in the files directory of that port for a template on how to remedy this directly in the qmake project file.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.