1
%% --------------------------------------------------------------
2
%% (C)Copyright 2001,2008,
3
%% International Business Machines Corporation,
4
%% Sony Computer Entertainment, Incorporated,
5
%% Toshiba Corporation,
7
%% All Rights Reserved.
8
%% --------------------------------------------------------------
11
SDK SAMPLES AND LIBRARY BUILD ENVIRONMENT OVERVIEW
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
20
A. Build Environment Files
22
The build environment consist of the following three (3) files. They
23
are processed by the make utility in the order specified.
25
make.header - Includes definitions required in advance to processing the
26
Makefile. This file includes make.env.
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.
32
HOST_COMPILER - specifies the default compiler to be used
33
for code targeted to execute on the host
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
47
XLC_VERSION - specifies the version of the default xlc
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
63
SPU_TIMING - specifies whether by default that a static
64
analysis timing file is created for all
65
generated assembly (.s) files.
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.
71
B. Anatomy of a Typical Makefile
73
All Makefiles have a common basic structure and may include the following
76
1. Specifies the subdirectories to visit before building the target
77
objects in this directory. The subdirs are specified as:
79
DIRS := <list of space separated subdirectories>
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.
86
To specify the processor type for the target
88
TARGET_PROCESSOR := "spu" | "ppu" | "ppu64" | "host"
90
To specify a program or list of program targets to be built:
92
PROGRAM := <target program>
93
PROGRAMS := <list of space separated target programs>
95
Alternatively, the program or programs and processor type for the target
96
can be specified with a single definition.
98
PROGRAM_<target> := <target program>
99
PROGRAMS_<target>:= <list if space separated target programs>
102
To specify the name of a library target (either shared or non-shared)
103
to be built, use one of the following:
105
LIBRARY := <library archive>
106
SHARED_LIBRARY := <shared library archive>
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:
111
SHARED_LIBRARY_VERSION := <major number>.<minor number>
112
SHARED_LIBRARY_SONAME := <major number>
113
SHARED_LIBRARY := <shared library libfoo.so>.<major>.<minor>
115
This will result in the library having the proper SONAME, and it will
116
create the correct files:
118
SHARED_LIBRARY_VERSION := 3.1
119
SHARED_LIBRARY_SONAME := 3
120
SHARED_LIBRARY := libfoo.so.3.1
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
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,
131
LIBRARY_embed := <library archive>
132
LIBRARY_embed64 := <library archive>
135
To specify other build targets that are not programs or libraries,
136
the following define can be included:
138
OTHER_TARGETS := <other space separated targets>
141
3. Specify an optional list of objects, compile and link options.
143
To specify additional source directories besides the current directory,
144
a VPATH directive can be specified.
146
VPATH := <list of colon separate paths>
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.
153
OBJS := <list of space separated objects>
155
To specify the objects for each (or a specific) program:
157
OBJS_<program> := <list of space separated objects>
159
There are several defines for specifying compilation, assembler, and
160
link flags. They include:
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.
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.
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.
182
CXXFLAGS Specifies additional C++ compilation flags.
183
CXXFLAGS_<program> Specifies the specific C++ compilation flags to be
184
applied to the specified program.
186
FFLAGS Specifies Fortran compilation flags.
188
INCLUDE Specifies the additional include directories. T
190
ASFLAGS Specifies the additional assembler flags.
191
ASFLAGS_<program> Specifies the additional assembler flags to be
192
applied to the specified program.
194
LDFLAGS Specifies the additional linker options.
195
LDFLAGS_<program> Specifies the additional linker options to be applied
196
when linking the specified program.
198
IMPORTS Specifies the libraries to be linked into the
200
IMPORTS_<program> Specifies the libraries to be linked into the
203
TARGET_INSTALL_DIR Specifies the directory in which all built targets
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.
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.
215
include $(CELL_TOP)/buildutils/make.footer
217
include ../../buildutils/make.footer
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.
225
The build environment provides several basic build targets. These include:
227
all - Default build target when no target is specified. Includes
228
the building of the "dirs", "libraries", "programs", "misc_"
229
and "install" targets.
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.
235
libraries - Build only the library (shared and non-shared) targets.
237
programs - Build only the program targets.
239
misc_ - Builds miscellaneous targets including OTHER_TARGETS. See
240
make.footer for a list of miscellaneous targets.
242
install - Install the built targets. See TARGET_INSTALL_DIR,
243
INSTALL_FILES, and INSTALL_DIR defines.
245
clean - Remove all built and installed targets, including objects,
246
libraries, and programs.
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.
253
D. Other Useful Variables
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).
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
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
278
Variables indicating where libraries will be at runtime, for use with the
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
284
Variables relating to the simulator:
285
$(SYSTEMSIM_INCLUDE) - directory with callthru and related include files