|
Home · All Classes · Annotated · Functions | |
This reference document aims to explain particular items found in the build system, however, it does not provide an overview of the complete functionality of the build system. It should be used in conjunction with the (Build System User Guide} outlining the bigger picture and the Build System Internals document for developer-oriented details.
qtopia_project(keyword ... keyword)
All .pro files must contain this function and there are a number of keywords defined by the project root as well as some global keywords.
All projects require one of the following:
| Keyword | Description |
|---|---|
| app | This is an application. |
| lib | This is a library. |
| plugin | This is a plug-in. |
| subdirs | This project lists other projects to build. |
| stub | This project does not build anything, however it can install packages and handle dependencies. |
The following keywords specify the Qt version to use:
| Keyword | Description |
|---|---|
| external | Non-Qt/Qtopia Core project. |
| embedded | Qtopia Core project. |
| desktop | Qt project. |
The following table defines keywords that are useful for specific project types:
| Project Type | Keyword | Description |
|---|---|---|
| External | qtopia | This is a Qtopia project. |
| qtopiadesktop | This is a Qtopia Desktop project. | |
| Qtopia and Qtopia Desktop | core | Do not depend on the usual libraries that is, libqtopia/libqtopiadesktop. |
The etc/themes root has the following keywords:
The src/plugins/designer root has the following keywords:
depends(libraries/qtopia)
depends(libraries/*,fake)
depends() registers a dependency using the same format as projects.pri. Dependencies are searched for in the current project root directory first, then the Qtopia and Qtopia Desktop project roots followed by all other project roots. There is no support for depending on a particular project in a particular project root but such support may appear in the future.
Note: This function must only be called from .pro files or from an implicit_deps.pr[if] file.
A second argument, fake, can be passed to create a fake dependency. Fake dependencies effect the order of building without changing the actual dependency tree. For example, src/build/extra/extra.pro depends on everything but is a fake dependency designed to be processed last.
For further information refer to: Dependencies.
dep(DEFINES+=CALLER=\$$TARGET)
dep(DEFINES+=CALLER=\$$TARGET,DEFINES)
dep() registers a command to be run by dependent projects. For example, a library can use this to affect the link line of dependent projects. A second argument can be passed that causes the command to run (and the variable to be exported) so that same command can be used for both this project and dependent projects.
There are some caveats to dep():
dep(LIBS+=-l$$TARGET)
dep(INCLUDEPATH+=../include,INCLUDEPATH)
idep() is similar to dep() but works for indirect dependents also. This is useful for DEFINES and INCLUDEPATHS that headers rely on. All LIBS additions should generally be with idep() so that the final link can find indirectly-used libraries.
uses_export($$TARGET)
uses_export() assists the set up of _EXPORT macros. This is required for Qtopia Desktop on Windows but is also useful for symbol hiding in GCC 4.
Note: This does not set the _EXPORT macros but instead sets a _MAKEDLL or _DLL macro that the library symbol header can use to setup the _EXPORT macros. The header for all Qtopia libs is qtopiaglobal.h.
qt_inc($$TARGET)
This function is used in libraries to enable Qt-style includes, for example: #include <ClassName>.
For further information about setting up headers refer to the Setting Up Headers section in the User Guide.
PREFIX=BLAH
BLAH_SOURCES=foo.cpp
BLAH_PRIVATE_SOURCES=bar.cpp
resolve_include()
The value in PREFIX is used to locate FORMS, HEADERS and SOURCES. It also collapses any PRIVATE_[FORMS|HEADERS|SOURCES] so that they are visible to qmake.
More functions are defined in src/build/functions.prf. Most of these are utility functions used by the build system and a brief description generally precedes each function.
CONFIG is a variable just like other qmake variables however there are special behaviors for CONFIG.
Testing for values in a variable is performed as follows:
VAR+=foo
contains(VAR,foo):message(foo)
!contains(VAR,bar):message(!bar)
While this works in CONFIG, the following shorthand also works:
CONFIG+=foo
foo:message(foo)
!bar:message(!bar)
There is also a CONFIG() function to help with mutually-exclusive values, that works as follows:
CONFIG+=debug
CONFIG+=release
debug:message(debug) # WRONG
CONFIG(debug,debug|release):message(debug) # CORRECT
Finally, after the .pro file is read, the values in CONFIG are used to locate .prf files:
CONFIG+=foo # will cause foo.prf to be loaded, if it exists
Since CONFIG is used for so many things there are some conventions to reduce the chance of a naming conflict:
The following table describes the available CONFIG values:
| Value | Usage | Description |
|---|---|---|
| no_install | CONFIG+=no_install | no_install is set to ensure your target is not installed. This done automatically for stub and subdirs projects. |
| qtopia_main | CONFIG+=qtopia_main | Notifies the build system that the application uses the QTOPIA_ADD_APPLICATION and QTOPIA_MAIN macros. For further information refer to: Applications. |
| no_quicklaunch | CONFIG+=no_quicklaunch | Notifies the build system that the application should not be built for quicklaunching. This is only applicable if the qtopia_main CONFIG value is used. For further information refer to: Applications. |
| no_singleexec |
CONFIG+=no_singleexec
idep(CONFIG+=no_singleexec,CONFIG)
| Notifies the build system that the application should not be built into the singleexec binary. This is only applicable if the qtopia_main CONFIG value is used. Libraries should use idep() so that dependents are also excluded from the build. For further information refer to: Applications. |
| singleexec_main | CONFIG+=singleexec_main | Notifies the build system that the application should be built into the singleexec binary, even though it does not support quicklauncher. You must ensure the application can be called by the server. For further information refer to: Applications. |
| no_dest | CONFIG+=no_dest | Some projects are built in particular locations by default. Setting no_dest prevents modification of DESTDIR, and ensures project output is located in the build directory. |
| no_tr | CONFIG+=no_tr | Set no_tr if your project does not use the tr() macro. This prevents any handling of i18n files. For further information refer to: Internationalization. |
| no_auto_translatables | CONFIG+=no_auto_translatables | Set to prevent the automatic adding of FORMS, HEADERS and SOURCES to TRANSLATABLES. |
| no_target | CONFIG+=no_target | Do not set target.path automatically. |
| no_pkg | CONFIG+=no_pkg | Do not allow the default package to be created. Packages can still be created, but must be created explicitly. For further information refer to: Packages. |
| build_all_dirs |
# Limit to two subdirectories.
# Leave SUBDIRS empty for all
# subdirectories.
SUBDIRS=foo bar
CONFIG+=build_all_dirs
| Used by a subdirs project to specify that all available sub-directories be built rather than relying on the PROJECTS variable. This is superior to having recursive subdirs files because dependencies cannot be processed when that is done. |
PREFIX=FOO
This variable is used by the resolve_include() function to locate FORMS, HEADERS and SOURCES.
FORMS+=foo.ui
Add one or more .ui files to a project.
HEADERS+=foo.h
Add one or more headers to a project. This is not strictly required but if not used, qmake will not create dependencies for the headers.
SOURCES+=foo.pp
Add one or more source files to a project.
foo.files=my.png
foo.path=/pics
INSTALLS+=foo
Register an install object. Qtopia allows Install Hints to be set to simplify installations.
Note: When referring to the Makefile target install_ must be prepended.
COND_SOURCES=foo.cpp
TRANSLATABLES+=$$COND_SOURCES
cond:SOURCES+=$$COND_SOURCES
TRANSLATABLES lists all of the translatable files for a project. For further information refer to: Internationalization.
TARGET=myapp
TARGET sets the name of the project and is used to name the output file. If a TARGET is not specified, the name of the directory is used. The build system sets a macro with the name as a string (ie. -DQTOPIA_TARGET="foo"). This can be used with the QTOPIA_MAIN macros (See Applications for details) and anywhere the name of the application is required.
TRTARGET=myapp
This sets the name of the project for translations. It is required because the TARGET can change for libraries and plug-ins (including quicklaunched applications). This defaults to TARGET before any changes are made to it. The build system sets a macro with the name as a string (ie. -DQTOPIA_TRTARGET="foo"). This can be used where the translation name of the application is requried.
DEFINES+=FOO
DEFINES+=BAR=value
Add a define. The first case can be tested with #ifdef FOO. The second can also be used as a value. Since this is passed to the compiler on the command line you will need to quote any shell characters. For example, a string should be passed as DEFINES+=STR=\"str\".
EXTRA_TS_FILES+=QtopiaHandwriting
Translations are generally handled for each .pro file but there are many common resources in Qtopia that are processed in one go from the server's .pro file. However, applications are still responsible for installing their own .ts files. This variable simplifies the process since you only need to list the name of the .ts file. For third party projects, this is probably not very useful unless you are creating .ts files on your own.
QTOPIA_LICENSE=GPL
Set the license for the project. This is not particularly helpful, however it exists to ensure that particular license conditions are not violated. See src/build/license.prf for details.
foo.name=foo
foo.targets=install_foo
PACKAGES+=foo
Register an additional package from a .pro file. For further information refer to: Packages.
plugin_type=application
Force the plug-in type. Normally the build system uses the parent directory's name but third party plug-ins may not be located appropriately for this to work. The value used here should match the plug-in type being built. See plugins/* for appropriate values.
VPATH+=some/dir
SOURCES+=foo.pp
Register another directory for qmake to search for files. By default qmake will search relative to both the source and build trees. This is useful when including source from another directory.
PROJECTS+=libraries/qtopia
This variable should only be set in files that projects.pri loads. It lists the projects to be built for the current project root.
For further information refer to: Deciding what to build for details.
THEMES+=qtopia
This variable should only be set in files that projects.pri loads. It lists the theme projects (located in etc/themes) to be built. For further information refer to: Deciding what to build.
SUBDIRS+=foo
Subdirs projects will build projects that are in the SUBDIRS variable.
INCLUDEPATH+=/usr/include
Add a directory for includes. This will be searched by qmake for dependencies and made available to the compiler using -I/usr/include.
foo.files=pics/*
foo.path=/pics/appname
foo.hint=pics
INSTALLS+=foo
Register an image install. This uses bin/installpic to install pictures so that icons (icons/<size>x<size>/*) are scaled appropriately and translated images (i18n/<lang>/*) are handled. If you cannot use pics/* then use pics/*.png pics/icons pics/i18n so that icons and translated images can be handled.
foo.files=$$HEADERS
foo.path=/include/qtopia/libname
foo.hint=headers
INSTALLS+=foo
Register a header install. For further information refer to: Setting Up Headers .
foo.source=/path/to/helproot
foo.files=foo.html
foo.hint=help
INSTALLS+=foo
Register a help install. This uses bin/installhelp so that translated help files (i18n/<lang>/*) are handled.
foo.hint=sdk
Register an SDK install. This install occurs when make sdk is run and can be combined with headers.
foo.hint=devsdk
Register a devsdk install. This install occurs make devsdk is run.
foo.files=example.desktop
foo.path=/apps/Applications
foo.hint=desktop
INSTALLS+=foo
Register a .desktop install. This uses docapi_installer to add the information from a .desktop file into the database.
foo.files=$$QTOPIA_DEPOT_PATH/etc/dict/internet
foo.path=/etc/dict
foo.hint=dawg
INSTALLS+=foo
Register a dawg install. This uses qdawggen to convert the input file into the .dawg format used by Qtopia.
foo.files=example.desktop
foo.path=/apps/Applications
foo.trtarget=example-nct
foo.hint=nct desktop
INSTALLS+=foo
foo.files=$$QTOPIA_DEPOT_PATH/etc/zoneinfo/zone.tab
foo.trtarget=timezone
# don't automatically install this
foo.CONFIG=no_path no_default_install
# We're really only interested in the translations for zone.tab
foo.hint=nct
INSTALLS+=zonetab
Register non-code translatable files. For further information refer to: Non-code Translatables.
| Copyright © 2006 Trolltech | Trademarks | Qtopia 4.1.7 |