rtems-docs/bsp-howto/makefiles.rst

.. comment SPDX-License-Identifier: CC-BY-SA-4.0

.. COMMENT: COPYRIGHT (c) 1988-2002.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

.. _Makefiles:

Makefiles
*********

.. warning::

   This chapter contains outdated and confusing information.

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:

- ``bootstrap``

- ``configure``

- ``build``

- ``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-block:: makefile

    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-block:: makefile

    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-block:: makefile

    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 will 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-block:: makefile

    # 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.