Home · All Classes · Annotated · Functions

Build System Internals

This document is designed for people who need to extend or modify the build system. If you are looking for information about using the build system (including writing .pro files) refer to: Build System User Guide and Build System Reference.

• Environment Variables
• Build Steps
• Features
• Install Prefixes
• Debugging qmake
• Finding Files, Directories and Paths
• Style
• Processing Order
• Project Roots
• Building Qt/Qtopia Core
• Command Redirection
• How Do I ...
• ... add a custom compiler?
• ... use install rules at other times?
• ... run some commands before the target is built?
• ... run some commands after the target is built?
• ... make my project get processed last?

Environment Variables

The User Guide states that environment variables are not required, however, that is not strictly correct. The build system causes the environment variables to be set appropriately when building and the configure, qtopiamake and Makefile scripts handle this for you. However, there are various scripts that cannot be run without environment variables set. If they are run from one of the scritps above, they will be fine but manual running will cause problems.

The following variable is expected by configure:

• QPEDIR
  • Set it to the location of the build tree.
  • Unlike previous versions of Qtopia, QPEDIR can no longer override PWD to set the location of the build tree.
  • You can leave QPEDIR unset when you run configure, qtopiamake or make.
  • A future version of Qtopia will not use QPEDIR.

The following variables can be defined if required:

• QTOPIA_DEPOT_PATH
  • Set it to the location of the Qtopia source tree.

The following table displays the variables that are set by configure and Makefile:

The following table describes the variables that Makefile allows you to override:

Build Steps

• configure
  • Configure Qt and Qtopia Core.
  • Create $QPEDIR/src/config.pri based on the options passed (and guessed/detected)
  • Prepare the build tree (eg. symlink files from the source tree)
  • Create a Makefile for every .pro file (mirrored into the source tree for depot hopping)
  • Create $QPEDIR/include and ensure libs have been processed (make syncqtopia)
  • Set up the project roots
    • $QPEDIR/src - Qtopia
    • $QPEDIR/src/qtopiadesktop - Qtopia Desktop
    • $QPEDIR/etc/themes - Themes
    • $QPEDIR/src/plugins/designer - Designer plugins
• Makefile
  • Perform depot hopping
  • Set up environment/overrides/etc.
  • Ensure Makefile.target is up-to-date
  • Run Makefile.target (the file qmake generates)
• .qmake.cache
  • There's one of these for each of the project roots.
  • Nothing much is done in this file. It exists because qmake will include it automatically.
  • include tree_config.pri
• tree_config.pri
  • There is one of these for each of the project roots.
  • Set up config values.
  • Add project keywords suitable for this part of the tree.
• default_pre.prf
  • This file is guaranteed to be loaded before the main project file
  • Load functions.prf
  • Load config.prf
• functions.prf
  • Set up custom functions
  • define the qtopia_project() function
• config.prf
  • Load config.pri
  • Set up static config
  • load projects.pri
• last_minute_config.prf
  • This is the last chance to set config before the .pro file is processed.
  • It is loaded from inside the qtopia_project() macro so scoping rules apply, that is you must export() variables to refer to them later.
• [project].pro
  • This is the actual .pro file for the project
  • qtopia_project() must be called or you'll get an error
• qtopia_project()
  • Set up defaults and configure build system for the type of project being built
• projects.pri
  • Set up the PROJECTS variable
  • See Deciding What To Build for details.
  • All applications that are applicable to a particular edition are enabled. The build system handles missing dependencies.
• default_post.prf
  • Ensure the order of CONFIG variables is correct.(some features should be loaded early, others should be late)

The rest of the feature files are described below since they are not all loaded for any given project.

Features

Features are introduced in qmake 4 and have the following characteristics:

• A feature is either explicitly or implicity loaded using load(). For example, CONFIG+=qtopiadesktop indicates that qtopiadesktop.prf will be loaded if it exists.
• A feature is not loaded more than once for each project instance.
• Qtopia feature files are located in $PROJECT_ROOT/features and $QTOPIA_DEPOT_PATH/src/build.
• qmake uses the QMAKEFEATURES variable to determine where to search for these directories.
• A feature can appear to load itself for example, default_pre.prf calls load(default_pre)) but what actually happens is that another feature in a later directory is loaded if it exists.

  The example provided is used because Qtopia's default_pre.prf needs to load the Qt default_pre.prf file.

Note: When adding a new .prf file that matches one of the global files, to the project root features directory, be sure to load the global file unless you completely replace its functionality. For example:

    # $QPEDIR/tests/features/qtopiadesktop.prf
    load(qtopiadesktop) # get the Qtopia one

    # override something that we didn't like

