Managing Code with smake

This chapter discusses:

• Overview of smake and how it works.
• Components of makefiles.
• Command line syntax and command options.
• Rules for how smake chooses dependency files.
• Using operating system commands in makefiles.
• Using macros in makefiles.
• Inference rules.
• Preprocessing directives.
• Using the MAKEDEP utility
• Using the TOUCH utility
• Using tools.ini
• Using response files
• Error messages

What is smake?

smake is particularly useful for programs that have many source files, since it recompiles only those source files that have changed. It does this by looking at the date and time stamp of each relevant file before performing any tasks.

Note: When using smake, always be sure your PC displays the correct date and time. Be especially careful when logging on to networks that change the time on the local machine, in case the network time is incorrect.

smake differs from a batch file in that it performs only the commands required to rebuild your program, while a batch file executes all tasks, whether or not they are necessary.

Writing Makefiles

The makefile contains one or more dependence lines, each followed by one or more command lines. Each dependence line specifies a target (upon which the associated command lines act), followed by a colon and a (possibly empty) list of dependent files (files needed to create the target). For example, this dependence line:

	app.exe : app.obj app.re app.def 

Command lines tell smake how to create the target. Command lines must begin with a tab or space character. For example:

	app.exe : app.obj app.res app.def
		link app,,NULL,lib,app 
		rcc app.res app.exe 

A makefile can also contain comments, macros, preprocessing directives, operating system commands, and inference rules.

Example of a simple makefile

	hello.exe: hello.obj     # Dependence line 1
		link hello.obj   # Command line 1 

	hello.obj: hello.cpp     # Dependence line 2
		dmc -c hello.cpp  # Command line 2 

The first dependence line indicates that hello.exe depends on hello.obj. The first command line specifies how to make hello.exe by executing link hello.obj.

The second dependence line indicates that hello.obj depends on hello.cpp. The second command line specifies how to make hello.obj by executing dmc -c hello.cpp.

Suppose you just finished editing hello.cpp and typed smake to create a new version of your program. smake reads the dependence lines from the makefile. It determines that hello.cpp is newer than hello.obj, so it re-creates hello.obj by executing dmc -c hello.cpp. Then it determines that hello.obj is now newer than hello.exe. It re-creates hello.exe by executing link hello.obj.

Makefile syntax

	target-file : dependent-file1 dependent-file2 ...
		command 1 
		command 2
		... 

Target files are typically executable files or libraries, but they can also be labels for sets of commands (like all:); these are often called pseudo-targets. Similarly, a dependent file is usually a C or C++ source file, but can be a pseudo-target. For more information see "Specifying targets" below.

Note: smake reads all the dependence lines in a makefile before executing any of the associated commands. It then compares the date and time of the dependents to the target and executes the commands for any target that is out of date. It also checks to see if that target has other dependents that might be more recent.

Dependence line syntax

Specifying targets

To build a complicated target that requires more than one set of dependence lines and commands, use double colons (::) to separate it from the dependents in each case. For example:

	app.exe :: app.obj app.def
		link app,,NULL,lib,app 

	app.exe :: app.res
		rc app.res app.exe 

	target.exe : file_1.obj
	target.exe : file_2.obj 
	# is interpreted as
	# target.exe : file_1.obj file_2.obj 

If a target is not specified on the smake command line, smake uses the first target it encounters in the makefile. smake always interprets a label used as a target name as being out of date; this is useful to avoid having to pass several targets on the command line. For example:

	all: app.exe app2.exe app3.exe 

Specifying dependent files

A search path can precede a dependent file; enclose the path in curly braces ({}) and separate the directories with semicolons (;). smake will search the specified directories in order for the dependent. (The search path applies only to the dependent it proceeds.) For example:

	app.exe : app.obj app.res \
		{c:\project; c:\default} app.def 

Special characters in makefiles

Note: A ^ at the end of a line includes the carriage return/line feed sequence in a macro or string.

Table 13-1 Special characters in makefiles

:

Separates target from rest of dependence line.

#

All characters following a # on a line are interpreted as a comment and ignored.

()

Encloses the value string of a macro to be expanded.

$

