/*************************************************************************/
                                  MAKE.TXT
                               TURBO ASSEMBLER

This file contains details on using MAKE and MAKER with TASM.
--------------------------------------------------------------------
                        TABLE OF CONTENTS
                        - - - - - - - - -
   MAKE basics
      BUILTINS.MAK
      Using TOUCH.EXE
      MAKE options
         Setting options on as defaults
         Compatibility with Microsoft's NMAKE
   Using makefiles
      Symbolic targets
         Rules for symbolic targets
   Explicit and implicit rules
      Explicit rule syntax
         Single targets with multiple rules
      Implicit rule syntax
         Explicit rules with implicit commands
      Commands syntax
         Command prefixes
         Using @
         Using -num and -
         Using &
         Command operators
         Debugging with temporary files
   Using MAKE macros
      Defining macros
      Using a macro
      String substitutions in macros
      Default MAKE macros
      Modifying default macros
   Using MAKE directives
      .autodepend
      !error
         Summing up error-checking controls
      !if and other conditional directives
      !include
      !message
      .path.ext
      .precious
      .suffixes
      !undef
      Using macros in directives
--------------------------------------------------------------------

MAKE.EXE is a command-line project-manager utility that helps you
quickly compile only those files in a project that have changed since
the last compilation. (MAKER is a real-mode version of MAKE.)

This chapter covers the following topics:
  o  MAKE basics
  o  Makefile contents
  o  Using explicit and implicit rules
  o  Using MAKE macros
  o  Using MAKE directives


MAKE basics
===========
MAKE uses rules from a text file (MAKEFILE or MAKEFILE.MAK by default)
to determine which files to build and how to build them. For example,
you can get MAKE to compile an .EXE file if the date-time stamps for
the .CPP files that contain the code for the .EXE are more recent than
the .EXE itself. MAKE is very useful when you build a program from
more than one file because MAKE will recompile only the files that you
modified since the last compile.

Two types of rules (explicit and implicit) tell MAKE what files depend
on each other. MAKE then compares the date-time stamp of the files in
a rule and determines if it should execute a command (the commands
usually tell MAKE which files to recompile or link, but the commands
can be nearly any operating system command).

The general syntax for MAKE is:

	MAKE [options...] [targets[s]]

(To get command-line help for MAKE, type MAKE -? or MAKE -h.)

"Options" are MAKE options that control how MAKE works, and
"targets" are the names of the files in a makefile that you want MAKE to
build. Options are separated from MAKE by a single space. Options and
targets are also separated by spaces.

If you type MAKE at the command prompt, MAKE performs the following
default tasks:

To place MAKE instructions in a file other than MAKEFILE, see
the section titled "MAKE options."

MAKE looks in the current directory for a file called BUILTINS.MAK
(this file contains rules MAKE always follows unless you use the -r option).
If it can't find the file in the current directory, it looks in the
directory where MAKE.EXE is stored. After loading BUILTINS.MAK, MAKE looks
for a file called MAKEFILE or MAKEFILE.MAK. If MAKE can't find any of these
files, it gives you an error message.

When MAKE finds a makefile, it tries to build only the first target
file in the makefile (although the first target can force other
targets to be built). MAKE checks the time and date of the dependent
files for the first target. If the dependent files are more recent
than the target file, MAKE executes the target commands, which update
the target. See the section called "Using makefiles" for more
information on instructions in makefiles.

 1) If a dependent file for the first target appears as a target elsewhere
    in the makefile, MAKE checks its dependencies and builds it before
    building the first target. This chain reaction is called linked
    dependency.

 2) If the MAKE build process fails, MAKE deletes the target file it was
    building. To get MAKE to keep a target when a build fails, see the
    .precious directive.

You can stop MAKE by using <Ctrl><Break> or <Ctrl><C>.


BUILTINS.MAK
------------
BUILTINS.MAK contains standard rules and macros that MAKE uses before
it uses a makefile (you can use the -r option to tell MAKE to ignore
BUILTINS.MAK). Use BUILTINS.MAK for instructions or macros you want
executed each time you use MAKE. Here's the default text of
BUILTINS.MAK:

#
# Borland C++ - (C) Copyright 1993 by Borland International
#

# default is to target 32BIT
# pass -DWIN16 to make to target 16BIT

!if !$d(WIN16)
CC       = bcc32
RC       = brcc32
AS       = tasm32
!else
CC       = bcc
RC       = brcc
AS       = tasm
!endif

.asm.obj:
      $(AS) $(AFLAGS) $&.asm

.c.exe:
      $(CC) $(CFLAGS) $&.c

.c.obj:
      $(CC) $(CFLAGS) /c $&.c

.cpp.exe:
      $(CC) $(CFLAGS) $&.cpp

.cpp.obj:
      $(CC) $(CPPFLAGS) /c $&.cpp

.rc.res:
      $(RC) $(RFLAGS) /r $&

.SUFFIXES: .exe .obj .asm .c .res .rc

!if !$d(BCEXAMPLEDIR)
BCEXAMPLEDIR = $(MAKEDIR)\..\EXAMPLES
!endif


Using TOUCH.EXE
---------------
Sometimes you'll want to force a target file to be recompiled or
rebuilt even though you haven't changed it. One way to do this is to
use the TOUCH utility. TOUCH changes the date and time of one or more
files to the current date and time, making it "newer" than the files
that depend on it.

