Page History

7.1 Introduction

rce modules and binary objects for host systems are compiled and linked with the gnu compiler and binutils collections. The build tool is gmake.

This chapter covers:

• #7.2 General compilation and linking requirements
• #7.3 Makefile and build product hierarchy
• #7.4 Global make variables
• #7.5 Constituent makefiles
• #7.6 Packages and project makefiles
• #7.7 Make examples
• #7.8 Make invocation options
• #7.9 Compiler options for rce modules
• #7.10 gnu linker options for rce modules

The reader is assumed to be familiar with the tools in the gnu collection.

7.2 General compilation and linking requirements

While naturally the build system automates much of the compilation and linking process, developers must manage build dependencies manually, setting up makefiles such that modules and objects "lower" on the dependency graph are built before those "higher" on the graph.

...

The dynamic linker fails if presented with duplicate symbol names. A given symbol can be used in more than one module, but only if those modules are never loaded together.

Host objects

TBW.

7.3 Makefile and build product hierarchy

Source code in the rce repository is organized using a two-level structure in which projects contain one or more packages. Packages contain code and makefiles for the construction of one or more constituents.

...

A set of repository-level makefiles allows gmake to be invoked at the top level to build all packages and projects locally, or build a full release of rce software. A set of makefile templates is used to clone new projects and packages. See Figure 4.Hierarchy of repository-level makefiles

Image Added

Building all projects at once is the exception. Typically, development iterations involve building and re-building individual packages and constituents. Figure 5 depicts the makefiles relevant to package and constituent builds.

Hierarchy of package- and constituent-level makefilesImage Added

Makefile search path

Under construction
[ Note: How "export library symbols...just like symbols in module sources."]
Inter-package and inter-project dependencies
Must be handled manually
If A depends on B, build B first
Order of projects in projects.mk
Order of packages in packages.mk
Library search order
When linking each library is searched once
In lists of libraries put the lower-level libs first
The search order will be the reverse of that listed

Build product hierarchy

TBW.

Directory structure for rce build products

Image Added

7.4 Global make variables

-Under construction-

The repository-level makefiles define a set of global make variables that can be useful to cite in package- and constituent-level makefiles, and which set compiler options for various targets.

...

Build directories for host (non-module) code:

objdir
libdir
bindir bindir

7.5 Constituent makefiles

This section describes the most common make rules and option flags for building constituents.

...

{span:class=steve}Is core under rce project?{span}

The following optional rules govern how static and shared object libraries appropriate for linking into an rce module at build time are themselves built and/or located for linking to the target module by gnu ld.Module makefiles: optional static and shared object library make rules
Rule Description

...

...

The following example constituents.mk file illustrates the use of these optional make rules in building an rce module, george.1.0.example, which is composed of its own compiled sources as well as two internal libraries in the fci and enet projects (libcontainer and libutil) and an external library (libmodcommon). Make instructions for the libcontainer library are included in the george makefile, and the two are built as part of the same sequence.

...

Constituent make rules for host objects

TBW.

7.6 Packages and project makefiles

Under construction

This section describes the most common make rules and option flags for packages.mk and project.mk. See Chapter Z for definitions of all options.

Use application-specific files
projects.mk at top level
packages.mk for projects

7.7 Make examples

gmake is invoked as follows:

...

// change directory to top of release tree
prompt> gmake rceapp.console.ppc-rtems-rce405.obj

7.8 Make invocation options

Path specification

gmake can be invoked at the release, project, or package level.

...

ppc-linux
ppc-rtems-rce405
ppc-rtems-ml405
i386-linux
x86_64-linux
sparc-solaris

Make actions

If a rule is not specified, then what is built?

{span:class=steve}Steve: If an action is not specified, then what is built?{span}

7.9 Compiler options for rce modules

The following compiler options are invoked via /make/sw/flags.mk. They are presented here for reference.
-shared
The linker will expect each module to have a "dynamic section" and a hash table for those symbols with global visibility.|
-fno-pic
Although pic saves on relocations (one per function instead of one per function call) it requires the dynamic linker to know the special relocation types needed for the Global Offset Table and the Procedure Linkage Table. The latter is especially tricky to get right. It's simpler to use non-pic and just deal with the regular relocations.
The other usual reason to use pic (that most of the code can be mapped into multiple address spaces at the same time) doesn't apply here since rtems only offers one global address space.|
-nostdlib
We supply our own module _init (rce_modinit) and module _fini (rce_modfinish) code. Another reason not to use the standard _init/_fini code is that their source code was compiled with -fpic.
-nostdlib also prevents searching of the standard C++ libraries. Instead we'll want to search the symbol table of the RTEMS+newlib executable either at the time the module is produced or at run time.
-fvisiblity=hidden
A shared object actually has two symbol tables, the normal one and a special "dynamic" table. The latter is the one that is searched in order to resolve inter-object references. In the past pretty much every non-static symbol from every object code file used to make the shared object went into the dynamic table. Since GCC 4.0 the compiler recognizes the -visibility option which controls the default visibility of symbols. Using -fvisibility=hidden makes "hidden" the default. Hidden symbols don't go into the dynamic symbol table so one can dramatically reduce its size. To make sure that the symbols associated with a variable, function or class do make it into the dynamic symbol table you need to mark it with _attribute_ ((visibility ("default"))):

