2.6 Build Scripts

All lines that immediately follow a dependency line and begin with white space are the target's build script. Each build script is a command or list of commands, such as compile or link, that omake executes to update the target. The explicit rule for a target consists of the dependency line plus the build scripts.

Build scripts appear in the following form:

target [ target ... ] [ attribute ... ] : [ dependency ... ]
build script
.
.
.

For example, the following makefile specifies that making project.exe requires running the program link to link main.obj and io.obj. This build script is run only if omake determines that project.exe needs to be rebuilt.

project.exe : main.obj io.obj
link /out:project.exe main.obj io.obj

A build script can appear on the dependency line by separating it from the last dependency by a semicolon. For example, the following lines are equivalent:

test.exe : test.c ; cl /c test.c

test.exe : test.c
cl /c test.c

A target can have a build script with multiple lines, listed one after the other. For example:

project.exe : main.obj io.obj
echo Linking project.exe
link /out:project.exe main.obj io.obj >link.out

The first line shows that Windows NT command processor commands can be executed by omake. The second line shows redirection of output, where the output of the link program is redirected to the link.out file.

Build Script Execution

omake executes build scripts in one of two ways:

• Direct execution of the shell-line command as an .exe file.

• By passing the build script to a shell program such as cmd.exe. This method is slower and takes additional memory, but is necessary if the build script requires a feature that only the shell program can provide.

Each build script runs in its own child process or subshell of omake, starting in the current directory. This behavior has special consequences for commands that are supposed to have effect between build scripts. For example, the build scripts

copy_to_tmp :
# Comment and blank lines are allowed
chdir some_directory
copy *.* c:\temp

copy the files that match *.* in the current directory to c:\temp. This occurs because the copy command starts in the current directory, irrespective of the chdir command executed before it. See Using Multiple-Command Build-Script Lines for the correct way to do this.

Auto-Detection Mode

By default, omake detects when to use the shell program (defined by the .SHELL directive; see Table 15 here) and when to use direct execution. The shell program is used when the command is or does one of the following:

• A Windows internal command

break, call, cd, chdir, cls, copy, ctty, date, del, delete, dir, echo, erase, for, if, md, mkdir, path, pause, prompt, rd, rem, ren, rename, rmdir, set, time, type, ver, verify, vol

To change the list of internal commands, use the SHELLCOMMANDS macro. See Table 5 here.

• A batch file (a file with a .bat or $(SHELLSUFFIX) extension

• A multiple-command shell line

• Uses redirection of input or output

Standard Execution Mode

The standard execution mode is to use the shell program for every build script. For Windows NT, the default shell program is named in the COMSPEC environment variable. If this EV is not defined, cmd.exe is used.

omake can execute the build script without using the shell program if the command being run is executable and the build script does not use I/O redirection. Use the colon (:) build-script prefix to have omake execute the build-script line without using the shell program (see Select the Shell Program).

Build-Script Line Exit Status

After it executes each build-script line, omake checks the command exit status. The exit status is a number the program returns and is tested by omake. At the Windows NT command line, you can check the exit status of the last executed program by using the if errorlevel command.

By convention, programs return a zero exit status when they finish without error and a nonzero status when an error occurs. The first build-script line that returns a nonzero exit status causes omake to display this message:

omake: shell line exit status exit_status. Stop.

This usually means that the program being executed failed. Immediately after displaying this message omake does any necessary deinitialization and exits. You can control this behavior with the -i or -k command-line options (see Command-Line Options), with build-script line prefixes (see Build-Script Line Prefixes), or with target attributes (see Target Attributes).

Some programs return a nonzero line exit status inappropriately; you can have omake ignore the exit status by using a build-script prefix. Prefixes are characters that appear before the program name and modify the way omake handles the command script. For example:

project.exe : main.obj io.obj
- link /out main.obj io.obj

The dash (-) prefix causes omake to ignore the exit status of that build-script line. If the exit status is nonzero, omake displays the following message:

omake: Shell line exit status exit_status (ignored)

See Build-Script Line Prefixes for more information.