summaryrefslogtreecommitdiff
path: root/development/tmake_ref.html
authorllornkcor <llornkcor>2002-06-23 14:32:50 (UTC)
committer llornkcor <llornkcor>2002-06-23 14:32:50 (UTC)
commit8672a04720e7421e7f41bbf49364bcc1df910bb2 (patch) (unidiff)
tree2da9fe69cffd302f0b13fa6a4b03f5fb97ef4b63 /development/tmake_ref.html
parentce9178fb13908eca5b7835e785fc0914a5022615 (diff)
downloadopie-8672a04720e7421e7f41bbf49364bcc1df910bb2.zip
opie-8672a04720e7421e7f41bbf49364bcc1df910bb2.tar.gz
opie-8672a04720e7421e7f41bbf49364bcc1df910bb2.tar.bz2
some dev docs
Diffstat (limited to 'development/tmake_ref.html') (more/less context) (ignore whitespace changes)
-rw-r--r--development/tmake_ref.html478
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>
3Reference 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>
11Specifies additional dependencies for the makefile target "all:".<p>
12
13
14<h4><a name="CLEAN_FILES"></a>CLEAN_FILES</h4>
15Specifies additional files to be removed for "make clean".<p>
16Example:<pre>
17 CLEAN_FILES = core *~
18</pre>
19
20
21<h4><a name="CONFIG"></a>CONFIG</h4>
22Sets the make configuration. It tells the tmake templates what compiler
23options to use and which extra libraries to link in.<p>
24These options control the compilation flags:
25<p>
26<table border="0">
27 <tr>
28 <td>&nbsp;</td>
29 <td>release</td>
30 <td>&nbsp;</td>
31 <td>Compile with optimization enabled, ignored if
32 "debug" is specified.</td>
33 </tr>
34 <tr>
35 <td>&nbsp;</td>
36 <td>debug</td>
37 <td>&nbsp;</td>
38 <td>Compile with debug options enabled.</td>
39 </tr>
40 <tr>
41 <td>&nbsp;</td>
42 <td>warn_on</td>
43 <td>&nbsp;</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>&nbsp;</td>
49 <td>warn_off</td>
50 <td>&nbsp;</td>
51 <td>The compiler should emit no warnings or as few as possible.</td>
52 </tr>
53</table>
54
55<p>
56These options defines the application/library type:
57<p>
58<table border="0">
59 <tr>
60 <td>&nbsp;</td>
61 <td>qt</td>
62 <td>&nbsp;</td>
63 <td>The target is a Qt application/library and requires Qt header
64 files/library.</td>
65 </tr>
66 <tr>
67 <td>&nbsp;</td>
68 <td>opengl</td>
69 <td>&nbsp;</td>
70 <td>The target requires the OpenGL (or Mesa) headers/libraries.</td>
71 </tr>
72 <tr>
73 <td>&nbsp;</td>
74 <td>x11</td>
75 <td>&nbsp;</td>
76 <td>The target is a X11 application (app.t only).</td>
77 </tr>
78 <tr>
79 <td>&nbsp;</td>
80 <td>windows</td>
81 <td>&nbsp;</td>
82 <td>The target is a Win32 window application (app.t only).</td>
83 </tr>
84 <tr>
85 <td>&nbsp;</td>
86 <td>console</td>
87 <td>&nbsp;</td>
88 <td>The target is a Win32 console application (app.t only).</td>
89 </tr>
90 <tr>
91 <td>&nbsp;</td>
92 <td>dll</td>
93 <td>&nbsp;</td>
94 <td>The target is a shared object/DLL (app.t only).</td>
95 </tr>
96 <tr>
97 <td>&nbsp;</td>
98 <td>staticlib</td>
99 <td>&nbsp;</td>
100 <td>The target is a static library (lib.t only).</td>
101 </tr>
102 <tr>
103 <td>&nbsp;</td>
104 <td>thread</td>
105 <td>&nbsp;</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>
112Specifies C/C++ macros (-D compiler option). On Windows you need
113to let DEFINES contain "QT_DLL" if you are building a Qt program
114which should link with the Qt DLL.
115
116
117<h4><a name="DEF_FILE"></a>DEF_FILE</h4>
118Win32/app.t only: Specifies a .def file.
119
120
121<h4><a name="DESTDIR"></a>DESTDIR</h4>
122Specifies where to put the target file.
123Example:<pre>
124 DESTDIR = ../../lib
125</pre>
126You must create this directory before running make.
127
128
129<h4><a name="DISTFILES"></a>DISTFILES</h4>
130Adds other files to the distribution archive ("dist target").
131The source files and project file are always included in the
132distribution archive.
133Example:<pre>
134 DISTFILES = CHANGES README
135</pre>
136
137
138<h4><a name="HEADERS"></a>HEADERS</h4>
139Defines the header files of the project.
140
141
142<h4><a name="INCPATH"></a>INCPATH</h4>
143This variable is generated from <code>INCLUDEPATH</code>. The ';' or ':'
144separators have been replaced by ' ' (single space). This makes it
145easier 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>
150This variable specifies the #include directories. It can be set in the
151project file, or by the <a href="#AddIncludePath">AddIncludePath()</a>
152function.<p>
153Example:<pre>
154 INCLUDEPATH = c:\msdev\include d:\stl\include
155</pre>
156Use ';' or space as the directory separator.
157
158
159<h4><a name="LIBS"></a>LIBS</h4>
160Defines additional libraries to be linked in when creating an application
161or a shared library. You probably want to use a platform qualifier since
162libraries are specified differently on Unix and Win32.<p>
163Example:<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>
170Specifies where to put the temporary moc output files. By default they
171are stored in the directory where the moc input files are.
172<p>
173Example:<pre>
174 MOC_DIR = tmp
175</pre>
176You must create this directory before running make.
177<p>
178See also: <a href="#OBJECTS_DIR">OBJECTS_DIR</a>.
179
180
181<h4><a name="OBJECTS"></a>OBJECTS</h4>
182This varialble is generated from <code>SOURCES</code> by the StdInit() function.
183The extension of each source file has been replaced by .o (Unix) or .obj
184(Win32).<p>
185Example:<pre>
186 SOURCES = a.x b.y
187</pre>
188Then <code>OBJECTS</code> become "a.o b.o" on Unix and "a.obj b.obj" on
189Win32.
190
191
192<h4><a name="OBJECTS_DIR"></a>OBJECTS_DIR</h4>
193Specifies where to put object files. By default they are stored in
194the directory where the source files are.<p>
195Example:<pre>
196 OBJECTS_DIR = tmp
197</pre>
198You must create this directory before running make.
199<p>
200See also: <a href="#MOC_DIR">MOC_DIR</a>.
201
202
203<h4><a name="OBJMOC"></a>OBJMOC</h4>
204This 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
206all intermediate moc object files.<p>
207Example:<pre>
208 HEADERS = demo.h
209 SOURCES = demo.cpp main.cpp
210</pre>
211If <tt>demo.h</tt> and <tt>main.cpp</tt> define classes that use signals
212and slots (i.e. the <code>Q_OBJECT</code> "keyword" is found in these two
213files), <code>OBJMOC</code> becomes:<pre>
214 OBJMOC = moc_demo.obj
215</pre>
216See also: <a href="#SRCMOC">SRCMOC</a>.
217
218
219<h4><a name="PROJECT"></a>PROJECT</h4>
220This is the name of the project. It defaults to the name of the project
221file, excluding the .pro extension.
222
223
224<h4><a name="RC_FILE"></a>RC_FILE</h4>
225Win32/app.t only: Specifies a .rc file. Cannot be used with the RES_FILE
226variable.
227
228
229<h4><a name="RES_FILE"></a>RES_FILE</h4>
230Win32/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>
235Defines the source files of the project.
236
237
238<h4><a name="SRCMOC"></a>SRCMOC</h4>
239This 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
241all intermediate moc files.<p>
242Example:<pre>
243 HEADERS = demo.h
244 SOURCES = demo.cpp main.cpp
245</pre>
246If <tt>demo.h</tt> and <tt>main.cpp</tt> define classes that use signals
247and slots (i.e. the <code>Q_OBJECT</code> "keyword" is found in these two
248files), <code>SRCMOC</code> becomes:<pre>
249 SRCMOC = moc_demo.cpp main.moc
250</pre>
251See also: <a href="#OBJMOC">OBJMOC</a>.
252
253
254<h4><a name="TARGET"></a>TARGET</h4>
255Sets the makefile target, i.e. what program to build.
256
257
258<h4><a name="TEMPLATE"></a>TEMPLATE</h4>
259Sets 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>
264Contains the name of the compiler.
265
266
267<h4><a name="TMAKE_CFLAGS"></a>TMAKE_CFLAGS</h4>
268Contains the default compiler flags.
269
270
271<h4><a name="TMAKE_FILEVARS"></a>TMAKE_FILEVARS</h4>
272Tells tmake which variables contain file names. This is because tmake
273on Windows replace the directory separator / with \.
274
275
276<hr>
277<h2>Function Reference</h2>
278This section contains a brief description of some important
279tmake functions used by the templates.
280
281
282<h3><a name="AddIncludePath"></a>AddIncludePath(path)</h3>
283Adds <em>path</em> to the include path variable,
284<a href="#INCLUDEPATH">INCLUDEPATH</a>. The include path is used
285for 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>
290Example:<pre>
291 #$ AddIncludePath('$QTDIR/include;/local/include');
292</pre>
293
294
295<h3>BuildMocObj(objects,sources)</h3>
296Creates build rules for moc source files. Generates
297include dependencies.<p>
298Example:<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>
307Creates moc source files from C++ files containing classes that
308define signals and slots. For a header file <tt>x.h</tt>, the
309generated 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
311should be #include'd by <tt>y.cpp</tt>.<p>
312Example:<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>
322Creates build rules for source files. Generates
323include dependencies.<p>
324Example:<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>
338Returns 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>
345Call this function to force tmake to generate no output until
346EnableOutput() 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>
355Enables tmake output after DisableOutput() was called.
356
357
358<h3>Expand(var)</h3>
359Expands 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>
367Expands a $project{} variable, splits on whitespace
368and joins with $glue. $prepend is put at the start
369of the string and $append is put at the end of the
370string. The resulting string ($text) becomes "" if
371the project variable is empty or not defined.<p>
372Example:<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>
383This function is suitable for expanding lists of files.
384Equivalent with <code>ExpandGlue($var,""," \\\n\t\t","")</code>.<p>
385Example:<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>
394Similar to ExpandGlue, except that it splits the items on a semicolon
395instead of space (if the variable contains at least one semicolon).
396
397
398<h3>IncludeTemplate(file)</h3>
399Includes a template file. The ".t" extension is optional.<p>
400Example:<pre>
401 #$ IncludeTemplate("mytemplate");
402</pre>
403
404
405<h3>Now()</h3>
406Sets $text to the current date and time.<p>
407Example:<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>
415This is a powerful function for setting and reading project
416variables. Returns the resulting project variables (joined with space
417between).
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>
450Scans a project file and stores the project variables and values in the
451global associative <code>%project</code> array.
452
453
454<h3><a name="StdInit"></a>StdInit()</h3>
455Standard initialization of tmake. StdInit() should be
456called from one of the first lines in the template.<p>
457
458This 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
466The moc-related variables are created only if <code>CONFIG</code> contains "qt"
467
468
469<h3>Substitute(string)</h3>
470This function takes a string and substitutes any occurrence of $$var
471with the actual content of the variable. Returns the substituted string.
472Also sets $text.
473<p>
474Important: Use single quotes around the string, otherwise perl will expand
475any $vars it finds.
476<p>Example:<pre>
477 Substitute('Project name: $$PROJECT, uses template $$TEMPLATE');
478</pre>