<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qmake-manual.qdoc -->
<title>Qt 4.8: qmake Function Reference</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>qmake Function Reference</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<link rel="prev" href="qmake-variable-reference.html" />
<link rel="next" href="qmake-environment-reference.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qmake-variable-reference.html">qmake Variable Reference</a>
<a class="nextPage" href="qmake-environment-reference.html">Configuring qmake's Environment</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#packagesexist-packages">packagesExist(packages)</a></li>
<li class="level1"><a href="#basename-variablename">basename(variablename)</a></li>
<li class="level1"><a href="#config-config">CONFIG(config)</a></li>
<li class="level1"><a href="#contains-variablename-value">contains(variablename, value)</a></li>
<li class="level1"><a href="#count-variablename-number">count(variablename, number)</a></li>
<li class="level1"><a href="#dirname-file">dirname(file)</a></li>
<li class="level1"><a href="#error-string">error(string)</a></li>
<li class="level1"><a href="#eval-string">eval(string)</a></li>
<li class="level1"><a href="#exists-filename">exists(filename)</a></li>
<li class="level1"><a href="#find-variablename-substr">find(variablename, substr)</a></li>
<li class="level1"><a href="#for-iterate-list">for(iterate, list)</a></li>
<li class="level1"><a href="#include-filename">include(filename)</a></li>
<li class="level1"><a href="#infile-filename-var-val">infile(filename, var, val)</a></li>
<li class="level1"><a href="#isempty-variablename">isEmpty(variablename)</a></li>
<li class="level1"><a href="#join-variablename-glue-before-after">join(variablename, glue, before, after)</a></li>
<li class="level1"><a href="#member-variablename-position">member(variablename, position)</a></li>
<li class="level1"><a href="#message-string">message(string)</a></li>
<li class="level1"><a href="#prompt-question">prompt(question)</a></li>
<li class="level1"><a href="#quote-string">quote(string)</a></li>
<li class="level1"><a href="#replace-string-old-string-new-string">replace(string, old_string, new_string)</a></li>
<li class="level1"><a href="#sprintf-string-arguments">sprintf(string, arguments...)</a></li>
<li class="level1"><a href="#system-command">system(command)</a></li>
<li class="level1"><a href="#unique-variablename">unique(variablename)</a></li>
<li class="level1"><a href="#warning-string">warning(string)</a></li>
</ul>
</div>
<h1 class="title">qmake Function Reference</h1>
<span class="subtitle"></span>
<!-- $$$qmake-function-reference.html-description -->
<div class="descr"> <a name="details"></a>
<p><a href="qmake-manual.html#qmake"><tt>qmake</tt></a> 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 <tt>$$</tt> operator. Functions that perform tests are usually used as the conditional parts of scopes; these are indicated in the function descriptions below.</p>
<a name="packagesexist-packages"></a>
<h2>packagesExist(packages)</h2>
<p>Uses the PKGCONFIG mechanism to determine whether or not the given packages exist at the time of project parsing.</p>
<p>This can be useful to optionally enable or disable features. For example:</p>
<pre class="cpp"> packagesExist(sqlite3 QtNetwork QtDeclarative) {
DEFINES += USE_FANCY_UI
}</pre>
<p>And then, in the code:</p>
<pre class="cpp"> #ifdef USE_FANCY_UI
// Use the fancy UI, as we have extra packages available
#endif</pre>
<a name="basename-variablename"></a>
<h2>basename(variablename)</h2>
<p>Returns the basename of the file specified. For example:</p>
<pre class="cpp"> FILE = /etc/passwd
FILENAME = $$basename(FILE) #passwd</pre>
<a name="config-config"></a>
<h2>CONFIG(config)</h2>
<p>[Conditional]</p>
<p>This function can be used to test for variables placed into the <tt>CONFIG</tt> 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 <tt>CONFIG</tt> 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:</p>
<pre class="cpp"> CONFIG = debug
CONFIG += release
CONFIG(release, debug|release):message(Release build!) #will print
CONFIG(debug, debug|release):message(Debug build!) #no print</pre>
<p>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.</p>
<a name="contains-variablename-value"></a>
<h2>contains(variablename, value)</h2>
<p>[Conditional]</p>
<p>Succeeds if the variable <i>variablename</i> contains the value <i>value</i>; otherwise fails. You can check the return value of this function using a scope.</p>
<p>For example:</p>
<pre class="cpp"> contains( drivers, network ) {
# drivers contains 'network'
message( "Configuring for network build..." )
HEADERS += network.h
SOURCES += network.cpp
}</pre>
<p>The contents of the scope are only processed if the <tt>drivers</tt> variable contains the value, <tt>network</tt>. If this is the case, the appropriate files are added to the <tt>SOURCES</tt> and <tt>HEADERS</tt> variables.</p>
<a name="count-variablename-number"></a>
<h2>count(variablename, number)</h2>
<p>[Conditional]</p>
<p>Succeeds if the variable <i>variablename</i> contains a list with the specified <i>number</i> of value; otherwise fails.</p>
<p>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:</p>
<pre class="cpp"> options = $$find(CONFIG, "debug") $$find(CONFIG, "release")
count(options, 2) {
message(Both release and debug specified.)
}</pre>
<a name="dirname-file"></a>
<h2>dirname(file)</h2>
<p>Returns the directory name part of the specified file. For example:</p>
<pre class="cpp"> FILE = /etc/X11R6/XF86Config
DIRNAME = $$dirname(FILE) #/etc/X11R6</pre>
<a name="error-string"></a>
<h2>error(string)</h2>
<p>This function never returns a value. <a href="qmake-manual.html#qmake"><tt>qmake</tt></a> displays the given <i>string</i> to the user, and exits. This function should only be used for unrecoverable errors.</p>
<p>For example:</p>
<pre class="cpp"> error(An error has occurred in the configuration process.)</pre>
<a name="eval-string"></a>
<h2>eval(string)</h2>
<p>[Conditional]</p>
<p>Evaluates the contents of the string using <a href="qmake-manual.html#qmake"><tt>qmake</tt></a>'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.</p>
<p>For example:</p>
<pre class="cpp"> eval(TARGET = myapp) {
message($$TARGET)
}</pre>
<p>Note that quotation marks can be used to delimit the string, and that the return value can be discarded if it is not needed.</p>
<a name="exists-filename"></a>
<h2>exists(filename)</h2>
<p>[Conditional]</p>
<p>Tests whether a file with the given <i>filename</i> 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.</p>
<p>For example:</p>
<pre class="cpp"> exists( $(QTDIR)/lib/libqt-mt* ) {
message( "Configuring for multi-threaded Qt..." )
CONFIG += thread
}</pre>
<p>Note that "/" can be used as a directory separator, regardless of the platform in use.</p>
<a name="find-variablename-substr"></a>
<h2>find(variablename, substr)</h2>
<p>Places all the values in <i>variablename</i> that match <i>substr</i>. <i>substr</i> may be a regular expression, and will be matched accordingly.</p>
<pre class="cpp"> MY_VAR = one two three four
MY_VAR2 = $$join(MY_VAR, " -L", -L) -Lfive
MY_VAR3 = $$member(MY_VAR, 2) $$find(MY_VAR, t.*)</pre>
<p>MY_VAR2 will contain '-Lone -Ltwo -Lthree -Lfour -Lfive', and MY_VAR3 will contains 'three two three'.</p>
<a name="for-iterate-list"></a>
<h2>for(iterate, list)</h2>
<p>This special test function will cause a loop to be started that iterates over all values in <i>list</i>, setting <i>iterate</i> to each value in turn. As a convenience, if <i>list</i> is 1..10 then iterate will iterate over the values 1 through 10.</p>
<p>The use of an else scope afer a condition line with a for() loop is disallowed.</p>
<p>For example:</p>
<pre class="cpp"> LIST = 1 2 3
for(a, LIST):exists(file.$${a}):message(I see a file.$${a}!)</pre>
<a name="include-filename"></a>
<h2>include(filename)</h2>
<p>[Conditional]</p>
<p>Includes the contents of the file specified by <i>filename</i> into the current project at the point where it is included. This function succeeds if <i>filename</i> is included; otherwise it fails. The included file is processed immediately.</p>
<p>You can check whether the file was included by using this function as the condition for a scope; for example:</p>
<pre class="cpp"> include( shared.pri )
OPTIONS = standard custom
!include( options.pri ) {
message( "No custom build options specified" )
OPTIONS -= custom
}</pre>
<a name="infile-filename-var-val"></a>
<h2>infile(filename, var, val)</h2>
<p>[Conditional]</p>
<p>Succeeds if the file <i>filename</i> (when parsed by <a href="qmake-manual.html#qmake"><tt>qmake</tt></a> itself) contains the variable <i>var</i> with a value of <i>val</i>; otherwise fails. If you do not specify a third argument (<i>val</i>), the function will only test whether <i>var</i> has been declared in the file.</p>
<a name="isempty-variablename"></a>
<h2>isEmpty(variablename)</h2>
<p>[Conditional]</p>
<p>Succeeds if the variable <i>variablename</i> is empty; otherwise fails. This is the equivalent of <tt>count( variablename, 0 )</tt>.</p>
<p>For example:</p>
<pre class="cpp"> isEmpty( CONFIG ) {
CONFIG += qt warn_on debug
}</pre>
<a name="join-variablename-glue-before-after"></a>
<h2>join(variablename, glue, before, after)</h2>
<p>Joins the value of <i>variablename</i> with <tt>glue</tt>. If this value is non-empty it prefixes the value with <i>before</i> and suffix it with <i>after</i>. <i>variablename</i> is the only required field, the others default to empty strings. If you need to encode spaces in <i>glue</i>, <i>before</i>, or <i>after</i> you must quote them.</p>
<a name="member-variablename-position"></a>
<h2>member(variablename, position)</h2>
<p>Returns the value at the given <i>position</i> in the list of items in <i>variablename</i>. If an item cannot be found at the position specified, an empty string is returned. <i>variablename</i> is the only required field. If not specified, <tt>position</tt> defaults to 0, causing the first value in the list to be returned.</p>
<a name="message-string"></a>
<h2>message(string)</h2>
<p>This function simply writes a message to the console. Unlike the <tt>error()</tt> function, this function allows processing to continue.</p>
<pre class="cpp"> message( "This is a message" )</pre>
<p>The above line causes "This is a message" to be written to the console. The use of quotation marks is optional.</p>
<p><b>Note:</b> 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 <tt>build_pass</tt> variable <a href="qmake-advanced-usage.html">in conjunction with a scope</a> to filter out messages during builds; for example:</p>
<pre class="cpp"> !build_pass:message( "This is a message" )</pre>
<a name="prompt-question"></a>
<h2>prompt(question)</h2>
<p>Displays the specified <i>question</i>, and returns a value read from stdin.</p>
<a name="quote-string"></a>
<h2>quote(string)</h2>
<p>Converts a whole <i>string</i> into a single entity and returns the result. This is just a fancy way of enclosing the string into double quotes.</p>
<a name="replace-string-old-string-new-string"></a>
<h2>replace(string, old_string, new_string)</h2>
<p>Replaces each instance of <tt>old_string</tt> with <tt>new_string</tt> in the contents of the variable supplied as <tt>string</tt>. For example, the code</p>
<pre class="cpp"> MESSAGE = This is a tent.
message($$replace(MESSAGE, tent, test))</pre>
<p>prints the message:</p>
<pre class="cpp"> This is a test.</pre>
<a name="sprintf-string-arguments"></a>
<h2>sprintf(string, arguments...)</h2>
<p>Replaces %1-%9 with the arguments passed in the comma-separated list of function <i>arguments</i> and returns the processed string.</p>
<a name="system-command"></a>
<h2>system(command)</h2>
<p>[Conditional]</p>
<p>Executes the given <tt>command</tt> 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:</p>
<p>For example:</p>
<pre class="cpp"> system(ls /bin):HAS_BIN=FALSE</pre>
<p>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:</p>
<pre class="cpp"> UNAME = $$system(uname -s)
contains( UNAME, [lL]inux ):message( This looks like Linux ($$UNAME) to me )</pre>
<a name="unique"></a><a name="unique-variablename"></a>
<h2>unique(variablename)</h2>
<p>This will return a list of values in variable that are unique (that is with repetitive entries removed). For example:</p>
<pre class="cpp"> ARGS = 1 2 3 2 5 1
ARGS = $$unique(ARGS) #1 2 3 5</pre>
<a name="warning-string"></a>
<h2>warning(string)</h2>
<p>This function will always succeed, and will display the given <i>string</i> to the user. message() is a synonym for warning().</p>
</div>
<!-- @@@qmake-function-reference.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qmake-variable-reference.html">qmake Variable Reference</a>
<a class="nextPage" href="qmake-environment-reference.html">Configuring qmake's Environment</a>
</p>
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
