3.12 Response Files

Many programs (for example, Microsoft link and lib, Gimpel lint, and omake) can receive their input from a response file. A response file is needed when the length of the build script exceeds the Windows NT command-line limit of 1024 bytes.

omake supports:

• Automatic response files and variables, where it generates a response file or places long command lines into an environment variable.

• Inline response files, where you place response file syntax around your build scripts.

The advantage of automatic responses (both files and variables) is that you don't worry about the command-line limit. When the build script exceeds the limit, a response file or variable is generated and the command is executed, using the response file or variable. You set up automatic responses once, for your linker, librarian, and so on. Thereafter, the build script for those programs can be arbitrarily long.

Inline response files are supported by a variety of other make utility vendors and omake supports the syntax they use.

Automatic Responses

A response class is a generalization that describes how and when to generate a response file or variable. When a response class has been defined, you tell omake which program names accept that class of response. We predefine most popular response classes, so you need only give omake the names of programs that accept these predefined responses.

To tell omake which programs accept response files or use environment variables, use the .RESPONSE.xxx directive, where xxx is a name of a response class. For example, we predefine a LINK response class that describes the response file acceptable by Microsoft Link.

The .RESPONSE.xxx directive is used to define or modify a response class and to add program names to an existing response class:

.RESPONSE.xxx : [ parameter ... ] [ program ... ]

The parameters describe the response class. Each program is either a base name (having neither path nor extension) or a pathname. Normally, you use a base name only, but for special circumstances you can use a pathname. If you use a pathname, you can have different response classes based on the literal name of the shell-line program, the pathname to the shell-line program, or the base name of the shell-line program.

Adding Program Names

To add program names to an existing response class, list them to the right of the directive. For example, adding LINK-style automatic response file support for SLR Systems optlink and Borland tlink is done as follows:

.RESPONSE.LINK : optlink tlink

The response classes are searched for program names in order from most recently defined to first defined, so your use of a program name overrides any predefined usage.

Response Class Parameters

Table 18 shows the parameters, the meaning of each parameter and its default value, and whether the parameter is used in response files and/or response variables.

Defining or Modifying a Response Class

To define a new response class or to modify an existing response class, use a .RESPONSE.XXX directive with only parameters. One of pre, suf, or env is required when defining or modifying a response type.

If env is defined, the response uses an environment variable, otherwise a file is used.

Disabling a Response Class

A directive with neither parameters nor program names removes support for this response class. For example, you can turn off all LINK response files with this directive:

.RESPONSE.LINK :

Response File Example #1

This directive defines response file support for Microsoft link:

.RESPONSE.LINK : pre=@ suf=.rsp sep=, con=+ link

This declares the LINK response class has a prefix of @, a suffix of .rsp, logical lines on the command line are separated with commas, and physical lines in the response file are connected into one logical line with +<ENTER>. This directive also declares that the program named link accepts LINK-style response files. With this definition, the build script

link module1.obj module2.obj ... moduleN.obj, test.exe;

is executed as

link @tempfile.rsp

The prefix @ tells link that what follows is the name of a response file. tempfile is a unique name of the form tempdir\MAKEnum, where num is a 5-digit number, and the response file suffix .rsp appears as the extension of the name. The response file contents:

module1.obj module2.obj ... +
... +
... moduleN.obj
test.exe;

The first logical line module1.obj ... moduleN.obj is broken up in to several physical lines in the response file, each line ending with +<ENTER>. The next logical line test.exe; appears as the next physical line in the response file.

Response File Example #2

This directive adds response variable support for Microsoft CL:

.RESPONSE.CL : env=CL e:\c6\bin\cl.exe

The CL response class uses environment variable CL, and e:\c6\bin\cl.exe accepts this kind of response. Because a pathname is used, the command line

cl /DRELEASE="Release 1.0" /DOS=nt /Ic:\local\include ...

becomes the command line

cl

