Subversion Repositories DevTools

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)