Defining a tool suite.	  (out of date)
=========================

The files in this directory defines a tool suite for use within the build
environment. Here a ``tool suite'' is a complete set of tools for compilation
/assembly/linking etc etc. The definition takes the form of a fragment of a 
makefile, subsequently included into a user's makefile. This file 
documents what is expected of a definition.

Throughout this document the word `target' or phrase `make target'
refers to a target defined and associated with a list of commands in a
makefile. The work `platform' and/or phrase `build platform' relates to
the platform on which the code being compiled/assembled/linked or
whatever will run.

0.1 Trivia.
==========

Each suite MUST define the following macros.

$(o)	The extension of an object filename.
$(s)	The extension of an assembler source filename.
$(a)	The extension of a archive (library) filename.


1.0	Defining a C compiler.

At a minimum only the definition of the make variables $(cc) and $(o)
must be provided in order to compile a C file. The rule for compilation
of such a file is as follows...

	%.$(o): %.c $(cc_build_cmd_file)
		$(cc_pre)
	ifdef cc_error_filter
	ifdef cc_redirect_output
		$(cc) $(cc_flags) $(cc_o_switch) $< > cc.out
		$(cc_error_filter) < cc.out
		$(rm) cc.out
	else
		$(cc) $(cflags) $(cc_o_switch) $< | $(cc_error_filer)
	endif
	else
		$(cc) $(cflags) $(cc_o_switch) $<
	endif
		$(cc_post)

If nothing other than $(cc) is defined the above reduces to...

	%.$(o): %.c
		$(cc) $<

If $(cc_build_cmd_file) is defined it names a make TARGET which will
constructs a command file for the compiler. The suite MUST define this
target. The commands associated with it will be executed once prior to
any C compilation. Therefore the command file cannot contain anything
which is dependent on the file being compiled, like output filenames.
Only options common to all C compilations for a particular platform may
be placed into a command file. As build environment invokes make
seperately for each platform for which a module must be compiled, a
seperate command file will be constructed on each occasion so platform
specific flags maybe written to a command file.

If $(cc_build_cmd_file) is defined then $(cc_remove_cmd_file) MUST
also be defined. It is also a make TARGET. The rule for the
compilation of a module is something like...

	<module>: <object-files> $(clean_up)

where the variable clean_up is defined as...

	clean_up = $(cc_remove_cmd_file) $(as_remove_cmd_file) \
			$(ar_remove_cmd_file) $(ld_remove_cmd_file)

Thus the commands of each of the targets in the list clean_up will be
executed after all the rules required to generate <object-files> have
been executed (but before the final commands associated with getting from
<object-files> to <module>).

If $(cc_error_filter) is defined it names a program through which the
output of the compiler feed before being presented to the user. If
$(cc_redirect_output) is also defined then the compiler's output will
be placed into a temporary file prior to being feed to the error file
otherwise the compiler output is piped directly into the error filter.
The use of pipes under DOS doesn't really work right... if any program
in a pipeline exists with an error the error code returned from the
pipeline is that of the last command in the chain. Unless that is the
program which detected the error the failure of the compilation will
not be detected and make will continue on rather than halting.

If necessary the variable $(cc_o_switch) maybe defined to include
whatever is required on the command line to specify the output
filename.  Typical this will make use of the automatic variable $@ to
reference the full name of the target file, something like...

	cc_o_switch = -o $@


1.1	Setting include paths, passing in defines and the like.

The variable $(include_path) contains a space seperated list of all
the directories in which the compiler should look for included files.
The definition of this variable includes a reference to
$(compiler_include) which maybe set by compiler definition to add
include directories specific to the compiler.

There are a number of mechanisms for passing additional information to
the compiler from rest of build environment.

	$(USER_CFLAGS) This maybe defined in the users template PMI file.
		It contains a space seperated list of -D and -I options
		to pass in additional definitions and include directories
		respectively. No other options should be allowed in the
		list as they cannot be made portable.

		Note that the now obsolete variable USER_FLAGS is treated
		in an identical manner by the current backend definition
		files.

	$(<tool-suite>_CFLAGS) where <tool-suite> is the name of the
		tool suite currectly being used maybe set in the users
		template PMI file to pass flags to a particular
		compiler. This may contain any options allowed by the
		compiler.

	$(PLATFORM_CFLAGS) is defined to be $(<platform-name>_CFLAGS)
		where <platform-name> is the current build platform
		name. This is to allow the user to pass build platform
		specific include and preprocessor defines into a
		compilation. See the document on defining a build
		platform for additional information.

	$(eos_platform_name) is defined by the platform specific make
		rules to be the EOS name for the platform.

	$(DEBUG) If this make variable is defined the tool suite
		definitions must arrange to define a preprocessor
		symbol of the same name.

	$(DLVL) Debug level setting. The value of this make variable must
		be used to define the value of a preprocessor symbol of
		the same name, ie, -DDLVL=$(DLVL) must be passed to the
		compiler.

	$(ALVL) Assert level setting. Must be treated like DLVL.

	USE_EOS If this variable is defined then the resulting program is
		to run under EOS. This probably only changes the
		arguments passed to the compiler by default.

Outside a DOS environment all the above would simply be passed on the
command line to each compilation. Unfortunately the command line length
limitation imposed by DOS makes this impossible for all but trivial
cases. A tool suite must take whatever action necessary to pass all the
above information into the compiler. Typically this is done by writing a
command file in the target cc_build_cmd_file or poking something into the
environment then using the command line $(cflags) to point the compiler
at this information. For example the definitions for using the watcom
tools extract all include path information from the above and construct a
semicolon separated list in the variable INCLUDE which is then exported
into the environment (the compiler looks for the environment variable by
default). All other options are then placed into the variable WCFLAGS
which is also exported into the environment and the variable $(cflags)
set to `@WCFLAGS' to instruct the compiler to look at the variable in its
environment.

To further assist the command sequences $(cc_pre) and $(cc_post) are
included in the rules for translating a C file. They may be defined to be
any sequence of commands using GNU-makes `define ... endef' form.


2.0	Defining an assembler.

	%.$(o):		%.$(s) $(as_init_target)
		$(as_pre)
		$(show_environment)
	ifdef as_error_filter
	ifdef as_redirect_output
		$(as) $(aflags) $(as_o_switch) $< > as.out
		$(as_error_filter) < as.out
		$(rm) as.out
	else
		$(as) $(aflags) $(as_o_switch) $< | $(as_error_filer)
	endif
	else
		$(as) $(aflags) $(as_o_switch) $<
	endif
		$(as_post)


3.0	Defining an archiver.

	%.$(a):		$(ar_init_target)
		$(ar_pre)
		$(show_environment)
		$(ar) $(arflags) $(ar_o_switch)
		$(ar_post)