Building the RI From Sources
Description: This document describes how to use the development kit for the Java Card 3 Platform, Connected Edition, Version 3.0.2, to develop applet applications, web applications, servlets, and extended applets
Date: December 2009

C H A P T E R 13

Building the RI From Sources

This chapter describes how to build a customized Java Card 3 platform RI. This chapter is useful only if you have a source release of the development kit. The src folder under JC_CONNECTED_HOME contains all of the source files for the RI including VM code, and all tools (such as the packager and installer). You can modify or add to these files and build a customized Java Card 3 platform RI according to their specific requirements. The following actions are possible reasons a developer might have for building a custom RI:

- Add additional classes or packages if a proprietary API or other implementation classes are used.

- Fine tune the existing sources.

- Update tools to work with target platform.

- Romize the applications. Romizing masks the applications into the `cjcre.exe`.

This chapter contains the following sections:

- Prerequisites to Building the RI

- Contents of JC_CONNECTED_HOME\src Folder

- Running the ROMizer Tool From the Command Line

- Building a Custom cjcre.exe

##

Prerequisites to Building the RI

Before building the RI, the following software must be installed on the system:

- MinGW

- JDK 6

- Ant

See Chapter 2 for more details on these requirements.

##

Contents of JC_CONNECTED_HOME`\src` Folder

The following describes the contents of the `src` folder.

- api - Contains all of the `.java` files required to build a custom RI. If a new package must be added, it is added under this folder.

- tools - Contains the source code of all shipped tools organized in separate folders. To make a tool to work with a target platform, edit the code of the corresponding tool.

- romized_apps - Contains the source files for the CardManager.

- vm\c - Contains the source files of core VM.

- vm\h - Contains the header files of core VM.

- vm\lib - Contains configuration files `config.properties` and `system`. See Chapter 12 for additional details.

- `vm\ignore.list` - If a class must be excluded from romization, add its name in this file.

- build.xml - The main file used to build the tools and `cjcre.exe` in a single step.

- aplImpl.jar

- bat.template

- crypto.jar

##

Running the ROMizer Tool From the Command Line

When building a custom RI, the ROMizer tool takes system class files and application modules as input and creates a ROM image of these in an output ROM image file. The ROMizer tool converts the class files into C code, which is often called a ROM mask or simply a mask. For applications, the ROMizer tool stores non-class files in appropriate directories in the internal Java Card 3 platform file system, so that these files are available during the execution of the application. See Building a Custom cjcre.exe for detailed description of using the ROMizer tool.

The command line interface for the ROMizer has the following syntax:

    romizer.bat subcommand [options]

The following is a list of the subcommands for the ROMizer:

- `romize` - Romizes the system class files and application modules

- `copyright` - Displays detailed copyright notice

- `help` - Displays information about the ROMizer command

### `romize` Subcommand

Use the `romize` subcommand and its options to romize the system class files and application modules. Options are used with the `romize` subcommand to specify files and directories.

#### `romize` Subcommand Options

TABLE 13-1 identifies the `romize` subcommand options and provides their descriptions.

TABLE 13-1 `romize` Subcommand Options
Option | Description
--- | ---
`-`a apps-filename or `--apps` apps-filename | Specifies the file that contains the list of applications to be masked.
`-`C command-options-file or `--commandoptionsfile` command-options-file | Optional. Specifies a file containing command line options.
`-e` EEPROM- filename or `--e2pfile` EEPROM- filename | Specifies the file where the initial `eeprom` file is written.
`-o` ROM-output-filename or `--out` ROM-output-filename | Specifies the file where the mask is written.

#### `romize` Subcommand Example

Either of the following commands will run the ROMizer tool:

    romizer.bat romize -o ROM-output-filename -e EEPROM- filename -a apps-filename

or

    romizer.bat romize --out ROM-output- filename --e2pfile EEPROM -filename \
    	--apps apps-filename

In the previous examples, the following options are used:

