Creating a Native Installer for a New Platform

Currently, you can create native installers for Windows, Linux Intel, Mac OS X, and Solaris Sparc with the JExpress license. If you want native installers for other platforms, then you simply need to purchase licenses for JExpress and JExpress Custom Native.

The JExpress Custom Native license includes the C++ source code to 2 small programs: C Installer and Unzip. Both programs are very likely to compile, without any changes, if you use a GNU C++ compiler that is configured for POSIX compatibility. Not all versions of all compilers work with JExpress. Here are the earliest versions of the compilers that we use for the standard platforms:

OS Compiler/Version
Windows gcc 4.4.1
Mac OS X gcc 3.3 20030304
Linux gcc-3.3
Solaris gcc version egcs-2.91.66 19990314 (egcs-1.1.2 release)
  1. Install JExpress Custom Native in your C++ development environment.
  2. Add a new subdirectory under the platforms subdirectory of your JExpress subdirectory. The new subdirectory should be named with the target system's name (e.g., HPUX, AIX).
  3. For each native platform,
    1. Create the following binary files in this order:
    2. Prepare a properties list for the platform
    3. Test the new native installer

 

UnzipSfx and UnzipX

DeNova modified the freely distributable unzipsfx so it can automatically launch another program after it expands the files an the archive.

  1. Move to the installation's subdirectory called unzip.
  2. Copy the file Makefile from the unix subdirectory to the unzip subdirectory.
    If there isn't a Makefile in the unix subdirectory, then issue the command mv unix/makefile unix/Makefile
  3. Review the Makefile to see which configuration fits your target system.
  4. Make sure your compiler is configured to use POSIX. If it's not, then be sure to use the -DPOSIX command line switch
  5. Issue the following command: Makefile [command] where [command] is the command name for your target machine. If you didn't see your specific target machine listed in the makefile, then you can probably use generic2. For example, if you're creating a native installer for a generic Unix system, then you'd type: Makefile generic2
  6. As soon as the makefile is successful, you'll have 2 new programs: unzipsfx and unzipx.
  7. You can test these programs by using the testmake.zip file included in the unzip subdirectory
  8. Issue the following commands to test unzipx:
    cd test
    cp ../unzipx .
    cp ../testmake.zip .
    cat unzipx testmake.zip >test
    chmod 777 test
    ./test
  9. If everything works properly, then there will be 2 extra files in the test subdirectory
  10. You can follow the same steps to test unzipsfx, but then the 2 files will be expanded in a temporary directory on your system.
  11. Move unzipsfx into the new subdirectory you created under JExpress's platforms subdirectory.

 

Self Extracting JRE

You must create a self extracting archive of the freely distributable JRE. After you obtain the JRE, use the following procedures to create the self extracting archive.

  1. Move to the subdirectory with the JRE. This is the directory which includes the bin and lib subdirectories for the JRE.
  2. Zip all the files, retaining the directory tree. Under usually, the command is probably:
    zip -r jre[targetCode] *
  3. Copy the file unzipx from the unzip subdirectory that you created earlier.
  4. Issue the following command:
    cat unzipx jre[targetCode].zip >jre[targetCode]
  5. You can test the jre[targetCode] file by issuing the following commands:
    cp jre[targetCode] [testDir] cd [testDir] chmod 0744 jre[targetCode] ./jre[targetCode]

    where [testDir] is a test directory you created for the purpose.

  6. You can verify the file expanded properly, if the [testDir] contains the same files and directory structure as the original JRE directory does.
  7. Move the jre[targetCode] file into the new subdirectory you created under JExpress's platforms subdirectory.

 

C Installer

The C Installer has the following primary functions:

  • locate any existing JREs on the target system
  • verify the detected JRE is the correct version
  • install the JRE if it doesn't find the correct one
  • launch the Java installer

To create the C Installer:

  1. Move to the cinstaller subdirectory
  2. Copy the makefile file from the unix subdirectory to the cinstaller directory
  3. Issue the command: make
  4. As soon as the makefile is successful, you'll have a new program called install.
  5. Move the install file into the new subdirectory you created under JExpress's platforms subdirectory.

 

