readme.makefile

神龙解压卡Linux下的完整开发包,绝对是超值超值超值

Documentation on how to use inc.Makefile
----------------------------------------

Basic rules:
------------
        1) write one Makefile per directory containing source
        2) select the target_type for this directory (only one type per Makefile)
        3) determine the target name (according to target type, this field may be optionnal)
        4) select the source files to compile
        5) (OPTIONNAL) select the dependencies (logical dep or link dep)
        6) (OPTIONNAL) add some flags in CFLAGS or LDFLAGS
	7) (OPTIONNAL) modify some inc.Makefile variables
        7) include inc.Makfile 
        8) (OPTIONNAL) add your own special target (install) 

so below is a typical makefile:
TARGET := EXECUTABLE
MAIN_SRC := testapp.c
SRC := internlib.c

STATIC_LINKS_WITH := ../externlib/src/externlib.o

include ../scripts/inc.Makefile

which produces an executable "testapp" from the local source code
testapp.c and internlib.c linked statically with
../externlib/src/externlib.o


TARGET_TYPE descriptions:
-------------------------
Use the variable TARGET_TYPE to select the type of output you want the
makefile to produce. Below is a full list of them.

TARGET_TYPE := OBJFILE
SRC := foo.c

is used to compile only one file. There is no link in this processus.
STATIC_LINKS_WITH and LINKS_WITH are therefore forbidden. The output
will have the name foo.o

TARGET_TYPE := OBJECT_LIBRARY
TARGET := libfoobar.o
SRC := foo.c bar.c

is used to produce a non shared library. Another piece of code can
only links statically with an OBJECT_LIBRARY. The output name will be
libfoobar.o and is produced by linking together foo.o and bar.o.

TARGET_TYPE := LIBRARY
TARGET := libfoobar.so
SRC := foo.c bar.c

is used to produce a library. This library can be an object library or
a shared library according to the environnement variable
COMPILKIND=static or not respectively.

TARGET_TYPE := EXECUTABLE
MAIN_SRC := testfoobar.c
SRC := intern.c

is used to produce an executable named testfoobar which is the result
of the link of testfoobar.o and intern.o.

TARGET_TYPE := MICROCODE
TARGET := foobar.bin
SRC := foo.spam bar.spasm

is used to produce a microcode binary file foobar.bin and the header
file containing exported microcode symbols foobar_labels.h.
No STATIC_LINKS_WITH or LINKS_WITH can be set.
the variable SPASM and SPBIN must be set correctly before (for example by 
running:
        source /path/to/scripts/mambo_sdk.env
)

Usually only one target is produced by a Makfile, an exception is for EXECUTABLE 
where a target is produced for each element in MAIN_SRC.

How to links together multiple libraries:
-----------------------------------------
In all the cases above except when marked otherwise the target can be
the result of a linking to other libraries. Here is the different
linking possibilities:

STATIC_LINKS_WITH: contains the list of object library or object file
to link statically with the local source code to produce the
target. Before doing the link the different libraries are check to be
uptodate, if not they are rebuilt.

EXTERNAL_STATIC_LINKS_WITH: is like STATIC_LINKS_WITH excepts that
make do not try to rebuild them.

LINKS_WITH: contains the list of files to link with. The link type
depends on the environnment variable COMPILKIND and can be static,
implicit or explicit according to COMPILKIND=static, implicit or
explicit respectively. The default linking type is explicit.

Note about implicit and explicit linking:
     implicit linking means that the shared library is loaded as soon
as the application is launched by the OS. The application can contain
unresolved symbols which are defined in the shared libraries. At the
end if symbols are still undefined the application abort. This kind of
linking is the default one when linking against the libc.

     explicit linking means that the shared library will be loaded
manually by the application when needed. The application does not
contain any unresolved symbol and the absence of the shared libraries
do not abort program execution.

DEPENDS_ON: contains a list of files to build before the local source
code. No linking step is done.

Note on the different Makefile targets:
---------------------------------------
Multiple Makefile targets are predifined in inc.Makefile. Here is the list:

all: builds the target and all its prerequisites.
local: builds the target without updating its dependencies.
clean: removes all local intermediate files.
cleanall: removes local and dependencies intermediate files.
localdist: copies the local needed files to build the target.
dist: copies the whole source tree needed to produce the target.
reduce_dist: after building the target dist, the dist directory may be 
populated wirh unsued directory hierarchy, reduce_dist will remove them. 
(WARNING: the dist path cannot contain twice the same directory) 
api: copies all the .h files to compile the local source code.
copy_shared: copies all the shared libraries in one sinle directory
prebuild: execute only the prebuild commands as set in PREBUILD variable
postbuild: execute only the postbuild commands as set in POSTBUILD variable

