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