with environment variable CL having the value /DRELEASE="Release 1.0" /DOS=nt /Ic:\local\include ..., but only if cl is found on the PATH as e:\c6\bin\cl.exe!

Using Automatic Responses

Write the build script as if the length of the command line were unlimited. When the build script gets too long, the automatic response is generated, a modified build script is executed, and the automatic response is removed.

Generation of Automatic Responses

To generate an automatic response, omake determines whether the program name given on the build script matches a .RESPONSE.xxx program name (the response names). To see whether there is a match, omake does the following:

• If any response names have path components, it first compares the literal shell-line program name with all response names. If there are no matches, it looks on disk for the pathname that corresponds to the shell-line program name and compares the pathname to all response names.

• If no match has been found yet, it compares the base name of the program and with the response names.

The first match found determines the response class.

When the response class specifies a response file, the response file is generated if the build script is longer than the in=num parameter.

When the response class specifies an environment variable and the build script is longer than the in=num parameter, omake places the contents of the build script in the response environment variable, appending to the value of the environment variable if it exists.

Deletion of Automatic Responses

Automatic response files are deleted after the build script that generated the response file is executed, unless the -#8 command-line option was used. Each automatic response variable is restored to its previous value after the build script that generated it executes.

Built-In Automatic Responses

omake has built-in automatic response file support for Gimpel lint and Microsoft cl, lib & link.

Built-in Responses for Windows NT

.RESPONSE.STD: pre=@ suf=.rsp omake link link32 lib lib32 cl cl386

.RESPONSE.LINT : suf=.lnt lint

Inline Response Files

In addition to automatic response files, omake also supports response files coded inline in the makefile. Here is the syntax for an inline response file:

target :
command [ prolog ] << [ response_file ]
[ line copied to response file verbatim ]
.
.
.
<< [ epilog ]

The first << introduces the response file; the last << terminates it. response_file names the file. If the name is omitted, omake generates a unique name of the form tempdir\MAKEnum.rsp, where num is a unique number. Everything between the pair of << is placed in the response file and the command is invoked as

command prolog response_file epilog

The prolog and epilog are optional text. Usually, prolog is used to indicate that the following argument is a response file, and @ is the most common prolog.

The epilog can be used for redirection or other text. There are three special words that can appear in the epilog:

• KEEP specifies that the response file is not to be deleted

• NOKEEP pecifies that it is be deleted.

• ECHO specifies that the contents of the response file be displayed. omake also shows the contents of the response file when the -n command-line option is used.

Other build scripts can appear both before and after the inline response.

Deletion of Inline Response Files

Inline response files are deleted unless the -#8 command-line option is used, or the KEEP keyword appears in the epilog. Response files named by omake are deleted after the build script is executed. User-named response files are deleted immediately before omake exits.

Inline Response File Example

Here is an example of an inline response file for Microsoft LINK:

program.exe : $(OBJS)
link @<< $(MAKE_TMP)\link.rsp
$(OBJS,W+\n)
$(.TARGET)
$(.TARGET,B,>.map)
$(LIBS,W+\n)
$(.TARGET,B,>.def);
<< KEEP ECHO

Here, $(OBJS) and $(LIBS) are assumed to be strings separated by white space. The W macro modifier replaces the white space with +<ENTER>, which is the appropriate line continuation for Microsoft link. If OBJS has the value 1.obj 2.obj, and LIBS has the value 3.lib, these build scripts evaluate to

link @$(MAKE_TMP)\link.rsp

where the contents of the response file are

1.obj+
2.obj
program.exe
program.map
3.lib
program.def;

The KEEP keyword has omake leave behind the response file. Otherwise, omake deletes it after the build script finishes. The ECHO keyword tells omake to display the contents of the response file after the link @$(MAKE_TMP)\link.rsp line is displayed. The default behavior is to display the contents only when doing omake -n.

Compatibility with Other Make Utilities

omake supports PM/CB local input scripts, NMAKE inline files and Borland Make's && redirection operator. See Appendix D, Compatibility and Emulation, for details.