Subversion Repositories or1k

@c

@c  COPYRIGHT (c) 1988-2002.

@c  On-Line Applications Research Corporation (OAR).

@c  All rights reserved.

@c

@c  makefiles.t,v 1.13 2002/01/17 21:47:44 joel Exp

@c

@chapter Makefiles

This chapter discusses the Makefiles associated with a BSP.  It does not

describe the process of configuring, building, and installing RTEMS.

This chapter will not provide detailed information about this process.

Nonetheless, it is important to remember that the general process consists

of three parts:

@itemize @bullet

@item configure

@item build

@item install

@end itemize

During the configure phase, a number of files are generated.  These

generated files are tailored for the specific host/target combination

by the configure script.  This set of files includes the Makefiles used

to actually compile and install RTEMS.

During the build phase, the source files are compiled into object files

and libraries are built.

During the install phase, the libraries, header files, and other support

files are copied to the BSP specific installation point.  After installation

is successfully completed, the files generated by the configure and build

phases may be removed.

@section Makefiles Used During The BSP Building Process

There is a file named @code{Makefile.in} in each directory of a BSP.

RTEMS uses the @b{GNU autoconf} automatic configuration package.

This tool specializes the @code{Makefile.in} files at the time that RTEMS

is configured for a specific development host and target.  Makefiles

are automatically generated from the @code{Makefile.in} files.  It is

necessary for the BSP developer to provide these files.  Most of the

time, it is possible to copy the @code{Makefile.in} from another

similar directory and edit it.

The @code{Makefile} files generated are processed when building

RTEMS for a given BSP.

The BSP developer is responsible for generating @code{Makefile.in}

files which properly build all the files associated with their BSP.

There are generally three types of Makefiles in a BSP source tree:

@itemize @bullet

@item Directory Makefiles

@item Source Directory Makefiles

@item Wrapup Makefile

@end itemize

@subsection Directory Makefiles

The Directory class of Makefiles directs the build process through

a set of subdirectories in a particular order.  This order is usually

chosen to insure that build dependencies are properly processed.

Most BSPs only have one Directory class Makefile.  The @code{Makefile.in}

in the BSP root directory (@code{c/src/lib/libbsp/CPU/BSP}) specifies

which directories are to be built for this BSP. For example, the

following Makefile fragment shows how a BSP would only build the

networking device driver if HAS_NETWORKING was defined:

@example

NETWORKING_DRIVER_yes_V = network

NETWORKING_DRIVER = $(NETWORKING_DRIVER_$(HAS_NETWORKING)_V)

[...]

SUB_DIRS=include start340 startup clock console timer \

    $(NETWORKING_DRIVER) wrapup

@end example

This fragment states that all the directories have to be processed,

except for the @code{network} directory which is included only if the

user configured networking.

@subsection Source Directory Makefiles

There is a @code{Makefile.in} in most of the directories in a BSP. This

class of Makefile lists the files to be built as part of the driver.

When adding new files to an existing directory, Do not forget to add

the new files to the list of files to be built in the @code{Makefile.in}.

@b{NOTE:} The @code{Makefile.in} files are ONLY processed during the configure

process of a RTEMS build. Therefore, when developing

a BSP and adding a new file to a @code{Makefile.in}, the

already generated @code{Makefile} will not include the new references.

This results in the new file not being be taken into account!

The @code{configure} script must be run again or the @code{Makefile}

(the result of the configure process) modified by hand.  This file will

be in a directory such as the following:

@example

MY_BUILD_DIR/c/src/lib/libbsp/CPU/BSP/DRIVER

@end example

@subsection Wrapup Makefile

This class of Makefiles produces a library.  The BSP wrapup Makefile

is responsible for producing the library @code{libbsp.a} which is later

merged into the @code{librtemsall.a} library.  This Makefile specifies

which BSP components are to be placed into the library as well as which

components from the CPU dependent support code library.  For example,

this component may choose to use a default exception handler from the

CPU dependent support code or provide its own.

This Makefile makes use of the @code{foreach} construct in @b{GNU make}

to pick up the required components:

@example

BSP_PIECES=startup clock console timer

CPU_PIECES=

GENERIC_PIECES=

# bummer; have to use $foreach since % pattern subst

#              rules only replace 1x

OBJS=$(foreach piece, $(BSP_PIECES), ../$(piece)/$(ARCH)/$(piece).o) \

 $(foreach piece, $(CPU_PIECES), \

   ../../../../libcpu/$(RTEMS_CPU)/$(piece)/$(ARCH)/$(piece).o) \

 $(wildcard \

   ../../../../libcpu/$(RTEMS_CPU)/$(RTEMS_CPU_MODEL)/fpsp/$(ARCH)/fpsp.rel) \

 $(foreach piece, \

   $(GENERIC_PIECES), ../../../$(piece)/$(ARCH)/$(piece).o)

@end example

The variable @code{OBJS} is the list of "pieces" expanded to include

path information to the appropriate object files.  The @code{wildcard}

function is used on pieces of @code{libbsp.a} which are optional and

may not be present based upon the configuration options.

@section Makefiles Used Both During The BSP Design and its Use

When building a BSP or an application using that BSP, it is necessary

to tailor the compilation arguments to account for compiler flags, use

custom linker scripts, include the RTEMS libraries, etc..  The BSP

must be built using this information.  Later, once the BSP is installed

with the toolset, this same information must be used when building the

application.  So a BSP must include a build configuration file.  The

configuration file is @code{make/custom/BSP.cfg}.

The configuration file is taken into account when building one's

application using the RTEMS template Makefiles (@code{make/templates}).

It is strongly advised to use these template Makefiles since they

encapsulate a number of build rules along with the compile and link

time options necessary to execute on the target board.

There is a template Makefile provided for each of class of RTEMS

Makefiles.  The purpose of each class of RTEMS Makefile is to:

@itemize @bullet

@item call recursively the makefiles in the directories beneath

the current one,

@item build a library, or

@item build an executable.

@end itemize

The following is a shortened and heavily commented version of the

make customization file for the gen68340 BSP.  The original source

for this file can be found in the @code{make/custom} directory.

@example

# The RTEMS CPU Family and Model

RTEMS_CPU=m68k

RTEMS_CPU_MODEL=mcpu32

include $(RTEMS_ROOT)/make/custom/default.cfg

# The name of the BSP directory used for the actual source code.

# This allows for build variants of the same BSP source.

RTEMS_BSP_FAMILY=gen68340

# CPU flag to pass to GCC

CPU_CFLAGS = -mcpu32

# optimization flag to pass to GCC

CFLAGS_OPTIMIZE_V=-O4 -fomit-frame-pointer

# The name of the start file to be linked with.  This file is the first

# part of the BSP which executes.

START_BASE=start340

[...]

# This make-exe macro is used in template makefiles to build the

# final executable. Any other commands to follow, just as using

# objcopy to build a PROM image or converting the executable to binary.

ifeq ($(RTEMS_USE_GCC272),yes)

# This has rules to link an application if an older version of GCC is

# to be used with this BSP.  It is not required for a BSP to support

# older versions of GCC.  This option is supported in some of the

# BSPs which already had this support.

[...]

else

# This has rules to link an application using gcc 2.8 or newer.

# All BSPs should support this.  This version is required to support

# GNAT/RTEMS.

define make-exe

        $(CC) $(CFLAGS) $(CFLAGS_LD) -o $(basename $@@).exe $(LINK_OBJS)

        $(NM) -g -n $(basename $@@).exe > $(basename $@@).num

        $(SIZE) $(basename $@@).exe

endif

@end example

@subsection Creating a New BSP Make Customization File

The basic steps for creating a @code{make/custom} file for a new BSP

are as follows:

@itemize @bullet

@item copy any @code{.cfg} file to @code{BSP.cfg}

@item modify RTEMS_CPU, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY,

RTEMS_BSP, CPU_CFLAGS, START_BASE, and make-exe rules.

@end itemize

It is generally easier to copy a @code{make/custom} file from a

BSP similar to the one being developed.