1 files changed, 226 insertions, 0 deletions
diff --git a/doc/bsp_howto/makefiles.t b/doc/bsp_howto/makefiles.t
new file mode 100644
index 0000000000..f27c77cf32
--- /dev/null
+++ b/doc/bsp_howto/makefiles.t
@@ -0,0 +1,226 @@
+@c
+@c  COPYRIGHT (c) 1988-2002.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@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
+
+RTEMS uses the @b{GNU automake} and @b{GNU autoconf} automatic
+configuration package.  Consequently, there are a number of
+automatically generated files in each directory in the RTEMS
+source tree.  The @code{bootstrap} script found in the top level
+directory of the RTEMS source tree is executed to produce the
+automatically generated files.  That script must be run from
+a directory with a @code{configure.ac} file in it.
+
+There is a file named @code{Makefile.am} in each directory of a BSP.
+This file is used by @b{automake} to produce the file 
+named @code{Makefile.in} which is also found in each directory of a BSP.
+The configure process 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 the @code{Makefile.am}
+files and generate the @code{Makefile.in} files.  Most of the
+time, it is possible to copy the @code{Makefile.am} from another
+similar directory and edit it.
+
+The @code{Makefile} files generated are processed when configuring
+and building RTEMS for a given BSP.
+
+The BSP developer is responsible for generating @code{Makefile.am} 
+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.am}
+in the BSP root directory (@code{c/src/lib/libbsp/CPU/BSP}) specifies
+following Makefile fragment shows how a BSP would specify the
+directories to be built and their order:
+
+@example
+SUB_DIRS=include start340 startup clock console timer \
+    network wrapup
+@end example
+
+@subsection Source Directory Makefiles
+
+There is a @code{Makefile.am} 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.am}
+and run @code{bootstrap}.
+
+@b{NOTE:} The @code{Makefile.am} files are ONLY processed by
+@code{bootstrap} and the resulting @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.am}, the 
+already generated @code{Makefile} will not automatically
+include the new references unless you configured RTEMS with the
+@code{--enable-maintainer-mode} option.
+Otherwise, the new file not being be taken into account! 
+
+If adding a new directory, be sure to add it to the list of
+automatically generated files in the BSP's @code{configure.ac}
+script.
+
+@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. 
+
+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.
+
+