The following table describes features that can be loaded after a project's .pro file . Note: Some of these files are described in more detail later:

Install Prefixes

Items are installed to different locations depending on the edition and platform you are building for.

Note:

1. Resources includes everything that is not an application, library or plug-in.
2. The situation with binaries on Mac OS X is unique. The binaries are actually located in:
   • Qtopia Desktop.app/Contents/MacOS/qtopiadesktop
   • Qtopia Desktop.app/Resources/assistant.app/Contents/MacOS/assistant

As you can see, no locations are common between the supported configurations. The install_prefix feature provides the following variables that allow the install path to be set correctly:

• $$bindir
• $$libdir
• $$plugdir
• $$resdir

Using these variables is not strictly required for Qtopia-only projects and there are some situations where you should not use them, including:

• Automatic installs (documented below) will get these automatically.
• Targets that are not part of an install (eg. SDK) should not use these prefixes.

Debugging qmake

To display debug messages (including dependency statements) touch $QPEDIR/src/build/debug_on or export QMAKE_DEBUG_ON=1.

To display qmake debug run the command: make qmake-debug. You can specify more verbosity by running make qmake-debug D="-d -d -d" (more -d's indicates a more verbose debug).

To display when each build system file is processed touch $QPEDIR/src/build/trace_on. The output has more information than it should but there is no easy way to fix that. The following is an annotated example, showing which parts are relevant:

    These files are not read by your project.
    Project MESSAGE: .qmake.cache
    Project MESSAGE: default_pre.prf
    Project MESSAGE: functions.prf
    Project MESSAGE: config.prf
    Project MESSAGE: .qmake.cache

    Here is the real starting point that is, the last .qmake.cache before the first functions.prf.
    Project MESSAGE: .qmake.cache
    Project MESSAGE: default_pre.prf
    Project MESSAGE: functions.prf
    Project MESSAGE: config.prf
    Project MESSAGE: datebook.pro
    Project MESSAGE: default_post.prf
    Project MESSAGE: qtopia.prf
    Project MESSAGE: depends.prf

    These files are not read by your project.
    Project MESSAGE: START DEPENDENCIES
    Project MESSAGE: default_pre.prf
    Project MESSAGE: functions.prf
    Project MESSAGE: config.prf
    Project MESSAGE: qtopia.pro
    Project MESSAGE: default_pre.prf
    Project MESSAGE: functions.prf
    Project MESSAGE: config.prf
    Project MESSAGE: qtopiapim.pro
    Project MESSAGE: default_pre.prf
    Project MESSAGE: functions.prf
    Project MESSAGE: config.prf
    Project MESSAGE: quicklauncher.pro
    Project MESSAGE: INDIRECT DEPENDENCIES
    Project MESSAGE: default_pre.prf
    Project MESSAGE: functions.prf
    Project MESSAGE: config.prf
    Project MESSAGE: server.pro
    Project MESSAGE: END DEPENDENCIES

    These files are being read by your project.
    Project MESSAGE: i18n.prf
    Project MESSAGE: installs.prf
    Project MESSAGE: common.prf

Finding Files, Directories and Paths

The following table describes the variables available to help you locate files, directories and paths:

Note:

1. The build system searches for files relative to PWD.
2. qmake searches for files in a number of places, generally relative to SRCDIR, OUT_PWD and each location in VPATH.
3. The Qt and Qtopia Core source trees are the same. The presence of both variables is for legacy purposes only.

Style

The following is a guide to style issues when coding:

• Do not use for loops in shell, alternatively use the qmake for() function instead. Look at existing files for an example of how to do this.
• Do not set DESTDIR or target.path unless the default values are not acceptable.
• Do not set CONFIG values such as qt, debug, warn, release, static unless absolutely neccessary.
• Values for CONFIG should be lower case, optionally using _ to separate words.
• Use $$VAR where possible. When followed by whitespace or /, you do not need the {} delimiters. However, there are cases where the delimiters are required, for example, $${VAR}_foo.
• Beware of object notation. Unlike most languages, qmake allows . to be part of a variable. For example, $$FOO.bar is the same as $${FOO.bar}, not $${FOO}.bar.
• Do not use $$(FOO) unless it is absolutely necessary as this will dereference an environment variable at the time the .pro file is processed.
• Do not use $(FOO) unless it is absolutely necessary as this will dereference a make variable when make is run. qmake does not dereference this as an environment variable so files specified using this will not be found.

Processing Order

Libraries must be processed before other projects that link to them. When qmake processes a library it creates a .prl file. When a project links to a library, qmake reads the .prl file. If the .prf file does not exist, qmake will guess the contents which can cause problems. The dependency system should be enough to prevent this from happening but to be sure, configure runs make syncqtopia to ensure all library directories are processed.

The build system installs headers based on install rules defined in .pro files. This means that projects cannot be built before the headers they depend on are installed. The dependency system should be enough to prevent this from happening but to be sure, configure runs make syncqtopia which causes the include directory to be set up.

Project Roots

The following files are expected (though optional) for each project root:

Building Qt/Qtopia Core

Qt/Qtopia Core is built by running make in the following locations:

• src/libraries/qt
• src/tools/qt
• src/plugins/qt
• src/libraries/qtopiacore
• src/tools/qtopiacore
• src/plugins/qtopiacore

Note: Do not build Qt/Qtopia core by enterin $QPEDIR/qtopiacore/[host|target].

Command Redirection

To override qmake-generated targets name them specially. The exception to this is the all target. The structure is redirect_<target> for example:

    redirect_clean.commands=@echo overriding the clean target
    QMAKE_EXTRA_TARGETS+=redirect_clean

The all target cannot be overridden but you can trigger a command to run at that time. This is mostly useful for stub projects as they do not build anything. For example:

    redirect_all.commands=@echo redirect_all
    ALL_DEPS+=redirect_all

There are some commands cannot be overriden:

• [first_]syncqtopia (libraries only)
• regenerate/qmake (you can hook onto this event though, see below)

    mytarget.commands=@echo regenerating
    QMAKE_EXTRA_TARGETS+=mytarget
    regenerate.depends+=mytarget

How Do I ...

... add a custom compiler?

The following is an example to compile some Flex (Lex) and Bison (YACC) files. These examples are useful because qmake's built-in support for these compilers is limited.

Note: This solution can only support one Flex and one Bison source file per project.

    FLEX_SOURCES=lexer.l
    BISON_SOURCES=parser.y

    flex.commands=flex -o${QMAKE_FILE_OUT} ${QMAKE_FILE_IN}
    flex.output=$$OUT_PWD/${QMAKE_FILE_BASE}.c
    flex.input=FLEX_SOURCES
    flex.variable_out=SOURCES
    flex.name=flex ${QMAKE_FILE_IN}
    # qmake can't parse lexer.l to see this dependency
    flex.depends=parser.h
    QMAKE_EXTRA_COMPILERS+=flex

    bisonsource.commands=bison -d -o${QMAKE_FILE_OUT} ${QMAKE_FILE_IN}
    bisonsource.output=$$OUT_PWD/${QMAKE_FILE_BASE}.c
    bisonsource.input=BISON_SOURCES
    bisonsource.variable_out=SOURCES
    bisonsource.name=bisonsource ${QMAKE_FILE_IN}
    QMAKE_EXTRA_COMPILERS+=bisonsource

    # This dummy entry is required so that qmake handles the header correctly
    bisonheader.commands=@true
    bisonheader.output=$$OUT_PWD/${QMAKE_FILE_BASE}.h
    bisonheader.input=BISON_SOURCES
    bisonheader.variable_out=HEADERS
    bisonheader.name=bisonheader ${QMAKE_FILE_IN}
    # this dependency is required so that files that depend on parser.h are processed after Bison is run
    bisonheader.depends=parser.c
    QMAKE_EXTRA_COMPILERS+=bisonheader

... use install rules at other times?

You need to set the following CONFIG:

    foo.CONFIG=no_default_install

This makes the rule exist but does not force the install target depend on it. For example, the headers hint uses this so that the rules for setting up the include directory do not trigger when you run make install.

... run some commands before the target is built?

It is somewhat tricky to get your code to run before the target is built. The easiest way is to create a compiler that outputs to the HEADERS or SOURCES variable.

    # This crap is needed to generate datasets.h
    GENERATOR=make_test_data.pl
    dataset.commands=$$COMMAND_HEADER\
        $$PWD/make_test_data.pl ${QMAKE_FILE_OUT}
    dataset.output=$$OUT_PWD/datasets.h
    dataset.input=GENERATOR
    dataset.variable_out=HEADERS
    dataset.name=Generate ${QMAKE_FILE_OUT}
    QMAKE_EXTRA_COMPILERS+=dataset

You need to #include the generated file in some other file to force this to run first.

... run some commands after the target is built?

You can force your target to run after the target is built by depending on it. Note: The use of the Makefile variable.

    foo.depends+=$(TARGET)

... make my project get processed last?

You can use fake dependencies to do this. However, src/build/extra already does this so you can just depend on it or put your commands in there.