/ani/mrses

To get this branch, use:
bzr branch http://darksoft.org/webbzr/ani/mrses

« back to all changes in this revision

Viewing changes to cell/buildutils/README_build_env.txt

  • Committer: Suren A. Chilingaryan
  • Date: 2010-04-28 04:30:08 UTC
  • Revision ID: csa@dside.dyndns.org-20100428043008-vd9z0nso9axezvlp
Initial import

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
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