Split document into seperate files by section.

1 files changed, 194 insertions, 0 deletions

diff --git a/bsp_howto/makefiles.rst b/bsp_howto/makefiles.rst
new file mode 100644
index 0000000..528617e
--- /dev/null
+++ b/bsp_howto/makefiles.rst
@@ -0,0 +1,194 @@
+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 four phases as shown here:
+
+- .. code:: c
+
+      bootstrap
+
+- .. code:: c
+
+      configure
+
+- .. code:: c
+
+      build
+
+- .. code:: c
+
+      install
+
+During the bootstrap phase, you are using the ``configure.ac`` and``Makefile.am`` files as input to GNU autoconf and automake to
+generate a variety of files.  This is done by running the ``bootstrap``
+script found at the top of the RTEMS source tree.
+
+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.
+
+Makefiles Used During The BSP Building Process
+==============================================
+
+RTEMS uses the *GNU automake* and *GNU autoconf* automatic
+configuration package.  Consequently, there are a number of
+automatically generated files in each directory in the RTEMS
+source tree.  The ``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 ``configure.ac`` file in it.  The ``bootstrap``
+command is usually invoked in one of the following manners:
+
+- ``bootstrap`` to regenerate all files that are generated by
+  autoconf and automake.
+
+- ``bootstrap -c`` to remove all files generated by autoconf and
+  automake.
+
+- ``bootstrap -p`` to regenerate ``preinstall.am`` files.
+
+There is a file named ``Makefile.am`` in each directory of
+a BSP.  This file is used by *automake* to produce the file named``Makefile.in`` which is also found in each directory of a BSP.
+When modifying a ``Makefile.am``, you can probably find examples of
+anything you need to do in one of the BSPs.
+
+The configure process specializes the ``Makefile.in`` files at the time that RTEMS
+is configured for a specific development host and target.  Makefiles
+are automatically generated from the ``Makefile.in`` files.  It is
+necessary for the BSP developer to provide the ``Makefile.am``
+files and generate the ``Makefile.in`` files.  Most of the
+time, it is possible to copy the ``Makefile.am`` from another
+similar directory and edit it.
+
+The ``Makefile`` files generated are processed when configuring
+and building RTEMS for a given BSP.
+
+The BSP developer is responsible for generating ``Makefile.am``
+files which properly build all the files associated with their BSP.
+Most BSPs will only have a single ``Makefile.am`` which details
+the set of source files to build to compose the BSP support library
+along with the set of include files that are to be installed.
+
+This single ``Makefile.am`` at the top of the BSP tree specifies
+the set of header files to install.  This fragment from the SPARC/ERC32
+BSP results in four header files being installed.
+.. code:: c
+
+    include_HEADERS = include/bsp.h
+    include_HEADERS += include/tm27.h
+    include_HEADERS += include/erc32.h
+    include_HEADERS += include/coverhd.h
+
+When adding new include files, you will be adding to the set of``include_HEADERS``.  When you finish editing the ``Makefile.am``
+file, do not forget to run ``bootstrap -p`` to regenerate the``preinstall.am``.
+
+The ``Makefile.am`` also specifies which source files to build.
+By convention, logical components within the BSP each assign their
+source files to a unique variable.  These variables which define
+the source files are collected into a single variable which instructs
+the GNU autotools that we are building ``libbsp.a``.  This fragment
+from the SPARC/ERC32 BSP shows how the startup related, miscellaneous
+support code, and the console device driver source is managed
+in the ``Makefile.am``.
+.. code:: c
+
+    startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \\
+    ../../shared/bsppredriverhook.c \\
+    ../../shared/bsppost.c ../../sparc/shared/bspstart.c \\
+    ../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \\
+    startup/spurious.c startup/erc32mec.c startup/boardinit.S
+    clock_SOURCES = clock/ckinit.c
+    ...
+    noinst_LIBRARIES = libbsp.a
+    libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ...
+
+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 corresponding``XXX_SOURCES`` variable in the ``Makefile.am`` and run``bootstrap``.
+
+Some BSPs use code that is built in ``libcpu``.  If you BSP does
+this, then you will need to make sure the objects are pulled into your
+BSP library.  The following from the SPARC/ERC32 BSP pulls in the cache,
+register window management and system call support code from the directory
+corresponding to its ``RTEMS_CPU`` model.
+.. code:: c
+
+    libbsp_a_LIBADD  = ../../../libcpu/@RTEMS_CPU@/cache.rel \\
+    ../../../libcpu/@RTEMS_CPU@/reg_win.rel \\
+    ../../../libcpu/@RTEMS_CPU@/syscall.rel
+
+*NOTE:* The ``Makefile.am`` files are ONLY processed by``bootstrap`` and the resulting ``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 ``Makefile.am``,
+the already generated ``Makefile`` will not automatically
+include the new references unless you configured RTEMS with the``--enable-maintainer-mode`` option.  Otherwise, the new file not
+being be taken into account!
+
+Creating a New BSP Make Customization File
+==========================================
+
+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 ``make/custom/BSP.cfg``.
+
+The configuration file is taken into account when building one’s
+application using the RTEMS template Makefiles (``make/templates``).
+These application template Makefiles have been included with the
+RTEMS source distribution since the early 1990’s.  However there is
+a desire in the RTEMS user community to move all provided examples to
+GNU autoconf. They are included in the 4.9 release series and used for
+all examples provided with RTEMS. There is no definite time table for
+obsoleting them.  You are free to use these but be warned they have
+fallen out of favor with many in the RTEMS community and may disappear
+in the future.
+
+The following is a slightly shortened version of the make customization
+file for the gen68340 BSP.  The original source for this file can be
+found in the ``make/custom`` directory.
+.. code:: c
+
+    # The RTEMS CPU Family and Model
+    RTEMS_CPU=m68k
+    RTEMS_CPU_MODEL=m68340
+    include $(RTEMS_ROOT)/make/custom/default.cfg
+    # This is the actual bsp directory used during the build process.
+    RTEMS_BSP_FAMILY=gen68340
+    # This contains the compiler options necessary to select the CPU model
+    # and (hopefully) optimize for it.
+    CPU_CFLAGS = -mcpu=cpu32
+    # optimize flag: typically -O2
+    CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer
+
+The make customization files have generally grown simpler and simpler
+with each RTEMS release.  Beginning in the 4.9 release series, the rules
+for linking an RTEMS application are shared by all BSPs.  Only BSPs which
+need to perform a transformation from linked ELF file to a downloadable
+format have any additional actions for program link time. In 4.8 and
+older, every BSP specified the "make executable" or ``make-exe``
+rule and duplicated the same actions.
+
+It is generally easier to copy a ``make/custom`` file from a
+BSP similar to the one being developed.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+