~oif-team/ubuntu/natty/qt4-x11/xi2.1

<td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="mainclasses.html"><font color="#004faf">Main Classes</font></a> · <a href="annotated.html"><font color="#004faf">Annotated</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>

[Previous: <a href="qmake-using.html">Using qmake</a>]

[<a href="qmake-manual.html">Contents</a>]

[Next: <a href="qmake-running.html">Running qmake</a>]

</p>

<h1 align="center">qmake Project Files</h1>

<p>Project files contain all the information required by <tt>qmake</tt> to build your application, library, or plugin. The resources used by your project are generally specified using a series of declarations, but support for simple programming constructs allow you to describe different build processes for different platforms and environments.</p>

<ul><li><a href="#project-file-elements">Project File Elements</a></li>

<ul><li><a href="#variables">Variables</a></li>

<li><a href="#comments">Comments</a></li>

<li><a href="#built-in-functions-and-control-flow">Built-in Functions and Control Flow</a></li>

</ul>

<li><a href="#project-templates">Project Templates</a></li>

<li><a href="#general-configuration">General Configuration</a></li>

<li><a href="#declaring-qt-libraries">Declaring Qt Libraries</a></li>

<li><a href="#configuration-features">Configuration Features</a></li>

</ul>

<h2>Project File Elements</h2>

<p>The project file format used by <tt>qmake</tt> can be used to support both simple and fairly complex build systems. Simple project files will use a straightforward declarative style, defining standard variables to indicate the source and header files that are used in the project. Complex projects may use the control flow structures to fine-tune the build process.</p>

<p>The following sections describe the different types of elements used in project files.</p>

<h3>Variables</h3>

<p>In a project file, variables are used to hold lists of strings. In the simplest projects, these variables inform <tt>qmake</tt> about the configuration options to use, or supply filenames and paths to use in the build process.</p>

<p><tt>qmake</tt> looks for certain variables in each project file, and it uses the contents of these to determine what it should write to a Makefile. For example, the list of values in the <tt>HEADERS</tt> and <tt>SOURCES</tt> variables are used to tell <tt>qmake</tt> about header and source files in the same directory as the project file.</p>

<p>Variables can also be used internally to store temporary lists of values, and existing lists of values can be overwritten or extended with new values.</p>

<p>The following lines show how lists of values are assigned to variables:</p>

<pre>  HEADERS = mainwindow.h paintwidget.h</pre>

<p>Note that the first assignment only includes values that are specified on the same line as the <tt>SOURCES</tt> variable. The second assignment splits the items across lines by using the \ character.</p>

<p>The list of values in a variable is extended in the following way:</p>

<pre>  SOURCES = main.cpp mainwindow.cpp \

paintwidget.h

CONFIG += qt</pre>

<p>The <tt>CONFIG</tt> variable is another special variable that <tt>qmake</tt> uses when generating a Makefile. It is discussed in the section on configuration later in this chapter. In the above line, <tt>QT</tt> is added to the list of existing values contained in <tt>CONFIG</tt>.</p>

<p>The following table lists the variables that <tt>qmake</tt> recognizes, and describes what they should contain.</p>

<tr valign="top" bgcolor="#a2c511"><th>Variable</th><th>Contents</th></tr>

<tr valign="top" bgcolor="#f0f0f0"><td>CONFIG</td><td>General project configuration options.</td></tr>

<tr valign="top" bgcolor="#e0e0e0"><td>DESTDIR</td><td>The directory in which the executable or binary file will be placed.</td></tr>

<tr valign="top" bgcolor="#f0f0f0"><td>FORMS</td><td>A list of .ui files to be processed by <tt>uic</tt>.</td></tr>

<tr valign="top" bgcolor="#e0e0e0"><td>HEADERS</td><td>A list of filenames of header (.h) files used when building the project.</td></tr>

<tr valign="top" bgcolor="#f0f0f0"><td>QT</td><td>Qt-specific configuration options.</td></tr>

