qmake Function Reference

Home · All Classes · All Functions · Overviews

[Previous: qmake Variable Reference] [Contents] [Next: Configuring qmake's Environment]

qmake Function Reference

qmake provides built-in functions to allow the contents of variables to be processed, and to enable tests to be performed during the configuration process. Functions that process the contents of variables typically return values that can be assigned to other variables, and these values are obtained by prefixing function with the $$ operator. Functions that perform tests are usually used as the conditional parts of scopes; these are indicated in the function descriptions below.

basename(variablename)

Returns the basename of the file specified. For example:

 FILE = /etc/passwd
 FILENAME = $$basename(FILE) #passwd

CONFIG(config)

[Conditional]

This function can be used to test for variables placed into the CONFIG variable. This is the same as regular old style (tmake) scopes, but has the added advantage a second parameter can be passed to test for the active config. As the order of values is important in CONFIG variables (i.e. the last one set will be considered the active config for mutually exclusive values) a second parameter can be used to specify a set of values to consider. For example:

 CONFIG = debug
 CONFIG += release
 CONFIG(release, debug|release):message(Release build!) #will print
 CONFIG(debug, debug|release):message(Debug build!) #no print

Because release is considered the active setting (for feature parsing) it will be the CONFIG used to generate the build file. In the common case a second parameter is not needed, but for specific mutual exclusive tests it is invaluable.

contains(variablename, value)

[Conditional]

Succeeds if the variable variablename contains the value value; otherwise fails. You can check the return value of this function using a scope.

For example:

 contains( drivers, network ) {
     # drivers contains 'network'
     message( "Configuring for network build..." )
     HEADERS += network.h
     SOURCES += network.cpp
 }

The contents of the scope are only processed if the drivers variable contains the value, network. If this is the case, the appropriate files are added to the SOURCES andHEADERS variables.

count(variablename, number)

[Conditional]

Succeeds if the variable variablename contains a list with the specified number of value; otherwise fails.

This function is used to ensure that declarations inside a scope are only processed if the variable contains the correct number of values; for example:

 options = $$find(CONFIG, "debug") $$find(CONFIG, "release")
 count(options, 2) {
     message(Both release and debug specified.)
 }

dirname(file)

Returns the directory name part of the specified file. For example:

 FILE = /etc/X11R6/XF86Config
 DIRNAME = $$dirname(FILE) #/etc/X11R6

error(string)

This function never returns a value. qmake displays the given string to the user, and exits. This function should only be used for unrecoverable errors.

For example:

 error(An error has occurred in the configuration process.)

eval(string)

[Conditional]

Evaluates the contents of the string using qmake's syntax rules and returns true. Definitions and assignments can be used in the string to modify the values of existing variables or create new definitions.

For example:

 eval(TARGET = myapp) {
     message($$TARGET)
 }

Note that quotation marks can be used to delimit the string, and that the return value can be discarded if it is not needed.

exists(filename)

[Conditional]

Tests whether a file with the given filename exists. If the file exists, the function succeeds; otherwise it fails. If a regular expression is specified for the filename, this function succeeds if any file matches the regular expression specified.

For example:

 exists( $(QTDIR)/lib/libqt-mt* ) {
       message( "Configuring for multi-threaded Qt..." )
       CONFIG += thread
 }

Note that "/" can be used as a directory separator, regardless of the platform in use.

find(variablename, substr)

Places all the values in variablename that match substr. substr may be a regular expression, and will be matched accordingly.

 MY_VAR = one two three four
 MY_VAR2 = $$join(MY_VAR, " -L", -L) -Lfive
 MY_VAR3 = $$member(MY_VAR, 2) $$find(MY_VAR, t.*)

MY_VAR2 will contain '-Lone -Ltwo -Lthree -Lfour -Lfive', and MY_VAR3 will contains 'three two three'.

for(iterate, list)

This special test function will cause a loop to be started that iterates over all values in list, setting iterate to each value in turn. As a convenience, if list is 1..10 then iterate will iterate over the values 1 through 10.

The use of an else scope afer a condition line with a for() loop is disallowed.

For example:

 LIST = 1 2 3
 for(a, LIST):exists(file.$${a}):message(I see a file.$${a}!)

include(filename)

[Conditional]

Includes the contents of the file specified by filename into the current project at the point where it is included. This function succeeds if filename is included; otherwise it fails. The included file is processed immediately.

You can check whether the file was included by using this function as the condition for a scope; for example:

 include( shared.pri )
 OPTIONS = standard custom
 !include( options.pri ) {
     message( "No custom build options specified" )
 OPTIONS -= custom
 }

infile(filename, var, val)

[Conditional]

Succeeds if the file filename (when parsed by qmake itself) contains the variable var with a value of val; otherwise fails. If you do not specify a third argument (val), the function will only test whether var has been declared in the file.

isEmpty(variablename)

[Conditional]

Succeeds if the variable variablename is empty; otherwise fails. This is the equivalent of count( variablename, 0 ).

For example:

 isEmpty( CONFIG ) {
 CONFIG += qt warn_on debug
 }

join(variablename, glue, before, after)

Joins the value of variablename with glue. If this value is non-empty it prefixes the value with before and suffix it with after. variablename is the only required field, the others default to empty strings. If you need to encode spaces in glue, before, or after you must quote them.

member(variablename, position)

Returns the value at the given position in the list of items in variablename. If an item cannot be found at the position specified, an empty string is returned. variablenameis the only required field. If not specified, position defaults to 0, causing the first value in the list to be returned.

message(string)

This function simply writes a message to the console. Unlike the error() function, this function allows processing to continue.

 message( "This is a message" )

The above line causes "This is a message" to be written to the console. The use of quotation marks is optional.

Note: By default, messages are written out for each Makefile generated by qmake for a given project. If you want to ensure that messages only appear once for each project, test the build_pass variable in conjunction with a scope to filter out messages during builds; for example:

 !build_pass:message( "This is a message" )

prompt(question)

Displays the specified question, and returns a value read from stdin.

quote(string)

Converts a whole string into a single entity and returns the result. Newlines, carriage returns, and tabs can be specified in the string with \n \r and \t. The return value does not contain either single or double quotation marks unless you explicitly include them yourself, but will be placed into a single entry (for literal expansion).

replace(string, old_string, new_string)

Replaces each instance of old_string with new_string in the contents of the variable supplied as string. For example, the code

 MESSAGE = This is a tent.
 message($$replace(MESSAGE, tent, test))

prints the message:

 This is a test.

sprintf(string, arguments...)

Replaces %1-%9 with the arguments passed in the comma-separated list of function arguments and returns the processed string.

system(command)

[Conditional]

Executes the given command in a secondary shell, and succeeds if the command returns with a zero exit status; otherwise fails. You can check the return value of this function using a scope:

For example:

 system(ls /bin):HAS_BIN=FALSE

Alternatively, you can use this function to obtain stdout and stderr from the command, and assign it to a variable. For example, you can use this to interrogate information about the platform:

 UNAME = $$system(uname -s)
 contains( UNAME, [lL]inux ):message( This looks like Linux ($$UNAME) to me )

unique(variablename)

This will return a list of values in variable that are unique (that is with repetitive entries removed). For example:

 ARGS = 1 2 3 2 5 1
 ARGS = $$unique(ARGS) #1 2 3 5

warning(string)

This function will always succeed, and will display the given string to the user. message() is a synonym for warning().

[Previous: qmake Variable Reference] [Contents] [Next: Configuring qmake's Environment]

---

Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies)

Trademarks

Qt 4.6.3