SDK Build Switches

# Build Switches

## Environment Variables Required When Building the SDK

The environment variables in the following table must be set before building the TWL-SDK tree. The default value is used if a variable is undefined. For more information about setting each build switch, see the Build Switch Usage Table.

TWLSDK_ROOT NITROSDK_ROOT * Important | Specifies the directory where the TWL-SDK is installed (the directory into which `$TwlSDK` is extracted). Default value: `C:/TwlSDK`

TWLSDK_PLATFORM
* Important

Specifies the build platform.
Use this environment variable to compile only the code you need.
For example, if you are using TWL-SDK to develop applications exclusively for TWL, set the environment variable `TWLSDK_PLATFORM` to `TWL` (TWLSDK_PLATFORM=TWL). The compiler will then generate TWL code only, not unneeded NITRO code.
When not specified, the build will halt with an error.

TWL | Generates code for TWL.
NITRO | Generates code for NITRO.
ALL | Generates code for both TWL and NITRO.
TWL NITRO

Default value: Unspecified

CWFOLDER_TWL
CWFOLDER_NITRO

Specifies the CodeWarrior installation directory.
`CWFOLDER_NITRO` will be configured automatically if CodeWarrior for NITRO is installed.
When making this setting using cygwin bash, the directory must be enclosed in single quotes as follows.
`% export CWFOLDER_NITRO='D:/Program Files/Freescale/CW for NINTENDO DS V2.0'`
When making this setting using a Windows environment variable, the specification takes the following form.
`D:/Program Files/Freescale/CW for NINTENDO DS V2.0`
Both `/` and `\` are accepted as path delimiters.
Default value: None (Usually set when CodeWarrior is installed)

LM_LICENSE_FILE | Specifies the license file path for CodeWarrior. Default value: None (Usually set when CodeWarrior is installed)
IS_TWL_DEBUGGER_DIR IS_NITRO_DIR | This is the IS-TWL-DEBUGGER installation folder. It is automatically set when IS-TWL-DEBUGGER is installed. If this environment variable exists, the IS-TWL-DEBUGGER-related libraries will be linked automatically. Default value: None (Usually set when IS-TWL-DEBUGGER is installed)

## Build Switches When Building the SDK

The build switches used to change the build conditions for the `TwlSDK` tree are shown below. Normally, these values are set by specifying them as parameters to the make command (for example, `make TWL_DEBUG=TRUE`) and including them within makefiles. However, they can also be set as individual environment variables. The default value is used if a variable is undefined. For more information about where each build switch can be set, see the Build Switch Usage Table.
The values of the TWL environment variables (`TWL_*`) will be given priority if changes are made to the following environment variables. (If `TWL_PROC=ARM9` and `NITRO_PROC=ARM7` are both present within a makefile, `TWL_PROC` is set to `ARM9`.)

TWL_PROC
NITRO_PROC
* No change necessary

Sets which processor code should be generated for the ARM9 (main processor) and the ARM7 (subprocessor).
Use the default value.

ARM9 | Generates code for the ARM9 (main processor). Default Value
ARM7 | Generates code for the ARM7 (subprocessor).

TWL_ARCHGEN

For TWL code, sets whether to generate TWL-exclusive code or NITRO/TWL hybrid code.
This build switch can be set with the build system.
Specifically, set whether LIMITED or HYBRID code should be built.
Reference this build switch in the makefile after `commondefs`.

LIMITED | Generates TWL-exclusive code.
HYBRID | Generates NITRO/TWL hybrid code. Default Value
ALL | Generates both LIMITED and HYBRID code.
LIMITED HYBRID

TWL_CODEGEN
NITRO_CODEGEN

Sets whether binary code generated by the compiler and assembler should use the ARM or Thumb instruction set.
If there is no explicit setting in the source, the compiler and assembler generate the code according to these values.
Reference this build switch value in the makefile after `commondefs`.

ARM | Generates ARM code. Default Value
THUMB | Generates Thumb code.
ALL | Generates both ARM code and Thumb code.
ARM THUMB

TWL_DEBUG
TWL_RELEASE
TWL_FINALROM
NITRO_DEBUG
NITRO_RELEASE
NITRO_FINALROM
* Important

Select from the following build types: `DEBUG`, `RELEASE`, and `FINALROM`.
When the `make` command is executed, the compile options and the linked libraries will change according to this setting.
Unlike other variables, this variable is specified by setting one of the build types to `TRUE`.
See `$TwlSDK/man/en_US/information/compiletarget.html` (compile target explanation) for more information about these three types.
Default value: When not specified, the RELEASE version will be built.

TWL_STD_PCHDR TWL_NO_STD_PCHDR NITRO_STD_PCHDR NITRO_NO_STD_PCHDR | When a value is set for `TWL_STD_PCHDR`, the build system precompiles `$TwlSDK/include/twl.h` and loads the result during the build. This should result in a faster build. To temporarily suppress this compile, set a value for `TWL_NO_STD_PCHDR`. Default value: TWL_STD_PCHDR=True

TWLSDK_LANG
NITROSDK_LANG

You can switch the `TwlSDK` compile options between Japanese and English.
For Japanese, the `-enc SJIS` option will be set. For English, the `-enc ascii` option will be set.

jp | Japanese [Default value]
en | English

TWL_ROMSPEED
NITRO_ROMSPEED

When the default RSF file is used, the `RomSpeedType` parameter in the Property section is assigned a value. The value of the `MAKEROM_ROMSPEED` symbol passed to the `makerom.TWL.exe` tool is used. When an original file is used instead of the default RSF file, it is ignored. For information on the `RomSpeedType` parameter, see the documentation for the `makerom.TWL.exe` tool. MROM cannot be used with TWL.

1TROM | One-time PROM
MROM | Mask ROM
UNDEFINED | None specified [Default value]

TWL_COMPRESS NITRO_COMPRESS * Important | When a value is specified, the STATIC/OVERLAY segment is compressed after the link is completed. Default value: None (no compression)
TWL_DIGEST NITRO_DIGEST | This build switch is enabled only for applications. It is disabled when building the SDK. If a value is set, code for a DS Single-Card Play child program that uses overlays will be built. Default value: None
TWL_PROFILE NITRO_PROFILE | If a value is set, the `-profile` option is added when compiling. This is primarily used during debugging so that input and output of each function can be traced during execution. For additional details, see the `OS_DumpCallTrace` function. Default value: None (`-profile` option is disabled)

TWL_MEMSIZE
NITRO_MEMSIZE
* No change necessary

Specifies the main memory size of TWL compile targets.
This build switch specification method was retained for backward compatibility.
Because it does not require you to rebuild the SDK, we recommend using `OS_EnableMainExArena` instead. Use the default value.

TWL_MEMSIZE
16M | 16 MB [Default value]
32M | 32 MB

NITRO_MEMSIZE
4M | 4 MB [Default value]
8M | 8 MB

TWL_NO_OPT_G NITRO_NO_OPT_G | When a value is set, the `-g` option used to specify normal compilation and linking is removed. Expect a reduction in linking times, which can be an issue in large projects. Default value: None (-g option enabled)

TWL_SVC_WAITVBLANK_COMPATIBLE
NITRO_SVC_WAITVBLANK_COMPATIBLE

Define this to NOT automatically replace the `SVC_WaitVBlankIntr` function call with the `OS_WaitVBlankIntr` function call. Note that the `SVC_WaitVBlankIntr` function will not release the resource to a low-priority thread. Depending on how this is used, some problems may occur. If a system call must be used as it was previously, it should only be used after thorough verification.
Note: This replacement is made using a `#define` statement inside a header file, so it will be valid only after the TWL-SDK is rebuilt. If these environment variables are defined with `make`, `SDK_SVC_WAITVBLANK_COMPATIBLE` will be defined, and you can find it in the source through `#ifdef`/`#endif` statements.
This is not defined by default, so the `SVC_WaitVBlankIntr` function call is automatically replaced with the `OS_WaitVBlankIntr` function call. Default value: None

