bzr branch
http://suren.me/webbzr/ani/mrses
1
by Suren A. Chilingaryan
Initial import |
1 |
%% -------------------------------------------------------------- |
2 |
%% (C)Copyright 2001,2008, |
|
3 |
%% International Business Machines Corporation, |
|
4 |
%% Sony Computer Entertainment, Incorporated, |
|
5 |
%% Toshiba Corporation, |
|
6 |
%% |
|
7 |
%% All Rights Reserved. |
|
8 |
%% -------------------------------------------------------------- |
|
9 |
%% PROLOG END TAG zYx |
|
10 |
||
11 |
SDK SAMPLES AND LIBRARY BUILD ENVIRONMENT OVERVIEW |
|
12 |
||
13 |
The SDK Samples and Library package provides a build environment to assist |
|
14 |
in the construction of fully functional makefiles. This document provides |
|
15 |
an overview of the commonly used build environment features. For samples |
|
16 |
of using the build environment, see the various Makefiles found within the |
|
17 |
SDK. |
|
18 |
||
19 |
||
20 |
A. Build Environment Files |
|
21 |
||
22 |
The build environment consist of the following three (3) files. They |
|
23 |
are processed by the make utility in the order specified. |
|
24 |
||
25 |
make.header - Includes definitions required in advance to processing the |
|
26 |
Makefile. This file includes make.env. |
|
27 |
||
28 |
make.env - File used to specify the default preferred compilers and tools |
|
29 |
to be used by make. These can be over-ridden by the definition |
|
30 |
of a user environment variables or edits to this file. |
|
31 |
||
32 |
HOST_COMPILER - specifies the default compiler to be used |
|
33 |
for code targeted to execute on the host |
|
34 |
system. |
|
35 |
PPU_COMPILER - specifies the default compiler to be used |
|
36 |
for C code targeted to execute on the PPE; |
|
37 |
either "gcc" or "xlc". |
|
38 |
PPU32_COMPILER - specifies the default compiler to be used |
|
39 |
for 32-bit C code targeted to execute on the |
|
40 |
PPE; either "gcc" or "xlc". |
|
41 |
PPU64_COMPILER - specifies the default compiler to be used |
|
42 |
for 64-bit C code targeted to execute on the |
|
43 |
PPE; either "gcc" or "xlc". |
|
44 |
SPU_COMPILER - specifies the default compiler to be used |
|
45 |
for C code targeted to run on a SPE, either |
|
46 |
"gcc" or "xlc". |
|
47 |
XLC_VERSION - specifies the version of the default xlc |
|
48 |
compiler. |
|
49 |
FTN_PPU_COMPILER - specifies the default compiler to be used |
|
50 |
for Fortran code targeted to execute on the |
|
51 |
PPE; either "gfortran" or "xlf". |
|
52 |
FTN_PPU32_COMPILER - specifies the default compiler to be used |
|
53 |
for 32-bit Fortran code targeted to execute |
|
54 |
on the PPE; either "gfortran" or "xlf". |
|
55 |
FTN_PPU64_COMPILER - specifies the default compiler to be used |
|
56 |
for 64-bit Fortran code targeted to execute |
|
57 |
on the PPE; either "gfortran" or "xlf". |
|
58 |
FTN_SPU_COMPILER - specifies the default compiler to be used |
|
59 |
for Fortran code targeted to run on a SPE, |
|
60 |
either "gfortran" or "xlf". |
|
61 |
XLF_VERSION - specifies the version of the default xlf |
|
62 |
compiler. |
|
63 |
SPU_TIMING - specifies whether by default that a static |
|
64 |
analysis timing file is created for all |
|
65 |
generated assembly (.s) files. |
|
66 |
||
67 |
make.footer - File that specifies all the build rules to be applied. SDK |
|
68 |
users are not expected to modify this file, but can be used |
|
69 |
to understand the default flags and build procedures. |
|
70 |
||
71 |
B. Anatomy of a Typical Makefile |
|
72 |
||
73 |
All Makefiles have a common basic structure and may include the following |
|
74 |
entries in order: |
|
75 |
||
76 |
1. Specifies the subdirectories to visit before building the target |
|
77 |
objects in this directory. The subdirs are specified as: |
|
78 |
||
79 |
DIRS := <list of space separated subdirectories> |
|
80 |
||
81 |
2. Specifies the build targets and target processor. It should be noted |
|
82 |
that the build environment only accommodates one processor type for |
|
83 |
each Makefile (directory). Building code for multiple processors or |
|
84 |
requires a separate directory and Makefile. |
|
85 |
||
86 |
To specify the processor type for the target |
|
87 |
||
88 |
TARGET_PROCESSOR := "spu" | "ppu" | "ppu64" | "host" |
|
89 |
||
90 |
To specify a program or list of program targets to be built: |
|
91 |
||
92 |
PROGRAM := <target program> |
|
93 |
PROGRAMS := <list of space separated target programs> |
|
94 |
||
95 |
Alternatively, the program or programs and processor type for the target |
|
96 |
can be specified with a single definition. |
|
97 |
||
98 |
PROGRAM_<target> := <target program> |
|
99 |
PROGRAMS_<target>:= <list if space separated target programs> |
|
100 |
||
101 |
||
102 |
To specify the name of a library target (either shared or non-shared) |
|
103 |
to be built, use one of the following: |
|
104 |
||
105 |
LIBRARY := <library archive> |
|
106 |
SHARED_LIBRARY := <shared library archive> |
|
107 |
||
108 |
In order to build shared libraries that are versioned (ie, libfoo.so.3.1 |
|
109 |
with an SONAME of libfoo.so.3), use the following: |
|
110 |
||
111 |
SHARED_LIBRARY_VERSION := <major number>.<minor number> |
|
112 |
SHARED_LIBRARY_SONAME := <major number> |
|
113 |
SHARED_LIBRARY := <shared library libfoo.so>.<major>.<minor> |
|
114 |
||
115 |
This will result in the library having the proper SONAME, and it will |
|
116 |
create the correct files: |
|
117 |
||
118 |
SHARED_LIBRARY_VERSION := 3.1 |
|
119 |
SHARED_LIBRARY_SONAME := 3 |
|
120 |
SHARED_LIBRARY := libfoo.so.3.1 |
|
121 |
||
122 |
libfoo.so.3.1 # real file |
|
123 |
libfoo.so.3 -> libfoo.so.3.1 # symlink for SONAME use by loader |
|
124 |
libfoo.so -> libfoo.so.3.1 # symlink for use when building |
|
125 |
||
126 |
To specify a SPU programs to be embeded into a PPU executable as a |
|
127 |
linked library, specify one of the following (depending upon whether |
|
128 |
the library is to be embedded in a 32-bit or 64-bit PPU executable, |
|
129 |
respectively): |
|
130 |
||
131 |
LIBRARY_embed := <library archive> |
|
132 |
LIBRARY_embed64 := <library archive> |
|
133 |
||
134 |
||
135 |
To specify other build targets that are not programs or libraries, |
|
136 |
the following define can be included: |
|
137 |
||
138 |
OTHER_TARGETS := <other space separated targets> |
|
139 |
||
140 |
||
141 |
3. Specify an optional list of objects, compile and link options. |
|
142 |
||
143 |
To specify additional source directories besides the current directory, |
|
144 |
a VPATH directive can be specified. |
|
145 |
||
146 |
VPATH := <list of colon separate paths> |
|
147 |
||
148 |
By default, if the objects are not specified, the target (library or |
|
149 |
program) will include all objects corresponding to the source files |
|
150 |
in the source directories (as specified by VPATH). Alternately, the |
|
151 |
list of objects can be directly specified for the program. |
|
152 |
||
153 |
OBJS := <list of space separated objects> |
|
154 |
||
155 |
To specify the objects for each (or a specific) program: |
|
156 |
||
157 |
OBJS_<program> := <list of space separated objects> |
|
158 |
||
159 |
There are several defines for specifying compilation, assembler, and |
|
160 |
link flags. They include: |
|
161 |
||
162 |
||
163 |
CPPFLAGS Specifies flags to be used by the C preprocessor. |
|
164 |
CPPFLAGS_gcc Specifies flags to be used by the C preprocessor only |
|
165 |
when compiling using gcc. |
|
166 |
CPPFLAGS_xlc Specifies flags to be used by the C preprocessor only |
|
167 |
when compiling using xlc. |
|
168 |
||
169 |
CC_OPT_LEVEL Specifies the optimization level. Default is -O3. |
|
170 |
Setting to optimization level to "CC_OPT_LEVEL_DEBUG" |
|
171 |
will build to code to debugging. |
|
172 |
||
173 |
CFLAGS Specifies additional C compilation flags. |
|
174 |
CFLAGS_gcc Specifies flags to be used for C compilation only |
|
175 |
when compiling using gcc. |
|
176 |
CFLAGS_xlc Specifies flags to be used for C preprocessor only |
|
177 |
when compiling using xlc. |
|
178 |
CFLAGS_<program> Specifies the specific C compilation flags to be |
|
179 |
applied to the specified program. |
|
180 |
||
181 |
||
182 |
CXXFLAGS Specifies additional C++ compilation flags. |
|
183 |
CXXFLAGS_<program> Specifies the specific C++ compilation flags to be |
|
184 |
applied to the specified program. |
|
185 |
||
186 |
FFLAGS Specifies Fortran compilation flags. |
|
187 |
||
188 |
INCLUDE Specifies the additional include directories. T |
|
189 |
||
190 |
ASFLAGS Specifies the additional assembler flags. |
|
191 |
ASFLAGS_<program> Specifies the additional assembler flags to be |
|
192 |
applied to the specified program. |
|
193 |
||
194 |
LDFLAGS Specifies the additional linker options. |
|
195 |
LDFLAGS_<program> Specifies the additional linker options to be applied |
|
196 |
when linking the specified program. |
|
197 |
||
198 |
IMPORTS Specifies the libraries to be linked into the |
|
199 |
targets. |
|
200 |
IMPORTS_<program> Specifies the libraries to be linked into the |
|
201 |
specified target. |
|
202 |
||
203 |
TARGET_INSTALL_DIR Specifies the directory in which all built targets |
|
204 |
are installed. |
|
205 |
INSTALL_FILES Specifies the list of file to be installed. |
|
206 |
INSTALL_DIR Specifies the directory all INSTALL_FILES are shipped |
|
207 |
to during installation. |
|
208 |
||
209 |
||
210 |
4. Include make.footer. This is simply done by the following Makefile lines, |
|
211 |
where the number of "../" depends upon the relative path depth within |
|
212 |
the SDK directory structure. |
|
213 |
||
214 |
ifdef CELL_TOP |
|
215 |
include $(CELL_TOP)/buildutils/make.footer |
|
216 |
else |
|
217 |
include ../../buildutils/make.footer |
|
218 |
endif |
|
219 |
||
220 |
5. In rare occurrences, it may be required to include additional, post |
|
221 |
make.footer build rules. If required, they will be placed here. |
|
222 |
||
223 |
C. Make Targets |
|
224 |
||
225 |
The build environment provides several basic build targets. These include: |
|
226 |
||
227 |
all - Default build target when no target is specified. Includes |
|
228 |
the building of the "dirs", "libraries", "programs", "misc_" |
|
229 |
and "install" targets. |
|
230 |
||
231 |
dirs - Traverse the make directory tree building the specified |
|
232 |
targets. This target is typically used in combination with |
|
233 |
the "libraries", "programs", "misc_", or "install" targets. |
|
234 |
||
235 |
libraries - Build only the library (shared and non-shared) targets. |
|
236 |
||
237 |
programs - Build only the program targets. |
|
238 |
||
239 |
misc_ - Builds miscellaneous targets including OTHER_TARGETS. See |
|
240 |
make.footer for a list of miscellaneous targets. |
|
241 |
||
242 |
install - Install the built targets. See TARGET_INSTALL_DIR, |
|
243 |
INSTALL_FILES, and INSTALL_DIR defines. |
|
244 |
||
245 |
clean - Remove all built and installed targets, including objects, |
|
246 |
libraries, and programs. |
|
247 |
||
248 |
listenv - Display the compilation environment to be applied to the |
|
249 |
current directory. Debug target useful for determining the |
|
250 |
targets, tools and flags to be used by make. |
|
251 |
||
252 |
||
253 |
D. Other Useful Variables |
|
254 |
||
255 |
The following additional variables are defined by the build environment |
|
256 |
and can be used within Makefiles. The advantage of using these variables is |
|
257 |
that make.footer automatically handles ppu and spu differences (ie, |
|
258 |
/usr/include versus /usr/spu/include), 32bit and 64bit differences (ie, |
|
259 |
/usr/lib versus /usr/lib64), and blade or cross environment differences |
|
260 |
(ie, /usr/include versus /opt/cell/sysroot/usr/include). |
|
261 |
||
262 |
Variables indicating where files are 'read' from (-L and -I directories): |
|
263 |
$(SDKBIN) - bin directory path for official GA code |
|
264 |
$(SDKLIB) - library directory path for official GA code |
|
265 |
$(SDKINC) - include directory path for official GA code |
|
266 |
$(SDKEXBIN) - bin directory path for SDK example code |
|
267 |
$(SDKEXLIB) - library directory path for SDK example code |
|
268 |
$(SDKEXINC) - include directory path for SDK example code |
|
269 |
$(SDKPRBIN) - bin directory path for SDK prototype code |
|
270 |
$(SDKPRLIB) - library directory path for SDK prototype code |
|
271 |
$(SDKPRINC) - include directory path for SDK prototype code |
|
272 |
||
273 |
Variables indicating where files are installed (exported): |
|
274 |
$(EXP_SDKBIN) - bin directory path |
|
275 |
$(EXP_SDKLIB) - library directory path |
|
276 |
$(EXP_SDKINC) - include directory path |
|
277 |
||
278 |
Variables indicating where libraries will be at runtime, for use with the |
|
279 |
linker -R flag: |
|
280 |
$(SDKRPATH) - installed library directory path for official GA code |
|
281 |
$(SDKEXRPATH) - installed library directory path for SDK example code |
|
282 |
$(SDKPRRPATH) - installed library directory path for SDK prototype code |
|
283 |
||
284 |
Variables relating to the simulator: |
|
285 |
$(SYSTEMSIM_INCLUDE) - directory with callthru and related include files |
|
286 |
(ie, profile.h) |
|
287 |