Build Environment Procedures


This section describes the procedures for building the PJAE. There are three main steps to using the PJES build environment:

Select the appropriate configuration options.

The table in the next section describes the configuration options that are available at build time. Many of these options provide a mechanism for balancing memory consumption against functionality.

Run the PJES build environment to generate a PJAE.

The PJES build environment is based on a set of makefiles that compiles the different Java, C and assembly source code files and generates a specific configuration of the PJAE for a target system.

Run a Java application with the PersonalJava application launcher.

Each sample implementation includes a pair of platform-dependent invocation tools for running Java software. See Using the PersonalJava emulation environment for a description of how to use the PersonalJava invocation tools and how to use debugging and profiling utilities with the PJAE.

Configuring the PJES Build Environment

The PersonalJava Application Environment Specification describes a set of packages and classes that are optional. The PJES build environment has a mechanism for building different configurations of the PJAE that adhere to this specification and provide different levels of API functionality. For example, if an implementation needs java.sql then the PJES build environment can be configured to build a PJAE that includes an implementation of the java.sql package.

java.awt Notes

The PersonalJava Application Environment Specification has different levels of implementation support for the classes and methods in java.awt. However, the PJES build environment does not include configuration options for java.awt. The java.awt.peer implementation in the PJAE supports the minimum requirements of the specification. The one exception to this is that FileDialog is listed as optional in the specification but is included in the current implementation.

java.security Notes

The PersonalJava Application Environment Specification indicates that java.security and java.security.interfaces are optional. The PJES build environment does not include a configuration option for these packages because the PJES reference implementation does not include implementations of them. The INCLUDECODESIGNING configuration option controls whether a PJAE implementation includes the optional code signing feature. The implementation for code signing is in sun.pjava.security, but that is not a public API.

Configuration Options

This section describes the configuration options that a licensee can select to use the PJES to build a specific configuration of the PJAE. The table below describes these configuration options. See Build Procedures for a description of how to use these configuration options with the gnumake command.

PJES Build Environment Configuration Options
CategoryOptionTypeDefaultDescription
Build Environment JAVATOP string Microsoft Windows 95/NT:
  C:/JDK1.1.5

Solaris:
  /usr/local/java/jdk1.1.5/solaris

The location of the top-level directory of a separate JDK used to build the PJAE.
ROMIZE boolean false If true, then the class files in classes.zip are ROMized by converting them to an object file format for linking with the PersonalJava image.
SUPPORTPROFILER boolean true for debug builds,
false for nodebug builds
If true, then include everything necessary to support profiling.
CLASSDEBUGINFO boolean true for debug builds,
false for nodebug builds
If true, include the code necessary to interpret class debug information (line numbers, etc.)
DEBUGCLASSES boolean true for debug builds,
false for nodebug builds
If true, compile the system classes with debugging information.
PJEEDIR string

install/
  PRODUCT
  [_rom]
  VERSION
  STATUS
  -BUILD
  -bin
  -PLATFORMNAME
  [BUILDLOCALE]
  -shelldate

example:
  install\
  /pjee3_0alpha\
  -q-bin-solsparc\
  -Oct_30/

The name of the sub-directory in install for building versions of the PJEE.
ROMIZEFILES boolean true If true, then the implementation will include support for the ROM file system. This includes using the JavaDataCompact and Stuffer tools, and including support for sun.io.RandomAccessROMFile and the routines in src/share/sun/jdc/romfiles.c.

See ROM File System for a description of the ROM file system.

See Adding Data Files for a description of how to add data files to the list of files that will be stored in the ROM file system.

USESTUFFER boolean true (Solaris only.) If true, then using JavaDataCompact is a two-step process. The second step is to stuff the .o file(s) with the contents of the data files that are stored in the ROM file system.
Virtual Machine CLOOP boolean true for debug builds,
false for nodebug builds
If true, then the implementation will use the C version of the interpreter loop instead of the hand optimized assembler version.

Note: For information on obtaining assembly language interpreter loops that have been optimized for specific CPUs, contact Java Technology Licensee Engineering.

Optional Classes INCLUDERMI boolean false If true, then the implementation will include support for java.rmi.
INCLUDESQL boolean false If true, then the implementation will include support for java.sql. Implies INCLUDEMATH.
INCLUDEMATH boolean false If true, then the implementation will include support for java.math.
INCLUDEZIPEXTRAS boolean false If true, then the implementation will include support for the optional parts of java.util.zip.
INCLUDECODESIGNING boolean false If true, then the implementation will include support for code signing. Implies INCLUDEMATH.
BUILDLOCALE string en_US Defines the locale to build. Currently supported:
en_US  - English US
ja     - Japan
ALL    - all locales

Note: country is optional. See Adding a Locale for a description of how to add support for a specific locale.