Precedes an instance of a macro to be expanded.

^

The next character is interpreted as a literal character.

\

Continues a line on the next line.

{}

On a dependence line, encloses a path name associated with a dependant.

!

As the first character on a line, recognized as the start of a preprocessing directive. On a dependence line, acts as a command modifier.

@

On a dependence line, acts as a command modifier.

-

On a dependence line, acts as a command modifier.

Using % and $ in commands

Note: smake interprets the $ and @ symbols as special characters, do not use these symbols in file or directory names that will be processed by smake.

Comments in makefiles

Running smake

	Target is up to date 

	smake > log

smake command line syntax

	smake {options} {macros} {targets}

options

Zero or more command line options used to control the current smake session. If no options are specified, smake uses the options specified in the tools. ini file. If a required option is not specified, smake uses the default value for that option specified in tools.ini.

macros

One or more macros of the form macro=text. A macro defined on the command line overrides any corresponding macro definition in the makefile.

targets

The targets to build.

Command line options

/A

Rebuilds all targets, including targets that are not out of date with respect to their dependents. Unrelated targets will not be rebuilt. See also /B, below.

/B

Rebuilds a target if its date and time are identical to the date and time of the dependent. Because most operating systems assign file date and time stamps to a resolution of two seconds, commands that execute very quickly might not result in a different date and time between a target and its dependent. Therefore, smake might conclude that a target is current when it is not. Though this option can result in unnecessary build steps, it is recommended for use on very fast systems. See also /A, above.

/C

Suppresses the default smake output, which includes any nonfatal error messages, warning messages, date and time information, as well as the smake copyright message. If both the /C and the /K options are specified, /C suppresses the warnings issued by the /K option. See also /K.

/D

Displays extra information during the smake session. smake displays the date and time of each target and its dependent when they are evaluated during the build, and outputs a message when a target does not yet exist. The names of the dependents for a target precede the target itself, and are indented. The /D, /N, and /P options are useful for debugging makefiles. See also /N, /P.

/E

Causes the settings for environment variables to override the macro definitions within the makefile.

/F filename

Specifies filename as the name of the makefile to be used. White space consisting of zero or more spaces or tabs can precede the filename. Using a dash (-) instead of a filename causes smake to get the makefile input from the standard input device. Keyboard input is then ended by typing either F6 or Ctrl-Z. smake can accept more than one makefile; use a separate /F specifier for each makefile. If /F is omitted, smake obtains its input from the file MAKEFILE.

/HELP

/?

Displays a brief summary of the smake command line syntax.

/I

Ignores exit codes from all commands processed by smake. To ignore errors for unrelated parts of the build, use the /K option; /I overrides /K if both are specified. See also .IGNORE, /K.

/K

Continues building unrelated parts of the dependencies, even if a command terminates with an error. smake normally stops processing if any command returns a non-zero exit code. /K allows smake to continue processing any unrelated targets (those which do not depend on the results of the current command). If an error is encountered, smake returns an error code of 1, unlike the /I option which ignores all exit codes. /I overrides /K if both options are specified. Also, /C suppresses the warnings issued by /K. See also /C, /I.

/N

Displays but does not execute the commands that smake would have executed. However, any preprocessing commands (. directive, !directive) are executed. Use /N to determine which targets are out of date. The /N, /D, and /P options are useful in debugging makefiles. Note that /N does not automatically recurse to subsequent calls to smake. See also /D, /P.

/NOLOGO

Suppresses the smake copyright message.

/P

Displays smake information to the standard output device before processing begins. This includes all macro definitions, inference rules, and target descriptions, as well as the .SUFFIXES list. Specifying /P without a makefile or command line target causes smake to display its information without issuing an error. The /P, /D and /N options are useful for debugging makefiles. See also /D, /N.

/Q

Checks the dates and times of targets that smake would haveupdated, but does not update any files; only the preprocessing commands (.directive, !directive) are executed. A non-zero exit code is returned if any target is not up to date. Note that /Q does not automatically recurse to subsequent calls to smake.

/R

Clears the .SUFFIXES list and ignores the default tools.ini settings.

/S

Suppresses the display of all commands executed by smake. See also .SILENT, @.

