Adding or unpacking a single file to a target directory

The <file> element

The <file> tag is a nested element of the <pack> element. It specifies a single file to be added to that pack.

You can use <fileset> to add multiple files.

Attributes

Attribute

Description

Required

Values
(Default)

src

the file location (relative path). The src name may contain previously defined static variables (see <variables>).

yes


targetdir

the destination directory, could be something like $INSTALL_PATH/subdirX

yes


os

Limit installation of this particular file only to the given target OS type.

no

"unix" | "windows" | "mac"

override

Whether to overwrite existing files.

  • true if the file should always overwrite an existing file with the same name.
  • false if the file should be skipped if the file already exists in the targetdir.
  • asktrue if the user should be interactively asked what to do and supply default value of "true" for non-interactive use.
  • askfalse if the user should be interactively asked what to do and supply default value of "false" for non-interactive use.
  • update if the new file is only installed if it's modification time is newer than the modification time of the already existing file. Note that this is not a reliable mechanism for updates - you cannot detect whether a file was altered after installation this way.
  • no

"true" | "false" | "asktrue" | "askfalse" | "update"
("update")

overrideRenameTo

Globmapper to rename a conflicting file to. This works similar to the <globmapper> in File Name Mappers, whereby the mapper's from attribute is set to the empty string and the to attribute exactly to the value given here. Example: overrideRenameTo="*.bak" will rename the target file by appending the suffix .bak instead of overwriting it. The override attribute must be set "true" to activate this feature.

Since IzPack 5.0

no

String - valid globmapper target expression

blockable

For Windows only, ignored on non-Windows systems:
Defines whether and how blocked target files on Windows should be handled. This might result in pending file operations which require a system reboot.

Pending file operations are introduced during the installation in two phases:

  1. The blockable attribute marks files pending to be replaced after a system reboot if they are blocked. Blocked files are recognized during physically installing them.
  2. How and whether the system should be really rebooted directly from the installer in case there are such pending file operations at the end of the installation can be controlled by the <rebootaction> tag nested to <info>.

Notes:
Using blockable does not necessarily force you to limit such files on Windows systems. For multi-platform installations there is a compiler warning shown that blockable will be ignored on non-Windows systems.
The native library WinSetupAPI must be explicitly included using this feature.

Possible values:

    • none
      No recognition of blocked target files will be done at all, this is the default behavior of previous IzPack versions.
    • auto
      Automatic recognition of a blocked target file by the operating system, resulting in leaving a pending file operation to be finished after system reboot. Using auto this applies only for files that are really blocked, the other files are copied normally, which can result in mixed, old and new target files at the end of the installation, unless the system won't be really rebooted.
    • force
      Forces target file to be always assumed a blocked, resulting in leaving a pending file operation to be finished after system reboot. Using force this applies for each file, regardless whether it is really blocked during installation. This makes sense if you don't want to mix files old and new files at the end of the installation to not disturbing a running process, but having the complete set of target files installed after system reboot.


Since IzPack 5.0

no

"none" | "auto" | "force"
("none")

unpack

if true and the file is an archive then its contents will be unpacked and added as individual files.

One or more nested <archivefileset> element can be added to define include and exclude path patterns similar to the <fileset> element nested to a <pack>.

Before IzPack 5.1.0, only ZIP archives were supported (including jar, war and zip files).

Since IzPack 5.1.0, all compression supported by the Apache common-compress library are automatically recognized by analyzing the file metadata and are extracted correctly. These include bzip2, Pack200, XZ, gzip, lzma, Z, deflate as well as archive types such as ar, arj, cpio, dump, tar, 7z, zip and their combinations like tar.gz.

Note: Unpacking 7z during compiling does not support all methods the format specifies, see Known Limitations (we use commons-compress 1.12 at the moment).

The file extension is ignored for this auto-recognition.

no

"true" | "false"
("false")

condition

Limit installation of this particular file to the given condition, which must be true during the file installation.

no

String - a valid condition ID

casesensitive

Whether to treat the file name case-sensitive.

no

"true" | "false"
("true")

defaultExcludes

Whether to use global default excludes.
Implicit default exclude patterns are typically:

*/~{}
*/##
*/.#
*/%%
*/._
**/CVS
*/CVS/*
**/.cvsignore
**/SCCS
*/SCCS/*
**/vssver.scc
**/.svn
*/.svn/*
**/.DS_Store

Since IzPack 5.0

no

"true" | "false"
("true")

followSymLinks

Whether to follow symbolic links on target systems which support them.
Since IzPack 5.0

no

"true" | "false"
("true")

Nested Elements

The following nested elements can be used in the <file> tag:

<os>

Limit the installation of this file to conditions depending on the target OS, see OS Restrictions.

<additionaldata>

This tag can also be specified in order to pass additional data related to a file tag for customizing.

Attribute

Description

key

key to identify the data

value

value which can be used by a custom action

;<additionaldata> is an element which may provide additional information as key-value pairs to certain custom actions. The particular key-value pairs will depend on the particular custom action.

 Currently, there are two built-in custom actions consuming such data, ChmodCompilerListener and ChmodInstallerListener, where relevant keys are

  • permission.dir,
  • permission.file

with integer values interpreted as permissions like in the Unix chmod:

If value begins with "0" -> octal number,

otherwise is is a decimal number representing some permission.

These permissions are applied to the appropriate files either during the compilation of the package or while installing them later, depending on whether the consumer implements a CompilerListener or InstallerListener.

<archivefileset>

If the unpack attribute is set to "true", one or more nested <archivefileset> elements can be added to define the patterns for include and exclude paths similar to the <fileset> element nested to a <pack>. In comparison to  <pack>, an <archivefileset> does not permit the specification of a targetdir and its dir attribute is optional (defaults to the root directory of the archive contents). Furthermore the dir attribute of an <archivefileset> can not refer to an absolute path, but must be relative to the archive root.

Example usage
<pack name="Oracle JRE" required="yes" id="pack.oracle.jre">
    <description>Oracle JRE</description>
    <file src="plain/jre-8u121-windows-x64.tar.gz" targetdir="${INSTALL_PATH}" unpack="true" override="true">
        <archivefileset dir="jre1.8.0_121" />
    </file>
</pack>

This part extracts the contents of the original Oracle JRE archive as received from the download site, but without the root directory jre1.8.0_121 from the archive to an installation folder of your choice, which can be referred to as %JAVA_HOME%.

An <archivefileset> does not allow the targetdir attribute to be defined. The target dir for that filter operation is taken from the targetdir attribute of the embedding <file> tag.

Since: IzPack 5.1

<pack200>

The <pack200> element adds Java bytecode compression to all files in this set of files.

Make sure to apply it only to JAR files or similar files containing Java bytecode.

See Compressing pack files for more information how to cutomize this feature.

Since: IzPack 5.1