CW_LIBFP

Specify one of the following floating-point libraries to the CodeWarrior compiler.
If nothing is specified, the first value shown in the following list is used. For details on the differences in performance between the libraries, see the CodeWarrior reference.

FP_fastI_v5t_LE.a | fast IEEE [Default value]
FP_fixedI_v5t_LE.a | fixed-rounding IEEE
FP_fullI_v5t_LE.a | full IEEE
FP_flush0_v5t_LE.a | flush to zero (not IEEE compatible)

## Build Switches Set in the SDK Makefile

The following table shows the build switches used to configure the build conditions for each directory in the TWL-SDK makefile.
It also specifies the source locations and makefiles to concatenate.
When switches are not configured, default values are used.

TARGET_PLATFORM
* Important

Sets whether to include the makefile for the build platform.
For example, to build a demo only for TWL, include `TARGET_PLATFORM=TWL` in the makefile. This will cause the demo to be built only in TWL mode, and will prevent it from being built in NITRO mode.
If this setting is not present in a makefile, code is generated for every build.

TWL | Only build when the build target is TWL.
NITRO | Only build when the build target is NITRO.
ALL | Always build. (Build when the build target is TWL or NITRO.) [Default value]
TWL NITRO

TWL_BUILD_TYPE NITRO_BUILD_TYPE Overwriting prohibited | `Debug`, `Release`, or `Rom` is set as the target build type. To reference the build type set in the makefile, reference this variable after `commondefs`.

