Installation

C H A P T E R 3

Installation

This chapter describes the prerequisites you need to install on your system before you use the development kit, how to install the development kit, how to set system variables, and how to uninstall the development kit. You can run both a Classic and Connected development kit simultaneously.

Binary and source code development kits are available for the Microsoft Windows XP SP2 operating system. Source code bundles allow you to change the development kit’s reference implementation, whereas the binary bundles allow you only to use the reference implementation.

Each development kit is provided in an executable JAR file bundle. See Chapter 1 for a description of this development kit bundle and Contents of All Releases for a list of all the files installed by this development kit.

Note - The Java Card specifications are not included in the development kit. The specifications must be downloaded separately.

Prerequisites to Installing the Development Kit

The following software must be installed before installing a development kit:

Java Development Kit - The commercial version of Java Development Kit (JDK software) version 6 Update 10 (JDK 6 Update 10) or later is required.

Download the JDK software from http://java.sun.com/javase/downloads and install it according to the instructions on the web site.

Apache ANT - Apache Ant 1.6.5 or higher is required to run the samples from command line or to build the cref from source code.

Download and install Apache Ant version 1.6.5 or higher from http://ant.apache.org.

GCC compiler - Minimal GNU for Windows (MinGW), version 5.1.4 or later is required to build the cref and tools from sources.

Download MinGW from http://sourceforge.net/projects/mingw. For MinGW installation information, go to http://www.mingw.org.

NetBeans IDE (optional) - The NetBeans IDE version 6.8 can be used to develop and debug classic applet applications. Download NetBeans IDE 6.8 from the following URL and install it according to the instructions on the web site:

http://www.netbeans.org/

Firefox browser (optional) - The Firefox browser (not Internet Explorer) is considered as a trusted agent for running the RI. Firefox can be obtained from http://www.mozilla.com.

javax.comm package - Install this if you are planning to use the development kit to communicate with a TLP224-compatible card reader.

Use the javax.comm package included in the latest version of the Java Communications API, available on Sun’s web site at: http://java.sun.com/products/javacomm.

Follow the instructions provided in the file Readme.html to install the package, and make sure that the comm.jar file is added to the CLASSPATH.

Install and Setup the Development Kit

This section describes how to install and set up the development kit for the Classic Edition.

Downloading the Development Kit

1. Verify that JDK 6 Update 10 or later is installed on the development system.

See Prerequisites to Installing the Development Kit for the download location and installation instructions of the JDK.

2. Download the development kit JAR file to a directory of your choice.

3. Launch the development kit installer.

The development kit can be launched automatically when you download the JAR file or by using the Windows file manager tool to navigate to the directory containing the development kit JAR file and double clicking the file name or icon.

The development kit can also be launched by opening a Command Prompt window, navigating to the directory containing the development kit JAR file, and executing the following command from the command line:

java -jar Bundle-Filename

In the command, Bundle-Filename is the name of the downloaded development kit JAR file.

The installation wizard displays the following screen.

Installation screen

4. Complete each action requested by the installer.

During installation, the development kit is installed in C:\JCDK3.0.2_ClassicEdition by default. If you specify a different installation directory, the names of the installation directory and its parent must not contain a space.

For example, the installation directory cannot be located in “C:\program files” because of the space in the “program files“ directory name.

Note - The installation directory, either the default C:\JCDK3.0.2_ClassicEdition directory or the alternate installation directory you specify, is referred to as JC_CLASSIC_HOME throughout this document.

5. Click the Finish button to complete installation.

The bundle installs files and directories containing the binary files and source code as described in Contents of All Releases. The files and directories are installed under the root installation directory referred to as JC_CLASSIC_HOME in this document.

Setting Up the System Variables

1. Set a JAVA_HOME system variable to the JDK software root directory and put its bin\ in the PATH.

Before running the Development Kit, you must set the JAVA_HOME environment variable permanently in the Windows Control Panel or temporarily from the command line:

a. To permanently set JAVA_HOME, go to Windows Control Panel > System > Advanced > Environment Variables dialog and either create or edit a System variable named JAVA_HOME with the literal value of the JDK root directory on your system. For example, in the System variables box enter the following:

Variable

Value

JAVA_HOME
C:\JAVA\jdk1.6.0_10

Note - The GUI entrance to setting environment variables might differ depending on the Microsoft Windows operating system (OS) version in use. If necessary, see the OS online help.

b. Alternately, to temporarily set JAVA_HOME, enter the following command in a command prompt window:

set JAVA_HOME=java_home_path

For example, if the JDK software is stored in the c:\jdk6 directory, enter:

set JAVA_HOME=C:\jdk6

c. After performing the previous steps, add JAVA_HOME\bin to the PATH:

set PATH=%JAVA_HOME%\bin;%PATH%

This can also be set permanently in the Control Panel System settings.

2. Set a ANT_HOME system variable to the Ant root directory and put its bin\ in the PATH.

Before running the Development Kit, you must set the ANT_HOME environment variable permanently in the Windows Control Panel or temporarily from the command line:

a. To permanently set ANT_HOME, go to Windows Control Panel > System > Advanced > Environment Variables dialog and either create or edit a System variable named ANT_HOME so that its value is the Apache Ant root folder. For example, in the System variables box enter the following:

Variable

Value

ANT_HOME
C:\ant\apache-ant-1.6.5

Note - The GUI entrance to setting environment variables might differ depending on the Microsoft Windows operating system (OS) version in use. If necessary, see the OS online help.