<tr valign="top" bgcolor="#e0e0e0"><td>RESOURCES</td><td>A list of resource (.rc) files to be included in the final project. See the <a href="resources.html">The Qt Resource System</a> for more information about these files.</td></tr>

<tr valign="top" bgcolor="#f0f0f0"><td>SOURCES</td><td>A list of source code files to be used when building the project.</td></tr>

<tr valign="top" bgcolor="#e0e0e0"><td>TEMPLATE</td><td>The template to use for the project. This determines whether the output of the build process will be an application, a library, or a plugin.</td></tr>

</table>

<p>The contents of a variable can be read by prepending the variable name with <tt>$$</tt>. This can be used to assign the contents of one variable to another:</p>

<pre>  TEMP_SOURCES = $$SOURCES</pre>

<p>The <tt>$$</tt> operator is used extensively with built-in functions that operate on strings and lists of values. These are described in the chapter on <a href="qmake-advanced-usage.html">qmake Advanced Usage</a>.</p>

<h3>Comments</h3>

<p>You can add comments to project files. Comments begin with the <tt>#</tt> symbol and continue to the end of the same line. For example:</p>

<pre>  # Comments usually start at the beginning of a line, but they

# can also follow other content on the same line.</pre>

<h3>Built-in Functions and Control Flow</h3>

<p><tt>qmake</tt> provides a number of built-in functions to allow the contents of variables to be processed. The most commonly used function in simple project files is the <tt>include</tt> function which takes a filename as an argument. The contents of the given file are included in the project file at the place where the <tt>include</tt> function is used. The <tt>include</tt> function is most commonly used to include other project files:</p>

<pre>  include(other.pro)</pre>

<p>Support for conditional structures is made available via <a href="qmake-advanced-usage.html#scopes">scopes</a> that behave like <tt>if</tt> statements in programming languages:</p>

<pre>  win32 {

SOURCES += paintwidget_win.cpp

}</pre>

<p>The assignments inside the scope are only made if the condition is true. In this case, the special <tt>win32</tt> variable must be set; this happens automatically on Windows, but this can also be specified on other platforms by running <tt>qmake</tt> with the <tt>-win32</tt> command line option (see <a href="qmake-running.html">Running qmake</a> for more information).</p>

<p>Simple loops are constructed by iterating over lists of values using the built-in <tt>for</tt> function. The following code adds directories to the <tt>SUBDIRS</tt> variable, but only if they exist:</p>

<pre>  EXTRAS = handlers tests docs

for(dir, EXTRAS) {

exists($$dir) {

SUBDIRS += $$dir

}

}</pre>

<p>More complex operations on variables that would usually require loops are provided by built-in functions such as <tt>find</tt>, <tt>unique</tt>, and <tt>count</tt>. These functions, and many others are provided to manipulate strings and paths, support user input, and call external tools. A list of the functions available can be found in the <a href="qmake-advanced-usage.html">qmake Advanced Usage</a> chapter of this manual.</p>

<h2>Project Templates</h2>

<p>The <tt>TEMPLATE</tt> variable is used to define the type of project that will be built. If this is not declared in the project file, <tt>qmake</tt> assumes that an application should be built, and will generate an appropriate Makefile (or equivalent file) for the purpose.</p>

<p>The types of project available are listed in the following table with information about the files that <tt>qmake</tt> will generate for each of them:</p>

<tr valign="top" bgcolor="#a2c511"><th>Template</th><th>Description of <tt>qmake</tt> output</th></tr>

100

<tr valign="top" bgcolor="#f0f0f0"><td>app (default)</td><td>Creates a Makefile to build an application.</td></tr>

101

<tr valign="top" bgcolor="#e0e0e0"><td>lib</td><td>Creates a Makefile to build a library.</td></tr>

102

<tr valign="top" bgcolor="#f0f0f0"><td>subdirs</td><td>Creates a Makefile that will go into the specified directories and run <tt>qmake</tt> on any project files found.</td></tr>

