Root/
Source at commit 1322 created 12 years 8 months ago. By meklort, Add doxygen to utils folder | |
---|---|
1 | <!doctype HTML public "-//W3C//DTD HTML 3.2//EN">␊ |
2 | <html><head><title>␊ |
3 | Reference Manual - tmake␊ |
4 | </title></head><body bgcolor="#ffffff">␊ |
5 | <p><h1 align=center>Reference Manual - tmake</h1>␊ |
6 | ␊ |
7 | <hr>␊ |
8 | <h2>Project Variable Reference</h2>␊ |
9 | ␊ |
10 | <h4><a name="ALL_DEPS"></a>ALL_DEPS</h4>␊ |
11 | Specifies additional dependencies for the makefile target "all:".<p>␊ |
12 | ␊ |
13 | ␊ |
14 | <h4><a name="CLEAN_FILES"></a>CLEAN_FILES</h4>␊ |
15 | Specifies additional files to be removed for "make clean".<p>␊ |
16 | Example:<pre>␊ |
17 | CLEAN_FILES = core *~␊ |
18 | </pre>␊ |
19 | ␊ |
20 | ␊ |
21 | <h4><a name="CONFIG"></a>CONFIG</h4>␊ |
22 | Sets the make configuration. It tells the tmake templates what compiler␊ |
23 | options to use and which extra libraries to link in.<p>␊ |
24 | These options control the compilation flags:␊ |
25 | <p>␊ |
26 | <table border="0">␊ |
27 | <tr>␊ |
28 | <td> </td>␊ |
29 | <td>release</td>␊ |
30 | <td> </td>␊ |
31 | <td>Compile with optimization enabled, ignored if␊ |
32 | "debug" is specified.</td>␊ |
33 | </tr>␊ |
34 | <tr>␊ |
35 | <td> </td>␊ |
36 | <td>debug</td>␊ |
37 | <td> </td>␊ |
38 | <td>Compile with debug options enabled.</td>␊ |
39 | </tr>␊ |
40 | <tr>␊ |
41 | <td> </td>␊ |
42 | <td>warn_on</td>␊ |
43 | <td> </td>␊ |
44 | <td>The compiler should emit more warnings than normally, ignored if␊ |
45 | "warn_off" is specified.</td>␊ |
46 | </tr>␊ |
47 | <tr>␊ |
48 | <td> </td>␊ |
49 | <td>warn_off</td>␊ |
50 | <td> </td>␊ |
51 | <td>The compiler should emit no warnings or as few as possible.</td>␊ |
52 | </tr>␊ |
53 | </table>␊ |
54 | ␊ |
55 | <p>␊ |
56 | These options defines the application/library type:␊ |
57 | <p>␊ |
58 | <table border="0">␊ |
59 | <tr>␊ |
60 | <td> </td>␊ |
61 | <td>qt</td>␊ |
62 | <td> </td>␊ |
63 | <td>The target is a Qt application/library and requires Qt header␊ |
64 | files/library.</td>␊ |
65 | </tr>␊ |
66 | <tr>␊ |
67 | <td> </td>␊ |
68 | <td>opengl</td>␊ |
69 | <td> </td>␊ |
70 | <td>The target requires the OpenGL (or Mesa) headers/libraries.</td>␊ |
71 | </tr>␊ |
72 | <tr>␊ |
73 | <td> </td>␊ |
74 | <td>x11</td>␊ |
75 | <td> </td>␊ |
76 | <td>The target is a X11 application (app.t only).</td>␊ |
77 | </tr>␊ |
78 | <tr>␊ |
79 | <td> </td>␊ |
80 | <td>windows</td>␊ |
81 | <td> </td>␊ |
82 | <td>The target is a Win32 window application (app.t only).</td>␊ |
83 | </tr>␊ |
84 | <tr>␊ |
85 | <td> </td>␊ |
86 | <td>console</td>␊ |
87 | <td> </td>␊ |
88 | <td>The target is a Win32 console application (app.t only).</td>␊ |
89 | </tr>␊ |
90 | <tr>␊ |
91 | <td> </td>␊ |
92 | <td>dll</td>␊ |
93 | <td> </td>␊ |
94 | <td>The target is a shared object/DLL (app.t only).</td>␊ |
95 | </tr>␊ |
96 | <tr>␊ |
97 | <td> </td>␊ |
98 | <td>staticlib</td>␊ |
99 | <td> </td>␊ |
100 | <td>The target is a static library (lib.t only).</td>␊ |
101 | </tr>␊ |
102 | </table>␊ |
103 | ␊ |
104 | ␊ |
105 | <h4><a name="DEFINES"></a>DEFINES</h4>␊ |
106 | Specifies C/C++ macros (-D compiler option). On Windows you need␊ |
107 | to let DEFINES contain "QT_DLL" if you are building a Qt program␊ |
108 | which should link with the Qt DLL.␊ |
109 | ␊ |
110 | ␊ |
111 | <h4><a name="DEF_FILE"></a>DEF_FILE</h4>␊ |
112 | Win32/app.t only: Specifies a .def file.␊ |
113 | ␊ |
114 | ␊ |
115 | <h4><a name="DESTDIR"></a>DESTDIR</h4>␊ |
116 | Specifies where to put the target file.␊ |
117 | Example:<pre>␊ |
118 | DESTDIR = ../../lib␊ |
119 | </pre>␊ |
120 | You must create this directory before running make.␊ |
121 | ␊ |
122 | ␊ |
123 | <h4><a name="HEADERS"></a>HEADERS</h4>␊ |
124 | Defines the header files of the project.␊ |
125 | ␊ |
126 | ␊ |
127 | <h4><a name="INCPATH"></a>INCPATH</h4>␊ |
128 | This variable is generated from <code>INCLUDEPATH</code>. The ';' or ':'␊ |
129 | separators have been replaced by ' ' (single space). This makes it␊ |
130 | easier to split. qtapp.t and other templates expand␊ |
131 | <code>INCPATH</code> to set -I options for the C++ compiler.␊ |
132 | ␊ |
133 | ␊ |
134 | <h4><a name="INCLUDEPATH"></a>INCLUDEPATH</h4>␊ |
135 | This variable specifies the #include directories. It can be set in the␊ |
136 | project file, or by the <a href="#AddIncludePath">AddIncludePath()</a>␊ |
137 | function.<p>␊ |
138 | Example:<pre>␊ |
139 | INCLUDEPATH = c:\msdev\include d:\stl\include␊ |
140 | </pre>␊ |
141 | Use ';' or space as the directory separator.␊ |
142 | ␊ |
143 | ␊ |
144 | <h4><a name="LIBS"></a>LIBS</h4>␊ |
145 | Defines additional libraries to be linked in when creating an application␊ |
146 | or a shared library. You probably want to use a platform qualifier since␊ |
147 | libraries are specified differently on Unix and Win32.<p>␊ |
148 | Example:<pre>␊ |
149 | unix:LIBS = -lXext -lm␊ |
150 | win32:LIBS = ole32.lib␊ |
151 | </pre>␊ |
152 | ␊ |
153 | ␊ |
154 | <h4><a name="MOC_DIR"></a>MOC_DIR</h4>␊ |
155 | Specifies where to put the temporary moc output files. By default they␊ |
156 | are stored in the directory where the moc input files are.␊ |
157 | <p>␊ |
158 | Example:<pre>␊ |
159 | MOC_DIR = tmp␊ |
160 | </pre>␊ |
161 | You must create this directory before running make.␊ |
162 | <p>␊ |
163 | See also: <a href="#OBJECTS_DIR">OBJECTS_DIR</a>.␊ |
164 | ␊ |
165 | ␊ |
166 | <h4><a name="OBJECTS"></a>OBJECTS</h4>␊ |
167 | This varialble is generated from <code>SOURCES</code> by the StdInit() function.␊ |
168 | The extension of each source file has been replaced by .o (Unix) or .obj␊ |
169 | (Win32).<p>␊ |
170 | Example:<pre>␊ |
171 | SOURCES = a.x b.y␊ |
172 | </pre>␊ |
173 | Then <code>OBJECTS</code> become "a.o b.o" on Unix and "a.obj b.obj" on␊ |
174 | Win32.␊ |
175 | ␊ |
176 | ␊ |
177 | <h4><a name="OBJECTS_DIR"></a>OBJECTS_DIR</h4>␊ |
178 | Specifies where to put object files. By default they are stored in␊ |
179 | the directory where the source files are.<p>␊ |
180 | Example:<pre>␊ |
181 | OBJECTS_DIR = tmp␊ |
182 | </pre>␊ |
183 | You must create this directory before running make.␊ |
184 | <p>␊ |
185 | See also: <a href="#MOC_DIR">MOC_DIR</a>.␊ |
186 | ␊ |
187 | ␊ |
188 | <h4><a name="OBJMOC"></a>OBJMOC</h4>␊ |
189 | This variable is generated by the <a href="#StdInit">StdInit()</a> function if␊ |
190 | <code>$moc_aware</code> is true. <code>OBJMOC</code> contains the name of␊ |
191 | all intermediate moc object files.<p>␊ |
192 | Example:<pre>␊ |
193 | HEADERS = demo.h␊ |
194 | SOURCES = demo.cpp main.cpp␊ |
195 | </pre>␊ |
196 | If <tt>demo.h</tt> and <tt>main.cpp</tt> define classes that use signals␊ |
197 | and slots (i.e. the <code>Q_OBJECT</code> "keyword" is found in these two␊ |
198 | files), <code>OBJMOC</code> becomes:<pre>␊ |
199 | OBJMOC = moc_demo.obj␊ |
200 | </pre>␊ |
201 | See also: <a href="#SRCMOC">SRCMOC</a>.␊ |
202 | ␊ |
203 | ␊ |
204 | <h4><a name="PROJECT"></a>PROJECT</h4>␊ |
205 | This is the name of the project. It defaults to the name of the project␊ |
206 | file, excluding the .pro extension.␊ |
207 | ␊ |
208 | ␊ |
209 | <h4><a name="RC_FILE"></a>RC_FILE</h4>␊ |
210 | Win32/app.t only: Specifies a .rc file. Cannot be used with the RES_FILE␊ |
211 | variable.␊ |
212 | ␊ |
213 | ␊ |
214 | <h4><a name="RES_FILE"></a>RES_FILE</h4>␊ |
215 | Win32/app.t only: Specifies a .res file. You can either specify a␊ |
216 | .rc file or one or more .res files.␊ |
217 | ␊ |
218 | ␊ |
219 | <h4><a name="SOURCES"></a>SOURCES</h4>␊ |
220 | Defines the source files of the project.␊ |
221 | ␊ |
222 | ␊ |
223 | <h4><a name="SRCMOC"></a>SRCMOC</h4>␊ |
224 | This variable is generated by the <a href="#StdInit">StdInit()</a> function if␊ |
225 | <code>CONFIG</code> contains "qt". <code>SRCMOC</code> contains the name of␊ |
226 | all intermediate moc files.<p>␊ |
227 | Example:<pre>␊ |
228 | HEADERS = demo.h␊ |
229 | SOURCES = demo.cpp main.cpp␊ |
230 | </pre>␊ |
231 | If <tt>demo.h</tt> and <tt>main.cpp</tt> define classes that use signals␊ |
232 | and slots (i.e. the <code>Q_OBJECT</code> "keyword" is found in these two␊ |
233 | files), <code>SRCMOC</code> becomes:<pre>␊ |
234 | SRCMOC = moc_demo.cpp main.moc␊ |
235 | </pre>␊ |
236 | See also: <a href="#OBJMOC">OBJMOC</a>.␊ |
237 | ␊ |
238 | ␊ |
239 | <h4><a name="TARGET"></a>TARGET</h4>␊ |
240 | Sets the makefile target, i.e. what program to build.␊ |
241 | ␊ |
242 | ␊ |
243 | <h4><a name="TEMPLATE"></a>TEMPLATE</h4>␊ |
244 | Sets the default template. This can be overridden by the tmake -t␊ |
245 | <a href="tmake.html#usage">option</a>.␊ |
246 | ␊ |
247 | ␊ |
248 | <h4><a name="TMAKE_CC"></a>TMAKE_CC</h4>␊ |
249 | Contains the name of the compiler.␊ |
250 | ␊ |
251 | ␊ |
252 | <h4><a name="TMAKE_CFLAGS"></a>TMAKE_CFLAGS</h4>␊ |
253 | Contains the default compiler flags.␊ |
254 | ␊ |
255 | ␊ |
256 | <h4><a name="TMAKE_FILEVARS"></a>TMAKE_FILEVARS</h4>␊ |
257 | Tells tmake which variables contain file names. This is because tmake␊ |
258 | on Windows replace the directory separator / with \.␊ |
259 | ␊ |
260 | ␊ |
261 | <hr>␊ |
262 | <h2>Function Reference</h2>␊ |
263 | This section contains a brief description of some important␊ |
264 | tmake functions used by the templates.␊ |
265 | ␊ |
266 | ␊ |
267 | <h3><a name="AddIncludePath"></a>AddIncludePath(path)</h3>␊ |
268 | Adds <em>path</em> to the include path variable,␊ |
269 | <a href="#INCLUDEPATH">INCLUDEPATH</a>. The include path is used␊ |
270 | for two purposes:<ol>␊ |
271 | <li>Searching files when generating include dependencies.␊ |
272 | <li>Setting -I options for the C/C++ compiler.␊ |
273 | </ol>␊ |
274 | <p>␊ |
275 | Example:<pre>␊ |
276 | #$ AddIncludePath('$QTDIR/include;/local/include');␊ |
277 | </pre>␊ |
278 | ␊ |
279 | ␊ |
280 | <h3>BuildMocObj(objects,sources)</h3>␊ |
281 | Creates build rules for moc source files. Generates␊ |
282 | include dependencies.<p>␊ |
283 | Example:<pre>␊ |
284 | #$ BuildMocObj($project{"OBJMOC"},$project{"SRCMOC"});␊ |
285 | </pre>Output:<pre>␊ |
286 | moc_hello.o: moc_hello.cpp \␊ |
287 | ␉␉hello.h \␊ |
288 | ␉␉...␊ |
289 | </pre>␊ |
290 | ␊ |
291 | <h3>BuildMocSrc(files)</h3>␊ |
292 | Creates moc source files from C++ files containing classes that␊ |
293 | define signals and slots. For a header file <tt>x.h</tt>, the␊ |
294 | generated moc file is called <tt>moc_x.h</tt>. For a source file␊ |
295 | <tt>y.cpp</tt>, the generates moc file is called <tt>y.moc</tt> and␊ |
296 | should be #include'd by <tt>y.cpp</tt>.<p>␊ |
297 | Example:<pre>␊ |
298 | #$ BuildMocSrc($project{"HEADERS"});␊ |
299 | #$ BuildMocSrc($project{"SOURCES"});␊ |
300 | </pre>Output:<pre>␊ |
301 | moc_hello.cpp: hello.h␊ |
302 | ␉$(MOC) hello.h -o moc_hello.cpp␊ |
303 | </pre>␊ |
304 | ␊ |
305 | ␊ |
306 | <h3>BuildObj(objects,sources)</h3>␊ |
307 | Creates build rules for source files. Generates␊ |
308 | include dependencies.<p>␊ |
309 | Example:<pre>␊ |
310 | #$ BuildObj($project{"OBJECTS"},$project{"SOURCES"});␊ |
311 | </pre>Output:<pre>␊ |
312 | hello.o: hello.cpp \␊ |
313 | ␉␉hello.h \␊ |
314 | ␉␉...␊ |
315 | ␊ |
316 | main.o: main.cpp \␊ |
317 | ␉␉hello.h \␊ |
318 | ␉␉...␊ |
319 | </pre>␊ |
320 | ␊ |
321 | ␊ |
322 | <h3>Config(string)</h3>␊ |
323 | Returns true if the <code>CONFIG</code> variable contains the given string.␊ |
324 | <p>Example:<pre>␊ |
325 | #$ if ( Config("release") { }␊ |
326 | </pre>␊ |
327 | ␊ |
328 | ␊ |
329 | <h3>DisableOutput()</h3>␊ |
330 | Call this function to force tmake to generate no output until␊ |
331 | EnableOutput() is called.␊ |
332 | <p>Example:<pre>␊ |
333 | #$ Config("debug") && DisableOutput();␊ |
334 | Anything here is skipped if CONFIG contains "debug".␊ |
335 | #$ Config("debug") && EnableOutput();␊ |
336 | </pre>␊ |
337 | ␊ |
338 | ␊ |
339 | <h3>EnableOutput()</h3>␊ |
340 | Enables tmake output after DisableOutput() was called.␊ |
341 | ␊ |
342 | ␊ |
343 | <h3>Expand(var)</h3>␊ |
344 | Expands a project variable. Equivalent to <code>$text = $project{$var}</code>.␊ |
345 | <p>Example:<pre>␊ |
346 | VERSION = #$ Expand("VERSION");␊ |
347 | </pre>Output:<pre>␊ |
348 | VERSION = 1.1␊ |
349 | </pre>␊ |
350 | ␊ |
351 | <h3>ExpandGlue(var,prepend,glue,append)</h3>␊ |
352 | Expands a $project{} variable, splits on whitespace␊ |
353 | and joins with $glue. $prepend is put at the start␊ |
354 | of the string and $append is put at the end of the␊ |
355 | string. The resulting string ($text) becomes "" if␊ |
356 | the project variable is empty or not defined.<p>␊ |
357 | Example:<pre>␊ |
358 | clear:␊ |
359 | #$ ExpandGlue("OBJECTS","-del","\n\t-del ","");␊ |
360 | </pre>Output (Windows NT):<pre>␊ |
361 | clear:␊ |
362 | -del hello.obj␊ |
363 | -del main.obj␊ |
364 | </pre>␊ |
365 | ␊ |
366 | ␊ |
367 | <h3>ExpandList(var)</h3>␊ |
368 | This function is suitable for expanding lists of files.␊ |
369 | Equivalent with <code>ExpandGlue($var,""," \\\n\t\t","")</code>.<p>␊ |
370 | Example:<pre>␊ |
371 | OBJECTS = #$ ExpandList("OBJECTS");␊ |
372 | </pre>Output:<pre>␊ |
373 | OBJECTS = hello.o \␊ |
374 | ␉ main.o␊ |
375 | </pre>␊ |
376 | ␊ |
377 | ␊ |
378 | <h3>ExpandPath(var,prepend,glue,append)</h3>␊ |
379 | Similar to ExpandGlue, except that it splits the items on a semicolon␊ |
380 | instead of space (if the variable contains at least one semicolon).␊ |
381 | ␊ |
382 | ␊ |
383 | <h3>IncludeTemplate(file)</h3>␊ |
384 | Includes a template file. The ".t" extension is optional.<p>␊ |
385 | Example:<pre>␊ |
386 | #$ IncludeTemplate("mytemplate");␊ |
387 | </pre>␊ |
388 | ␊ |
389 | ␊ |
390 | <h3>Now()</h3>␊ |
391 | Sets $text to the current date and time.<p>␊ |
392 | Example:<pre>␊ |
393 | # Generated at #$ Now()␊ |
394 | </pre>Output:<pre>␊ |
395 | # Generated at 12:58, 1996/11/19␊ |
396 | </pre>␊ |
397 | ␊ |
398 | ␊ |
399 | <h3>Project(strings)</h3>␊ |
400 | This is a powerful function for setting and reading project␊ |
401 | variables. Returns the resulting project variables (joined with space␊ |
402 | between).␊ |
403 | <p>Examples:<pre>␊ |
404 | # Get a project variable:␊ |
405 | $s = Project("TEMPLATE");␉ -> $s = "TEMPLATE"␊ |
406 | ␊ |
407 | # Set a project variable:␊ |
408 | Project("TEMPLATE = lib");␉ -> TEMPLATE = lib␊ |
409 | Project("CONFIG =";)␉ -> CONFIG empty␊ |
410 | ␊ |
411 | # Append to a project variable:␊ |
412 | Project("CONFIG = qt");␉ -> CONFIG = qt␊ |
413 | Project("CONFIG += debug");␉ -> CONFIG = qt debug␊ |
414 | ␊ |
415 | # Append to a project variable if it does not contain the value already:␊ |
416 | Project("CONFIG = qt release"); -> CONFIG = qt release␊ |
417 | Project("CONFIG *= qt");␉ -> CONFIG = qt release␊ |
418 | Project("CONFIG *= opengl"); -> CONFIG = qt release opengl␊ |
419 | ␊ |
420 | # Subtract from a project variable:␊ |
421 | Project("THINGS = abc xyz"); -> THINGS = abc xyz␊ |
422 | Project("THINGS -= abc");␉ -> THINGS = xyz␊ |
423 | ␊ |
424 | # Search/replace on a project variable:␊ |
425 | Project("CONFIG = tq opengl"); -> CONFIG = tq opengl␊ |
426 | Project("CONFIG /= s/tq/qt/"); -> CONFIG = qt opengl␊ |
427 | ␊ |
428 | # The operations can be performed on several project variables at a time.␊ |
429 | ␊ |
430 | Project("TEMPLATE = app", "CONFIG *= opengl", "THINGS += klm");␊ |
431 | </pre>␊ |
432 | ␊ |
433 | ␊ |
434 | <h3><a name="ScanProject"></a>ScanProject(file)</h3>␊ |
435 | Scans a project file and stores the project variables and values in the␊ |
436 | global associative <code>%project</code> array.␊ |
437 | ␊ |
438 | ␊ |
439 | <h3><a name="StdInit"></a>StdInit()</h3>␊ |
440 | Standard initialization of tmake. StdInit() should be␊ |
441 | called from one of the first lines in the template.<p>␊ |
442 | ␊ |
443 | This function creates some new project variables:<ul>␊ |
444 | <li><code><a href="#OBJECTS">OBJECTS</a></code>␊ |
445 | - Object files corresponding to␊ |
446 | <code><a href="#SOURCES">SOURCES</a></code>.␊ |
447 | <li><code><a href="#SRCMOC">SRCMOC</a></code> - moc source files.␊ |
448 | <li><code><a href="#OBJMOC">OBJMOC</a></code> - moc object files.␊ |
449 | </ul>␊ |
450 | ␊ |
451 | The moc-related variables are created only if <code>CONFIG</code> contains "qt"␊ |
452 | ␊ |
453 | ␊ |
454 | <h3>Substitute(string)</h3>␊ |
455 | This function takes a string and substitutes any occurrence of $$var␊ |
456 | with the actual content of the variable. Returns the substituted string.␊ |
457 | Also sets $text.␊ |
458 | <p>␊ |
459 | Important: Use single quotes around the string, otherwise perl will expand␊ |
460 | any $vars it finds.␊ |
461 | <p>Example:<pre>␊ |
462 | Substitute('Project name: $$PROJECT, uses template $$TEMPLATE');␊ |
463 | </pre>␊ |
464 |