%% -------------------------------------------------------------- %% (C)Copyright 2001,2008, %% International Business Machines Corporation, %% Sony Computer Entertainment, Incorporated, %% Toshiba Corporation, %% %% All Rights Reserved. %% -------------------------------------------------------------- %% PROLOG END TAG zYx SDK SAMPLES AND LIBRARY BUILD ENVIRONMENT OVERVIEW The SDK Samples and Library package provides a build environment to assist in the construction of fully functional makefiles. This document provides an overview of the commonly used build environment features. For samples of using the build environment, see the various Makefiles found within the SDK. A. Build Environment Files The build environment consist of the following three (3) files. They are processed by the make utility in the order specified. make.header - Includes definitions required in advance to processing the Makefile. This file includes make.env. make.env - File used to specify the default preferred compilers and tools to be used by make. These can be over-ridden by the definition of a user environment variables or edits to this file. HOST_COMPILER - specifies the default compiler to be used for code targeted to execute on the host system. PPU_COMPILER - specifies the default compiler to be used for C code targeted to execute on the PPE; either "gcc" or "xlc". PPU32_COMPILER - specifies the default compiler to be used for 32-bit C code targeted to execute on the PPE; either "gcc" or "xlc". PPU64_COMPILER - specifies the default compiler to be used for 64-bit C code targeted to execute on the PPE; either "gcc" or "xlc". SPU_COMPILER - specifies the default compiler to be used for C code targeted to run on a SPE, either "gcc" or "xlc". XLC_VERSION - specifies the version of the default xlc compiler. FTN_PPU_COMPILER - specifies the default compiler to be used for Fortran code targeted to execute on the PPE; either "gfortran" or "xlf". FTN_PPU32_COMPILER - specifies the default compiler to be used for 32-bit Fortran code targeted to execute on the PPE; either "gfortran" or "xlf". FTN_PPU64_COMPILER - specifies the default compiler to be used for 64-bit Fortran code targeted to execute on the PPE; either "gfortran" or "xlf". FTN_SPU_COMPILER - specifies the default compiler to be used for Fortran code targeted to run on a SPE, either "gfortran" or "xlf". XLF_VERSION - specifies the version of the default xlf compiler. SPU_TIMING - specifies whether by default that a static analysis timing file is created for all generated assembly (.s) files. make.footer - File that specifies all the build rules to be applied. SDK users are not expected to modify this file, but can be used to understand the default flags and build procedures. B. Anatomy of a Typical Makefile All Makefiles have a common basic structure and may include the following entries in order: 1. Specifies the subdirectories to visit before building the target objects in this directory. The subdirs are specified as: DIRS := 2. Specifies the build targets and target processor. It should be noted that the build environment only accommodates one processor type for each Makefile (directory). Building code for multiple processors or requires a separate directory and Makefile. To specify the processor type for the target TARGET_PROCESSOR := "spu" | "ppu" | "ppu64" | "host" To specify a program or list of program targets to be built: PROGRAM := PROGRAMS := Alternatively, the program or programs and processor type for the target can be specified with a single definition. PROGRAM_ := PROGRAMS_:= To specify the name of a library target (either shared or non-shared) to be built, use one of the following: LIBRARY := SHARED_LIBRARY := In order to build shared libraries that are versioned (ie, libfoo.so.3.1 with an SONAME of libfoo.so.3), use the following: SHARED_LIBRARY_VERSION := . SHARED_LIBRARY_SONAME := SHARED_LIBRARY := .. This will result in the library having the proper SONAME, and it will create the correct files: SHARED_LIBRARY_VERSION := 3.1 SHARED_LIBRARY_SONAME := 3 SHARED_LIBRARY := libfoo.so.3.1 libfoo.so.3.1 # real file libfoo.so.3 -> libfoo.so.3.1 # symlink for SONAME use by loader libfoo.so -> libfoo.so.3.1 # symlink for use when building To specify a SPU programs to be embeded into a PPU executable as a linked library, specify one of the following (depending upon whether the library is to be embedded in a 32-bit or 64-bit PPU executable, respectively): LIBRARY_embed := LIBRARY_embed64 := To specify other build targets that are not programs or libraries, the following define can be included: OTHER_TARGETS := 3. Specify an optional list of objects, compile and link options. To specify additional source directories besides the current directory, a VPATH directive can be specified. VPATH := By default, if the objects are not specified, the target (library or program) will include all objects corresponding to the source files in the source directories (as specified by VPATH). Alternately, the list of objects can be directly specified for the program. OBJS := To specify the objects for each (or a specific) program: OBJS_ := There are several defines for specifying compilation, assembler, and link flags. They include: CPPFLAGS Specifies flags to be used by the C preprocessor. CPPFLAGS_gcc Specifies flags to be used by the C preprocessor only when compiling using gcc. CPPFLAGS_xlc Specifies flags to be used by the C preprocessor only when compiling using xlc. CC_OPT_LEVEL Specifies the optimization level. Default is -O3. Setting to optimization level to "CC_OPT_LEVEL_DEBUG" will build to code to debugging. CFLAGS Specifies additional C compilation flags. CFLAGS_gcc Specifies flags to be used for C compilation only when compiling using gcc. CFLAGS_xlc Specifies flags to be used for C preprocessor only when compiling using xlc. CFLAGS_ Specifies the specific C compilation flags to be applied to the specified program. CXXFLAGS Specifies additional C++ compilation flags. CXXFLAGS_ Specifies the specific C++ compilation flags to be applied to the specified program. FFLAGS Specifies Fortran compilation flags. INCLUDE Specifies the additional include directories. T ASFLAGS Specifies the additional assembler flags. ASFLAGS_ Specifies the additional assembler flags to be applied to the specified program. LDFLAGS Specifies the additional linker options. LDFLAGS_ Specifies the additional linker options to be applied when linking the specified program. IMPORTS Specifies the libraries to be linked into the targets. IMPORTS_ Specifies the libraries to be linked into the specified target. TARGET_INSTALL_DIR Specifies the directory in which all built targets are installed. INSTALL_FILES Specifies the list of file to be installed. INSTALL_DIR Specifies the directory all INSTALL_FILES are shipped to during installation. 4. Include make.footer. This is simply done by the following Makefile lines, where the number of "../" depends upon the relative path depth within the SDK directory structure. ifdef CELL_TOP include $(CELL_TOP)/buildutils/make.footer else include ../../buildutils/make.footer endif 5. In rare occurrences, it may be required to include additional, post make.footer build rules. If required, they will be placed here. C. Make Targets The build environment provides several basic build targets. These include: all - Default build target when no target is specified. Includes the building of the "dirs", "libraries", "programs", "misc_" and "install" targets. dirs - Traverse the make directory tree building the specified targets. This target is typically used in combination with the "libraries", "programs", "misc_", or "install" targets. libraries - Build only the library (shared and non-shared) targets. programs - Build only the program targets. misc_ - Builds miscellaneous targets including OTHER_TARGETS. See make.footer for a list of miscellaneous targets. install - Install the built targets. See TARGET_INSTALL_DIR, INSTALL_FILES, and INSTALL_DIR defines. clean - Remove all built and installed targets, including objects, libraries, and programs. listenv - Display the compilation environment to be applied to the current directory. Debug target useful for determining the targets, tools and flags to be used by make. D. Other Useful Variables The following additional variables are defined by the build environment and can be used within Makefiles. The advantage of using these variables is that make.footer automatically handles ppu and spu differences (ie, /usr/include versus /usr/spu/include), 32bit and 64bit differences (ie, /usr/lib versus /usr/lib64), and blade or cross environment differences (ie, /usr/include versus /opt/cell/sysroot/usr/include). Variables indicating where files are 'read' from (-L and -I directories): $(SDKBIN) - bin directory path for official GA code $(SDKLIB) - library directory path for official GA code $(SDKINC) - include directory path for official GA code $(SDKEXBIN) - bin directory path for SDK example code $(SDKEXLIB) - library directory path for SDK example code $(SDKEXINC) - include directory path for SDK example code $(SDKPRBIN) - bin directory path for SDK prototype code $(SDKPRLIB) - library directory path for SDK prototype code $(SDKPRINC) - include directory path for SDK prototype code Variables indicating where files are installed (exported): $(EXP_SDKBIN) - bin directory path $(EXP_SDKLIB) - library directory path $(EXP_SDKINC) - include directory path Variables indicating where libraries will be at runtime, for use with the linker -R flag: $(SDKRPATH) - installed library directory path for official GA code $(SDKEXRPATH) - installed library directory path for SDK example code $(SDKPRRPATH) - installed library directory path for SDK prototype code Variables relating to the simulator: $(SYSTEMSIM_INCLUDE) - directory with callthru and related include files (ie, profile.h)