CTR-SDK Build System Manual (for DLLs)

Introduction

About This Document

This document provides information necessary to use the SDK build system to build cro and applications using cro.

• Descriptions of added build-system variables
• Added tasks

Information about the following can be found in the referenced documentation.

• Information about developing your own build system:
  Guide to Developing a Build System (for DLLs)
• Information about developing a more sophisticated build system:
  Guide to Developing a Build System (for High-Level DLLs)

This document assumes basic knowledge of cro. See the DLL Manual for a basic introduction to cro.

Notation Used in This Document

In this document, we sometimes enclose text in colored boxes (as shown below) to indicate that it is sample OMakefile code.

command option1 option2

Added Variables

The following build variables have been added for specifying and controlling cro builds.

• TARGET_MODULE
• MODULE_LIST
• MODULE_EXPORT_TYPE
• MODULE_ENABLE_OFFSET
• MODULE_ADD_DEBUG_INFO

These variables are described below.

TARGET_MODULE

Specifies the name of the cro module to create. It is used in place of TARGET_PROGRAM. Specifying a value for this variable will build cro.

Sample Configuration:

TARGET_MODULE   = TestModule1

MODULE_LIST

Specifies a list of build directories automatically referenced by the module that the current OMakefile is building. If the module being built uses undefined symbols, then the build system will look for definitions in the modules specified by MODULE_LIST. If the build system cannot find definitions in any module, it will raise a link error in the final static module.

Sample Configuration:

MODULE_LIST     = ../App ../TestModule2 ../TestModule3

MODULE_EXPORT_TYPE

Specifies the export type. The available values are SYMBOL, INDEX, and OFFSET. The default is SYMBOL.

The meanings of the various values are as follows.

Sample Configuration:

MODULE_EXPORT_TYPE  = INDEX

MODULE_ENABLE_OFFSET

Specifies whether to perform the build procedure required when modules reference symbols with an export type of OFFSET.
A specific build procedure is required when referencing a symbol exported as an offset. This build procedure has the following restriction: the module that references the symbol must be built after or at the same time as the module that exports it. In order to satisfy this restriction, the SDK's build system assumes that all modules will be built simultaneously.
You can prevent this build procedure by setting MODULE_ENABLE_OFFSET to false. This will enable you to build each module whenever you like. The trade-off of this option is that you will no longer be able to reference symbols exported as offsets.
The default value is true.

Sample Configuration:

MODULE_ENABLE_OFFSET    = false

MODULE_ADD_DEBUG_INFO

This includes the necessary information to debug the .cro object in the .crr object. Debugging information for the .cro object must be included in the .crr object in order to debug the .cro source in the debugger. Set MODULE_ADD_DEBUG_INFO to TRUE to include debugging information in the .crr object, and enable .cro source-code debugging in the debugger. Set MODULE_ADD_DEBUG_INFO to FALSE to disable .cro source-code debugging. This makes the .crr file smaller because it does not contain debugging information.
The default value is TRUE.

Sample Configuration:

MODULE_ADD_DEBUG_INFO    = false

Settings Required for Build

The following are required for building cro or an application that uses it, in addition to the requirements for creating ordinary applications.

• Creating Build Directories for cro
• Creating an OMakefile for the cro Build
• Adding Code for cro File to Application's OMakefile
• Storing cro, crs, and crr Files in ROM-FS

Creating Build Directories for cro

The SDK's build system assumes that you will create static and dynamic modules in separate directories. It also creates each dynamic module in its own directory. You must therefore create directories for building each of your dynamic modules, separate from the directory for the application itself.

As an example, the ro sample demo has the following directory structure.

Parent Directory ┬ Application Build Directory
               │   ├ Source of static module
               │   └ OMakefile　
               ├ Build directory of dynamic module 1
               │   ├ Source of dynamic module 1
               │   └ OMakefile　
               ├ Build directory of dynamic module 2
               │   ├ Source of dynamic module 2
               │   └ OMakefile　
               …
               ├ Build directory of dynamic module N
               │   ├ Source of dynamic module N
               │   └ OMakefile　
               └ OMakefile

You must specify each of these build directories in SUBDIRS in order to target them for the build.

Creating an OMakefile for the cro Build

You must create an OMakefile with the settings for building cro in each cro build directory. The minimum required contents of the OMakefile for creating cro are as follows.

TARGET_MODULE   = Module1
MODULE_LIST     = ../App ../Module2
SOURCES         = module.cpp

include $(ROOT_OMAKE)/modulerules

build: $(DEFAULT_TARGETS)

Change the variables above as required to configure your cro build. Also change the TARGET_MODULE, MODULE_LIST, and SOURCES settings in accordance with your project.
Note: The value of TARGET_MODULE must match the directory name. Also, do not include the target module ("../Module1" in the example above) in MODULE_LIST.

Adding Code for cro File to Application's OMakefile

Specify an appropriate value for the MODULE_LIST variable in the application's OMakefile. Ordinarily, you should specify all the dynamic modules that the application uses.

MODULE_LIST     = ../Module1 ../Module2

This setting causes the CRS and CRR files to be created in images.

Storing CRO, CRS, and CRR Files in ROM-FS

The settings above generated cro, crs, and crr, so we must now store the generated files in ROM-FS. You can store cro and crs in ROM-FS in any format you wish, including compressed and archive formats. In contrast, there are strong restrictions on storing crr. You must store this directly below a crr directory that is directly under the ROM-FS root, without changing it in any way. The crr directory must not contain any file other than the CRR file.

If you automate this process using OMake, the application's OMakefile must include code similar to the following example.

MODULE_NAMES        = Module1 Module2
MODULES_ROOT        = ../

MODULE_CRO          = $(addprefix $(ROMFS_ROOT)/,$(addsuffix .cro,$(MODULE_NAMES)))
STATIC_CRS          = $(ROMFS_ROOT)/static.crs
STATIC_CRR          = $(ROMFS_ROOT)/.crr/static.crr
ROMFS_DEPENDENCIES  = $(MODULE_CRO) $`(STATIC_CRS) $`(STATIC_CRR)

foreach(TARGET, $(BUILDER.getTargets $(SUPPORTED_TARGETS)))
    foreach(module, $(MODULE_NAMES))
        src = $(file $(TARGET.getImageDirectoryOf $(MODULES_ROOT)$(module))/$(module).cro)
        dst = $(addprefix $(ROMFS_ROOT)/,$(addsuffix .cro,$(module)))

        $(dst) : $(src)
            cp $< $@

    $(STATIC_CRS): $(TARGET.getImageDirectory false)/$(TARGET_PROGRAM).crs
        cp $< $@

    $(STATIC_CRR): $(TARGET.getImageDirectory false)/$(TARGET_PROGRAM).crr
    	mkdir -p $(dirname $@)
        cp $< $@

You must change the values of variables between MODULE_NAMES and STATIC_CRR (inclusive) to appropriate values for your project. The example above assumes that TARGET_PROGRAM and ROMFS_ROOT are configured appropriately elsewhere.

Revision History

2012/06/22

Added a link to Guide to Developing a Build System (for High-Level DLLs).

2011/09/26

Added description of MODULE_ADD_DEBUG_INFO to Added Variables.
Added the Revision History section.

2011/08/03

Initial version.

CTR-06-0202-002-F
CONFIDENTIAL