/T

Changes the dates and times of the command line targets to the current date and time and executes the preprocessing commands, but does not process the normal target commands. If a command line target is not passed, smake changes the date and time of the first target in the makefile. The contents of the target files are not changed, only the date and time stamp is updated.

/X filename

Sends all smake error output to filename. This can be either a file or a device. White space consisting of zero or more spaces or tabs can precede filename. Using a dash (-) instead of a filename causes smake to send the error messages to the standard output device. smake normally sends any error messages to the standard error device. This option only affects the smake output, and not the output of any command executed by smake.

@command

A command file can be used to pass command line options to smake. smake first attempts to interpret command as an environment variable. If it does not exist, smake attempts to open a linker response file with that name.
The command file name must be preceded by the @ character, with no white space separating the @ character from the file name. Use of a command file also permits a command sequence longer than the 128 character limit imposed by DOS. The command file options can be placed on a single line separated by white space, or on multiple lines. If multiple lines are used, carriage return/ line feed sequences are replaced by spaces when the lines are concatenated into a full command. Macro definitions can be continued on multiple lines by putting a backspace (\) character at the end of the lines that are to be continued.

Specifying what targets to build

	all: count.exe write.exe read.exe 

	count.exe: count.c
		dmc count.c 

	write.exe: write.c
		dmc write.c 

	read.exe: read.c
		dmc read.c

To create just some targets, specify them on the command line. For example, this command creates the programs write.exe and read.exe:

	smake write.exe read.exe makefile 

	clean:
		del *.obj 

Choosing Dependency Files

Suppose that hello.cpp includes the file hello.h. The dependence line for hello.obj looks like this:

	hello.obj : hello.cpp hello.h

Dependencies can be automatically generated with MAKEDEP.

Including files

	!include filespec 

Defining Macros

Define a macro by putting a line with the following syntax in the makefile, in tools.ini, or on the smake command line:

	macro=text 

The text can be any sequence of characters, including no characters, or white space (interpreted as a null string). It includes all the text between the equals sign and the end of the line. Note that a macro defined as a null string is not equivalent to an undefined macro; it is still defined in relation to directives like !IFDEF and !IFNDEF.

To specify an instance of a macro that is to be expanded, enclose the macro name in parentheses and put a dollar sign in front of it, like this:

Examples of when to use macros

	FLAGS=-c -g -DDEBUG=1 -ml 

	file1.obj: file1.cpp file2.h
		dmc  file1.cpp 

	file2.obj: file2.cpp
		dmc  file2.cpp 

	MYLIB=c:\dev\lib 

	prog.exe: prog.obj \mylib.lib
		dmc prog.obj \mylib.lib 

Comments in macros

Specifying text to be substituted

	MODEL=L		# defines macro
		# instance to be expanded 
		# expands 'L' to 'S' 

Overriding macros on the command line

	smake MYLIB=c:\dev\test\lib 

	set temp=c:\dos 

	test.obj: test.cpp
		dmc -cod\test.cod test.cpp 

1. Definitions on the command line
2. Definitions in the makefile
3. Definitions in the environment (specified using the SET command)

Recursively defined macros

• Macros specified on the command line
• Macros predefined by environment variables
• One of the macros MAKE, MAKEDIR, or MAKEFLAG

Predefined macros

Macro Description

MAKE

The name of the executable specified on the smake command line. The default is smake.

MAKEDIR

The current directory when smake was called.

MAKEFLAG

The current smake options (you can change these with the !CMDSWITCHES directive).

$?

Lists dependencies that are newer than the target.

$**

Full list of dependents of the current target.

$*

Current target's name and path, without the extension.

$<

The dependent file that is newer than the target. This macro is only valid within commands in inference rules.

$@

The current target's fully qualified path name.

$$@

The current target's fully qualified path name. This macro is valid only for specifying a dependent on a dependence line.

$$

Expands to $.

Modifiers for predefined macros

Table 13-5 Filename modifiers for use with predefined macros

For example, for the file c:\project\app.exe:

	$(@D) refers to c:\project
	$(@F) refers to app.exe 
	$(@B) refers to app 
	$(@R) refers to c:\project\app 

Predefined command and option macros

Table 13-6 Predefined command and option macros

Macros for predefined environment variables

Macro precedence

1. Macros defined on the command line
2. Macros defined in a makefile or include file
3. Macros that correspond to predefined environment variables
4. Macros defined in tools.ini
5. Macros that correspond to commands or command options, like CPP or CPPFLAGS

Using Operating System Commands

A command line must begin with one or more spaces or tabs, and must immediately follow the dependence line. No blank lines can separate them; however, a line containing only white space can be used to specify a null command. Blank lines can appear within a list of commands. Continue commands by ending the line to be continued with a backslash (\). If any characters, including spaces or tabs, follow the backslash, smake interprets them literally. Place single commands at the end of a dependence line by separating the dependency from the command with a semicolon (;).

To let smake know how to execute a command line, precede a command with any of the following modifiers. More than one modifier can be used with a command:

	Table 13-7 Modifiers for smake commands 
	Modifier Description 

	-	Tells smake to ignore the exit status from a command; 
		processing continues no matter what value the command 
		returns. Otherwise, smake stops executing if a command 
		returns an error. 

	-N	Tells smake to halt execution only if the exit status a 
		command returns is greater than the number N (even if 
		.IGNORE or /I are not being used). Otherwise smake 
		halts when a command returns a non-zero exit code. 

	@	Tells smake not to display a command when it is 
		executed, even if /S or .SILENT are not specified. 
		Otherwise, smake displays commands as they are 
		executed. 

	!	Executes a command for each of the dependents in the 
		dependency list. The command must use one of the file 
		name macros $** or $?, or the ! prefix is ignored. $** 
		causes the command to be executed for all of the 
		dependent files. $? causes the command to be executed 
		only for those dependent files which are more recent 
		than the target. 

	*	Allows smake to accept long command lines. Causes all 
		arguments to be assigned to the temporary variable 
		$MAKE$, and all arguments to be replaced with 
		@$MAKE$. 

	<<file	Specified after a command. If file is specified it must 
		appear immediately after the angle brackets (<<), with no 
		white space. If file is not specified, smake uses a unique 
		filename. 

		Tells smake to use inline files when processing a 
		command. The file is created from the literal text 
		beginning on the line immediately following the angle 
		brackets. End the inline file by beginning a line with 
		<<. Optionally, you can write one of the modifiers KEEP 
		or NOKEEP immediately after the closing <<. NOKEEP 
		(the default) tells smake to delete file at the end of the 
		session. KEEP tells smake not to delete file at the end of 
		the session (though file will be overwritten each time it is 
		used). 

	install:
		-rm \bin\prog 

	break cd chdir cls copy 
	ctty date del dir echo 
	erase exit if md mkdir 
	pause rd rem rmdir ren 
	rename time type verify vol 

		del  

Preprocessing Directives

There are two types of preprocessing directives:

