Installer SFX creation using XSEBuilder

This document describes creation of XSE archives using XSEBuilder and archive definition files. XSE stands for eXtended SelfExtracting. While you still can use old technique, which described in Installer SFX creation, we strongly recommend to use XSEBuilder - it's much easier and convenient way.

Overview

Creation of XSE archive is consist of two steps: creating XSE Archive Definition File and passing it with some arguments to the builder. This document covers Archive Definition format and usage of XSEBuilder.

XSE Modules Overview

XSE Module is an executable, which when launched does next steps:

1. Unpacks to system temporary folder files and folder, what marked as necessary.
2. Unpacks to system temporary folder autorun executable.
3. Executes unpacked executable with stored in XSE Archive command line parameters and waits it to

Usually XSEArchive consists of many files and folders, not required for autorun executable to function. So, native launcher unpacks only files and folders, which marked in XSE Archive as "necessary". After that, the launcher unpacks autourun itself and execute it with (if any defined in archive) command line arguments. There is reserved command line argument "$#launcher#", it will be replaced by the launcher to absolute path to itself. Most frequent usage of XSE is like this: create an XSE Module with distributive of end-user data and an installer for it, mark all installer-required data as necessary and put $#launcher# as argument for installer executable. In this use case, when module launched it unpacks installer-only data and pass to installer absolute path of the XSE Module. Installer then opens it as a XSE Archive, using XSEArchiveFactory class, thus gaining access to module data which farther can be used in it's "installer duties".

Archive Definition File Format

Archive Definition File is a XML file with structure like in example below:

<?xml version="1.0" encoding="UTF-8"?>
 <?sfx version="1.0"?>

 <sfxArchive>
	 <source path="C:\Folder_with_content">
		<dir path="autorun_required_directory" unpack="true"/>
		<file path="some_not_required_by_autorun_file"/>
                <file path="another_not_required_by_autorun_file" unpack="false"/>
		<file path="autorun_required_file" unpack="true"/>
	</source>
	 <destination path="C:\name of archive.sfx" cmd="some_autorun_module.exe autorun_required_file some_another_argument"/>
 </sfxArchive>

The definition file consist of two major parts: source and destination. Every sub element of source element is a description of archive entry: it's type (file or directory), path (path attribute value) and necessity of entry extraction before starting autorun application(value of unpack attribute). The source element must have attribute path, which is path to folder, where files and directories, listed in sub elements, are located. So it's exactly the same as 1st argument to XSEComiler. The destination element describes name of produced archive/sfx module(value of path attribute) and autorun command with arguments (value of cmd attribute). Name of output file can be overriden (we will cover this later). Please note, that autorun application, "some_autorun_module.exe", is not in list of source files and directories. XSEBuilder will automatically include autorun application to source list, and mark it as required.
While you can make archive definition files manually we strongly advice to use GUI (link needed!).

Using XSEBuilder

Where to get and requirements

XSEBuilder can be downloaded from CVS repository at dev.eclipse.org (module /cvsroot/technology/org.eclipse.epp/plugins/org.eclipse.epp.sfx.tools). It requires this Java projects : org.eclipse.epp.sfx.archive and org.eclipse.epp.installer.core. They are located in same repository.

Producing Archives and XSE modules

XSEBuilder takes from 3 to 4 arguments:

module-type path_to_archive_definition_file path_to_launchers_directory [output-path]

Where:

1. argument, "module-type" is type of build. Currently supported only two: "sfx" and "exe". "sfx" tells builder that we want XSE archive only. The "exe" keyword tells XSEBuilder that we want produce an Windows self-extracting module. When XSEBuilder met "exe" keyword, it compiles new archive and links it with native launcher (it looks for Windows native launcher, "extractor.exe", in "path_to_launchers_directory\win32.x86\" folder).
2. argument, "path_to_archive_definition_file" is a path to file with definition of archive.
3. argument, "path_to_launchers_directory" is a path to folder, where template launchers are located. Typically it's "PATH_TO_YOUR_WORKSPACE_HERE\org.eclipse.epp.sfx.tools\templates".
4. argument, "output-path" is optional. It is path to output file. By passing this argument you override path, specified in definition file. NOTE: By default (without output-path argument passed), for an "exe mode" XSEBuilder will create resulting file under name "destination_path_in_definition_file" with appended ".exe". E.g. if destination path was "c:\my_archive.sfx", self-extracting module will be named "c:\my_archive.sfx.exe".