...

-fvisibility=hidden also hides out-of-line code generated for inline functions and other compiler-generated code.|
-mlongcall
By default GCC will compile function calls into branch instructions which use 26-bit PC-relative offsets. In general this won't be adequate for inter-module calls so the compiler must be instructed to make all function calls "long" calls. These use full 32-bit addresses at the cost of some speed.|

Compiler options required for rebuilding system or third-party libraries

...

ifeq ($(tgt_cpu_family)-$(tgt_os),ppc-rtems)

AS  := powerpc-rtems-as
CPP := powerpc-rtems-cpp
CC  := powerpc-rtems-gcc
CXX := powerpc-rtems-g++
LD  := powerpc-rtems-ld
LX  := powerpc-rtems-g++

ifeq ($(tgt_board),rce405)
RTEMSDIR := $(RELEASE_DIR)/build/rtems/target/powerpc-rtems/rce405/lib
endif

ifeq ($(tgt_board),ml405)
RTEMSDIR := $(RELEASE_DIR)/build/rtems/target/powerpc-rtems/ml405/lib
endif

LDTOOLSD := $(RELEASE_DIR)/rce/ldtools
LIBEXTNS := a
DEPFLAGS := -B$(RTEMSDIR) -MM
DEFINES  += -Dppc405
CPPFLAGS :=
CFLAGS   := -B$(RTEMSDIR) -specs bsp_specs -qrtems -mcpu=403 -Wall
CXXFLAGS := $(CFLAGS)
CASFLAGS := -x assembler-with-cpp -P $(CFLAGS)
LDFLAGS  := -r
LXFLAGS  := -B$(RTEMSDIR) -specs $(LDTOOLSD)/dynamic_specs \
            -qrtems -qnolinkcmds -Wl,-T$(LDTOOLSD)/dynamic.ld \
            -mcpu=403
MANAGERS := timer sem msg event signal part region dpmem io rtmon ext mp

MDEFINES  := $(DEFINES)
             -DEXPORT='__attribute__((visibility("default")))'
MCFLAGS   := -B$(RTEMSDIR) -specs $(LDTOOLSD)/module_specs \
             -qrtems -Wall -fvisibility=hidden -mlongcall
             -fno-pic -mcpu=403
MCXXFLAGS := $(MCFLAGS)
MCASFLAGS := -x assembler-with-cpp -P $(MCFLAGS)
MLDFLAGS  := -r
MLXFLAGS  := -B$(RTEMSDIR) -specs $(LDTOOLSD)/module_specs \
             -qrtems -qnolinkcmds -Wl,-T$(LDTOOLSD)/module.ld-mcpu=403 \
             -shared -nostdlib

7.10 gnu linker options for rce modules

The following gnu ld options are invoked via /make/sw/flags.mk. They are presented here for reference.

Static linking must be done by calling ld explicitly, rather than relying on g++ to do it implicitly. The latter uses the linker option --eh-frame-hdr which causes ld to abort with an error about a "non-representable section" in the output.

-shared and -nostdlib
as for g++.|
-z combreloc
Makes sure that all relocation table entries go into a single contiguous sub-region of the shared object, even if by mischance they end up in more than one output section. This option also causes the linker to sort the entries so that those reference the same symbol occur together. This allows the dynamic linker to use a one-entry symbol lookup cache.|
-T scriptname
Use the custom linker script.|
-Map filename
to make a link map.|
-soname modulename.major.minor.branch
to set the soname field to the module's name with version numbers and development branch appended.|
-o modulename.major.minor.branch.so
Module filename.|
-fhash-style=sysv
to suppress generation of a GNU-style hash table.|

Each module that the one being constructed depends on should be named on the linker command line so that each of their sonames will be recorded in a DT_NEEDED entry in the elf dynamic section. This defines a minimum set of compatbility requirements; compatibility requirements can be expanded by implementing an rce_isCompatible function, as described in Chapter Y.

{span:class=steve}Steve: Can set rce core comaptibility here? Is this optional, only for cases where the dependency is not direct? Won't dynalink try to resolve?{span}