- `-o` (or `--out)` - Must be followed by the path to the output file where the mask is written`.` For example:

    --out MyROMJava.c

See Romizer Tool Output for a description of the ROM output file.

- `-e` (or `--e2pfile)` - Must be followed by the path to the initial `eeprom` file`.` For example:

    --e2pfile myeeprom.eeprom

- `-a` (or `--apps)` - Must be followed by the path to the applications list file which contains the list of applications to be masked. For example:

    --apps myapps.list.

See Example Contents of Apps List File for a description of the configuration file.

### `copyright` Subcommand

The `copyright` subcommand displays the detailed copyright notice. There are no options associated with this subcommand.

### `help` Subcommand

The `help` subcommand displays information about the ROMizer. Options are used with the `help` subcommand to specify the information that is displayed about each sub-command.

For example, to see detailed help about the ROMizer tool, type:

    romizer.bat help romize

### Apps list File Contents

The apps list file contains information about applications that need to be romized. All system classes and applications must be provided as input to the `romizer` in compressed files (`.jar`, `.war`, or `.zip` files).

Each application file must be specified in the apps list file on a new line. Each application module entry in the configuration file must provide additional information as noted in the following format example:

    application-module -t <web|classic-applet|extended-applet|classic-lib| \
    	extension-lib> -s signature-file -n module-name

In the previous example, the following parameters are used:

- application-module is the `.jar`, `.war`, or `.zip` application module file.

- `-t` followed by `web`, `classic-applet,` `extended-applet,` `classic-lib`, or `extension-lib` to identify the type of application being romized.

- `-s` followed by the name of the properties file that contains the BASE64 encoded certificate and signature, where signature-file represents the file name.

This file is a simple properties file containing the following properties as name-value pairs:

- `signature`=base64 encoded signature

- `certificate`=certificate to validate this group and digest

- `-n` followed by the module name that will be referenced by `cjcre.exe` for this application module.

The following is an example of an entry in the configuration file:

    HelloWorld.war -t web 	-s mykey1.txt -n helloapp

#### Example Contents of Apps List File

The following is an example of the contents of an apps list file:

    HelloWorld.war -t web 	-s key1.txt -n helloapp
    GCFClient.war -t web -s key2.txt -n gcfapp

### Romizer Tool Output

The output created by running the ROMizer tool is a preliminary EEPROM file and a C language source file that contains the ROM image of the input file including the following:

- Java class files that contain the API implementation

- Implementation of containers

- Applications selected by the user for romization

##

Building a Custom `cjcre.exe`

The `build.xml` provided in the src folder build everything including tools and `cjcre.exe`. This section gives details on how the `cjcre.exe` is generated.

Developers can modify the RI by adding or modifying the reference implementation code and using the ROMizer tool. RI consists of .`java` and C source files. The core VM is written in C programming language and rest of the API and supported implementation is written in the Java programming language. The ROMizer tool converts the class files into C code, which is often called the ROM mask or simply the mask. Then all the C source code is compiled to an executable to generate `cjcre.exe.`

The ROM image can include any supported application files (web, extended-applet, classic-applet, extension library, and classic library). ROMized applications can be instantiated without requiring download after the runtime environment starts up. The ROMizer tool takes system class files and application module as input and creates a ROM image of these in an output ROM image file.

For applications, the ROMizer tool stores the non-class files in appropriate directories in the internal Java Card 3 platform file system, so that these files are available during the execution of the application.

FIGURE 13-1 illustrates the procedure of building the `cjcre.exe` from sources.

FIGURE 13-1 Building cjcre.exe From Sources

Java files are compiled into class files using the `javac` compiler. Details of applications to be ROMized are listed in a text file. The class files and the list file are given as input to the `romizer.bat` tool (see Preprocessor Symbols to Customize the VM). By default `romizer.bat` generates `ROMJava.c`, a `C` file that contains the information about all classes and applications.

The GNU C compiler (`gcc`) is used to build the final executable. The generated `ROMJava.c` and the rest of the `C` files are compiled using `gcc`, which generates `cjcre.exe`. Use the provided ANT build file to build custom `cjcre.exe`. See Build a Custom RI From the Command Line.

### Preprocessor Symbols to Customize the VM

The following preprocessor symbols can be used to customize the Java Card VM:

- `INCLUDEDEBUGCODE=0`

- `TRACE_EXCEPTIONS_NATIVE=1`

- `INCLUDE_FIREWALL_DEBUG_CODE=0`

- `ENABLE_JAVA_DEBUGGER=1`

Enables the `kdwp` code. Default is 1. If set to 0, then `cjcre` can not be used to debug the applications.

- `ENABLE_LOGGING=1`

Enables the logging messages that are printed by using `-loggerlevel=`<value>. Default is 1. If set to 0, then even if `-loggerlevel` is set to `all`, no logging messages are printed from native code.

- `APDU_PROTOCOL_T=0`

Controls the protocol that will be supported by cjcre. default is t=0. Valid values are 0, 1 for T=0, T=1 respectively.

- `APDU_INTERFACE=0`

Contacted or contactless or both. Valid values are 0, 1, 2 for contacted, contactless and Dual respectively

### Build a Custom RI From the Command Line

1. Edit the files or add more files.

2. Update the tools source code if required.

3. From command line navigate to the `src` folder and run the `ant` command.

If there is a apps list file that contains the list of applications for ROMization, set the property `apps_file_for_romizer` while running the `ant` command as shown:

    	ant -Dapps_file_for_romizer=path-to-apps-file

The `ant` command creates the JC_CONNECTED_HOME`\custom_build` folder with a `bin` and `lib` folder under it.

- The `bin` directory contains the new `cjcre.exe` and all of the other tool’s `.bat` files.

- The `lib` folder contains the .`jar` files and config files.

JC_CONNECTED_HOME`\custom_build\bin` and
JC_CONNECTED_HOME`\custom_build\lib` are similar to JC_CONNECTED_HOME`\bin` and JC_CONNECTED_HOME`\lib`, except that `custom_build` contains the binaries from the updated source code.

### Test the Custom RI

Use the following command to run the new `cjcre.exe` file stored in JC_CONNECTED_HOME\`custom_build\bin`.

    JC_CONNECTED_HOME\custom_build\bin\cjcre.exe [options]

See Chapter 5 for a description of the available options.

Files created as a result of running or building the custom RI are stored in the JC_CONNECTED_HOME\`custom_build\bin` and JC_CONNECTED_HOME\`custom_build\lib` directories. These directories are created the first time the RI is built and will be over written every time the RI is built.

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.