diff options
| author | Dimitri van Heesch <dimitri@stack.nl> | 1999-12-15 19:34:06 (GMT) |
|---|---|---|
| committer | Dimitri van Heesch <dimitri@stack.nl> | 1999-12-15 19:34:06 (GMT) |
| commit | ee8333a5d2ecf84deeb5d05ed8b23c212729cdac (patch) | |
| tree | 43e0b215b5d3d2b436509cbb1cd22102aef61b1d /tmake/doc | |
| parent | 6aa7383e23c850af36c25b87e5737a2e2f635083 (diff) | |
| download | Doxygen-ee8333a5d2ecf84deeb5d05ed8b23c212729cdac.zip Doxygen-ee8333a5d2ecf84deeb5d05ed8b23c212729cdac.tar.gz Doxygen-ee8333a5d2ecf84deeb5d05ed8b23c212729cdac.tar.bz2 | |
mods for doxygen-0.49-990829
Diffstat (limited to 'tmake/doc')
| -rw-r--r-- | tmake/doc/tmake.html | 219 | ||||
| -rw-r--r-- | tmake/doc/tmake_ref.html | 117 |
2 files changed, 190 insertions, 146 deletions
diff --git a/tmake/doc/tmake.html b/tmake/doc/tmake.html index b19af51..1b14809 100644 --- a/tmake/doc/tmake.html +++ b/tmake/doc/tmake.html @@ -1,52 +1,36 @@ <!doctype HTML public "-//W3C//DTD HTML 3.2//EN"> <html><head><title> -tmake User's Guide +User's Guide - tmake </title></head><body bgcolor="#ffffff"> -<p><h1 align=center>tmake User's Guide</h1> - - -<hr> -<h2>License Statement</h2> - -Copyright (C) 1996-1998 by Troll Tech AS. All rights reserved.<p> - -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, provided -that this copyright notice appears in all copies. -No representations are made about the suitability of this software for any -purpose. It is provided "as is" without express or implied warranty. +<p><h1 align=center>User's Guide - tmake</h1> <hr> <h2>Introduction</h2> -tmake is an easy-to-use tool for creating and maintaining makefiles across -many platforms and compilers. The idea is that you should spend your time -writing code, not makefiles. - -<p> -We wrote tmake because we spent too much time maintaining makefiles for -Windows and Unix compilers. Being the developer of the multi-platform GUI -toolkit <a href="http://www.troll.no/qt">Qt</a>, Troll Tech must provide -Qt makefiles for more than 30 different OS/compiler combinations. +tmake is an easy-to-use tool from Troll Tech to create and maintain +makefiles for software projects. It can be a painful task to manage +makefiles manually, especially if you develop for more than one platform +or use more than one compiler. tmake automates and streamlines this +process and lets you spend your valuable time on writing code, not +makefiles. <p> -We looked at GNU autoconf, but it was Unix-specific and not flexible -enough in our opinion. Our makefile system also had to deal with Qt -<a href="http://www.troll.no/qt/metaobjects.html">meta object -compiler</a> (moc) issues. The moc program extracts meta information from -C++ files and generates a C++ file with data tables etc. It takes work to -add makefile rules for the moc and wanted to automate this task. +Our main motivation for developing tmake was that we spent far too much +time maintaining makefiles for <a href="http://www.troll.no/qt">Qt</a>, +our cross-platform GUI toolkit. Qt supports around 15 flavors of Unix, +Microsoft Windows, and around 15 different C++ compilers. We looked at +GNU autoconf, but it was Unix-specific and not flexible enough in our +opinion. Our makefile system also had to deal with Qt <a +href="http://www.troll.no/qt/metaobjects.html">meta object compiler</a> +(moc) issues. The moc program extracts meta information from C++ files and +generates a C++ file with data tables etc. It takes extra work to add +makefile rules for the moc and wanted to automate this task. <p> -The tmake project was started around mid 1996 and version 1.0 was released -in September 1997. It soon became a success and is now widely used among -Qt programmers. - -<p> -tmake is written in Perl and requires perl version 5 or newer. You do not -need to be familiar with Perl programming to use tmake, but you should -learn Perl if you want to write your own makefile templates. +tmake is written in Perl and requires that you have installed perl version +5 or newer. Basic use of tmake requires no perl knowledge, but if you know +perl you can extend tmake and write your own makefile templates. <p> <b>Windows users:</b> The tmake distribution for Win32 includes tmake.exe @@ -56,9 +40,14 @@ perl scripts. You can download perl for Win32 (Windows NT and 95) from <a href="http://www.activestate.com">www.activestate.com</a> <p> -Feedback is highly appreciated. Contact the author hanord@troll.no if you -have ideas, patches etc. for tmake. +tmake is free software and you may use, copy, modify and distribute tmake +and its documentation for any purpose and without any fee. See the +LICENSE file for details. +<p> +Feedback is highly appreciated. Contact the author, Haavard Nord <a +href="mailto:hanord@troll.no">(hanord@troll.no)</a>, if you have ideas, +patches etc. for tmake. <hr> <h2>Installation</h2> @@ -66,7 +55,7 @@ have ideas, patches etc. for tmake. <ol> <li>Make sure you have perl version 5 or later installed (optional for Windows users). -<li>Unpack the tmake tar.gz or zip archive. +<li>Unpack the tmake tar.gz archive for Unix or the tmake .zip file for Windows. <li>Set the TMAKEPATH environment variable to the directories containing the template files (see below). <li>Add the tmake/bin directory to your PATH. @@ -84,14 +73,15 @@ Here are some examples:<p> setenv PATH $PATH:/local/tmake/bin </pre> -<strong>Windows NT and Windows 95:</strong><pre> +<strong>Microsoft Windows:</strong><pre> set TMAKEPATH=c:\tmake\lib\win32-msvc set PATH=%PATH%;c:\tmake\bin </pre> <p> -The template directory name has the form <em>platform</em>-<em>compiler</em>. -Each template directory contains template files and a configuration file. +The template directory name has the form <em>platform</em>-<em>compiler</em> +and contains a platform configuration file (tmake.conf) and tmake template +files. <p> Supported platforms: AIX, Data General, FreeBSD, HPUX, SGI Irix, Linux, @@ -99,8 +89,7 @@ NetBSD, OpenBSD, OSF1/DEC, SCO, Solaris, SunOS, Ultrix, Unixware and Win32. <p> -Have a look at the tmake/lib directory to see if your platform-compiler -combination is supported. If it's not there, please tell us. +You can find your platform-compiler combination in the <tt>tmake/lib</tt>. <p> <b>Unix users:</b> tmake requires that perl is in /usr/bin. If your @@ -114,7 +103,7 @@ make a small shell script which invokes tmake with the correct perl. Let's assume you have a small Qt application consisting of one C++ header file and two source files. -First you need to create a project file, e.g. hello.pro:<pre> +First you need to create a tmake project file, e.g. hello.pro:<pre> HEADERS = hello.h SOURCES = hello.cpp main.cpp TARGET = hello @@ -173,7 +162,7 @@ these files: <p> The hello.pro project file above does not have a <code>TEMPLATE</code> or -a <code>CONFIG</code> tag. The default template is <tt>app</tt> (the .t +a <code>CONFIG</code> variable. The default template is <tt>app</tt> (the .t extension is optional) and the default configuration is <tt>qt warn_on release</tt>. @@ -191,7 +180,7 @@ above:<pre> <h4>Makefile Configuration</h4> <p> -The <code>CONFIG</code> tag is recognized by both the app.t and lib.t +The <code>CONFIG</code> variable is recognized by both the app.t and lib.t templates and specifies what compiler options to use and which extra libraries to link in. @@ -247,7 +236,7 @@ These options defines the application/library type: <td> </td> <td>x11</td> <td> </td> - <td>The target is a X11 application (app.t only).</td> + <td>The target is a X11 application or library.</td> </tr> <tr> <td> </td> @@ -265,7 +254,7 @@ These options defines the application/library type: <td> </td> <td>dll</td> <td> </td> - <td>The target is a shared object/DLL (app.t only).</td> + <td>The target is a shared object/DLL.</td> </tr> <tr> <td> </td> @@ -283,7 +272,7 @@ read:<pre> </pre> <p> -The most common tmake options and project tags are described here. +The most common tmake options and project variables are described here. See the tmake <a href="tmake_ref.html">reference manual</a> for details.<p> @@ -294,7 +283,7 @@ details.<p> The application template, app.t, lets you compile and link executable programs or shared objects (DLLs). -This template recognizes several tags. +This template recognizes several variabless. <p> <table border="0"> <tr> @@ -372,10 +361,9 @@ The library template, lib.t, lets you compile and create static or shared libraries. <p> -The lib.t template supports the same project tags as app.t, but also +The lib.t template supports the same project variables as app.t, but also <code>VERSION</code>. <code>VERSION</code> is the version number of the -target library, e.g. 1.40. The version is important for Unix shared -libraries, but ignored on Windows. +target library, e.g. 1.40. The version is important for shared libraries. @@ -383,7 +371,7 @@ libraries, but ignored on Windows. The subdirs template, subdirs.t, lets you invoke make in subdirectories. -<p>The <code>SUBDIRS</code> tag contains the name of all subdirectories to +<p>The <code>SUBDIRS</code> variable contains the name of all subdirectories to be processed. @@ -418,29 +406,130 @@ template):<pre> <hr> -<h2><a name="usage"></a>Program Usage: tmake</h2> +<h2>Project File Syntax</h2> + +The tmake project file has a very simple syntax. You may set +project variables, append to project variables, remove from +project variable and substitute project variables. + +To set a project variable:<pre> + HEADERS = gui.h xml.h url.h +</pre> + +If you cannot fit everything on one line, use '\' to split it up:<pre> + HEADERS = gui.h \ + xml.h \ + url.h +</pre> + +<p> +Project variables contains lists of items (such as header files, +compiler options etc.) and use whitespace to separate the items. +This means that tmake cannot deal with items containing whitespace. +The INCLUDEPATH variable is an exception. If INCLUDEPATH contains +one or more semicolons (;), tmake uses the semicolon to separate +the include directories, hence you can have include directories +containing whitespace (this is quite common on Windows). + +<p> +Here is an example:<pre> + INCLUDEPATH = C:\Program Files\DBLib\Include;C:\qt\include +</pre> + +<p> +tmake supports <em>project variable expension</em>. Use $$ to expand +any project variable:<pre> + ALLFILES = $$HEADERS $$SOURCES +</pre> + +<p> +Most often you assign some value to a project variable, but you can +also add to, remove from or replace parts of a project variable.<pre> + A = abc + X = xyz + A += def # A = abc def + X *= xyz # X = xyz + B = $$A # B = abc def + B -= abc # B = def + X /= s/y/Y/ # X = xYz +</pre> +The *= operation adds the value if the variable does not already contain it. +The /= operation performs regular expression substitution. + +<p> +You can also set variables from the command line when running the tmake +program. For instance, if you want to generate a makefile with debug +information:<pre> + tmake "CONFIG+=debug" hello.pro +</pre> + +<p> +Use the <tt>unix:</tt> or <tt>win32:</tt> (conditional) qualifier if you want a +platform-specific variable:<pre> + SOURCES = common.cpp # common for all platforms + unix:SOURCES += unix.cpp # additional sources for Unix + win32:SOURCES += win32.cpp # additional sources for Windows + unix:LIBS += -lm # on Unix we need the math lib +</pre> +If none of the platforms match, tmake looks for the variable in CONFIG +variable:<pre> + debug:SOURCES += dbgstuff.cpp # additional source for debugging +</pre> + +Finally, you can set platform and compiler-dependent variables:<pre> + linux-g++:TMAKE_CFLAGS = -fno-rtti +</pre> + +<p> +You may define your own project variables to be used by custom templates. A +project variable is stored in <code>%project</code>, which is an associative +Perl array. Access it like this: <code>$project{"var"}</code> or via the +function <code>Project("var")</code>. For example, after reading +"hello.pro", <code>$project{"SOURCES"}</code> contains "hello.cpp +main.cpp".<p> + + +<hr> +<h2><a name="usage"></a>Running tmake</h2> Usage:<pre> - tmake [options] <em>project-file</em> + tmake [options] <em>project files or project settings</em> </pre> Options:<pre> -e expr Evaluate the Perl expression. Ignores the template file. -nodepend Don't generate dependency information. -o <em>file</em> Write output to <em>file</em> instead of stdout. - -p <em>file</em> Load an additional project file. -t <em>file</em> Specify a template <em>file</em>. -unix Force tmake into Unix mode. -v Verbose/debugging on. -win32 Force tmake into Win32 mode. </pre> -The -t option overrides any <code>TEMPLATE</code> tag in the project file. +The -t option overrides any <code>TEMPLATE</code> variable in the project file. <p> The default project file extension is ".pro". The default template file extension is ".t". If you do not specify these extension tmake will automatically add them for you. + +<p> +Example of basic use:<pre> + tmake hello -o Makefile +</pre> + +<p> +Example of how to create a makefile with debugging information:<pre> + tmake "CONFIG+=debug" hello -o Makefile +</pre> + <p> +Exmaple of how to specify a TMAKEPATH:<pre> + tmake "TMAKEPATH=/local/tmake/lib/hpux-g++" hello.pro -o Makefile +</pre> +Example of how to evaluate a perl expression (print names of headers +and source files):<pre> + tmake hello -e 'Expand("HEADERS","SOURCES")' +</pre> <hr> <h2><a name="progen"></a>The progen Utility</h2> @@ -478,12 +567,12 @@ settings in your project file:<pre> solaris-cc:TMAKE_CC = /opt/bin/CC_5.0 solaris-cc:TMAKE_CFLAGS = -pts unix:TMAKE_LIBS = -lXext - win32:INCLUDE_PATH = c:\myinclude + win32:INCLUDEPATH = c:\myinclude win32-borland:DEFINES = NO_BOOL </pre> -You can prefix a project tag with unix: or win32: to make it specific for -either Unix or Windows. You can also prefix tags with +You can prefix a project variable with unix: or win32: to make it specific for +either Unix or Windows. You can also prefix a variable with <em>platform-compiler</em> <h4>Your Own Templates</h4> @@ -496,10 +585,10 @@ can do with tmake. First you need to know how tmake works. When you run tmake, it first reads the <tt>tmake.conf</tt> file. This configuration file has the same syntax as the project file. -tmake then reads the project file and sets the project tags it +tmake then reads the project file and sets the project variables it finds, e.g. <code>HEADERS</code>, <code>SOURCES</code> etc. -All tags and values are stored in a global associative Perl hash +All variables and values are stored in a global associative Perl hash array called <code>project</code>. For example, <code>$project{"SOURCES"}</code> contains "hello.cpp main.cpp" after processing hello.pro. diff --git a/tmake/doc/tmake_ref.html b/tmake/doc/tmake_ref.html index 0b89b28..c9124c4 100644 --- a/tmake/doc/tmake_ref.html +++ b/tmake/doc/tmake_ref.html @@ -1,67 +1,11 @@ <!doctype HTML public "-//W3C//DTD HTML 3.2//EN"> <html><head><title> -tmake Reference Manual +Reference Manual - tmake </title></head><body bgcolor="#ffffff"> -<p><h1 align=center>tmake Reference Manual</h1> +<p><h1 align=center>Reference Manual - tmake</h1> <hr> -<h2>Project Settings</h2> - -tmake recognizes several project tags. The syntax for setting a -project variable is:<pre> - TAG = value -</pre> -You can also do tag expansion using $$:<pre> - ALLFILES = Project files: $$HEADERS $$SOURCES -</pre> -Normally you assign to a tag, but you can also add to a tag, subtract -from a tag or replace parts of the tag.<pre> - A = abc - X = xyz - A += def # A = abc def - X *= xyz # X = xyz - B = $$A # B = abc def - B -= abc # B = def - X /= s/y/Y/ # X = xYz -</pre> -The *= operation adds the value if the tag does not already contain it. -The /= operation performs regular expression substitution. - -<p> -You can also set tags from the command line when running the tmake program. -For instance, if you want to generate a makefile with debug information:<pre> - tmake hello.pro "CONFIG+=debug" -</pre> - -<p> -Use the <tt>unix:</tt> or <tt>win32:</tt> qualifier if you want a -platform-specific tag:<pre> - SOURCES = common.cpp # common for all platforms - unix:SOURCES += unix.cpp # additional sources for Unix - win32:SOURCES += win32.cpp # additional sources for Windows - unix:LIBS += -lm # on Unix we need the math lib -</pre> -If none of the platforms match, tmake looks for the tag in <a -href="#CONFIG">CONFIG</a> setting:<pre> - debug:SOURCES += dbgstuff.cpp # additional source for debugging -</pre> - -Finally, you can set platform and compiler-dependent tags:<pre> - linux-g++:TMAKE_CFLAGS = -fno-rtti -</pre> - -<p> -You may define your own project tags to be used by custom templates. A -project tag is stored in <code>%project</code>, which is an associative -Perl array. Access it like this: <code>$project{"tag"}</code> or via the -function <code>Project('tag')</code>. For example, after reading -"hello.pro", <code>$project{"SOURCES"}</code> contains "hello.cpp -main.cpp". One limitation of tmake is that it cannot handle file names -with white space.<p> - - -<hr> -<h2>Project Tag Reference</h2> +<h2>Project Variable Reference</h2> <h4><a name="ALL_DEPS"></a>ALL_DEPS</h4> Specifies additional dependencies for the makefile target "all:".<p> @@ -158,6 +102,12 @@ These options defines the application/library type: </table> +<h4><a name="DEFINES"></a>DEFINES</h4> +Specifies C/C++ macros (-D compiler option). On Windows you need +to let DEFINES contain "QT_DLL" if you are building a Qt program +which should link with the Qt DLL. + + <h4><a name="DEF_FILE"></a>DEF_FILE</h4> Win32/app.t only: Specifies a .def file. @@ -175,14 +125,14 @@ Defines the header files of the project. <h4><a name="INCPATH"></a>INCPATH</h4> -This tag is generated from <code>INCLUDEPATH</code>. The ';' or ':' +This variable is generated from <code>INCLUDEPATH</code>. The ';' or ':' separators have been replaced by ' ' (single space). This makes it easier to split. qtapp.t and other templates expand <code>INCPATH</code> to set -I options for the C++ compiler. <h4><a name="INCLUDEPATH"></a>INCLUDEPATH</h4> -This tag specifies the #include directories. It can be set in the +This variable specifies the #include directories. It can be set in the project file, or by the <a href="#AddIncludePath">AddIncludePath()</a> function.<p> Example:<pre> @@ -214,7 +164,7 @@ See also: <a href="#OBJECTS_DIR">OBJECTS_DIR</a>. <h4><a name="OBJECTS"></a>OBJECTS</h4> -This tag is generated from <code>SOURCES</code> by the StdInit() function. +This varialble is generated from <code>SOURCES</code> by the StdInit() function. The extension of each source file has been replaced by .o (Unix) or .obj (Win32).<p> Example:<pre> @@ -236,7 +186,7 @@ See also: <a href="#MOC_DIR">MOC_DIR</a>. <h4><a name="OBJMOC"></a>OBJMOC</h4> -This tag is generated by the <a href="#StdInit">StdInit()</a> function if +This variable is generated by the <a href="#StdInit">StdInit()</a> function if <code>$moc_aware</code> is true. <code>OBJMOC</code> contains the name of all intermediate moc object files.<p> Example:<pre> @@ -258,7 +208,7 @@ file, excluding the .pro extension. <h4><a name="RC_FILE"></a>RC_FILE</h4> Win32/app.t only: Specifies a .rc file. Cannot be used with the RES_FILE -tag. +variable. <h4><a name="RES_FILE"></a>RES_FILE</h4> @@ -271,7 +221,7 @@ Defines the source files of the project. <h4><a name="SRCMOC"></a>SRCMOC</h4> -This tag is generated by the <a href="#StdInit">StdInit()</a> function if +This variable is generated by the <a href="#StdInit">StdInit()</a> function if <code>CONFIG</code> contains "qt". <code>SRCMOC</code> contains the name of all intermediate moc files.<p> Example:<pre> @@ -303,8 +253,8 @@ Contains the name of the compiler. Contains the default compiler flags. -<h4><a name="TMAKE_FILETAGS"></a>TMAKE_FILETAGS</h4> -Tells tmake which tags contain file names. This is because tmake +<h4><a name="TMAKE_FILEVARS"></a>TMAKE_FILEVARS</h4> +Tells tmake which variables contain file names. This is because tmake on Windows replace the directory separator / with \. @@ -370,7 +320,7 @@ Example:<pre> <h3>Config(string)</h3> -Returns true if the <code>CONFIG</code> tag contains the given string. +Returns true if the <code>CONFIG</code> variable contains the given string. <p>Example:<pre> #$ if ( Config("release") { } </pre> @@ -390,20 +340,20 @@ EnableOutput() is called. Enables tmake output after DisableOutput() was called. -<h3>Expand(tag)</h3> -Expands a project tag. Equivalent to <code>$text = $project{$tag}</code>. +<h3>Expand(var)</h3> +Expands a project variable. Equivalent to <code>$text = $project{$var}</code>. <p>Example:<pre> VERSION = #$ Expand("VERSION"); </pre>Output:<pre> VERSION = 1.1 </pre> -<h3>ExpandGlue(tag,prepend,glue,append)</h3> -Expands a $project{} tag, splits on whitespace +<h3>ExpandGlue(var,prepend,glue,append)</h3> +Expands a $project{} variable, splits on whitespace and joins with $glue. $prepend is put at the start of the string and $append is put at the end of the string. The resulting string ($text) becomes "" if -the project tag is empty or not defined.<p> +the project variable is empty or not defined.<p> Example:<pre> clear: #$ ExpandGlue("OBJECTS","-del","\n\t-del ",""); @@ -414,9 +364,9 @@ Example:<pre> </pre> -<h3>ExpandList(tag)</h3> +<h3>ExpandList(var)</h3> This function is suitable for expanding lists of files. -Equivalent with <code>ExpandGlue($tag,""," \\\n\t\t","")</code>.<p> +Equivalent with <code>ExpandGlue($var,""," \\\n\t\t","")</code>.<p> Example:<pre> OBJECTS = #$ ExpandList("OBJECTS"); </pre>Output:<pre> @@ -425,6 +375,11 @@ Example:<pre> </pre> +<h3>ExpandPath(var,prepend,glue,append)</h3> +Similar to ExpandGlue, except that it splits the items on a semicolon +instead of space (if the variable contains at least one semicolon). + + <h3>IncludeTemplate(file)</h3> Includes a template file. The ".t" extension is optional.<p> Example:<pre> @@ -477,7 +432,7 @@ between). <h3><a name="ScanProject"></a>ScanProject(file)</h3> -Scans a project file and stores the project tags and values in the +Scans a project file and stores the project variables and values in the global associative <code>%project</code> array. @@ -485,7 +440,7 @@ global associative <code>%project</code> array. Standard initialization of tmake. StdInit() should be called from one of the first lines in the template.<p> -This function creates some new project tags:<ul> +This function creates some new project variables:<ul> <li><code><a href="#OBJECTS">OBJECTS</a></code> - Object files corresponding to <code><a href="#SOURCES">SOURCES</a></code>. @@ -493,16 +448,16 @@ This function creates some new project tags:<ul> <li><code><a href="#OBJMOC">OBJMOC</a></code> - moc object files. </ul> -The moc-related tags are created only if <code>CONFIG</code> contains "qt" +The moc-related variables are created only if <code>CONFIG</code> contains "qt" <h3>Substitute(string)</h3> -This function takes a string and substitutes any occurrence of $$tag -with the actual content of the tag. Returns the substituted string. +This function takes a string and substitutes any occurrence of $$var +with the actual content of the variable. Returns the substituted string. Also sets $text. <p> Important: Use single quotes around the string, otherwise perl will expand -any $tags it finds. +any $vars it finds. <p>Example:<pre> Substitute('Project name: $$PROJECT, uses template $$TEMPLATE'); </pre> |