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:

Clearly show build rules as they change while Cafe SDK evolves.
Clearly state all build rules for adaptation into an application's build environment.
Illustrate how to build an application binary (RPX).
Illustrate how to build one or more dynamically-loadable library modules (RPL).
Provide a central location in which build system differences between SDKs are readily apparent.
Provide a makefile that is relocatable, outside of the Cafe SDK directory structure.
Do not attempt to create a general purpose build system.

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.

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