b. Alternately, to temporarily set ANT_HOME, enter the following command in a command prompt window:

set ANT_HOME=ant_home_path

For example, if the ANT software is stored in the C:\ant\apache-ant1.6.5 directory, enter:

set ANT_HOME=C:\ant\apache-ant1.6.5

c. After performing the previous steps, add ANT_HOME\bin to the PATH:

set PATH=%ANT_HOME%\bin;%PATH%

This can also be set permanently in the Control Panel System settings.

3. Set a JC_CLASSIC_HOME system variable to the development kit root directory and add it to the PATH.

Before running the development kit, you must set the JC_CLASSIC_HOME environment variable permanently in the Windows Control Panel or temporarily from the command line.

Note - The command line tools and included application samples require that the JC_CLASSIC_HOME variable is set correctly.

a. To permanently set JC_CLASSIC_HOME, go to Windows Control Panel > System > Advanced > Environment Variables dialog and either create or edit a system variable named JC_CLASSIC_HOME so that its value is either C:\JCDK3.0.2_ClassicEdition or the directory you specified during installation. For example, in the System variables box enter the following:

Variable

Value

JC_CLASSIC_HOME
C:\JCDK3.0.2_ClassicEdition

Note - The GUI entrance to setting environment variables might differ depending on the Microsoft Windows operating system (OS) version in use. If necessary, see the OS online help.

b. Alternately, to temporarily set JC_CLASSIC_HOME, enter the following command in a command prompt window:

set JC_CLASSIC_HOME=jc-home-path

For example if you installed in C:\JCDK3.0.2_ClassicEdition, enter:

set JC_CLASSIC_HOME=C:\JCDK3.0.2_ClassicEdition

c. After performing the previous steps, add JC_CLASSIC_HOME to the PATH:

set PATH=%JC_CLASSIC_HOME%;%PATH%

This can also be set permanently in the Control Panel System settings.

4. Add MinGW to the PATH variable.

MinGW is not required if only the Development Kit binary bundle is installed. If the Development Kit source bundle is installed, set the MinGW environment variable permanently in the Windows Control Panel or temporarily from the command line:

To permanently set the MinGW path, edit the PATH variable in the System variables box to include the location of MinGW\bin:

;C:\MinGW\bin;

To temporarily set the MinGW path, enter the following command in a Command Prompt window:

set PATH=C:\MinGW_path;%PATH%

For example, if MinGW is installed in the C:\mingw directory, enter:

set PATH=C:\mingw\bin;%PATH%

Note - If you choose to set the JAVA_HOME variable and MinGW PATH each time you run the Development Kit, place the appropriate JAVA_HOME variable and MinGW PATH commands in a batch file.

Installed Files and Directories

The files and directories are installed under the root installation directory, either C:\JCDK3.0.2_ClassicEdition or the directory you specified during installation. The root installation directory is referred to as JC_CLASSIC_HOME in this guide.

The source release contains all the files installed with the binary release, plus a src directory.

Contents of All Releases

TABLE 3-1 describes the files and directories that the installation procedure places in the root installation directory, represented by JC_CLASSIC_HOME.

These files are installed in binary releases and are also installed for source releases, see TABLE 3-2.

TABLE 3-1 Contents of All Releases
Directory/File	Description
api_export_files	Contains the export files for version 3.0.2 of the Java Card API packages. If you have a development kit that includes cryptography, this also includes the directory `api_export_files\javacardx\crypto`.
bin	Contains all shell scripts or batch files for running the tools (such as the `apdutool`, `capdump`, `converter` and so forth), and the `cref` binary executables.
docs	Contains the RI’s APIs in Javadoc tool files and this book in both PDF and HTML format. It also contains two subdirectories each with respective compilations of the Javadoc tool files for the Java Card Client RMI API and the APDU I/O API. Note - The RI for the Classic Edition supports RMI but the RI for the Connected Edition does not.
legal	Contains license files.
lib	Contains all Java programming language JAR files required for the running tools using the BAT files provided in the `bin` directory.
samples	Contains sample applets.
RELEASENOTES	Release notes and copyright files for the development kit.
Uninstaller	Contains `uninstaller.jar` to run for uninstalling the product.

Contents of the Source Release

TABLE 3-2 describes the items in the src directory installed if you have the source release of the development kit. For the descriptions of other installed items, see Contents of All Releases.

TABLE 3-2 Contents of the Source Release `src` Directory
Directory/File	Description
`api`	Contains the source files for the development kit. 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. If you have a development kit that includes cryptography, this also includes the directory com/sun/javacard/crypto.
`installer`	Contains the source files for the installer.
`tools`	Contains the source files for the development kit 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.
`vm/c`	Contains the source files of core VM.
`vm/h`	Contains the header files of core VM.
`build.xml`	The main file used to build the tools and `cref` in a single step.
apiImpl.jar
vm_build.xml

Uninstalling the Development Kit

To uninstall the development kit, version 3.0.2, run the Uninstaller tool found at JC_CLASSIC_HOME\Uninstaller\uninstaller.jar. Do not change the location of this tool. Before running the Uninstaller, exit all development kit tools and the NetBeans IDE. Any files under the control of the host operating system are not removed using the Uninstaller. When you execute the file, it displays this dialog:

Selecting the check box or not in this dialog box yields the same result, because in either case the Uninstaller removes the version 3.0.2 development kit in which the uninstaller.jar file resides.

You can also uninstall a development kit for any Java Card 3 Platform release by simply deleting all its JC_CLASSIC_HOME directories and files from your hard drive.