mirror of
https://git.rtems.org/rtems-docs/
synced 2025-10-19 01:21:45 +08:00
Rename all manuals with an _ to have a -. It helps released naming of files.
This commit is contained in:
Chris Johns
190
bsp-howto/makefiles.rst
Normal file
190
bsp-howto/makefiles.rst
Normal file
@@ -0,0 +1,190 @@
|
||||
.. 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
|
||||
#########
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user