Building with Examplemake

Overview

The Cafe SDK is based upon a sophisticated hierarchy of makefiles. It is designed to accommodate multiple processor architectures and target platforms. Applications are also complex affairs, and reconciling their build systems with the SDK can be a daunting task.

Examplemake demonstrates how to build an external application for the Cafe platform with minimum dependence on the SDK environment. The examplemake folder contains an example for the current SDK of the preferred way of building an application. An external package is available for the version from the previous SDK for use in determining the changes for each SDK.

Folder Description
cafe_sdk This is part of the SDK and provides the current example.
cafe_sdk This is an external package and shows link-time cross references with RPL v1.0.

To minimize dependencies on the Cafe SDK, the root to the Cafe SDK must be set in the environment or passed to make as a DOS style path using forward slashes (/). For example:

$ make CAFE_SDK_DIR=c:/cafe_sdk

Each SDK folder for examplemake is a set of three demos. The first example, the helloworld demo, has a single makefile that produces a simple application.

examplemake/cafe_sdk/helloworld/makefile

The second example, the helloworld_rpl demo, has a makefile and sample code that produce an RPX and a RPL. This example shows how to build a RPX and a RPL which both reference each other. The makefile for this demo can be found here:

examplemake/cafe_sdk/helloworld_rpl/makefile

The third example, the replace_core_user demo, has a makefile and sample code that produce an RPX. The RPX shows how to override default memory manager functions using the __preinit_user function. The makefile for this demo can be found here:

examplemake/cafe_sdk/replace_core_user/makefile

Goals

The goals of examplemake:

Requirements

Shell Environment

The examplemake demos must be executed from a Cygwin shell. However, examplemake does not require a Cafe Cygwin shell.

System Variables

The following variables must be defined in each examplemake makefile or shell environment:

Variable Description
CAFE_SDK_DIR The installation path of the Cafe SDK.
GHS_DIR The installation path of the Green Hills Software MULTI tool chain.

Customizing examplemake for your Application

The makefiles for these demos define key environment variables for adaptation into your application's build system. Refer to the makefiles for more information. Common customizations are discussed below.

Moving Outside Cafe SDK

The examplemake demos can be moved to any location on the host PC. However, ensure that the CAFE_SDK_DIR and GHS_DIR variables are set correctly in each makefile.

Location of Executables

All RPX and RPL files must be located in the same directory when executing. The RPL_TARGET variable indicates the directory to which executables will be installed.

Other Variables

The following variables may also be useful when adapting your build process for Cafe.

Variable Description Remarks
BUILD_TYPE Changes settings based on the build type specified. Set to NDEBUG for Release builds. Otherwise, Debug build is assumed.
DEFINES #define values needed by the SDK headers.
CCLDFLAGS Directives needed by both the compiler and linker.
CCFLAGS Compiler directives/flags.
LDFLAGS Linker directives/flags.

For more information and additional variables, refer to the makefiles directly.

Generating RPX and RPL files

See the Build Products section of the Building the SDK MAN page.

Known Issues

Auto SDA Optimization

Large applications may encounter link failures if the Small Data Area optimization is enabled, due to a known issue in the compiler/linker tool chain.

The examplemake demo illustrates how to work around this problem by disabling SDA optimizations.

For RPLs and RPXs, the -sda=none flag is used.

Refer to the examplemake makefiles for more information.

General Design Stability

The build system and application structure continue to evolve as the platform matures. We hope to concisely capture these changes within the examplemake demo. Check back often, and we apologize for the inconvenience.

The RPL tools allow building import libraries with the preprpl[32|64] tool. Additionally preprpl[32|64] can run without object files allowing it to run before any compile steps. This allows full parallization of building RPLs and the RPX after preprpl[32|64] has built the export object files and the import library files.

See Also

Environment Settings
Building the SDK
RPX/RPL Cross-Referencing
RPX/RPL Developer Overview
makerpl[32|64]
preprpl[32|64]

Revision History

2014/01/15 Removed refs to cafe_sdk-1_8
2014/01/15 replace_core_user demo uses __preinit_user.
2013/05/08 Automated cleanup pass.
2012/07/23 Minor documentation updates.
2011/10/19 Update new release procedure.
2011/08/03 Add helloworld examples.
2011/07/21 Caferun -l option added.
2011/02/21 Initial version.


CONFIDENTIAL