• Directives that begin with an exclamation point (!) work like C preprocessing directives. The ! must be the first character the line; it can be followed by white space. ! directives are not case sensitive.
• Directives that begin with a period (.) and end with a colon (:) cannot appear among dependency lines and commands. They must begin the line on which they appear, and are case sensitive.

	Table 13-8 ! preprocessing directives 
	Directive Description 

	!CMDSWITCHES{+/-} opt 
		Turns on or off one or more command line 
		options with the exception of /F, /HELP, 
		/NOLOGO, /X, or /?. In the makefile, only the 
		/D, /I, /N, and /S options are valid, though 
		tools.ini can contain the others. 

	!ELSE	If the preceding !IF, !IFDEF or !IFNDEF 
		evaluated to zero, the statements between the 
		!ELSE and the next !ENDIF are processed. An 
		additional IF, IFDEF or IFNDEF can be 
		combined on the same line. 

	!ELSEIF	Equivalent to the !ELSE IF directives. 

	!ELSEIFDEF Equivalent to the !ELSE IFDEF directives. 

	!ELSEIFNDEF Equivalent to the !ELSE IFNDEF directives. 

	!ENDIF	Marks the end of a block beginning with an !IF, 
		!IFDEF, or !IFNDEF directive. 

	!ERROR text
		Stops the smake session with a fatal error, 
		followed by the text. This directive will stop the 
		session even if other options, directives or 
		command modifiers, such as 
		/K, /I, .IGNORE, or -, are being used. 

	!IF expression
		If the expression evaluates to other than zero, the 
		statements between the !IF and the next !ELSE 
		or !ENDIF are processed. See "Expressions in 
		preprocessing directives" below for information. 

	!IFDEF macro
		If the macro is defined, even with a null value, 
		the statements between the !IFDEF and the next 
		!ELSE or !ENDIF are processed. 

	!IFNDEF macro
		If the macro is not defined, the statements 
		between the !IFDEF and the next !ELSE or 
		!ENDIF are processed. 

	!INCLUDE <filename> 
		Reads and evaluates the filename and continues 
		the smake session. If angle brackets (<>) are 
		used, the directories in the INCLUDE macro is 
		searched to locate the filename. If angle brackets 
		are not used, the current directory or the 
		specified path is searched to locate the filename. 

		For compatibility with NMAKE and Digital Mars 
		MAKE, you can specify this directive without the 
		! prefix. 

	!MESSAGE text
		Writes the text to the standard output and 
		continues the smake session. 

	!UNDEF macro
		Removes the macro from the smake symbol 
		table. 

	Table 13-9 . preprocessing directives 

	Directives Description 

	.IGNORE	Directs smake to ignore exit codes from all the 
		commands it processes from this point to the 
		end of the file. You can also use 
		!CMDSWITCHES+/I. 
		See also /I, -, -number. 

	.LONGCOMMANDLINE: tools 
		Permits longer command lines. tools is a list of 
		one or more executable program names, with no 
		path or extension. Multiple occurrences of 
		.LONGCOMMANDLINE are cumulative. If tools is 
		not specified, the current list is cleared. Any tool 
		on the tools list whose name appears in the 
		makefile has its command line arguments passed 
		in a temporary environment variable. For 
		example: 
		.LONGCOMMANDLINE: dmc link lib 

	.PRECIOUS : targets 
		Tells smake not to delete the target if the 
		command to make it is interrupted. If a 
		command is interrupted with a CTRL+C or 
		CTRL+BREAK, smake deletes the target by 
		default. Making a target .PRECIOUS: will make 
		the target immune to deletion across the entire 
		makefile, not just a portion of it. 

	.SILENT Disables the display of command lines before 
		they are executed. You can also use 
		!CMDSWITCHES/S. 
		See also /S, @. 

	.SUFFIXES : lis
		Provides a list of file name suffixes for smake to 
		use when applying inference rules. The 
		predefined list (as defined in tools.ini) 
		contains: .exe .obj .asm .c .cpp .cxx .res 
		.rc. 

		Additional suffixes can be added by using 
		.SUFFIX; separate each suffix in the list with 
		white space, one or more spaces, or tabs. To 
		clear the suffix list, specify .SUFFIX without any 
		suffixes. 
		See also /P. 

Expressions in preprocessing directives

Group subexpressions by enclosing them in parentheses. Any constant string in an expression must be enclosed in double quotation marks (""), even if it is a macro. Quoted strings can be compared using the equality (==) or inequality (!=) operators.

Numeric values are treated as signed long integers. Numbers are assumed to be decimal values. Octal values must start with 0; hexadecimal values must start with 0x. Constant expressions can use any binary operators (see below); the integer constants can also use the unary operators.

An expression can also consist of the name of an external program, enclosed in square brackets ([]). The program will be executed during the preprocessing phase of makefile processing, and that portion of the expression will be replaced by an integer value equal to the error level returned by the executed program.