DEBUGAGENT boolean true for debug builds,
false for nodebug builds
If true, then the build environment includes support for the sun.tools.debug debug agent. Implies INCLUDEZIPEXTRAS.

See the document Using the PersonalJava emulation environment for a description of techniques for debugging and profiling Java software for the PJAE.

FILEIOPKG string file
file
Build the file IO classes in java.io with an implementation based on the native file system.

rom
Build the file IO classes in java.io with an implementation based on the ROM file system. On startup, the java.home property should point to /javahome which will be used as the search base for locating files.

Be sure to include all the necessary property files in the ROM file system when building. See Adding Data Files for a description of how to add data files to the list of files that will be stored in the ROM file system. Implies ROMIZEFILES=true.

url
Build the file IO classes in java.io with an implementation based on the URL classes in java.net. On startup, the java.home property points to a URL that will be used as the search base for locating files.

null
Build java.io without the optional file IO classes. This option will cause all file searches performed by the class library to fail.

See the PersonalJava Application Environment Specification for a description of the optional classes in java.io.

USETRUFFLE boolean true If true, then the implementation will be built with Truffle. If false, then the implementation will be built with the old platform-based peers.
Remote Class Loading REMOTECLASSLOADING boolean false If true, then the implementation will include support for remotely loading core classes from Zip files on a well known server.
REMOTERMI boolean true if REMOTECLASSLOADING is enabled. If true, then the build environment will bundle the files for supporting java.rmi into a Zip file that can be loaded remotely. Implies REMOTECLASSLOADING and INCLUDERMI.
REMOTESQL boolean true if REMOTECLASSLOADING is enabled. If true, then the build environment will bundle the files for supporting java.sql into a Zip file that can be loaded remotely. Implies REMOTECLASSLOADING, INCLUDESQL and INCLUDEMATH.
REMOTEMATH boolean true if REMOTECLASSLOADING is enabled. If true, then the build environment will bundle the files for supporting java.math into a Zip file that can be loaded remotely. Implies REMOTECLASSLOADING and INCLUDEMATH.
REMOTEAGENT boolean true if REMOTECLASSLOADING is enabled. If true, then the build environment will bundle the files for supporting the sun.tools.debug debug agent into a Zip file that can be loaded remotely. Implies REMOTECLASSLOADING and DEBUGAGENT.

Estimated Memory Requirements

The table below describes the relative memory requirements for the configuration options that represent optional parts of the PersonalJava class library. These are nominal statistics based on ROMized builds for Solaris/SPARC. Each statistic is based on a comparison with a base-level build without any optional components. The actual memory requirements for a given platform should be measured empirically. See Determining Memory Requirements for a description of how to generate memory statistics for a build.

OptionValueEstimated Additional Memory
INCLUDECODESIGNINGtrue0.374 MB
INCLUDEMATHtrue0.070
INCLUDERMItrue0.287
INCLUDESQLtrue0.145
INCLUDEZIPEXTRAStrue0.032
REMOTECLASSLOADINGtrue0.003
FILEIOPKGfile0.032
 rom0.034
 url0
 null0

Build Procedures

The following sections describe how to use and modify the PJES build environment.

Building a PJAE Target

The table above describes a set of macro definitions that are contained in the PJES build environment's makefiles. The values of these macro definitions can be changed to select different configuration options by passing command-line options to the gnumake command. The example below builds the PJAE with a configuration option:

  1. Change the shell's current directory to the directory containing the platform-dependent makefiles.
    % cd build/platform
    

  2. Build the PJAE target. This example builds an optimized version of the PJAE with ROMized class files.
    % gnumake ROMIZE=true nodebug
    

Build Commands

The following table describes the main build commands for the PJES build environment.

Build Commands
CommandDescription
gnumake all Builds both the debug and nodebug build targets based on the current set of configuration options.
gnumake debug Builds a version of the PJAE in build/platform directory that contains debug capabilities. This includes the pjava_g and pappletviewer_g invocation tools with symbol tables and, for non-ROMized builds, a classes_g.zip file without symbol tables.

Sets the following configuration options to true:

  • DEBUGAGENT

  • CLASSDEBUGINFO

  • CLOOP

  • DEBUGCLASSES

  • SUPPORTPROFILER

See Using the PersonalJava emulation environment for a description of techniques for debugging and profiling Java software.

gnumake nodebug Builds a version of the PJAE in build/platform directory. This includes the pjava and pappletviewer invocation tools and, for non-ROMized builds, a classes.zip file without symbol tables.
gnumake pjee Builds a directory that contains an installable set of files for running the PJAE on a separate target system. The INSTALLDIR macro defines the name of the target directory.
gnumake javadoc Uses javadoc to build HTML API reference files. These include the PersonalJava class library as well as internal APIs like Truffle.
gnumake clean Removes all the class files, object files and other temporary build files from the PJES build environment.

