diff options
Diffstat (limited to 'tmake/doc/tmake.html')
| -rw-r--r-- | tmake/doc/tmake.html | 638 |
1 files changed, 638 insertions, 0 deletions
diff --git a/tmake/doc/tmake.html b/tmake/doc/tmake.html new file mode 100644 index 0000000..b19af51 --- /dev/null +++ b/tmake/doc/tmake.html @@ -0,0 +1,638 @@ +<!doctype HTML public "-//W3C//DTD HTML 3.2//EN"> +<html><head><title> +tmake User's Guide +</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. + + +<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. + +<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. + +<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. + +<p> +<b>Windows users:</b> The tmake distribution for Win32 includes tmake.exe +(built by the perl2exe utility) and you do not need to download and +install perl unless you want to modify the tmake source code or run other +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. + + +<hr> +<h2>Installation</h2> + +<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>Set the TMAKEPATH environment variable to the directories +containing the template files (see below). +<li>Add the tmake/bin directory to your PATH. +</ol> + +Here are some examples:<p> +<strong>Unix Bourne shell:</strong><pre> + TMAKEPATH=/local/tmake/lib/linux-g++ + PATH=$PATH:/local/tmake/bin + export TMAKEPATH PATH +</pre> + +<strong>Unix C shell:</strong><pre> + setenv TMAKEPATH /local/tmake/lib/linux-g++ + setenv PATH $PATH:/local/tmake/bin +</pre> + +<strong>Windows NT and Windows 95:</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. + +<p> +Supported platforms: AIX, Data General, FreeBSD, HPUX, SGI Irix, Linux, +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. + +<p> +<b>Unix users:</b> tmake requires that perl is in /usr/bin. If your +version of perl is elsewehere, either change the first line of tmake or +make a small shell script which invokes tmake with the correct perl. + + +<hr> +<h2>Getting Started</h2> + +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> + HEADERS = hello.h + SOURCES = hello.cpp main.cpp + TARGET = hello +</pre> + +Then run tmake to create a Makefile:<pre> + tmake hello.pro -o Makefile +</pre> +And finally:<pre> + make +</pre> +This builds the hello program. Remember to set the <code>TMAKEPATH</code> +environment variable before you run tmake. +<p> +See <a href="m-linux-gcc.html">Makefile for Linux/g++</a>.<br> +See <a href="m-win32-msvc.html">Makefile for Win32/msvc</a> +(Microsoft Visual C++).<br> + + +<hr> +<h2>Makefile Templates</h2> + +The tmake distribution includes three makefile templates and one +configuration file for each platform/compiler combination. The +<code>TMAKEPATH</code> environment variable tells tmake where to find +these files: +<p> +<table border="0"> + <tr> + <td> </td> + <td>app.t</td> + <td> </td> + <td>Creates a makefile for building applications.</td> + </tr> + <tr> + <td> </td> + <td>lib.t</td> + <td> </td> + <td>Creates a makefile for building libraries.</td> + </tr> + <tr> + <td> </td> + <td>subdirs.t</td> + <td> </td> + <td>Creates a makefile for building targets in subdirectories.</td> + </tr> + <tr> + <td> </td> + <td>tmake.conf</td> + <td> </td> + <td>This configuration file contains compiler options and lists + tools and libraries. + </tr> +</table> + + +<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 +extension is optional) and the default configuration is <tt>qt warn_on +release</tt>. + +This project file produces exactly the same result as the hello.pro +above:<pre> + TEMPLATE = app + CONFIG = qt warn_on release + HEADERS = hello.h + SOURCES = hello.cpp main.cpp + TARGET = hello +</pre> + + + +<h4>Makefile Configuration</h4> + +<p> +The <code>CONFIG</code> tag 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. + +These options control the compilation flags: +<p> +<table border="0"> + <tr> + <td> </td> + <td>release</td> + <td> </td> + <td>Compile with optimization enabled, ignored if + "debug" is specified.</td> + </tr> + <tr> + <td> </td> + <td>debug</td> + <td> </td> + <td>Compile with debug options enabled.</td> + </tr> + <tr> + <td> </td> + <td>warn_on</td> + <td> </td> + <td>The compiler should emit more warnings than normally, ignored if + "warn_off" is specified.</td> + </tr> + <tr> + <td> </td> + <td>warn_off</td> + <td> </td> + <td>The compiler should emit no warnings or as few as possible.</td> + </tr> +</table> + +<p> +These options defines the application/library type: +<p> +<table border="0"> + <tr> + <td> </td> + <td>qt</td> + <td> </td> + <td>The target is a Qt application/library and requires Qt header + files/library.</td> + </tr> + <tr> + <td> </td> + <td>opengl</td> + <td> </td> + <td>The target requires the OpenGL (or Mesa) headers/libraries.</td> + </tr> + <tr> + <td> </td> + <td>x11</td> + <td> </td> + <td>The target is a X11 application (app.t only).</td> + </tr> + <tr> + <td> </td> + <td>windows</td> + <td> </td> + <td>The target is a Win32 window application (app.t only).</td> + </tr> + <tr> + <td> </td> + <td>console</td> + <td> </td> + <td>The target is a Win32 console application (app.t only).</td> + </tr> + <tr> + <td> </td> + <td>dll</td> + <td> </td> + <td>The target is a shared object/DLL (app.t only).</td> + </tr> + <tr> + <td> </td> + <td>staticlib</td> + <td> </td> + <td>The target is a static library (lib.t only).</td> + </tr> +</table> + +<p> +As an example, if the hello application uses both Qt and OpenGL and you +want to compile it for debugging, your <code>CONFIG</code> line should +read:<pre> + CONFIG = qt opengl debug +</pre> + +<p> +The most common tmake options and project tags are described here. +See the tmake <a href="tmake_ref.html">reference manual</a> for +details.<p> + + + +<h4>The Application Template</h4> + +The application template, app.t, lets you compile and link executable +programs or shared objects (DLLs). + +This template recognizes several tags. +<p> +<table border="0"> + <tr> + <td> </td> + <td>HEADERS</td> + <td> </td> + <td>Header files.</td> + </tr> + <tr> + <td> </td> + <td>SOURCES</td> + <td> </td> + <td>Source files.</td> + </tr> + <tr> + <td> </td> + <td>TARGET</td> + <td> </td> + <td>Name of executable (adds .exe if on Windows).</td> + </tr> + <tr> + <td> </td> + <td>DESTDIR</td> + <td> </td> + <td>Where to put the target.</td> + </tr> + <tr> + <td> </td> + <td>DEFINES</td> + <td> </td> + <td>Tell compiler to define C preprocessor macros (-D option).</td> + </tr> + <tr> + <td> </td> + <td>INCLUDEPATH</td> + <td> </td> + <td>Sets the include file search path for the compiler (-I + option). + </td> + </tr> + <tr> + <td> </td> + <td>DEPENDPATH</td> + <td> </td> + <td>Sets the dependency search path for tmake.</td> + </tr> + <tr> + <td> </td> + <td>DEF_FILE</td> + <td> </td> + <td>Win32 only: Link with a .def file.</td> + </tr> + <tr> + <td> </td> + <td>RC_FILE</td> + <td> </td> + <td>Win32 only: Use a .rc file (compile to temporary .res). + </td> + </tr> + <tr> + <td> </td> + <td>RES_FILE</td> + <td> </td> + <td>Win32 only: Link with a .res file. + </td> + </tr> +</table> + +<p> + + +<h4>The Library Template</h4> + +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 +<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. + + + +<h4>The Subdirs Template</h4> + +The subdirs template, subdirs.t, lets you invoke make in subdirectories. + +<p>The <code>SUBDIRS</code> tag contains the name of all subdirectories to +be processed. + + +<h4>Special Templates for Microsoft Visual C++</h4> + +If you have Microsoft Visual C++ 5.0, you can use two special templates to +generate a MSVC++ IDE project (.dsp file). After you have generated +e.g. hello.dsp, choose "File"->"Open Workspace" and select the hello.dsp +file. Visual C++ will then create a workspace (.dsw file) for you.<p> +<table border="0"> + <tr> + <td> </td> + <td>vcapp.t</td> + <td> </td> + <td>Creates an application project file (Microsoft Visual C++ 5.0 + only).</td> + </tr> + <tr> + <td> </td> + <td>vclib.t</td> + <td> </td> + <td>Creates a library project file (Microsoft Visual C++ 5.0 + only).</td> + </tr> +</table> + +<p> +Run tmake to create a hello.dsp file (use -t to override the default +template):<pre> + tmake -t vcapp -o hello.dsp hello.pro +</pre> + + +<hr> +<h2><a name="usage"></a>Program Usage: tmake</h2> + +Usage:<pre> + tmake [options] <em>project-file</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. +<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> + + +<hr> +<h2><a name="progen"></a>The progen Utility</h2> + +The progen utility creates project files for you. It can be used like +this:<pre> + progen -n hello -o hello.pro +</pre> +If no .cpp or .h files are specified on the command line, progen +searches for .cpp and .h (except moc_*.cpp) in the current directory +and below. +<p> +Usage:<pre> + progen [options] [<em>C/C++ header files and source files</em>] +</pre> +Options:<pre> + -lower Lower-case letters in filenames (useful on Windows). + -n <em>name</em> Specify a project name (<code>TARGET</code>). + -o <em>file</em> Write output to <em>file</em> instead of stdout. + -t <em>file</em> Specify a template <em>file</em>. +</pre> + + +<hr> +<h2>Advanced Topics</h2> + +In most cases you will be happy with using tmake as described above, but +sometimes you need to add special compiler options or even add new +makefile rules. This chapter describes how to customize your makefiles. + +<h4>Conditional Project Settings</h4> + +If you need a special compiler option etc., you can add platform-dependent +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-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 +<em>platform-compiler</em> + +<h4>Your Own Templates</h4> + +If you know Perl programming, there is virtually no limitation to what you +can do with tmake. First you need to know how tmake works. + +<h4>Template Processing</h4> + +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 +finds, e.g. <code>HEADERS</code>, <code>SOURCES</code> etc. + +All tags 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. + +When both the <tt>tmake.conf</tt> and the project files have been +read, tmake starts reading the template file line by line and +executes any Perl code it finds in the template. + +<ul> +<li>Anything after <code>#$</code> until newline is + evaluated as perl code. The perl code is substituted + with the contents of the <code>$text</code> + variable. +<li>Block of perl code: <code>#${</code> until + <code>#$}</code>. +<li>Comments; <code>#!</code> until newline is stripped. +<li>Anything else is copied directly from the template to + the output. +</ul> + +<p> +Example:<pre> + #! This is a comment which will be removed. + This text will appear in the output. + #$ $text = "The header file(s) are: " . $project{"HEADERS"}; + # This text also appears in the output. + #${ + $a = 12; + $b = 13; + $text = $a * $b; + #$} + That's all. +</pre> +Output:<pre> + This text will appear in the output. + The header file(s) are: hello.h + # This text also appears in the output. + 156 + That's all. +</pre> + + +<h3>Using tmake With Lex and Yacc</h3> + +The standard tmake templates knows how to process C and C++ files, but +sometimes you need to process additional files and link them into your +project. A typical example is to process lex and yacc files when you're +building a parser. + +<p> +Parser template:<pre> + #! + #! parser.t: This is a custom template for building a parser + #! + #$ IncludeTemplate("app.t"); + + ####### Lex/yacc programs and options + + LEX = flex + YACC = #$ $text = ($is_unix ? "yacc -d" : "byacc -d"); + + ####### Lex/yacc files + + LEXIN = #$ Expand("LEXINPUT"); + LEXOUT = lex.yy.c + YACCIN = #$ Expand("YACCINPUT"); + YACCOUT = y.tab.c + YACCHDR = y.tab.h + PARSER = #$ Expand("PARSER"); + + ####### Process lex/yacc files + + $(LEXOUT): $(LEXIN) + $(LEX) $(LEXIN) + + $(PARSER): $(YACCIN) $(LEXOUT) + $(YACC) $(YACCIN) + #$ $text = ($is_unix ? "-rm -f " : "-del ") . '$(PARSER)'; + #$ $text = ($is_unix ? "-mv " : "-ren ") . '$(YACCOUT) $(PARSER)'; +</pre> + +The parser template adds some extra rules to the application template +in order to build the lex and yacc portions of the project. This +template is portable across Unix and Windows since it generates different +commands depending on the <code>$is_unix</code> variable. + +<p> +To learn more about the Expand() function and other Perl functions which +tmake provides, consult the <a href="tmake_ref.html">reference manual</a>. + +<p> +Example project file:<pre> + TEMPLATE = parser.t + CONFIG = console release + LEXINPUT = lexer.l + YACCINPUT = grammar.y + PARSER = parser.cpp + SOURCES = $$PARSER \ + node.cpp \ + asmgen.cpp + TARGET = parser +</pre> + +Here we use macro expansion <code>$$PARSER</code> to avoid writing parser.cpp +two places. + + +<h3>Counting the Number of Code Lines</h3> + +tmake is generic since it is based on Perl. You can create your own +templates for other purposes than producing makefiles. Here is an example +template that counts the number of code lines in our project. + +<p> +Template wc.t:<pre> + #! Template that count number of C++ lines. + The number of C++ code lines for #$ $text=$project_name; + #${ + $files = $project{"HEADERS"} . " " . $project{"SOURCES"}; + $text = `wc -l $files`; + #$} +</pre> +Run it:<pre> + tmake -t wc hello +</pre> +Output:<pre> + The number of C++ code lines for hello.pro + 25 hello.h + 98 hello.cpp + 38 main.cpp + 161 total +</pre> +This will only work if the wc program is installed on your system. + + +</body></html> |