COMPILKIND envrironnement variable:
-----------------------------------
The COMPILKIND environnement variable allows to change some compilation attributes.
Here is a full description of them:

COMPILKIND = debug (default), defines _DEBUG macro, removes optimization and lets 
debug symbols in binary.

COMPILKIND = release, optimizes the code and remove debug symbols

COMPILKIND = user (default) sets compilation flags for compilation of a user library.

COMPILKIND = kernel sets compilation flags for compilation of a kernel module.

COMPILKIND = withthreads defines the macro WITH_THREADS and links with pthread library.

COMPILKIND = withdl enables support for explicit dynamic loader.

COMPILKIND = static makes all libraries object library and all link type static.

COMPILKIND = implicit makes shared libraries to be linked implicitely

COMPILDIND = explicit (default) makes shared libraries to not be linked with the application. 
The application is in charge of loading them at run time.

COMPILKIND = leakchecker sets the compilation to use the leak checker. (leackchecker cvs module must
be checkouted and compiled first)

Cross compilation, different compiler, different Makefile names:
----------------------------------------------------------------
inc.Makefile has support for cross compilation and also support for multiple compilers.
Each makefile can specify the c compiler and c++ compiler used to compile the files locally. 
This is done via the variables:
CCOMPILER and CXXCOMPILER, by default they are set as follows:
CCOMPILER := gcc and CXXCOMPILER := g++

The compiler used to produce binary file is in fact CC and CXX, and are the concatenation of the 
variable CROSS and CCOMPILER and CXXCOMPILER respectively. For example to compile with 
arm-elf-gcc you need to set CROSS (via environnement variable to make it availabe for all makefiles, 
or locally in one Makefile if needed) to arm-elf- (don't forget the last -)

The linker to produce an executable or a shared library can also be specified, this is done via 
the LINKER variable and by default it is set to CC.

If a Makefile produce a library or an executable specific for the host and not the target, the 
TARGET_TYPE variable of the Makefile can be prefixed by HOST_, for exemple to produce a host 
executable use:
TARGET_TYPE := HOST_EXECUTABLE, this makes inc.Makefile to ignore the CROSS variable.

inc.Makefile is written so it recurses into all dependent directories, the Makefile to call in 
each directory is configurable with the variable MAKEFILE_NAME which is set by default to Makefile.
Locally a Makefile can be named otherwise (need to call it explicitely) and the variable LOCAL_MAKEFILE
need to be set up correctly in order to write the dependencies.
example in a file named Makefile.rmf, LOCAL_MAKEFILE must be set to Makefile.rmf 

Internal inc.Makefile variables:
--------------------------------
inc.Makefile have internal variables to change its behaviour. Each of this variable can be overriden
by the environnement or by a Makefile before including inc.Makefile.
DEPEND_FILE: (Makefile.d) this is the name of the file stored in each directory which contains dependencies.
MAKEFILE_NAME: (Makefile) global name of the makefiles
LOCAL_MAKEFILE: ($LOCAL_MAKEFILE) local makefile name
CCOMPILER: (gcc) c compiler to use. (does not contain target prefix when cross compiling)
CXXCOMPILER: (g++) c++ compiler to use. (does not contain target prefix when cross compiling)
LINKER: ($CC) application to use to generate an executable or a shared library
RMPREFIX: (..) used for target (api, dist, copy_shared) where destination is 
($RMPREFIX/externalpi, $RMPREFIX/dist, $RMPREFIX/lib) respectively.
DISABLE_WARNINGS: if set, disable all warning flags.
USE_STD_LIB: if set, allow the source code to include system headers.
EXTRA_DIST_FILES: used only for target dist, contains extra files to copy.
RMCFLAGS: you should not defined CFLAGS in the environnement because it will propagate to "sub-make" 
which is not what you want. Therefore RMCFLAGS is used to set a flag via the environnement for all "sub-make".

prebuild and postbuild targets:
-----------------------------
inc.Makfile allow any Makefiles to execute commands before building anything and to execute
commands after the target has been built. This is done by setting the variables PREBUILD and 
POSTBUILD before including inc.Makefile.
For example to display a message before compilation
PREBUILD := @echo "Hello!"  

note the @ before echo, it is used to tell Makefile not to display the command line but only
the resulting line. (See Makefile documentation for a full explanation). 

PREBUILD and POSTBUILD can be run without building the target by running make prebuild and make postbuild.