Build system documentation

1. Building

To build this software, from the source directory, just type make.

The following variables are understood by the make to specify build variants:

	BUILD_ARCH	the processor architecture of the target, e.g.,
			i386, x86_64, mips, etc.
	BUILD_OS	the OS target, e.g., linux, menlofw, etc.
	BUILD_OPT	the build variant, e.g., debug, prod, etc.

To limit your build to a certain architecture, the above three variables can be set on the make command line or in the environment.

A make may be performed in any directory in the source tree that has a Makefile.

2. Writing Makefiles:

2.1 Programs

A program Makefile example would be:

	SRC = ../..			# path to the root of the source tree
	PROGRAM = hello			# resulting program to make
	SOURCES = hello.c		# source files for the program

	include $(SRC)/make/Makefile.inc	# include the master makefile

2.2 Libraries

A library Makefile would contain:

	SRC = ../..			# path to the root of the source tree
	LIBRARY = hello.a hello.so	# resulting libraries to make
	SOURCES = hello.c		# source files for the program

	include $(SRC)/make/Makefile.inc	# include the master makefile

2.3 Subdirectories

A directory which has subdirectories set the SUBDIRS variable to the list of
subdirectories to be visited by the build, in the order they should be made.

	SUBDIRS = a b c
	include $(SRC)/make/Makefile.inc

In general, a directory will usually have a program, a library or
subdirectories, and won't be a mix of these types.
	
2.4 Pre-defined variables

The BUILD_* variables mentioned in section 1 are available inside Makefiles
also.  So, a Makefile may have conditional source lists, such as:

	ifeq "$(BUILD_ARCH)" "mips"
	SOURCES += subr_mips.c
	endif

2.5 Doxygen

To make documentation using Doxygen, just set DOCSRC to the list of
subdirectories that should be included in your documentation set.

Then, at the top of the source tree, a 'make doc doc_index' will build all
documentation sets and a handy index.html page at the top of
$(BUILD_DIR)/doc/html.

The doxygen support is just a start for testing.