Initial revision

doc/develenv/compile.texi

@@ -0,0 +1,157 @@
+@c This chapter is not currently in the Development Environment Guide.
+
+@c
+@c  COPYRIGHT (c) 1988-1997.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@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.
+
+