Prepare a Properties List for the platform

Use a standard text editor to create a properties list file, called platforms.properties, in the new subdirectory you created under JExpress's platforms subdirectory. The file must contain the following key pairs. If you're creating a native installer for a Unix platform, then you probably just want to copy the sample platforms.properties.

Key Description Recommended Value
unzipExecutable Name of the program that creates a self extracting archive unzipsfx
installerExtraFiles List of extra filenames to be included in native installation unzipsfx install jreTarget
jvmSelfExtractor Filename of the self extracting archive for the JVM jreTarget
jvmName Type of JVM installed, i.e., JRE, JDK JRE
jvmCommandName Command to start the JVM java
jvmVersion Version of the JVM in the self extracting archive 1.5.0
jvmRequiredVersion Required version of the JVM to operate your app, strongly recommend at least 1.5 1.4.0
jvmExtraParameters Extra parameters used on the JVM's command line  
installerExecutable Filename for target platform's native installer jinstall
loaderClasspath Classpath for the installer .;install.jar
systemSecurityPolicyFilename System security filename ${java.home}/lib/security/java.policy
userSecurityPolicyFilename System security filename ${user.home}/.java/policy
loaderJavaCommand Main classname for installer load
jvmClasspathSwitch Command line switch for the JVM to set the classpath -cp
installJvmParameters Command line switches used for the installer  

For details on all the properties that a JExpress installer supports, see InstallPropertyNames. You do not want to include any other properties in the platform.properties file, then those listed below and also listed in the InstallPropertyNames that are related to the native installer.

Sample platform.properties

#Platform Options
#Mon Jan 18 10:42:19 CDT 2006
unzipExecutable=unzipsfx
installerExtraFiles=jrelnx install
jvmSelfExtractor=jrelnx
jvmName=JRE
jvmCommandName=jre
jvmVersion=1.5.0
jvmRequiredVersion=1.5.0
installerExecutable=jinstall
jvmExtraParameters=
loaderClasspath=.;install.jar
systemSecurityPolicyFilename=${java.home}/lib/security/java.policy
userSecurityPolicyFilename=${user.home}/.java/policy
jvmClasspathSwitch=-cp
keystoreFilename=${user.home}/identitydb.obj
loaderJavaCommand=com.denova.JExpress.Installer.JExpressInstaller
installJvmParameters=

 

Testing A New Native Installer

Testing with JExpress

The most reliable way to test your new native installer is with JExpress. First, make sure the following files are in the new subdirectory you created under the platforms subdirectory:

Next, start JExpress and load your project. Check the native installer box on the Build panel. Copy the file from the subdirectory under the build directory's to your target system.

Testing Manually

There is an alternative method that we do not recommend and we will not support. Nonetheless, if you've had to change any of the source files, then it might be easier to test using this Q&D method. Plus, we use our docs to help remind our own engineers how to perform these procedures. :)
  1. Create a test directory
  2. Copy the following files to the directory: install, jre[targetCode], install.jar, and jex.control to the test subdirectory.
    • Copy the install.jar and jex.control file from the cinstaller directory.
  3. In the jex.control file, modify the value for the jvmSelfExtractor to match the new self extracting archive for the JRE.
  4. Zip all the files in the test directory into a file called jinstall.zip. Under Unix, the command is probably: zip jinstall *
  5. Copy the unzipsfx file to the test directory
  6. Issue the following commands:
    cat unzipsfx jinstall.zip >jinstall
    chmod 0744 jinstall
    ./jinstall
  7. If all goes well, your application's installer will start up

 

Notes

  • If you get an error during compilation that reports a comma is missing or that a command ends too soon, then strip the makefile of all carriage returns.
  • If you get an error from one of the unzip C files that reports a character is unrecognized, then strip the C file of all carriage returns.
  • The makefile under the unix subdirectory must be upper/lower case (i.e., Makefile).

 

 

jre[targetCode] is a 3-5 character representation of the target system. For example, for a Linux system, we've named the self extracting archive jrelnx and on a Windows system, jrewin.