source: rtems/doc/bsp_howto/makefiles.t @ 0ab65474

4.104.114.84.95
Last change on this file since 0ab65474 was 0ab65474, checked in by Joel Sherrill <joel.sherrill@…>, on Jun 10, 2000 at 8:33:47 PM

Purged as many egcs references as possible.

  • Property mode set to 100644
File size: 8.3 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1999.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Makefiles
10
11This chapter discusses the Makefiles associated with a BSP.  It does not
12describe the process of configuring, building, and installing RTEMS. 
13This chapter will not provide detailed information about this process.
14Nonetheless, it is important to remember that the general process consists
15of three parts:
16
17@itemize @bullet
18@item configure
19@item build
20@item install
21@end itemize
22
23During the configure phase, a number of files are generated.  These
24generated files are tailored for the specific host/target combination
25by the configure script.  This set of files includes the Makefiles used
26to actually compile and install RTEMS.
27
28During the build phase, the source files are compiled into object files
29and libraries are built.
30
31During the install phase, the libraries, header files, and other support
32files are copied to the BSP specific installation point.  After installation
33is successfully completed, the files generated by the configure and build
34phases may be removed.
35
36@section Makefiles Used During The BSP Building Process
37
38There is a file named @code{Makefile.in} in each directory of a BSP.
39RTEMS uses the @b{GNU autoconf} automatic configuration package.
40This tool specializes the @code{Makefile.in} files at the time that RTEMS
41is configured for a specific development host and target.  Makefiles
42are automatically generated from the @code{Makefile.in} files.  It is
43necessary for the BSP developer to provide these files.  Most of the
44time, it is possible to copy the @code{Makefile.in} from another
45similar directory and edit it.
46
47The @code{Makefile} files generated are processed when building
48RTEMS for a given BSP.
49
50The BSP developer is responsible for generating @code{Makefile.in}
51files which properly build all the files associated with their BSP.
52There are generally three types of Makefiles in a BSP source tree:
53
54
55@itemize @bullet
56@item Directory Makefiles
57@item Source Directory Makefiles
58@item Wrapup Makefile
59@end itemize
60
61@subsection Directory Makefiles
62
63The Directory class of Makefiles directs the build process through
64a set of subdirectories in a particular order.  This order is usually
65chosen to insure that build dependencies are properly processed.
66Most BSPs only have one Directory class Makefile.  The @code{Makefile.in}
67in the BSP root directory (@code{c/src/lib/libbsp/CPU/BSP}) specifies
68which directories are to be built for this BSP. For example, the
69following Makefile fragment shows how a BSP would only build the
70networking device driver if HAS_NETWORKING was defined:
71
72@example
73NETWORKING_DRIVER_yes_V = network
74NETWORKING_DRIVER = $(NETWORKING_DRIVER_$(HAS_NETWORKING)_V)
75
76[...]
77
78SUB_DIRS=include start340 startup clock console timer \
79    $(NETWORKING_DRIVER) wrapup
80@end example
81
82This fragment states that all the directories have to be processed,
83except for the @code{network} directory which is included only if the
84user configured networking.
85
86@subsection Source Directory Makefiles
87
88There is a @code{Makefile.in} in most of the directories in a BSP. This
89class of Makefile lists the files to be built as part of the driver.
90When adding new files to an existing directory, Do not forget to add
91the new files to the list of files to be built in the @code{Makefile.in}.
92
93@b{NOTE:} The @code{Makefile.in} files are ONLY processed during the configure
94process of a RTEMS build. Therefore, when developing
95a BSP and adding a new file to a @code{Makefile.in}, the
96already generated @code{Makefile} will not include the new references.
97This results in the new file not being be taken into account!
98The @code{configure} script must be run again or the @code{Makefile}
99(the result of the configure process) modified by hand.  This file will
100be in a directory such as the following:
101
102@example
103MY_BUILD_DIR/c/src/lib/libbsp/CPU/BSP/DRIVER
104@end example
105
106@subsection Wrapup Makefile
107
108This class of Makefiles produces a library.  The BSP wrapup Makefile
109is responsible for producing the library @code{libbsp.a} which is later
110merged into the @code{librtemsall.a} library.  This Makefile specifies
111which BSP components are to be placed into the library as well as which
112components from the CPU dependent support code library.  For example,
113this component may choose to use a default exception handler from the
114CPU dependent support code or provide its own.
115
116This Makefile makes use of the @code{foreach} construct in @b{GNU make}
117to pick up the required components:
118
119@example
120BSP_PIECES=startup clock console timer
121CPU_PIECES=
122GENERIC_PIECES=
123
124# bummer; have to use $foreach since % pattern subst
125#              rules only replace 1x
126OBJS=$(foreach piece, $(BSP_PIECES), ../$(piece)/$(ARCH)/$(piece).o) \
127 $(foreach piece, $(CPU_PIECES), \
128   ../../../../libcpu/$(RTEMS_CPU)/$(piece)/$(ARCH)/$(piece).o) \
129 $(wildcard \
130   ../../../../libcpu/$(RTEMS_CPU)/$(RTEMS_CPU_MODEL)/fpsp/$(ARCH)/fpsp.rel) \
131 $(foreach piece, \
132   $(GENERIC_PIECES), ../../../$(piece)/$(ARCH)/$(piece).o)
133@end example
134
135The variable @code{OBJS} is the list of "pieces" expanded to include
136path information to the appropriate object files.  The @code{wildcard}
137function is used on pieces of @code{libbsp.a} which are optional and
138may not be present based upon the configuration options.
139
140@section Makefiles Used Both During The BSP Design and its Use
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 @code{make/custom/BSP.cfg}.
149
150The configuration file is taken into account when building one's
151application using the RTEMS template Makefiles (@code{make/templates}).
152It is strongly advised to use these template Makefiles since they
153encapsulate a number of build rules along with the compile and link
154time options necessary to execute on the target board.
155
156There is a template Makefile provided for each of class of RTEMS
157Makefiles.  The purpose of each class of RTEMS Makefile is to:
158
159@itemize @bullet
160@item call recursively the makefiles in the directories beneath
161the current one,
162
163@item build a library, or
164
165@item build an executable.
166
167@end itemize
168
169The following is a shortened and heavily commented version of the
170make customization file for the gen68340 BSP.  The original source
171for this file can be found in the @code{make/custom} directory.
172
173@example
174
175# The RTEMS CPU Family and Model
176RTEMS_CPU=m68k
177RTEMS_CPU_MODEL=mcpu32
178
179include $(RTEMS_ROOT)/make/custom/default.cfg
180
181# The name of the BSP directory used for the actual source code.
182# This allows for build variants of the same BSP source.
183RTEMS_BSP_FAMILY=gen68340
184
185# CPU flag to pass to GCC
186CPU_CFLAGS = -mcpu32
187
188# optimization flag to pass to GCC
189CFLAGS_OPTIMIZE_V=-O4 -fomit-frame-pointer
190
191# The name of the start file to be linked with.  This file is the first
192# part of the BSP which executes.
193START_BASE=start340
194
195[...]
196
197# This make-exe macro is used in template makefiles to build the
198# final executable. Any other commands to follow, just as using
199# objcopy to build a PROM image or converting the executable to binary.
200
201ifeq ($(RTEMS_USE_GCC272),yes)
202# This has rules to link an application if an older version of GCC is
203# to be used with this BSP.  It is not required for a BSP to support
204# older versions of GCC.  This option is supported in some of the
205# BSPs which already had this support.
206[...]
207else
208# This has rules to link an application using gcc 2.8 or newer.
209# All BSPs should support this.  This version is required to support
210# GNAT/RTEMS.
211define make-exe
212        $(CC) $(CFLAGS) $(CFLAGS_LD) -o $(basename $@@).exe $(LINK_OBJS)
213        $(NM) -g -n $(basename $@@).exe > $(basename $@@).num
214        $(SIZE) $(basename $@@).exe
215endif
216@end example
217
218@subsection Creating a New BSP Make Customization File
219
220The basic steps for creating a @code{make/custom} file for a new BSP
221are as follows:
222
223@itemize @bullet
224
225@item copy any @code{.cfg} file to @code{BSP.cfg}
226
227@item modify RTEMS_CPU, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY,
228RTEMS_BSP, CPU_CFLAGS, START_BASE, and make-exe rules.
229
230@end itemize
231
232It is generally easier to copy a @code{make/custom} file from a
233BSP similar to the one being developed.
234
235
Note: See TracBrowser for help on using the repository browser.