103

<tr valign="top" bgcolor="#e0e0e0"><td>vcapp</td><td>Creates a Visual Studio Project file to build an application.</td></tr>

104

<tr valign="top" bgcolor="#f0f0f0"><td>vclib</td><td>Creates a Visual Studio Project file to build a library.</td></tr>

105

</table>

106

<p>See the <a href="qmake-tutorial.html">qmake Tutorial</a> for advice on writing project files for projects that use the <tt>app</tt> and <tt>lib</tt> templates.</p>

107

<p>When the <tt>subdirs</tt> template is used, <tt>qmake</tt> generates a Makefile to examine each specified subdirectory, process any project file it finds there, and run the platform's <tt>make</tt> tool on the newly-created Makefile.</p>

108

<p>The only system variable that is recognised for this template is the <tt>SUBDIRS</tt> variable. This variable contains a list of all the subdirectories that contain project files to be processed. It is essential that the project file in each subdirectory has the same name as the subdirectory, so that <tt>qmake</tt> can find it. For example, if the subdirectory is called <tt>myapp</tt> then the project file in that directory should be called <tt>myapp.pro</tt>.</p>

109

110

<h2>General Configuration</h2>

111

<p>The <tt>CONFIG</tt> variable specifies the options and features that the compiler should use and the libraries that should be linked against. Anything can be added to the <tt>CONFIG</tt> variable, but the options covered below are recognized by <tt>qmake</tt> internally.</p>

112

<p>The following options control the compiler flags that are used to build the project:</p>

113

114

<tr valign="top" bgcolor="#a2c511"><th>Option</th><th>Description</th></tr>

115

<tr valign="top" bgcolor="#f0f0f0"><td>release</td><td>The project is to be built in release mode. This is ignored if <tt>debug</tt> is also specified.</td></tr>

116

<tr valign="top" bgcolor="#e0e0e0"><td>debug</td><td>The project is to be built in debug mode.</td></tr>

117

<tr valign="top" bgcolor="#f0f0f0"><td>warn_on</td><td>The compiler should output as many warnings as possible. This is ignored if <tt>warn_off</tt> is specified.</td></tr>

118

<tr valign="top" bgcolor="#e0e0e0"><td>warn_off</td><td>The compiler should output as few warnings as possible.</td></tr>

119

</table>

120

<p>Note that each of the options specified in the <tt>CONFIG</tt> variable can also be used as a condition in scopes. This enables different configurations to be defined for <tt>release</tt> and <tt>debug</tt> builds, and is described in more detail in the <a href="qmake-advanced-usage.html#scopes">Scopes</a> section of the Advanced Usage chapter of this manual.</p>

121

<p>The following options define the type of project to be built. Note that some of these options only take effect when used on the relevant platform. On other platforms, they have no effect.</p>

122

123

<tr valign="top" bgcolor="#a2c511"><th>Option</th><th>Description</th></tr>

124

<tr valign="top" bgcolor="#f0f0f0"><td>qt</td><td>The project is a Qt application and should link against the Qt library. You can use the <tt>QT</tt> variable to control any additional Qt modules that are required by your application.</td></tr>

125

<tr valign="top" bgcolor="#e0e0e0"><td>thread</td><td>The project is a multi-threaded application.</td></tr>

126

<tr valign="top" bgcolor="#f0f0f0"><td><a href="winsystem.html#x11">x11</a></td><td>The project is an <a href="winsystem.html#x11">X11</a> application or library.</td></tr>

127

</table>

128

<p>When using the <tt>app</tt> or <tt>lib</tt> templates, more specialized configuration options can be used to fine tune the build process. These are explained in details in the <a href="qmake-common-projects.html">Common Projects</a> chapter of this manual.</p>

129

<p>For example, if your application uses the Qt library and you want to build it as a multi-threaded application in <tt>debug</tt> mode, your project file will contain the following line:</p>

130