Operators

	Table 13-10 Operators used in smake expressions 

	Operator Description 

	DEFINED(macro) 
		Unary operator that evaluates to TRUE if the macro 
		is defined. The expression !IF DEFINED( macro) is 
		equivalent to the expression !IFDEF macro. 

	EXIST(path)
		Unary operator that evaluates to TRUE if the path 
		exists. Some operating systems allow spaces within 
		the path name. If a space is used, the path must be 
		surrounded by double quotation marks ("). 

	+	Addition 
	-	Subtraction 
	*	Multiplication 
	/	Division 
	==	 Equality 
	!=	Inequality 
	>	Greater than 
	>=	Greater than or equal to 
	<	Less than 
	<=	Less than or equal to 
	&	Bitwise AND 
	|	Bitwise OR 
	^	Bitwise XOR 
	&&	Logical AND 
	||	Logical OR 
	<<	Left shift 
	>>	Right shift 
	%	Modulus 

Running programs with preprocessing directives

	!if [c:\mydir\myprog] == 0
	# continue processing 
	!else
	# do something else 
	!endif 

Inference Rules

smake interprets inference rules as templates for creating a target from dependent files, based on the extensions of the files involved. Use predefined inference rules or write your own; they can be specified in the makefile or in tools.ini.

To determine priorities for applying inference rules, smake uses the list associated with the .SUFFIXES directive.

When smake applies inference rules

• A dependence line does not contain any dependents or is not followed by any commands
• A target is specified that does not exist in the makefile (or the makefile does not exist).
• A dependent file does not exist and is not itself a target.

Inference rule syntax

	{dependent_path}.dependent_ext{target_path}target_ext: 
		commands

Use macros for paths and extensions. Use the macros in Table 13-4 to specify the arguments. Do not use white space in an inference rule.

For example, this rule builds an object file from a C++ file:

	.cpp.obj :
		dmc -c $*	# $* contains the name of 
				# the target file without
				# an extension 

	.cpp.obj
		dmc -c $* 

	.obj.exe
		dmc $** 

	test.exe: test.obj util.obj 
	test.obj: test.cpp util.h
	util.obj: util.cpp 

Levels of inference rules

	.c.obj: ;dmc -c $
	.obj.exe: ;dmc $ 
	hello.exe: hello.c # ERROR 

How inference rules work

	.cpp.obj:   $< 

If the target specified has a .exe extension, smake searches for a file with the same base name and an extension that is in the .SUFFIXES list to find which inference rule to use.

If the dependence line is followed by commands but does not list dependents, smake will use the inference rules and the .SUFFIXES list to determine the dependent file and then apply the commands specified in the makefile for the target.

Order of precedence for inference rules

Predefined inference rules

Table 13-11 Predefined inference rules

	[SMAKE]
	# macro redefinitions 
		CCFLAGS=-A -wx -mn
		DEBUGFLAGS=-gh 
	# inference rule
	.c.obj: 
		  $< 

When it searches for tools.ini, smake searches the directory for executable files first, then the current directory, and finally in the directory specified by the INIT environment variable.

Creating Response Files

To write a line to a response file, use the command ECHO and redirect its output with one and two greater-than signs (>>). Write the first line with one greater-than sign so that ECHO creates a new file. Write the rest of the lines with two greater-than signs so that ECHO does not overwrite the file you just created.

For example, this makefile creates the program main.exe from the source files main.cpp and funcs.cpp. It not only creates a linker response file, but also writes the linker's output to cmp.err:

	main.exe: main.obj funcs.obj
		echo main.obj+funcs.obj > linker.rsp 
		echo main.exe,,, >> linker.rsp
		+link @linker.rsp > lnk.err 

	main.obj: main.cpp
		+dmc -c main.cpp > cmp.err 

	funcs.obj: funcs.cpp
		+dmc -c funcs.cpp >> cmp.err 

List of smake Error Messages

access denied

can't create response file filename

can't create temporary file filename

can't execute command

can't nest response file

can't open error file filename

can't open include file filename

can't open makefile filename

can't reopen filename for input

command expression retured with error code number

directory not found

don't know how to make filename

error in macro substitution syntax: identifier

exceeded max nesting level for conditionals

extension ext too long in rule

file not found

illegal operator and/or operand in expression

illegal string expression

invalid option number in parameter number

invalid parameter number

not enough memory for command

out of memory

parameter number requires a filename

special macro expression is undefined in this context

syntax error: expression

text found after !ELSE

too many rules or blocks for target filename

unexpected directive

unknown error

unknown error number executing command

unmatched quotes in command identifier filename