DEFAULT_COMP_ARM7
* Important

The ARM7 component to be used is configured within the makefile.
For more information on ARM7 components, see `$TwlSDK/docs/TechnicalNotes/AboutComponents.pdf`.

mongoose | Uses the mongoose component for NITRO ROMs, and the mongoose.TWL component for HYBRID ROMs.
racoon | Uses the racoon.TWL component for LIMITED ROMs.
ferret | Uses the ferret.TWL component for LIMITED ROMs.

Default value: mongoose for NITRO or HYBRID ROMs, racoon for LIMITED ROMs

SUBDIRS * Important | Enumerates the directories you want the make process to concatenate. Default value: None
SUBMAKES | Enumerates the makefiles you want the make process to concatenate. Default value: None

SRCS
* Important

Enumerates the source files you want to compile and assemble.
The `make` command tries to generate an object file with the compiler or assembler of the programming language shown in the following table, according to the extension of each file.

Extension | Programming Language
.c | C
.cpp | C++
.s | Assembler

Default value: None

SRCS_OVERLAY For overlay | Enumerates the source files you want to compile and assemble. The object files generated from the files specified here are registered as belonging to an OVERLAY group.
SRCDIR | Specifies the source-file directory. Default value: ./src (Indicates a relative path to src from the make directory)
INCDIR | Specifies the directory if there are private include files (module-specific include files). Default value: ./include
OBJDIR BINDIR LIBDIR Rewrite prohibited | Specifies the directory where the `make` command outputs temporary files. This specification is used often in a source tree, so be careful changing the assignment in individual directories.
LCFILE | Specifies your own link command file (`.lcf`). Default value: $TwlSDK/include/nitro/ARM9.TS.lcf
LCFILE_SPEC | Specify the configuration file to use as the base to automatically generate a link command file with the `makelcf` command. Default value: Unspecified
ROM_SPEC | Specifies the file that describes the contents of the ROM file. This file will be passed to the `makerom` command, and the ROM will be generated based on the configuration of this file.

TARGET_BIN
* Important

Specifies a target file in SRL or TEF format.
It compiles or assembles the source files specified by SRCS and links the resulting object files, making them the target files. A TEF file will be created automatically if an SRL file is specified as the target.
The following values cannot be set for this variable.

- Values that include hyphens ("`-`")
- Values that begin with an underscore ("`_`")
- Values that begin with a number

TARGET_LIB | Specify this to create a library file. It compiles or assembles the source files specified by SRCS and links the resulting object files, making them a library. Normally, `TARGET_BIN` and `TARGET_LIB` are not configured at the same time.
TARGET_OBJ | Specify this to create an object file as a target. This is not normally used. In the library, this is used when `crt0.c` is compiled and installed as a library.
TARGETS Rewrite prohibited | Targets to which the relative path was added to `TARGET_BIN` and `TARGET_LIB` are set up automatically. The storage directories for `.srl` and `.a` files change depending on the `TWL_PLATFORM` and `TWL_DEBUG/TWL_RELEASE/TWL_FINALROM` settings. This macro was prepared to absorb this change.
INSTALL_TARGETS | Enumerates the files you want to install. The TARGETS described above will function in this setting. Default value: None
INSTALL_DIR | Specifies the installation directory. Default value: None
LINCLUDES | Specifies the directory if there are other include files. Default value: None
LLIBRARY_DIRS LLIBRARIES | If there are other library files, this enumerates their directory with `LLIBRARY_DIRS` and the library files with `LLIBRARIES`.
LDIRT_CLEAN LDIRT_CLOBBER | Specifies the files to delete along with object files when executing the `make clean` or `make clobber` command. With `make clean`, all files specified with `LDIRT_CLEAN` are deleted. With `make clobber`, all files specified with `LDIRT_CLEAN` and `LDIRT_CLOBBER` are deleted.
MAKELCF_FLAGS | Define this build variable when you want to give your own additional run options to `makelcf`. Default value: None
MAKEROM_FLAGS | Define this build variable when you want to give your own additional run options to `makerom`. Default value: None

FORCE_DISABLE_IS_NITRO_DEBUGGER

Although debugging features are not available when using IS-NITRO-DEBUGGER or IS-NITRO-EMULATOR, this option conserves the amount of memory used.
Define only when debugging with IS-TWL-DEBUGGER (software/hardware).
No default value is defined. This allows for all debugging features installed on the build PC to be used.
Default value: None

## Build Switch Usage Table

This table indicates where the SDK build switches can be set.
It includes only the `TWL_*` build switches, but the same information applies to the `NITRO_*` switches.

#### Environment Variables Required When Building the SDK

Build Switches | Command Line | makefile (before `commondefs`) | makefile (after `commondefs`) | Environment Variables | Initial Value
TWLSDK_ROOT | W | W | R | W | C:/TwlSDK
TWLSDK_PLATFORM | W | W | R | W | -
CWFOLDER_TWL | W | W | R | W | -
LM_LICENSE_FILE | W | W | R | W | -
IS_TWL_DEBUGGER_DIR | W | W | R | W | -
WR = Can be changed and referenced W = Can be changed R = Can be referenced — = Cannot be used

#### Build Switches When Building the SDK

Build Switches | Command Line | makefile (before `commondefs`) | makefile (after `commondefs`) | Environment Variables | Initial Value
TWL_PROC | W | W | - | W | ARM9
TWL_ARCHGEN (TWL-exclusive) | W | W | WR | W | HYBRID
TWL_CODEGEN | W | W | WR | W | ARM
TWL_DEBUG | W | W | - | W | -
TWL_RELEASE | W | W | - | W | TRUE
TWL_FINALROM | W | W | - | W | -
TWL_STD_PCHDR | W | W | - | W | True
TWL_NO_STD_PCHDR | W | W | - | W | -
TWLSDK_LANG | W | W | W | W | jp
TWL_ROMSPEED | W | W | W | W | UNDEFINED
TWL_COMPRESS | W | W | W | W | -
TWL_DIGEST | W | W | W | W | -
TWL_PROFILE | W | W | W | W | -
TWL_PROFILE_TYPE | W | W | W | W | -
TWL_MEMSIZE | W | W | - | W | 16M
TWL_NO_OPT_G | W | W | W | W | -
TWL_SVC_WAITVBLANK_COMPATIBLE | W | W | W | W | -
CW_LIBFP | W | W | R | W | FP_fastI_v5t_LE.a
WR = Can be changed and referenced W = Can be changed R = Can be referenced — = Cannot be used

#### Build Switches Set in the SDK Makefile

Build Switches | Command Line | makefile (before `commondefs`) | makefile (after `commondefs`) | Environment Variables | Initial Value
TARGET_PLATFORM | - | W | R | - | ALL
TWL_BUILD_TYPE | - | - | R | - | -
DEFAULT_COMP_ARM7 | - | W | R | - | mongoose for NITRO or HYBRID ROMs, racoon for LIMITED ROMs.
FORCE_DISABLE_IS_NITRO_DEBUGGER | - | W | R | - | -
WR = Can be changed and referenced W = Can be changed R = Can be referenced — = Cannot be used

TWL-06-0010-001-C
CONFIDENTIAL