Adding Class Files

The PJES build environment can be modified to include Java class files that are not part of the PJES reference release. Including new class files with the platform class files will cause them to be included in ROMization with JavaCodeCompact. The procedure described below shows how to add new class files to the list of class files managed by the PJES build environment.

  1. Edit build/makefiles/javai_platform.mk.

  2. Add the full class names to the JAVAIPLATFORMCLASSES macro definition. For example,

    JAVAIPLATFORMCLASSES = \
        java.lang.UNIXProcess \
        \
        sun.audio.AudioDevice \
        sun.audio.AudioTranslatorStream \
        sun.audio.NativeAudioStream
        \
        com.yournamehere.HelloWorld
    

Adding Object Files

Object files can also be added to the list of object files managed by the PJES build environment. This is the normal way to add native method implementations to the PJES build environment.

  1. Edit build/makefiles/javai_platform.mk.

  2. Add the full class names to the JAVAIPLATFORMOBJECTS macro definition. For example,

    JAVAIPLATFORMOBJECTS += $(JAVAISOLARISOBJECTS) \
        libHelloWorld-Solaris-sparc-Imp.o
    

Adding Data Files

JavaDataCompact prepares data files for storage in the ROM file system. To add new data files to the list of data files to be stored in the ROM file system.

  1. Edit build/makefiles/jdc.mk.

  2. Add the new files to the ROMFILES_FILES macro.

By default, the property files in src/share/lib and src/platform/lib are added to the list of files that will be stored in the ROM file system.

Adding a Locale

By default, the PJES build environment has configuration options for building the locales for English/US, Japanese and a collection containing all available locales. The procedure described below shows how to modify the PJES build environment to include configuration options for other locales.

  1. Choose which locale(s) to support.

  2. Choose which character encodings to support beyond the base PersonalJava character encodings.

  3. Edit build/makefiles/properties.mk to include a new macro named FONTPROPERTIES_language_country (where language is an ISO 639 language code and country is an ISO 3166 country code). This macro refers to the font.properties file appropriate for the new locale. For example,

    FONTPROPERTIES_en_US = \
        font.properties
    

    refers to the locale for the English language and United States.

  4. Edit build/makefiles/locale.mk to include a new macro named TEXTRESOURCECLASSLIST_language_country. This macro contains references to the specific resource files for the new locale. For example,
    TEXTRESOURCECLASSLIST_en_US = \
      java.text.resources.DateFormatZoneData_en_US \
      java.text.resources.LocaleElements_en_US
    

  5. Edit build/makefiles/locale.mk to include a new macro named CHARCONVERTERLIST_language_country. Place the converter classes for the necessary character encodings in this list. Also include all the parent converter classes for the necessary converters. For example,

    CHARCONVERTERLIST_ALL = \
      sun.io.ByteToCharISO8859_5 \
      sun.io.CharToByteISO8859_5 \
      sun.io.ByteToCharSingleByte \
      sun.io.CharToByteSingleByte
    

    sun.io.ByteToCharConverter and sun.io.CharToByteConverter are not necessary in this list because they are in the standard set of converter classes.

  6. If the character encodings have platform-dependent variances from the relevant standard, then adapter classes are needed to handle these variances. sun.awt.motif.CharToByteX11JIS0208 is an example.

  7. Modify the font properties in src/platform/sun/sun/awt/GUI/font.properties.language_country to map logical fonts to platform fonts.

Remote Classes

The PJAE allows certain classes to be loaded remotely from a Zip archive on a server. The REMOTE* configuration options determine which classes will be loaded remotely. The lib/remote-classes.properties file specifies the location where the class files are stored and defines a mapping between the different class files and the Zip archive files.

Determining Memory Requirements (Solaris only)

The selection of different configuration options represents a tradeoff of functionality against memory requirements. To provide an idea of the memory requirements of a specific configuration of the PJAE, the PJES build environment generates a statistical summary after a nodebug build is completed. For example,

Static sizes for bin/sparc/pjava tool on Solaris in Megabytes
                 ROM     RAM    Total
w/ libs         2.094   0.064   2.158
w/o libs        2.091   0.059   2.149
ROMized classes 1.538   0.005   1.543
classfiles(est) 2.011   2.842   4.853

The classfiles(est) statistic is an estimate of the class file memory usage before ROMization.

These statistics will vary depending on CPU and configuration options. Varying the configuration options and recording the memory requirement statistics provide a quick way to gauge the memory costs of different configuration options.

Running Java Software

See Using the PersonalJava emulation environment for a description of how to run Java software with the sample implementations of the PJAE. That document also describes techniques for debugging and profiling Java software.