Code development in the Cell Broadband Engine™ (Cell/B.E.)™ SDK can be a bit awkward, and it requires special makefile code. Using the standard make is challenging for some developers because of the need to use two sets of tools to build a Cell/B.E. application:

• ppu-gcc and spu-gcc for the respective object files, then
• ppu-embedspu to combine them

Early in the Cell Broadband Engine™ Architecture development, a pseudo-build environment was created with a make.footer makefile. This environment has evolved over time, but it is important to remember that make.footer is not a full-featured, all-encompassing build environment. It does support enough features to build the basics of Cell/B.E. code, but it is really only intended and designed to be used with the examples and demonstration code that ships with the SDK.

This article shows you the variables that are included in make.footer and how they are used in some of the SDK example makefiles.

Discovering the make environment files

SDK 3.1 ships three environment files that help to define what is needed for make to work correctly.

• make.header
  This file includes definitions required in advance to process the makefile. It also includes the other main make environment file, make.env.
  
  
• make.env
  This file specifies the default preferred compilers and tools to be used by make. You can override these by defining user environment variables or editing this file. The following is the list of compiler variables available in SDK 3.1:
  • HOST_COMPILER
    Specifies the default compiler to be used for code targeted to execute on the host system.
    
    
  • PPU_COMPILER, PPU32_COMPILER, PPU64_COMPILER
    Specifies the default compiler to be used for all 32-bit and 64-bit C code targeted to execute on the PPU (either gcc or xlc).
    
    
  • SPU_COMPILER
    Specifies the default compiler to be used for C code targeted to run on an SPE (either gcc or xlc).
    
    
  • FTN_PPU_COMPILER, FTN_PPU32_COMPILER, FTN_PPU64_COMPILER
    Specifies the default compiler to be used for all 32-bit and 64-bit FORTRAN code targeted to execute on the PPU (either gfortran or xlf.
    
    
  • FTN_SPU_COMPILER
    Specifies the default compiler to be used for FORTRAN code targeted to run on an SPE (either gfortran or xlf).
    
    
  • XLC_REL, XLF_REL
    Specifies the release number of the xlc and xlf compilers.
    
    
  • SPU_TIMING
    Specifies whether a static analysis timing file is created for all generated assembly (.s) files by default.
  
  
  
• make.footer
  This file specifies all of the build rules that are to be applied. SDK users should not modify this file, but it can be used to understand the default flags and build procedures.

Back to top

Understanding the anatomy of an SDK example makefile

All of the example and demonstration makefiles in the SDK have a common basic structure. They might include the following entries in order:

• Subdirectories
• Build targets and target processor
• Objects
• Compile and link flags
• Include make.footer

Subdirectories

To specify the subdirectories to visit before building the target objects in this directory:

DIRS := <list of space separated subdirectories>

Some makefiles in the SDK use this to build multiple programs, while other makefiles use this because the spu code is in a separate directory.

Build targets and target processor

There are several ways to specify the build targets and target processor. Note that the build environment only accommodates one processor type for each makefile (directory)—building code for multiple processors requires a separate directory and makefile. As such, the spu code is always in a separate directory. Some of the examples have the ppu code in the high-level directory, while other examples have it in a ppu directory at the same level as the spu directory.

To specify the processor type for the target:

TARGET_PROCESSOR := "spu" | "ppu" | "ppu64" | "host"

To specify a program or list of program targets to build:

PROGRAM  := <program> 
PROGRAMS := <list of space separated programs>

Alternatively, you can specify the program or programs and processor type for the target with a single definition. Typically, this is used to differentiate between building ppu (32-bit) and ppu64 (64-bit) programs.

PROGRAM_<target> := <program>
PROGRAMS_<target>:= <list if space separated programs>

To specify the name of a library target (either shared or non-shared) to build, use one of the following:

LIBRARY         := <library archive>
SHARED_LIBRARY  := <shared library archive>

To specify an SPU program to be embedded 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 archive>
LIBRARY_embed64 := <library archive>

To specify other build targets that are not programs or libraries:

OTHER_TARGETS := <other space separated programs>

Objects

There are other ways to specify other objects that need to be built as well.

To specify source directories other than the current directory, you can define a VPATH directive. Some of the SDK examples use this to build both 32-bit and 64-bit ppu code from the same source files.

VPATH := <list of colon separate paths>

By default, if the objects are not specified, the target (library or program) includes all objects corresponding to the source files in the source directories (as specified by VPATH). Alternatively, you can directly specify the list of objects for the program.

OBJS := <list of space separated objects>

To specify the objects for each (or one specific) program:

OBJS_<program> := <list of space separated objects>

Compile and link flags

There are several definitions for specifying compilation, assembler, and link flags. They are used in the makefiles to change behaviors from the default. They include:

• CPPFLAGS, CPPFLAGS_gcc, CPPFLAGS_xlc, CPPFLAGS_<program>
  Specifies flags for the C preprocessor to use for the default or specified compiler for all programs, or for the specified program.
  
  
• CC_OPT_LEVEL
  Specifies the optimization level. The default is -O3. Setting this equal to $(CC_OPT_LEVEL_DEBUG) builds to code for debugging.
  
  
• CFLAGS, CFLAGS_gcc, CFLAGS_xlc, CFLAGS_<program>
  Specifies additional C compilation flags for the default or specified compiler for all programs or for the specified program.
  
  
• CXXFLAGS, CXXFLAGS_<program>
  Specifies additional C++ compilation flags for all programs or for the specified program.
  
  
• FFLAGS
  Specifies additional FORTRAN compilation flags for all FORTRAN programs.
  
  
• INCLUDE
  Specifies the additional include directories, each prefaced with -I.
  
  
• ASFLAGS, ASFLAGS_<program>
  Specifies the additional assembler flags for all programs or for the specified program.
  
  
• LDFLAGS, LDFLAGS_gcc, LDFLAGS_xlc, LDFLAGS_<program>
  Specifies the additional linker options for the default or specified compiler for all programs or for the specified program.
  
  
• IMPORTS, IMPORTS_<program>
  Specifies the libraries or objects to be linked in for all programs or for the specified program. This can be either a path and a filename or an -lname, where the linker can find libname.so or libname.a.
  
  
• TARGET_INSTALL_DIR
  Specifies the directory in which all built programs are installed (copied) after being built.
  
  
• INSTALL_FILES, INSTALL_DIR
  Specifies the list of files and directories to be installed. This is used for non-built code, such as copying data files or header files into more public locations.

Include make.footer

In order for the example makefiles to use the variables discussed in this article, the make.footer file must be included. Do this by using the following makefile lines, where the number of "../" depends on the relative path depth within the SDK directory structure.

ifdef CELL_TOP
   include $(CELL_TOP)/buildutils/make.footer
else
   include ../../buildutils/make.footer
endif

Occasionally you might be required to include additional post-make.footer build rules. If required, the rules are placed after the include of the make.footer file.

Back to top

Using make targets

The build environment provides several basic build targets you can use from the command line. These include:

• all
  Offers the default build target when no target is specified. Includes the building of the dirs, libraries, programs, misc_, and install targets.
  
  
• dirs
  Traverses the make directory tree, building the specified targets. This target is typically used in combination with the libraries, programs, misc_, or install targets.
  
  
• libraries
  Builds only the LIBRARY, SHARED_LIBRARY, and LIBRARY_embed targets.
  
  
• programs
  Builds only the PROGRAM_<target> and PROGRAMS_<target> targets.
  
  
• misc_
  Builds miscellaneous targets, including OTHER_TARGETS. See make.footer for a list of miscellaneous targets.
  
  
• install
  Installs the built targets. See TARGET_INSTALL_DIR, INSTALL_FILES, and INSTALL_DIR definitions.
  
  
• clean
  Removes all built and installed targets, including objects, libraries, and programs.
  
  
• listenv
  Displays the compilation environment to be applied to the current directory. This is a debug target useful for determining the targets, tools, and flags make uses.

Back to top

Learning about other useful makefile variables

The following additional variables, which are defined by the build environment, are used within some of the example makefiles. The advantage of using these variables is that make.footer automatically handles ppu and spu differences (such as /usr/include or /usr/spu/include), 32- and 64-bit differences (such as /usr/lib or /usr/lib64), and blade or cross-environment differences (such as /usr/include or /opt/cell/sysroot/usr/include).

Variables indicating where files are read from (-L and -I directories):

• $(SDKBIN), $(SDKLIB), $(SDKINC)
  bin, library, and include directory paths for official GA code (such as /usr/bin).
  
  
• $(SDKEXBIN), $(SDKEXLIB), $(SDKEXINC)
  bin, library, and include directory paths for SDK example code (such as /opt/cell/sdk/usr/bin).
  
  
• $(SDKPRBIN), $(SDKPRLIB), $(SDKPRINC)
  bin, library, and include directory paths for SDK prototype code (such as /opt/cell/sdk/prototype/usr/bin).

Variables indicating where files are installed (exported):

• $(EXP_SDKBIN), $(EXP_SDKLIB), $(EXP_SDKINC)
  bin, library, and include directory paths for installing code (/opt/cell/sdk/).

Variables indicating where libraries will be at runtime, for use with the linker -R flag:

• $(SDKRPATH), $(SDKEXRPATH), $(SDKPRRPATH)
  Installed library directory path for SDK GA, example, and prototype code (/opt/cell/sdk/usr/lib).

Variables relating to the simulator:

• $(SYSTEMSIM_INCLUDE)
  Directory with callthru and related include files (profile.h).

Back to top

Exploring other build tools in the SDK

In addition to the make.footer file included in SDK 3.1, there are other tools you can use to control building and executing the examples.

• cellsdk_select_compiler
  This tool in the /opt/cell/sdk/buildutils directory is used to switch between the gnu gcc/gfortran and IBM XL xlc/xlf compilers (if installed). Running it with no options shows the different options available. The script modifies the ${CELL_TOP}/buildutils/make.env file to change the variables to point to the specified compilers.
  
  
• cellsdk_sync_simulator
  This tool in the /opt/cell directory is used to copy files from the build environment's sysroot into the simulator's sysroot. If the examples are rebuilt, they can install their binaries into the /opt/cell/sysroot directory structure. Use the cellsdk_sync_simulator script to synchronize that sysroot with the one that the simulator uses.

Back to top

Conclusion

This article offered you a tour of the variables (and how they can be used as a pseudo-build environment) in make.footer in the IBM SDK for Multicore Acceleration 3.1. This article offered the clues you need to understand how the examples and demos are built.

Resources

Learn

• Use an RSS feed to request notification for the upcoming articles in this series. (Find out more about RSS feeds of developerWorks content.)
  
  
• Find the first installment in this series, "A close-up on SDK 3.0, Part 1: Rebuilding code from src.rpm" (developerWorks, 2008), which shows you how to install and rebuild SDK code from a src.rpm package for SDK 3.0. It's still germane.
  
  
• Check out the GCC online documentation repository for a bonanza of GCC manuals, from release 2.95.3 to 4.3.2, plus user-level and internal documentation related to current development.
  
  
• Visit information center for IBM compilers supporting Cell/B.E. processors for information on SDK 3.0/3.1 compilers for C and FORTRAN, including IBM XL C/C++ for Multicore Acceleration for Linux™ 9.0 and/or IBM XL FORTRAN for Multicore Acceleration for Linux 11.1.
  
  
• Find every Cell/B.E. document imaginable—guides, handbooks, tutorials, specifications—in the Cell Resource Center's Docs page. It contains a link to "Programmer's Guide to the IBM SDK for Multicore Acceleration."
  
  
• The IBM Systems® Information Center provides you with a single, searchable information center where you can access product documentation for IBM Systems hardware, operating systems, and server software. Navigate to SDK documentation by selecting the following in the navigation bar: System software > Cell Broadband Engine solution > SDK > SDK 3.1.
  
  
• Need roundups of fast info on how to use major Cell/B.E.-related technologies?
  • See Programming with ALF: The series (developerWorks, October 2007-July 2008) for a roundup of short guides and longer articles to help you understand and use the Accelerated Library Framework with the SDK.
  • See Programming with DaCS: The series (developerWorks, October 2007-August 2008) for a roundup of short guides and longer articles to help you understand and use Data Communication and Synchronization services with the SDK.
  • See Programming with BLAS: The series (developerWorks, November 2007-July 2008) for a roundup of short guides and longer articles to help you understand and use the Basic Linear Algebra Subroutines library with the SDK.
  
  
• Learn more about Cell/B.E. programming from the developerWorks series:
  • "Programming high-performance applications on the Cell/B.E. processor"
  • "PS3 fab-to-lab"
  • "The little broadband engine that could"
  
  
• Refer to the Cell Broadband Engine documentation section of the IBM Semiconductor Solutions Technical Library for a wealth of downloadable manuals, specifications, and more.
  
  
• Sign up for the developerWorks newsletter and get the latest developer news and Cell/B.E. happenings delivered to your inbox each week. Check Power Architecture ® when you sign up to receive Cell/B.E. news in your newsletter.
  
  

Get products and technologies

• Get your copy of the IBM SDK for Multicore Acceleration 3.1 or browse through the library of Cell/B.E. documentation.
  
  
• Find all Cell/B.E.-related articles, discussion forums, downloads, and more at the IBM developerWorks Cell Broadband Engine resource center: your definitive resource for all things Cell/B.E.
  
  
• Contact IBM about custom Cell/B.E.-based or custom-processor based solutions.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Check out the Cell Broadband Engine Architecture forum to get your technical questions about the processor answered. Juicy problems and answers from the forums are rounded up periodically and highlighted in the "Forum watch" blog series.
  
  
• Go to the Cell Broadband Engine/Power Architecture blog for news, downloads, instructional resources, and event notifications for Cell/B.E. and other Power Architecture-related technologies. You can find the popular "Forum watch" blog series (Q&A roundup), the "FixIt" technology updates, and the Infobomb quick-read technology introductions.
  
  

About the author

Brian Horton has been with the Cell/B.E. SDK development team since early 2007, working on issues with the samples and build environment, as well as with the DaCS library.

Rate this article

Comments

Back to top

Table of contents

• Discovering the make environment files
• Understanding the anatomy of an SDK example makefile
• Using make targets
• Learning about other useful makefile variables
• Exploring other build tools in the SDK
• Conclusion
• Resources
• About the author
• Comments

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers