preprpl[32|64] - Prepare RPL

Syntax

preprpl[32|64] -x <file> -o <file> -l <file> -r <rpl-name> \
               [-log <file>] [-v] [@<file>]

preprpl[32|64] [-o <file>] [-log <file>;] [-x <file>] \
               [-xall] [-xnot <file>] [-v] [@<file>;] [<file> ...]

Options

-o <file> Specify the output .o file. Default is pre_rpl.o.
-l <file>; Specify the output .a file.
-r <rpl-name> Specify the name of the final RPL/RPX.
-L<file> Search file in path.
-log <file> Emit a text log to the specified file.
-x <file> Export symbols specified in <file> (text, extension optional).
-xall Export all global non-weak loadable symbols. Not recommended; use rplexportall instead.
-xnot <file> Exclude symbols specified in <file> (text, extension optional).
-noar Do not generate library header.
-v Verbose reporting.
@<file> Insert <file> in the command line.
[<file> ...] List of object files which are also passed to the linker. Optional when using -x <file> -r <rpl-name> -l <file>.
-checknosda Deprecated. Pass this option to makerpl[32|64] if desired.
-e <symbol> Deprecated. Ignored.
-warnsti When passed, static initializers are allowed as exports with warning. Default: attempt to export a static initializer is an error.
-warnlinkonce When passed, symbols in linkonce sections are allowed as exports with warning. Default: attempt to export a linkonce symbol is an error.

Description

This Windows tool is provided in two flavors: preprpl32.exe and preprpl64.exe, for 32-bit and 64-bit operating systems, respectively.

preprpl[32|64] is called before linking. It generates an object (.o) file which must then be passed to the linker.

Optionally, preprpl[32|64] can generate an import library (.a) to which other modules can link.

The tool preprpl[32|64] streamlines the build process by generating the export object file (.o) and the import library file (.a) from an export definition file (via the “-x <file>” option).

The “pre-v1.0” method of invoking preprpl[32|64] with the same file list that is provided to the linker is still supported. In this mode, all application object files and system object files (such as coredyn.a, mtx.a, etc) must be passed to preprpl[32|64].

WARNING:
Nintendo strongly suggests that you do not export static initializers and linkonce symbols.

As of SDK 2.11.03, rplexportall and preprpl[32|64] have been modified to exclude static initializers and linkonce symbols because these symbols can cause problems if they are exported. You can read more information about linkonce symbols in the GHS documentation (see $GHS_ROOT/manuals/build_ppc.pdf). Static initializers are a problem because static initializers from a RPL will become imported if any other symbol from that RPL is imported. This could cause the static initializer to be recalled for every RPL that imports the static initializer.

Perhaps upon examination of your situation that you can determine that you want these exclusions. If so, you can manually add them back into your exports.def file and pass one or both of the new preprpl[32|64] options to allow them to be added to your RPL's exports (-warnsti and -warnlinkonce). However, we consider that these new options should only be used as a last resort.

If you have a static initializer and you want to remove it from your exports, see Removing a Static Initializer from the Exports.

Contact your local Nintendo developer support group for advice if you are unable to dispense with these symbols due to backward compatibility issues.
IMPORTANT:
The following descriptions reference the Examplemake demo package. The package demonstrates various aspects of the build system, including the latest RPL tool enhancements. The version of Examplemake included in the SDK is compatible with the current SDK. For comparison with older SDK versions, obtain the Examplemake package from your local Nintendo developer support group.

Exporting Symbols

When building RPX and RPL files, you export the symbols that other modules wish to access.

Consider the Examplemake demo program helloworld_rpl. In this example, the primary application hello.rpx is loaded first. The application implicitly loads (or “acquires”) the RPL world.rpl.

All modules export symbols. The exported symbols are specified in the hello.def and world.def export definition files.

The build process for each component invokes preprpl[32|64] before linking, and generates a .o file and a .a file. The .o file contains exported symbol information, making the symbols accessible to other RPX and RPL modules. The .a file contains import symbol information, used by other RPX and RPL modules to reference the exported symbols.

NOTE:
Only global, non-weak, data and functions may be exported.

Exporting Symbols Explicitly

The -x <file> option can be used with the -r <rpl-name> and the -l <rpl_name.a> arguments to generate an export object .o and an import library .a. By this method, preprpl[32|64] does not require any object files.

This is the method used in the helloworld_rpl demo. See the hello.def or world.def files in the demo for more information.

The default file extension for the <file> argument is .def.

C++ code is at a disadvantage in this scenario, given the mangling of symbols at link-time. The rplexportall script generates an export definition file (.def) from a list of object files. This generated file can be edited and then passed to preprpl[32|64]. For example:

$ rplexportall hello.o

Produces:

; Generated Export List

[CODE]
main                                    ; main
rpx_gethello                            ; rpx_gethello

[DATA]
hello                                   ; hello

Exporting Symbols Explicitly With Object Files

The -x <file> option will only export symbols listed in the specified text file. This is the method used in the helloworld_rpl demo. For information, see the hello.def or world.def files in the demo.

Exporting All Symbols

The -xall option will export all global, non-weak symbols from all listed .o files. While not generally useful, this method may be the most viable for C++ applications given the mangling of symbol names at link-time.

Excluding Symbols from the Export Process

The -xnot <file> option will exclude the symbols listed in the specified text file.

Export Conflicts

If you use the -xall option for an RPX, you may inadvertently export a symbol that conflicts with a symbol from an RPL. To resolve this, you can exclude the conflicting symbol using -xnot <file> for the RPX.

Removing a Static Initializer from the Exports

If you discover that you have a static initializer in your exports file, you can safely remove it if you have not released your module and if every other module that has used your module can be rebuilt. If that is incorrect, then you can occasionally neutralize potential problems with this technique:

  1. Examine the static initializer name, for example __sti___10_foobar_cpp_f5d9abb2. This static initializer is in the source file foobar.cpp. Also, all of the characters are legal C language characters.
  2. Change the name of the source file. For example, change it to foobar_fixed.cpp. This will rename your static initializer; make sure it does not get exported.
  3. Create a new C file. For example, call it phony_initializer.c. Make it C to avoid warnings from MULTI if you use C++.
  4. Create an extern "C" function with the old static initializer name and have it do nothing.
  5. Add the old static initializer to your exports file.
  6. If you are using SDK 2.11.03, pass the -warnsti option to preprpl.
  7. Recompile your module's sources and relink. Any module that imported the old static initializer will now call the version in phony_initializer.c and will not reinitialize your class objects.

Cross Referencing

Exporting and importing symbols simultaneously between two modules is supported. For more information, see the notes on RPX/RPL Cross-Referencing.

Example

The Examplemake demo program helloworld_rpl illustrates how to create RPX and RPL modules using preprpl[32|64]. For convenience, we will use the definitions below to describe the various parameters for building the example.

Definitions for preprpl[32|64] Commands for RPX and RPL

CAFE_TOOL_DIR $(CAFE_SDK_DIR)/system/bin/tool
LIB_DIR $(CAFE_SDK_DIR)/system/lib/ghs/cafe/$(BUILD_TARGET)

To create an RPX, the tool is used like this:

$(CAFE_TOOL_DIR)/preprpl64 -x hello.def -r hello.rpx -l hello.a -o hello_rpl_export.o

To create an RPL:

$(CAFE_TOOL_DIR)/preprpl64 -x world.def -r world.rpl -l world.a -o hello_rpl_export.o

There are no major differences between the preparation of an RPX versus an RPL.

See Also

RPX/RPL Overview
RPX/RPL Cross-Referencing
Building with Examplemake
makerpl[32|64]
rplexportall
dumprpl

Revision History

2013/12/13 New exclusions from preprpl[32|64].
2013/05/08 Automated cleanup pass.
2012/07/23 Removed references to old SDKs. Updated Examplemake references.
2011/10/19 Examplemake addition.
2011/02/21 Initial version.


CONFIDENTIAL