<pre>  CONFIG += qt thread debug</pre>

131

<p>Note, that you must use "+=", not "=", or <tt>qmake</tt> will not be able to use Qt's configuration to determine the settings needed for your project.</p>

132

133

<h2>Declaring Qt Libraries</h2>

134

<p>If you enable qmake's support for Qt with the <tt>CONFIG</tt> variable, it is possible to further specify which of the Qt libraries you will link with your application. This is achieved with the <tt>QT</tt> variable which can be used to declare the required extension modules. For example, we can enable the XML and network modules in the following way:</p>

135

<pre>  CONFIG += qt

136

QT += network xml</pre>

137

<p>Note that <tt>QT</tt> includes the core and GUI modules by default, so the above declaration <i>adds</i> the network and XML modules to this default list. The following assignment <i>omits</i> the default modules, and will lead to errors when the application's source code is being compiled:</p>

138

<pre>  QT = network xml # This will omit the core and GUI modules.</pre>

139

<p>If you want to build a project <i>without</i> the GUI module, you need to exclude it with the "-=" operator. By default, <tt>QT</tt> contains both <tt>core</tt> and <tt>gui</tt>, so the following line will result in a minimal Qt project being built:</p>

140

<pre>  QT -= gui # Only the core module is used.</pre>

141

<p>The table below shows the options that can be used with the <tt>QT</tt> variable and the features that are associated with each of them:</p>

142

143

<tr valign="top" bgcolor="#a2c511"><th>Option</th><th>Features</th></tr>

144

<tr valign="top" bgcolor="#f0f0f0"><td>core (included by default)</td><td>Classes that provide fundamental Qt features</td></tr>

145

<tr valign="top" bgcolor="#e0e0e0"><td>gui (included by default)</td><td>Widgets and other GUI classes</td></tr>

146

<tr valign="top" bgcolor="#f0f0f0"><td>network</td><td><a href="networking.html">Network Module</a> classes</td></tr>

147

<tr valign="top" bgcolor="#e0e0e0"><td>opengl</td><td><a href="opengl.html">OpenGL Module</a> classes</td></tr>

148

<tr valign="top" bgcolor="#f0f0f0"><td>sql</td><td><a href="sql.html">SQL Module</a> classes</td></tr>

149

<tr valign="top" bgcolor="#e0e0e0"><td>xml</td><td><a href="xml.html">XML Module</a> classes</td></tr>

150

<tr valign="top" bgcolor="#f0f0f0"><td><a href="qt3support.html#qt3support">qt3support</a></td><td>Enables the use of Qt 3 support classes (see the <a href="porting4.html">Porting to Qt 4</a> guide)</td></tr>

151

</table>

152

153

<h2>Configuration Features</h2>

154

<p><tt>qmake</tt> can be set up with extra configuration features that are specified in feature (.prf) files. These extra features often provide support for custom tools that are used during the build process. To add a feature to the build process, append the feature name (the stem of the feature filename) to the <tt>CONFIG</tt> variable.</p>

155

<p>For example, <tt>qmake</tt> can configure the build process to take advantage of external libraries that are supported by <a href="http://www.freedesktop.org/wiki/Software_2fpkgconfig">pkg-config</a>, such as the D-BUS and ogg libraries, with the following lines:</p>

156

<pre>  � � CONFIG += link_pkgconfig

157

� � PKGCONFIG += ogg dbus-1</pre>

158

<p>More information about features can be found in the <a href="qmake-advanced-usage.html#adding-new-configuration-features">Adding New Configuration Features</a> section of the <a href="qmake-advanced-usage.html">qmake Advanced Usage</a> chapter.</p>

159

<p>

160

[Previous: <a href="qmake-using.html">Using qmake</a>]

161

[<a href="qmake-manual.html">Contents</a>]

162

[Next: <a href="qmake-running.html">Running qmake</a>]

163

</p>

164

165

166

167

<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>

168

169

</tr></table></div></address></body>

170

</html>

Older »