# Reference Manual - tmake

## Project Variable Reference

#### ALL_DEPS

Specifies additional dependencies for the makefile target "all:".

#### CLEAN_FILES

Specifies additional files to be removed for "make clean".

Example:

      CLEAN_FILES = core *~

#### CONFIG

Sets the make configuration. It tells the tmake templates what compiler options to use and which extra libraries to link in.

These options control the compilation flags:

| release |  | Compile with optimization enabled, ignored if "debug" is specified.
| debug |  | Compile with debug options enabled.
| warn_on |  | The compiler should emit more warnings than normally, ignored if "warn_off" is specified.
| warn_off |  | The compiler should emit no warnings or as few as possible.

These options defines the application/library type:

| qt |  | The target is a Qt application/library and requires Qt header files/library.
| opengl |  | The target requires the OpenGL (or Mesa) headers/libraries.
| x11 |  | The target is a X11 application (app.t only).
| windows |  | The target is a Win32 window application (app.t only).
| console |  | The target is a Win32 console application (app.t only).
| dll |  | The target is a shared object/DLL (app.t only).
| staticlib |  | The target is a static library (lib.t only).
| thread |  | The target is a multi-threaded application/library.

#### DEFINES

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.

#### DEF_FILE

Win32/app.t only: Specifies a .def file.

#### DEFINES_PREFIX

Specifies the prefix to use for DEFINES. On almost all platforms this defaults to "-D".

#### DESTDIR

Specifies where to put the target file. Example:

      DESTDIR = ../../lib

You must create this directory before running make.

#### DISTFILES

Adds other files to the distribution archive ("dist target"). The source files and project file are always included in the distribution archive. Example:

      DISTFILES = CHANGES README

#### HEADERS

Defines the header files of the project.

#### INCPATH

This variable is generated from `INCLUDEPATH`. The ';' or ':' separators have been replaced by ' ' (single space). This makes it easier to split. qtapp.t and other templates expand `INCPATH` to set -I options for the C++ compiler.

#### INCLUDE_PREFIX

Specifies the prefix to use for INCLUDES. On almost all platforms this defaults to "-I".

#### INCLUDEPATH

This variable specifies the #include directories. It can be set in the project file, or by the AddIncludePath() function.

Example:

      INCLUDEPATH = c:\msdev\include d:\stl\include

Use ';' or space as the directory separator.

#### LIBS

Defines additional libraries to be linked in when creating an application or a shared library. You probably want to use a platform qualifier since libraries are specified differently on Unix and Win32.

Example:

      unix:LIBS  = -lXext -lm
      win32:LIBS = ole32.lib

#### MOC_DIR

Specifies where to put the temporary moc output files. By default they are stored in the directory where the moc input files are.

Example:

      MOC_DIR = tmp

You must create this directory before running make.

See also: OBJECTS_DIR.

#### OBJ_IMPL_OUT

Specifies the output string to use for Makefile implicit rules, such as '-o$@ $<'.

#### OBJECTS

This varialble is generated from `SOURCES` by the StdInit() function. The extension of each source file has been replaced by .o (Unix) or .obj (Win32).

Example:

      SOURCES = a.x b.y

Then `OBJECTS` become "a.o b.o" on Unix and "a.obj b.obj" on Win32.

#### OBJECTS_DIR

Specifies where to put object files. By default they are stored in the directory where the source files are.

Example:

      OBJECTS_DIR = tmp

You must create this directory before running make.

See also: MOC_DIR.

#### OBJMOC

This variable is generated by the StdInit() function if `$moc_aware` is true. `OBJMOC` contains the name of all intermediate moc object files.

Example:

      HEADERS = demo.h
      SOURCES = demo.cpp main.cpp

If `demo.h` and `main.cpp` define classes that use signals and slots (i.e. the `Q_OBJECT` "keyword" is found in these two files), `OBJMOC` becomes:

      OBJMOC  = moc_demo.obj

See also: SRCMOC.

#### OUTBASE

Defaults to 'Makefile' for all output types except unix-kdev and msvstudio, where it defaults to the project name. If the OUTFILE variable is specified, OUTBASE is the base of the filename (excluding the .* extension, if given).

See also: OUTFILE.

#### OUTEXT