You can force MAKE to rebuild a target file by touching one of the
files that target depends on. To touch a file (or files), type the
following at the command prompt:

	touch filename [filename...]

TOUCH updates the file's creation date and time.

Before you use TOUCH, make sure your system's internal clock is set
correctly. If it isn't, TOUCH and MAKE won't work properly.


MAKE options
------------
Command-line options control MAKE behavior. Options are
case-sensitive. Type options with either a preceding - or /. For
example, to use a file called PROJECTA.MAK as the makefile, type MAKE
-fPROJECTA.MAK (a space after -f is optional). Many of the
command-line options have equivalent directives that are used in the
makefile. The following table describes MAKE's command-line options.


Option		Description
------		-----------
-h or -?	Displays MAKE options and shows defaults with
		a trailing plus sign.

-B		Builds all targets regardless of file dates.

-D<macro>	Defines <macro> as a single character, causing
		an expression <!ifdef macro> written in the
		makefile to return true.

[-D]<macro>=[string]	Defines <macro> as "string." If "string"
			contains any spaces or tabs, enclose "string"
			in quotation marks. The -D is optional.

-I<directory>	Searches for include files in the current
		directory first, then in <directory>.

-K		Keeps temporary files that MAKE creates (MAKE
		usually deletes them).

-N		Executes MAKE like Microsoft's NMAKE (see the
		section following this table for more
		information).

-U<macro>	Undefines previous definitions of <macro>.

-W		Writes the current specified non-string
		options to MAKE.EXE making them defaults.

-f<filename>	Uses <filename> or <filename>.MAK instead of
		MAKEFILE (space after -f is optional).

-a		Checks dependencies of include files and
		nested include files associated with .OBJ
		files and updates the .OBJ if the .H file
		changed. See also -c.

-c		Caches autodependency information, which can
		improve MAKE's speed. Use with -a; don't use
		if MAKE changes include files (such as using
		TOUCH from a makefile or creating header or
		include files during the MAKE process).

-d<directory>	Used with -S to specify the drive and
		directory MAKE uses when it swaps out of
		memory. The option is ineffective when used
		with the MAKER.

-e		Ignores a macro if its name is the same as an
		environment variable (MAKE uses the
		environment variable instead of the macro).

-i		Ignores the exit status of all programs run
		from MAKE and continues the build process.

-m		Displays the date and time stamp of each file
		as MAKE processes it.

-n		Prints the commands but doesn't actually
		perform them, which is helpful for debugging
		a makefile.

-p		Displays all macro definitions and implicit
		rules before executing the makefile.

-q		Returns 0 if the target is up-to-date and
		nonzero if is is not (for use with batch
		files).

-r		Ignores any rules defined in BUILTINS.MAK.

-s		Suppresses onscreen command display.

-S		Swaps MAKER out of memory while commands are
		executed, reducing memory overhead and
		allowing compilation of large modules. This
		option has no effect on MAKER.

-W		Sets MAKE defaults.


Setting options on as defaults
- - - - - - - - - - - - - - - -
The -W option lets you set some MAKE options on as defaults so that
each time you use MAKE, those options are used. To set MAKE options,
type:

	make  -option[-]  [-option][-]  . . . -W

For example, you could type "MAKE -m -W" to always view file dates and
times. Type "MAKE -m- -W" to turn off the default option. When MAKE asks
you to write changes to MAKE.EXE, type Y.

The -W option doesn't work when the DOS Share program
is running. The message "Fatal: unable to open file MAKE.EXE" is
displayed. The -W option doesn't work with the following MAKE options:
  o  -D<macro>
  o  -D<macro>=<string>
  o  -d<directory>
  o  -U<symbol>
  o  -f<filename>
  o  -? or -h
  o  -I<directory>


Compatibility with Microsoft's NMAKE
- - - - - - - - - - - - - - - - - - -
Use the -N option if you want to use makefiles that were originally
created for Microsoft's NMAKE. The following changes occur when you
use -N:

  MAKE interprets the << operator like the && operator: temporary files
  are used as response files, then deleted. To keep a file, either use
  the -K command-line option or use KEEP in the makefile.

	<<TEMPFILE.TXT!
	text

	!KEEP

  If you don't want to keep a temporary file, type NOKEEP or type
  only the temporary file name. If you use NOKEEP with a temporary
  file, then use the -K option with MAKE, MAKE deletes the temporary file.

  o  The $d macro is treated differently. Use "!ifdef" or "!ifndef" instead.

  o  Macros that return paths won't return the last \. For example, if
     $(<D) normally returns C:\CPP\, the -N option makes it return C:\CPP.

  o  Unless there's a matching .suffixes directive, MAKE searches rules
     from bottom to top of the makefile.

  o  The $* macro always expands to the target name instead of the
     dependent in an implicit rule.


Using makefiles
===============
A makefile is an ASCII file of instructions for MAKE.EXE. MAKE assumes
your makefile is called MAKEFILE or MAKEFILE.MAK unless you use the -f
option.

MAKE either builds targets you specify at the MAKE command line or it
builds only the first target it finds in the makefile (to build more
than one target, see the section "Symbolic targets.") Makefiles can
contain:
  o  Comments
  o  Explicit rules
  o  Implicit rules
  o  Macros
  o  Directives


Symbolic targets
----------------
A symbolic target forces MAKE to build multiple targets in a makefile