source: rtems-docs/bsp_howto/makefiles.rst @ f916fca

4.115
Last change on this file since f916fca was d389819, checked in by Amar Takhar <amar@…>, on 01/18/16 at 05:37:40

Convert all Unicode to ASCII(128)

  • Property mode set to 100644
File size: 8.3 KB
Line 
1Makefiles
2#########
3
4This chapter discusses the Makefiles associated with a BSP.  It does not
5describe the process of configuring, building, and installing RTEMS.
6This chapter will not provide detailed information about this process.
7Nonetheless, it is important to remember that the general process consists
8of four phases as shown here:
9
10- .. code:: c
11
12      bootstrap
13
14- .. code:: c
15
16      configure
17
18- .. code:: c
19
20      build
21
22- .. code:: c
23
24      install
25
26During the bootstrap phase, you are using the ``configure.ac`` and``Makefile.am`` files as input to GNU autoconf and automake to
27generate a variety of files.  This is done by running the ``bootstrap``
28script found at the top of the RTEMS source tree.
29
30During the configure phase, a number of files are generated.  These
31generated files are tailored for the specific host/target combination
32by the configure script.  This set of files includes the Makefiles used
33to actually compile and install RTEMS.
34
35During the build phase, the source files are compiled into object files
36and libraries are built.
37
38During the install phase, the libraries, header files, and other support
39files are copied to the BSP specific installation point.  After installation
40is successfully completed, the files generated by the configure and build
41phases may be removed.
42
43Makefiles Used During The BSP Building Process
44==============================================
45
46RTEMS uses the *GNU automake* and *GNU autoconf* automatic
47configuration package.  Consequently, there are a number of
48automatically generated files in each directory in the RTEMS
49source tree.  The ``bootstrap`` script found in the top level
50directory of the RTEMS source tree is executed to produce the
51automatically generated files.  That script must be run from
52a directory with a ``configure.ac`` file in it.  The ``bootstrap``
53command is usually invoked in one of the following manners:
54
55- ``bootstrap`` to regenerate all files that are generated by
56  autoconf and automake.
57
58- ``bootstrap -c`` to remove all files generated by autoconf and
59  automake.
60
61- ``bootstrap -p`` to regenerate ``preinstall.am`` files.
62
63There is a file named ``Makefile.am`` in each directory of
64a BSP.  This file is used by *automake* to produce the file named``Makefile.in`` which is also found in each directory of a BSP.
65When modifying a ``Makefile.am``, you can probably find examples of
66anything you need to do in one of the BSPs.
67
68The configure process specializes the ``Makefile.in`` files at the time that RTEMS
69is configured for a specific development host and target.  Makefiles
70are automatically generated from the ``Makefile.in`` files.  It is
71necessary for the BSP developer to provide the ``Makefile.am``
72files and generate the ``Makefile.in`` files.  Most of the
73time, it is possible to copy the ``Makefile.am`` from another
74similar directory and edit it.
75
76The ``Makefile`` files generated are processed when configuring
77and building RTEMS for a given BSP.
78
79The BSP developer is responsible for generating ``Makefile.am``
80files which properly build all the files associated with their BSP.
81Most BSPs will only have a single ``Makefile.am`` which details
82the set of source files to build to compose the BSP support library
83along with the set of include files that are to be installed.
84
85This single ``Makefile.am`` at the top of the BSP tree specifies
86the set of header files to install.  This fragment from the SPARC/ERC32
87BSP results in four header files being installed.
88.. code:: c
89
90    include_HEADERS = include/bsp.h
91    include_HEADERS += include/tm27.h
92    include_HEADERS += include/erc32.h
93    include_HEADERS += include/coverhd.h
94
95When adding new include files, you will be adding to the set of``include_HEADERS``.  When you finish editing the ``Makefile.am``
96file, do not forget to run ``bootstrap -p`` to regenerate the``preinstall.am``.
97
98The ``Makefile.am`` also specifies which source files to build.
99By convention, logical components within the BSP each assign their
100source files to a unique variable.  These variables which define
101the source files are collected into a single variable which instructs
102the GNU autotools that we are building ``libbsp.a``.  This fragment
103from the SPARC/ERC32 BSP shows how the startup related, miscellaneous
104support code, and the console device driver source is managed
105in the ``Makefile.am``.
106.. code:: c
107
108    startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \\
109    ../../shared/bsppredriverhook.c \\
110    ../../shared/bsppost.c ../../sparc/shared/bspstart.c \\
111    ../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \\
112    startup/spurious.c startup/erc32mec.c startup/boardinit.S
113    clock_SOURCES = clock/ckinit.c
114    ...
115    noinst_LIBRARIES = libbsp.a
116    libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ...
117
118When adding new files to an existing directory, do not forget to add
119the new files to the list of files to be built in the corresponding``XXX_SOURCES`` variable in the ``Makefile.am`` and run``bootstrap``.
120
121Some BSPs use code that is built in ``libcpu``.  If you BSP does
122this, then you will need to make sure the objects are pulled into your
123BSP library.  The following from the SPARC/ERC32 BSP pulls in the cache,
124register window management and system call support code from the directory
125corresponding to its ``RTEMS_CPU`` model.
126.. code:: c
127
128    libbsp_a_LIBADD  = ../../../libcpu/@RTEMS_CPU@/cache.rel \\
129    ../../../libcpu/@RTEMS_CPU@/reg_win.rel \\
130    ../../../libcpu/@RTEMS_CPU@/syscall.rel
131
132*NOTE:* The ``Makefile.am`` files are ONLY processed by``bootstrap`` and the resulting ``Makefile.in`` files are only
133processed during the configure process of a RTEMS build. Therefore,
134when developing a BSP and adding a new file to a ``Makefile.am``,
135the already generated ``Makefile`` will not automatically
136include the new references unless you configured RTEMS with the``--enable-maintainer-mode`` option.  Otherwise, the new file not
137being be taken into account!
138
139Creating a New BSP Make Customization File
140==========================================
141
142When building a BSP or an application using that BSP, it is necessary
143to tailor the compilation arguments to account for compiler flags, use
144custom linker scripts, include the RTEMS libraries, etc..  The BSP
145must be built using this information.  Later, once the BSP is installed
146with the toolset, this same information must be used when building the
147application.  So a BSP must include a build configuration file.  The
148configuration file is ``make/custom/BSP.cfg``.
149
150The configuration file is taken into account when building one's
151application using the RTEMS template Makefiles (``make/templates``).
152These application template Makefiles have been included with the
153RTEMS source distribution since the early 1990's.  However there is
154a desire in the RTEMS user community to move all provided examples to
155GNU autoconf. They are included in the 4.9 release series and used for
156all examples provided with RTEMS. There is no definite time table for
157obsoleting them.  You are free to use these but be warned they have
158fallen out of favor with many in the RTEMS community and may disappear
159in the future.
160
161The following is a slightly shortened version of the make customization
162file for the gen68340 BSP.  The original source for this file can be
163found in the ``make/custom`` directory.
164.. code:: c
165
166    # The RTEMS CPU Family and Model
167    RTEMS_CPU=m68k
168    RTEMS_CPU_MODEL=m68340
169    include $(RTEMS_ROOT)/make/custom/default.cfg
170    # This is the actual bsp directory used during the build process.
171    RTEMS_BSP_FAMILY=gen68340
172    # This contains the compiler options necessary to select the CPU model
173    # and (hopefully) optimize for it.
174    CPU_CFLAGS = -mcpu=cpu32
175    # optimize flag: typically -O2
176    CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer
177
178The make customization files have generally grown simpler and simpler
179with each RTEMS release.  Beginning in the 4.9 release series, the rules
180for linking an RTEMS application are shared by all BSPs.  Only BSPs which
181need to perform a transformation from linked ELF file to a downloadable
182format have any additional actions for program link time. In 4.8 and
183older, every BSP specified the "make executable" or ``make-exe``
184rule and duplicated the same actions.
185
186It is generally easier to copy a ``make/custom`` file from a
187BSP similar to the one being developed.
188
189.. COMMENT: COPYRIGHT (c) 1988-2002.
190
191.. COMMENT: On-Line Applications Research Corporation (OAR).
192
193.. COMMENT: All rights reserved.
194
Note: See TracBrowser for help on using the repository browser.