CTR-SDK Build System Manual (for DLLs)

(2012/06/22)

Introduction

About This Document

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

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 files. See the DLL Manual for a basic introduction to CRO files.

Notation Used in This Document

Content in shaded boxes, as shown below, indicate 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 builds the CRO file.

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 looks for definitions in the modules specified by MODULE_LIST. If the build system cannot find definitions in any module, it raises 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.

Specified Value	Description
`SYMBOL`	The export type is a name.
`INDEX`	The export type is an index.
`OFFSET`	The export type is an offset.

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 requires that the module referencing the symbol must be built no earlier than 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 enables you to build each module whenever you like. However, 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`

Place the information required to debug the CRO object in the CRR object. The debugging information for the CRO object must be placed in the CRR object in order to debug the CRO source in the debugger. Setting MODULE_ADD_DEBUG_INFO to true allows debugging information to be placed in the CRR object, allowing the CRO source code to be debugged in the debugger. Setting MODULE_ADD_DEBUG_INFO to false does not allow the CRO source code to be debugged in the debugger. However, because it does not contain debugging information, CRR is smaller in size. The initial value is true.

Sample Configuration:

MODULE_ADD_DEBUG_INFO    = false

Settings Required for Build

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

Creating Build Directories for CRO Files
Creating an OMakefile for the CRO Build
Adding Code for CRO Files to the Application's OMakefile
Storing CRO, CRS, and CRR Files in ROM-FS

Creating Build Directories for CRO Files

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.

For 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 to target them for the build.

Creating an OMakefile for the CRO Build

You must create an OMakefile with the settings for building CRO files in each CRO build directory. The minimum required contents of the OMakefile for creating CRO files 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 Files to the 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 files, so you must now store the generated files in ROM-FS. You can store CRO and CRS files in ROM-FS in any format you want, including compressed and archive formats. In contrast, there are strong restrictions on storing the CRR file. You must store it 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 files 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-H
CONFIDENTIAL