This variable is empty by default for all output types except unix-kdev (.kdev) and msvstudio (.dsw if subdir template, .dsp otherwise). If the OUTFILE variable is specified, OUTEXT is the extension of the filename (excluding the filename base), otherwise it derives its value from the outtype template's TMAKE_OUTEXT value.

See also: OUTFILE, TMAKE_OUTEXT.

#### OUTFILE

Specifies the output filename, built from OUTBASE.OUTEXT. It can be over-ridden by the -o command line option.

#### PROJECT

This is the name of the project. It defaults to the name of the project file, excluding the .pro extension.

#### RC_FILE

Win32/app.t only: Specifies a .rc file. Cannot be used with the RES_FILE variable.

#### RES_FILE

Win32/app.t only: Specifies a .res file. You can either specify a .rc file or one or more .res files.

#### SOURCES

Defines the source files of the project.

#### SRCMOC

This variable is generated by the StdInit() function if `CONFIG` contains "qt". `SRCMOC` contains the name of all intermediate moc files.

Example:

      HEADERS = demo.h
      SOURCES = demo.cpp main.cpp

If `demo.h` and `main.cpp` define classes that use signals and slots (i.e. the `Q_OBJECT` "keyword" is found in these two files), `SRCMOC` becomes:

      SRCMOC  = moc_demo.cpp main.moc

See also: OBJMOC.

#### TARGET

Sets the makefile target, i.e. what program to build.

#### TARGET_EXT

Specifies the extension to use for a target. If present, will over-ride the TEMPLATE default such as .so or .dll for a 'Config += dll' lib.

#### TARGET_PREFIX

Specifies the prefix to use for a target. If present, will over-ride the TEMPLATE default such as "lib" for a 'Config += dll' lib on a Unix platform.

#### TEMPLATE

Sets the default template. This can be overridden by the tmake -t option.

#### TMAKE_CC

Contains the name of the compiler.

#### TMAKE_CFLAGS

Contains the default compiler flags.

#### TMAKE_FILEVARS

Tells tmake which variables contain file names. This is because tmake on Windows replace the directory separator / with \.

#### TMAKE_LIB_CMD

Specifies the Makefile command to use to link a static library for a platform.

#### TMAKE_LINK_CMD

Specifies the Makefile command to use to link all binaries for a platform except for static libraries (see TMAKE_LIB_CMD).

#### TMAKE_MAKE_HEADER

Some text to go into the header of the makefile. For an example, look at lib/win32-watcom.

#### TMAKE_OUTEXT

Variable for templates to specify the default OUTEXT for an output-type. When present, causes the OUTBASE to switch from 'Makefile' to the project name. See OUTEXT and OUTBASE.

#### TMAKE_REMOVE

Specifies the remove command to use for a platform's makefile. On unix this defaults to '-rm -f', in win32 defaults to '-del'.

#### OUTTYPE

Specifies the output type such as make, nmake, msvstudio or kdevelop.

#### VERSION

Specifies the version of the binary being built. On unix platforms that support versioned sonames, this is also used to build the soname extensions for shared libraries.

## Function Reference

This section contains a brief description of some important tmake functions used by the templates.

### AddIncludePath(path)

Adds path to the include path variable, INCLUDEPATH. The include path is used for two purposes:

1. Searching files when generating include dependencies.
2. Setting -I options for the C/C++ compiler.

Example:

      #$ AddIncludePath('$QTDIR/include;/local/include');

### BuildMocObj(objects,sources)

Creates build rules for moc source files. Generates include dependencies.

Example:

      #$ BuildMocObj($project{"OBJMOC"},$project{"SRCMOC"});

Output:

      moc_hello.o: moc_hello.cpp \
    		hello.h \
    		...

### BuildMocSrc(files)

Creates moc source files from C++ files containing classes that define signals and slots. For a header file `x.h`, the generated moc file is called `moc_x.h`. For a source file `y.cpp`, the generates moc file is called `y.moc` and should be #include'd by `y.cpp`.

Example:

      #$ BuildMocSrc($project{"HEADERS"});
      #$ BuildMocSrc($project{"SOURCES"});

Output:

      moc_hello.cpp: hello.h
    	$(MOC) hello.h -o moc_hello.cpp

### BuildObj(objects,sources)

Creates build rules for source files. Generates include dependencies.

Example:

      #$ BuildObj($project{"OBJECTS"},$project{"SOURCES"});

