Compile and Link with the Build Tool (Compact 7)

Article
03/14/2014

3/12/2014

The build system uses build.exe to make (compile and link) code. This program makes code in multiple directories as indicated by dirs files and sources files. A dirs file is a list of directories in which build.exe will make code; a sources file lists the files to compile.

Recursive Operation and Dirs Files

The first step that build.exe takes is to produce a list of all directories in which it will compile and link code.

It does this as follows:

It adds the directory from which it is called to the directory list.
It searches that directory for a dirs file. If it does not find one, the process is complete, and the directory list contains only one entry.
If it does find a dirs file, it searches in turn all of the directories listed in that file. For each such directory, it does the following:
1. Adds it to the directory list.
2. Determines whether it contains a dirs file. If it finds a dirs. file, it treats each of the directories listed in that file just as it treats the directory that contains the dirs file; that is, it adds it to the directory list and searches it for a dirs file.

This process is recursive - each directory examined can provide another dirs file that contains a list of directories to examine. The process ends when all directories listed in all the discovered dirs files have been handled.

In the following example of a dirs file, the entries in the DIRS list (SDHCLib, etc.) are the directories that build.exe will search.

DIRS= \
   SDHCLib \
   SDCard_Lib \
   SDCardLib \
   SDBus \
   SDBus_dll \
   SDHCDrivers \        
   SDClientDrivers

Sources Files

After build.exe creates the directory list, it returns to each directory in turn to make code. It checks each directory for a sources file.

In the following example of a sources file (Platform\Common\Src\Common\Bldr\Log\Sources), the .c files listed under SOURCES= \ are the files that will be compiled:

TARGETNAME=boot_log
TARGETTYPE=LIBRARY

INCLUDES=..\inc;$(INCLUDES);

SOURCES= \
    format.c \
    log.c \
    dump.c \
    oalLog.c \
    debugLog.c \
    kitlLog.c

WARNLEVEL=4 
WARNISERROR=1

Build.exe processes the file as follows:

Compiles all of the .c files listed in the file, including headers from the standard include path and the ..\inc directory.
Links the output file boot_log.lib, using the highest level of compiler warnings and throwing an error if any warnings are found during compilation.

For more information about the contents of a sources file, see Sources Macros.

Program Arguments

The build.exe program takes a number of arguments, but is most often used in one of the following ways:

build.exe (no arguments): compiles and links only files that have changed since the last time build.exe was called
build.exe -c: compiles and links files regardless of their time stamps (the "clean" option)

For reference information about build.exe, see Build Tool (Build.exe).

Input Files

Build.exe compiles and links source code based on several types of input:

Sources.cmn (a common environment file that is typically found at the root directory)
The sources file in the directory that it is compiling and/or linking
Environment variables in the local environment

Output Files

Build.exe starts executing in the directory in which it is called. There it creates the following log files that describe what occurred during execution:

build.err - for errors only
build.wrn - for warnings
build.log - for all output, including errors and warnings

Build.exe also provides the compiled and linked code to a variety of locations. This is covered in Sources Macros.

In This Section

Sources Macros
Describes some of the more common macros that are encountered during normal development.

A Build Example
Provides an example of build.exe at work.

Share via