Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Installer SFX creation using XSEBuilder"
m (→Producing Archives and SFX modules) |
m (→Archive Definition File Format) |
||
| (12 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | This document describes creation of | + | 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== | ==Overview== | ||
| − | Creation of | + | 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: | |
| − | + | # Unpacks to system temporary folder files and folder, what marked as ''necessary''. | |
| − | + | # Unpacks to system temporary folder ''autorun executable''. | |
| − | Archive Definition File is | + | # Executes unpacked executable with stored in XSE Archive command line parameters and waits it to finish. |
| + | 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 <tt>XSEArchiveFactory</tt> 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: | ||
<code><nowiki><?xml version="1.0" encoding="UTF-8"?> | <code><nowiki><?xml version="1.0" encoding="UTF-8"?> | ||
<?sfx version="1.0"?> | <?sfx version="1.0"?> | ||
| Line 12: | Line 17: | ||
<sfxArchive> | <sfxArchive> | ||
<source path="C:\Folder_with_content"> | <source path="C:\Folder_with_content"> | ||
| − | <dir path=" | + | <dir path="autorun_required_directory" unpack="true"/> |
| − | <file path=" | + | <file path="some_not_required_by_autorun_file"/> |
| − | <file path=" | + | <file path="another_not_required_by_autorun_file" unpack="false"/> |
| − | <file path=" | + | <file path="autorun_required_file" unpack="true"/> |
</source> | </source> | ||
| − | <destination path="C:\name of archive | + | <destination path="C:\name of archive.xse" cmd="some_autorun_module.exe autorun_required_file some_another_argument"/> |
</sfxArchive></nowiki></code> | </sfxArchive></nowiki></code> | ||
| − | + | The definition file consist of two major parts: <tt>source</tt> and <tt>destination</tt>. Every sub element of <tt>source</tt> element is a description of archive entry: it's type (<tt>'''file'''</tt> or <tt>'''dir'''ectory</tt>), path (<tt>'''path'''</tt> attribute value) and necessity of entry extraction before starting autorun application(value of '''unpack''' attribute). The <tt>'''source'''</tt> element must have attribute <tt>'''path'''</tt>, which is path to folder, where files and directories, listed in sub elements, are located. It's exactly the same as 1st argument for [[Installer SFX creation#Arguments|XSEComiler]]. | |
| − | The <tt>'''destination'''</tt> element describes name of produced archive | + | The <tt>'''destination'''</tt> element describes name of produced archive(value of <tt>'''path'''</tt> attribute) and autorun command with arguments (value of <tt>'''cmd'''</tt> 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.<br>While you can make archive definition files manually we strongly advice to use [[Installer SFX creation UI|GUI tool]]. |
| − | ===Producing Archives and | + | ==Using XSEBuilder== |
| − | + | ===Where to get and requirements=== | |
| − | <code> | + | <tt>XSEBuilder</tt> can be downloaded from CVS repository at <tt>dev.eclipse.org</tt> (module <tt>/cvsroot/technology/org.eclipse.epp/plugins/org.eclipse.epp.sfx.tools</tt>). It requires this Java projects : <tt>org.eclipse.epp.sfx.archive</tt> and <tt>org.eclipse.epp.installer.core</tt>. They are located in same repository. |
| + | |||
| + | ===Producing Archives and XSE modules=== | ||
| + | <tt>XSEBuilder</tt> takes from 3 to 4 arguments: | ||
| + | <code>module-type path_to_archive_definition_file path_to_launchers_directory [output-path]</code> | ||
'''Where:''' | '''Where:''' | ||
| − | #argument, "'''sfx'''" tells builder that we want only | + | #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). |
#argument, "'''path_to_archive_definition_file'''" is a path to file with definition of archive. | #argument, "'''path_to_archive_definition_file'''" is a path to file with definition of archive. | ||
#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''". | #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''". | ||
| − | #argument is optional | + | #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" <tt>XSEBuilder</tt> will create resulting file under name "'''''destination_path_in_definition_file'''''" with appended "''.exe''". E.g. if destination path was "''c:\my_archive.xse''", XSE module will be named "''c:\my_archive.xse'''.exe'''''". |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
Latest revision as of 05:39, 22 June 2007
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.
Contents
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:
- Unpacks to system temporary folder files and folder, what marked as necessary.
- Unpacks to system temporary folder autorun executable.
- Executes unpacked executable with stored in XSE Archive command line parameters and waits it to finish.
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.xse" 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. It's exactly the same as 1st argument for XSEComiler.
The destination element describes name of produced archive(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 tool.
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:
- 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).
- argument, "path_to_archive_definition_file" is a path to file with definition of archive.
- 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".
- 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.xse", XSE module will be named "c:\my_archive.xse.exe".