rtems/doc/develenv/compile.texi

@c This chapter is not currently in the Development Environment Guide.

@c
@c  COPYRIGHT (c) 1988-2002.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  $Id$
@c

@ifinfo
@node Compilation and GNU Make Stanzas, Compilation and GNU Make Stanzas Building the Entire Tree, Test Suite Source Directory, Top
@end ifinfo
@chapter Compilation and GNU Make Stanzas
@ifinfo
@menu
* Compilation and GNU Make Stanzas Building the Entire Tree::
* Compilation and GNU Make Stanzas Making a Component::
* Compilation and GNU Make Stanzas Optional Manager Support::
@end menu
@end ifinfo

RTEMS is compiled using the GNU gmake(1G) utilities.
All examples in this section are with the gmake(1G) command.
Note that the installation procedure for GNU Make installs it as
make.  It is referred to as gmake in this document to
distinguish it from any other make utilities which may also be
on the development system.

The GNU Make utility uses a file that describes the
relationships among the files and the operations necessary for
updating each file. The GNU Make utility uses stanzas to specify
which set of relationships to update.  Each component and suite
control directory contains a make control file, Makefile, which
describes the relationships which must be checked and the
associated update operations for each stanza. This facility is
used to perform compilation, to remove intermediate files, to
install RTEMS, and to maintain release and working set source
and documentation notebooks. The following is a list of stanzas
used by RTEMS make control files:

@ifset use-texinfo-tables
@table @code
@item all
perform compilation but do not install

@item install
perform compilation if directory contains source but do not install

@item clean
delete most generated files and directories for the current CPU and target

@item clobber
delete all generated files and directories for the current CPU and target
@end table
@end ifset

@ifclear use-texinfo-tables
@html
<CENTER>
  <TABLE COLS=2 WIDTH="80%" BORDER=2>
<TR><TD ALIGN=center>all</TD>
    <TD ALIGN=center>perform compilation but do not install</TD></TR>
<TR><TD ALIGN=center>install</TD>
    <TD ALIGN=center>perform compilation if directory contains source 
        but do not install</TD></TR>
<TR><TD ALIGN=center>clean</TD>
    <TD ALIGN=center>delete most generated files and directories for 
        the current CPU and target</TD></TR>
<TR><TD ALIGN=center>clobber</TD>
    <TD ALIGN=center>delete all generated files and directories for 
        the current CPU and target</TD></TR>
  </TABLE>
</CENTER>
@end html
@end ifclear

@ifinfo
@node Compilation and GNU Make Stanzas Building the Entire Tree, Compilation and GNU Make Stanzas Making a Component, Compilation and GNU Make Stanzas, Compilation and GNU Make Stanzas
@end ifinfo
@section Building the Entire Tree

At the top of the C source tree, execute the command
gmake all.  This will build and install all components and tests
into the directory <TARGET> in this directory.

@ifinfo
@node Compilation and GNU Make Stanzas Making a Component, Compilation and GNU Make Stanzas Optional Manager Support, Compilation and GNU Make Stanzas Building the Entire Tree, Compilation and GNU Make Stanzas
@end ifinfo
@section Making a Component

A single component can be compiled by changing to the
directory which contains that component and performing the
following command:

@example
gmake
@end example


This is equivalent to the following command:

@example
gmake all
@end example

Both commands will result in the GNU Make utility
determining which files require compilation or assembly.  If any
files require compilation or assembly, then these operations
will be performed followed by the appropriate archive or link
command. Files installed are placed in subdirectories under the
install point.  The install point is determined by the setting
of the variable PROJECT_HOME in the file
c/make/custom/<TARGET>.cfg.

If the current directory is not a leaf directory,
then the requested operation will be performed recursively to
all subdirectories under the current directory.

By specifying one of the other stanzas supported by
the Makefile, the GNU Make utility can be used to perform such
operations as removing all automatically generated files in a
component (clean and clobbers stanza).

NOTE: For many components it is not possible to
compile them until other components have been installed.

@ifinfo
@node Compilation and GNU Make Stanzas Optional Manager Support, Sample Applications, Compilation and GNU Make Stanzas Making a Component, Compilation and GNU Make Stanzas
@end ifinfo
@section Optional Manager Support

RTEMS allows the C applications developer to build
images that only contain those components of the executive that
are needed, leaving out those that will not be utilized.  This
is accomplished by the RTEMS Makefile system linking in the
"stub" versions of the optional managers in the place of those
managers not needed by the specific application.   The
application Makefile sets the system variable $(MANAGERS) list
to contain those managers that are required by the application.
The RTEMS Makefile system then is able to build a list of
managers that are unwanted, effectively linking in the stubbed
versions of these managers before the RTEMS library is built.

For more information and implementation details refer
to the following files:

@itemize @bullet
@item c/make/leaf.cfg,

@item a Makefile for a test or sample application, and

@item a compiler description file from c/make/compilers
@end itemize

These files demonstrate the use of $(MANAGERS) and
how the unwanted managers are handled.