author | llornkcor <llornkcor> | 2002-06-23 14:32:50 (UTC) |
---|---|---|
committer | llornkcor <llornkcor> | 2002-06-23 14:32:50 (UTC) |
commit | 8672a04720e7421e7f41bbf49364bcc1df910bb2 (patch) (unidiff) | |
tree | 2da9fe69cffd302f0b13fa6a4b03f5fb97ef4b63 /development/tmake_ref.html | |
parent | ce9178fb13908eca5b7835e785fc0914a5022615 (diff) | |
download | opie-8672a04720e7421e7f41bbf49364bcc1df910bb2.zip opie-8672a04720e7421e7f41bbf49364bcc1df910bb2.tar.gz opie-8672a04720e7421e7f41bbf49364bcc1df910bb2.tar.bz2 |
some dev docs
-rw-r--r-- | development/tmake_ref.html | 478 |
1 files changed, 478 insertions, 0 deletions
diff --git a/development/tmake_ref.html b/development/tmake_ref.html new file mode 100644 index 0000000..4bf82b3 --- a/dev/null +++ b/development/tmake_ref.html | |||
@@ -0,0 +1,478 @@ | |||
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 | <tr> | ||
103 | <td> </td> | ||
104 | <td>thread</td> | ||
105 | <td> </td> | ||
106 | <td>The target is a multi-threaded application/library.</td> | ||
107 | </tr> | ||
108 | </table> | ||
109 | |||
110 | |||
111 | <h4><a name="DEFINES"></a>DEFINES</h4> | ||
112 | Specifies C/C++ macros (-D compiler option). On Windows you need | ||
113 | to let DEFINES contain "QT_DLL" if you are building a Qt program | ||
114 | which should link with the Qt DLL. | ||
115 | |||
116 | |||
117 | <h4><a name="DEF_FILE"></a>DEF_FILE</h4> | ||
118 | Win32/app.t only: Specifies a .def file. | ||
119 | |||
120 | |||
121 | <h4><a name="DESTDIR"></a>DESTDIR</h4> | ||
122 | Specifies where to put the target file. | ||
123 | Example:<pre> | ||
124 | DESTDIR = ../../lib | ||
125 | </pre> | ||
126 | You must create this directory before running make. | ||
127 | |||
128 | |||
129 | <h4><a name="DISTFILES"></a>DISTFILES</h4> | ||
130 | Adds other files to the distribution archive ("dist target"). | ||
131 | The source files and project file are always included in the | ||
132 | distribution archive. | ||
133 | Example:<pre> | ||
134 | DISTFILES = CHANGES README | ||
135 | </pre> | ||
136 | |||
137 | |||
138 | <h4><a name="HEADERS"></a>HEADERS</h4> | ||
139 | Defines the header files of the project. | ||
140 | |||
141 | |||
142 | <h4><a name="INCPATH"></a>INCPATH</h4> | ||
143 | This variable is generated from <code>INCLUDEPATH</code>. The ';' or ':' | ||
144 | separators have been replaced by ' ' (single space). This makes it | ||
145 | easier to split. qtapp.t and other templates expand | ||
146 | <code>INCPATH</code> to set -I options for the C++ compiler. | ||
147 | |||
148 | |||
149 | <h4><a name="INCLUDEPATH"></a>INCLUDEPATH</h4> | ||
150 | This variable specifies the #include directories. It can be set in the | ||
151 | project file, or by the <a href="#AddIncludePath">AddIncludePath()</a> | ||
152 | function.<p> | ||
153 | Example:<pre> | ||
154 | INCLUDEPATH = c:\msdev\include d:\stl\include | ||
155 | </pre> | ||
156 | Use ';' or space as the directory separator. | ||
157 | |||
158 | |||
159 | <h4><a name="LIBS"></a>LIBS</h4> | ||
160 | Defines additional libraries to be linked in when creating an application | ||
161 | or a shared library. You probably want to use a platform qualifier since | ||
162 | libraries are specified differently on Unix and Win32.<p> | ||
163 | Example:<pre> | ||
164 | unix:LIBS = -lXext -lm | ||
165 | win32:LIBS = ole32.lib | ||
166 | </pre> | ||
167 | |||
168 | |||
169 | <h4><a name="MOC_DIR"></a>MOC_DIR</h4> | ||
170 | Specifies where to put the temporary moc output files. By default they | ||
171 | are stored in the directory where the moc input files are. | ||
172 | <p> | ||
173 | Example:<pre> | ||
174 | MOC_DIR = tmp | ||
175 | </pre> | ||
176 | You must create this directory before running make. | ||
177 | <p> | ||
178 | See also: <a href="#OBJECTS_DIR">OBJECTS_DIR</a>. | ||
179 | |||
180 | |||
181 | <h4><a name="OBJECTS"></a>OBJECTS</h4> | ||
182 | This varialble is generated from <code>SOURCES</code> by the StdInit() function. | ||
183 | The extension of each source file has been replaced by .o (Unix) or .obj | ||
184 | (Win32).<p> | ||
185 | Example:<pre> | ||
186 | SOURCES = a.x b.y | ||
187 | </pre> | ||
188 | Then <code>OBJECTS</code> become "a.o b.o" on Unix and "a.obj b.obj" on | ||
189 | Win32. | ||
190 | |||
191 | |||
192 | <h4><a name="OBJECTS_DIR"></a>OBJECTS_DIR</h4> | ||
193 | Specifies where to put object files. By default they are stored in | ||
194 | the directory where the source files are.<p> | ||
195 | Example:<pre> | ||
196 | OBJECTS_DIR = tmp | ||
197 | </pre> | ||
198 | You must create this directory before running make. | ||
199 | <p> | ||
200 | See also: <a href="#MOC_DIR">MOC_DIR</a>. | ||
201 | |||
202 | |||
203 | <h4><a name="OBJMOC"></a>OBJMOC</h4> | ||
204 | This variable is generated by the <a href="#StdInit">StdInit()</a> function if | ||
205 | <code>$moc_aware</code> is true. <code>OBJMOC</code> contains the name of | ||
206 | all intermediate moc object files.<p> | ||
207 | Example:<pre> | ||
208 | HEADERS = demo.h | ||
209 | SOURCES = demo.cpp main.cpp | ||
210 | </pre> | ||
211 | If <tt>demo.h</tt> and <tt>main.cpp</tt> define classes that use signals | ||
212 | and slots (i.e. the <code>Q_OBJECT</code> "keyword" is found in these two | ||
213 | files), <code>OBJMOC</code> becomes:<pre> | ||
214 | OBJMOC = moc_demo.obj | ||
215 | </pre> | ||
216 | See also: <a href="#SRCMOC">SRCMOC</a>. | ||
217 | |||
218 | |||
219 | <h4><a name="PROJECT"></a>PROJECT</h4> | ||
220 | This is the name of the project. It defaults to the name of the project | ||
221 | file, excluding the .pro extension. | ||
222 | |||
223 | |||
224 | <h4><a name="RC_FILE"></a>RC_FILE</h4> | ||
225 | Win32/app.t only: Specifies a .rc file. Cannot be used with the RES_FILE | ||
226 | variable. | ||
227 | |||
228 | |||
229 | <h4><a name="RES_FILE"></a>RES_FILE</h4> | ||
230 | Win32/app.t only: Specifies a .res file. You can either specify a | ||
231 | .rc file or one or more .res files. | ||
232 | |||
233 | |||
234 | <h4><a name="SOURCES"></a>SOURCES</h4> | ||
235 | Defines the source files of the project. | ||
236 | |||
237 | |||
238 | <h4><a name="SRCMOC"></a>SRCMOC</h4> | ||
239 | This variable is generated by the <a href="#StdInit">StdInit()</a> function if | ||
240 | <code>CONFIG</code> contains "qt". <code>SRCMOC</code> contains the name of | ||
241 | all intermediate moc files.<p> | ||
242 | Example:<pre> | ||
243 | HEADERS = demo.h | ||
244 | SOURCES = demo.cpp main.cpp | ||
245 | </pre> | ||
246 | If <tt>demo.h</tt> and <tt>main.cpp</tt> define classes that use signals | ||
247 | and slots (i.e. the <code>Q_OBJECT</code> "keyword" is found in these two | ||
248 | files), <code>SRCMOC</code> becomes:<pre> | ||
249 | SRCMOC = moc_demo.cpp main.moc | ||
250 | </pre> | ||
251 | See also: <a href="#OBJMOC">OBJMOC</a>. | ||
252 | |||
253 | |||
254 | <h4><a name="TARGET"></a>TARGET</h4> | ||
255 | Sets the makefile target, i.e. what program to build. | ||
256 | |||
257 | |||
258 | <h4><a name="TEMPLATE"></a>TEMPLATE</h4> | ||
259 | Sets the default template. This can be overridden by the tmake -t | ||
260 | <a href="tmake.html#usage">option</a>. | ||
261 | |||
262 | |||
263 | <h4><a name="TMAKE_CC"></a>TMAKE_CC</h4> | ||
264 | Contains the name of the compiler. | ||
265 | |||
266 | |||
267 | <h4><a name="TMAKE_CFLAGS"></a>TMAKE_CFLAGS</h4> | ||
268 | Contains the default compiler flags. | ||
269 | |||
270 | |||
271 | <h4><a name="TMAKE_FILEVARS"></a>TMAKE_FILEVARS</h4> | ||
272 | Tells tmake which variables contain file names. This is because tmake | ||
273 | on Windows replace the directory separator / with \. | ||
274 | |||
275 | |||
276 | <hr> | ||
277 | <h2>Function Reference</h2> | ||
278 | This section contains a brief description of some important | ||
279 | tmake functions used by the templates. | ||
280 | |||
281 | |||
282 | <h3><a name="AddIncludePath"></a>AddIncludePath(path)</h3> | ||
283 | Adds <em>path</em> to the include path variable, | ||
284 | <a href="#INCLUDEPATH">INCLUDEPATH</a>. The include path is used | ||
285 | for two purposes:<ol> | ||
286 | <li>Searching files when generating include dependencies. | ||
287 | <li>Setting -I options for the C/C++ compiler. | ||
288 | </ol> | ||
289 | <p> | ||
290 | Example:<pre> | ||
291 | #$ AddIncludePath('$QTDIR/include;/local/include'); | ||
292 | </pre> | ||
293 | |||
294 | |||
295 | <h3>BuildMocObj(objects,sources)</h3> | ||
296 | Creates build rules for moc source files. Generates | ||
297 | include dependencies.<p> | ||
298 | Example:<pre> | ||
299 | #$ BuildMocObj($project{"OBJMOC"},$project{"SRCMOC"}); | ||
300 | </pre>Output:<pre> | ||
301 | moc_hello.o: moc_hello.cpp \ | ||
302 | hello.h \ | ||
303 | ... | ||
304 | </pre> | ||
305 | |||
306 | <h3>BuildMocSrc(files)</h3> | ||
307 | Creates moc source files from C++ files containing classes that | ||
308 | define signals and slots. For a header file <tt>x.h</tt>, the | ||
309 | generated moc file is called <tt>moc_x.h</tt>. For a source file | ||
310 | <tt>y.cpp</tt>, the generates moc file is called <tt>y.moc</tt> and | ||
311 | should be #include'd by <tt>y.cpp</tt>.<p> | ||
312 | Example:<pre> | ||
313 | #$ BuildMocSrc($project{"HEADERS"}); | ||
314 | #$ BuildMocSrc($project{"SOURCES"}); | ||
315 | </pre>Output:<pre> | ||
316 | moc_hello.cpp: hello.h | ||
317 | $(MOC) hello.h -o moc_hello.cpp | ||
318 | </pre> | ||
319 | |||
320 | |||
321 | <h3>BuildObj(objects,sources)</h3> | ||
322 | Creates build rules for source files. Generates | ||
323 | include dependencies.<p> | ||
324 | Example:<pre> | ||
325 | #$ BuildObj($project{"OBJECTS"},$project{"SOURCES"}); | ||
326 | </pre>Output:<pre> | ||
327 | hello.o: hello.cpp \ | ||
328 | hello.h \ | ||
329 | ... | ||
330 | |||
331 | main.o: main.cpp \ | ||
332 | hello.h \ | ||
333 | ... | ||
334 | </pre> | ||
335 | |||
336 | |||
337 | <h3>Config(string)</h3> | ||
338 | Returns true if the <code>CONFIG</code> variable contains the given string. | ||
339 | <p>Example:<pre> | ||
340 | #$ if ( Config("release") { } | ||
341 | </pre> | ||
342 | |||
343 | |||
344 | <h3>DisableOutput()</h3> | ||
345 | Call this function to force tmake to generate no output until | ||
346 | EnableOutput() is called. | ||
347 | <p>Example:<pre> | ||
348 | #$ Config("debug") && DisableOutput(); | ||
349 | Anything here is skipped if CONFIG contains "debug". | ||
350 | #$ Config("debug") && EnableOutput(); | ||
351 | </pre> | ||
352 | |||
353 | |||
354 | <h3>EnableOutput()</h3> | ||
355 | Enables tmake output after DisableOutput() was called. | ||
356 | |||
357 | |||
358 | <h3>Expand(var)</h3> | ||
359 | Expands a project variable. Equivalent to <code>$text = $project{$var}</code>. | ||
360 | <p>Example:<pre> | ||
361 | VERSION = #$ Expand("VERSION"); | ||
362 | </pre>Output:<pre> | ||
363 | VERSION = 1.1 | ||
364 | </pre> | ||
365 | |||
366 | <h3>ExpandGlue(var,prepend,glue,append)</h3> | ||
367 | Expands a $project{} variable, splits on whitespace | ||
368 | and joins with $glue. $prepend is put at the start | ||
369 | of the string and $append is put at the end of the | ||
370 | string. The resulting string ($text) becomes "" if | ||
371 | the project variable is empty or not defined.<p> | ||
372 | Example:<pre> | ||
373 | clear: | ||
374 | #$ ExpandGlue("OBJECTS","-del","\n\t-del ",""); | ||
375 | </pre>Output (Windows NT):<pre> | ||
376 | clear: | ||
377 | -del hello.obj | ||
378 | -del main.obj | ||
379 | </pre> | ||
380 | |||
381 | |||
382 | <h3>ExpandList(var)</h3> | ||
383 | This function is suitable for expanding lists of files. | ||
384 | Equivalent with <code>ExpandGlue($var,""," \\\n\t\t","")</code>.<p> | ||
385 | Example:<pre> | ||
386 | OBJECTS = #$ ExpandList("OBJECTS"); | ||
387 | </pre>Output:<pre> | ||
388 | OBJECTS = hello.o \ | ||
389 | main.o | ||
390 | </pre> | ||
391 | |||
392 | |||
393 | <h3>ExpandPath(var,prepend,glue,append)</h3> | ||
394 | Similar to ExpandGlue, except that it splits the items on a semicolon | ||
395 | instead of space (if the variable contains at least one semicolon). | ||
396 | |||
397 | |||
398 | <h3>IncludeTemplate(file)</h3> | ||
399 | Includes a template file. The ".t" extension is optional.<p> | ||
400 | Example:<pre> | ||
401 | #$ IncludeTemplate("mytemplate"); | ||
402 | </pre> | ||
403 | |||
404 | |||
405 | <h3>Now()</h3> | ||
406 | Sets $text to the current date and time.<p> | ||
407 | Example:<pre> | ||
408 | # Generated at #$ Now() | ||
409 | </pre>Output:<pre> | ||
410 | # Generated at 12:58, 1996/11/19 | ||
411 | </pre> | ||
412 | |||
413 | |||
414 | <h3>Project(strings)</h3> | ||
415 | This is a powerful function for setting and reading project | ||
416 | variables. Returns the resulting project variables (joined with space | ||
417 | between). | ||
418 | <p>Examples:<pre> | ||
419 | # Get a project variable: | ||
420 | $s = Project("TEMPLATE"); -> $s = "TEMPLATE" | ||
421 | |||
422 | # Set a project variable: | ||
423 | Project("TEMPLATE = lib"); -> TEMPLATE = lib | ||
424 | Project("CONFIG =";) -> CONFIG empty | ||
425 | |||
426 | # Append to a project variable: | ||
427 | Project("CONFIG = qt"); -> CONFIG = qt | ||
428 | Project("CONFIG += debug"); -> CONFIG = qt debug | ||
429 | |||
430 | # Append to a project variable if it does not contain the value already: | ||
431 | Project("CONFIG = qt release"); -> CONFIG = qt release | ||
432 | Project("CONFIG *= qt"); -> CONFIG = qt release | ||
433 | Project("CONFIG *= opengl"); -> CONFIG = qt release opengl | ||
434 | |||
435 | # Subtract from a project variable: | ||
436 | Project("THINGS = abc xyz"); -> THINGS = abc xyz | ||
437 | Project("THINGS -= abc"); -> THINGS = xyz | ||
438 | |||
439 | # Search/replace on a project variable: | ||
440 | Project("CONFIG = tq opengl"); -> CONFIG = tq opengl | ||
441 | Project("CONFIG /= s/tq/qt/"); -> CONFIG = qt opengl | ||
442 | |||
443 | # The operations can be performed on several project variables at a time. | ||
444 | |||
445 | Project("TEMPLATE = app", "CONFIG *= opengl", "THINGS += klm"); | ||
446 | </pre> | ||
447 | |||
448 | |||
449 | <h3><a name="ScanProject"></a>ScanProject(file)</h3> | ||
450 | Scans a project file and stores the project variables and values in the | ||
451 | global associative <code>%project</code> array. | ||
452 | |||
453 | |||
454 | <h3><a name="StdInit"></a>StdInit()</h3> | ||
455 | Standard initialization of tmake. StdInit() should be | ||
456 | called from one of the first lines in the template.<p> | ||
457 | |||
458 | This function creates some new project variables:<ul> | ||
459 | <li><code><a href="#OBJECTS">OBJECTS</a></code> | ||
460 | - Object files corresponding to | ||
461 | <code><a href="#SOURCES">SOURCES</a></code>. | ||
462 | <li><code><a href="#SRCMOC">SRCMOC</a></code> - moc source files. | ||
463 | <li><code><a href="#OBJMOC">OBJMOC</a></code> - moc object files. | ||
464 | </ul> | ||
465 | |||
466 | The moc-related variables are created only if <code>CONFIG</code> contains "qt" | ||
467 | |||
468 | |||
469 | <h3>Substitute(string)</h3> | ||
470 | This function takes a string and substitutes any occurrence of $$var | ||
471 | with the actual content of the variable. Returns the substituted string. | ||
472 | Also sets $text. | ||
473 | <p> | ||
474 | Important: Use single quotes around the string, otherwise perl will expand | ||
475 | any $vars it finds. | ||
476 | <p>Example:<pre> | ||
477 | Substitute('Project name: $$PROJECT, uses template $$TEMPLATE'); | ||
478 | </pre> | ||