Output:

      hello.o: hello.cpp \
    		hello.h \
    		...

      main.o: main.cpp \
    		hello.h \
    		...

### ComputeConfigDependencies()

Based on the config parameters specified,

1) Ensure they make sense,

2) Update TMAKE_xxx flags to include values from tmake.conf.

This function should be used by all templates as a uniform way to compute and inherit all TMAKE_variable parameters from Config parameters. It should be placed before the StdInit() function.

### ComputeUnixTargetVersions()

This function provides a uniform way for calculating the TARGET variable with possible version extensions for unix. It should be placed after the StdInit() function, and used in all Unix based templates.

### ComputeWin32TargetVersions()

Like ComputeUnixTargetVersions(), except for win32. It should be placed after the StdInit() function, and used in all win32 based templates.

### Config(string)

Returns true if the `CONFIG` variable contains the given string.

Example:

      #$ if ( Config("release") { }

### DisableOutput()

Call this function to force tmake to generate no output until EnableOutput() is called.

Example:

      #$ Config("debug") && DisableOutput();
          Anything here is skipped if CONFIG contains "debug".
      #$ Config("debug") && EnableOutput();

### EnableOutput()

Enables tmake output after DisableOutput() was called.

### Expand(var)

Expands a project variable. Equivalent to `$text = $project{$var}`.

Example:

      VERSION = #$ Expand("VERSION");

Output:

      VERSION = 1.1

### ExpandGlue(var,prepend,glue,append)

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 variable is empty or not defined.

Example:

      clear:
              #$ ExpandGlue("OBJECTS","-del","\n\t-del ","");

Output (Windows NT):

      clear:
              -del hello.obj
              -del main.obj

### ExpandList(var)

This function is suitable for expanding lists of files. Equivalent with `ExpandGlue($var,""," \\\n\t\t","")`.

Example:

      OBJECTS = #$ ExpandList("OBJECTS");

Output:

      OBJECTS = hello.o \
    	    main.o

### ExpandPath(var,prepend,glue,append)

Similar to ExpandGlue, except that it splits the items on a semicolon instead of space (if the variable contains at least one semicolon).

### IncludeTemplate(file)

Includes a template file. The ".t" extension is optional.

Example:

      #$ IncludeTemplate("mytemplate");

### Now()

Sets $text to the current date and time.

Example:

      # Generated at #$ Now()

Output:

      # Generated at 12:58, 1996/11/19

### Project(strings)

This is a powerful function for setting and reading project variables. Returns the resulting project variables (joined with space between).

Examples:

    # Get a project variable:
        $s = Project("TEMPLATE");	    -> $s = "TEMPLATE"

    # Set a project variable:
        Project("TEMPLATE = lib");	    -> TEMPLATE = lib
        Project("CONFIG =";)	    -> CONFIG empty

    # Append to a project variable:
        Project("CONFIG = qt");	    -> CONFIG = qt
        Project("CONFIG += debug");	    -> CONFIG = qt debug

    # Append to a project variable if it does not contain the value already:
        Project("CONFIG = qt release"); -> CONFIG = qt release
        Project("CONFIG *= qt");	    -> CONFIG = qt release
        Project("CONFIG *= opengl");    -> CONFIG = qt release opengl

    # Subtract from a project variable:
        Project("THINGS = abc xyz");    -> THINGS = abc xyz
        Project("THINGS -= abc");	    -> THINGS = xyz

    # Search/replace on a project variable:
        Project("CONFIG = tq opengl");  -> CONFIG = tq opengl
        Project("CONFIG /= s/tq/qt/");  -> CONFIG = qt opengl

    # The operations can be performed on several project variables at a time.

        Project("TEMPLATE = app", "CONFIG *= opengl", "THINGS += klm");

### ScanProject(file)

Scans a project file and stores the project variables and values in the global associative `%project` array.

### StdInit()

Standard initialization of tmake. StdInit() should be called from one of the first lines in the template.

This function creates some new project variables:

- `OBJECTS` - Object files corresponding to `SOURCES`.
- `SRCMOC` - moc source files.
- `OBJMOC` - moc object files.

The moc-related variables are created only if `CONFIG` contains "qt"

### Substitute(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.

Important: Use single quotes around the string, otherwise perl will expand any $vars it finds.

Example:

        Substitute('Project name: $$PROJECT, uses template $$TEMPLATE');