Native Libraries - <natives>

Owned by Former user (Deleted)
Last updated: Feb 08, 2016 by René Krell

Usage

Several listeners or panels might need access to OS-dependent shared libraries. They are divided into

  • built-in libraries,
  • 3rd party libraries.

Built-in libraries are available for inclusion at compile time out of the box.

To minimize the size of resulting installers, each native library must be explicitly included. This is done by the <natives> element.

The <natives> element can embed an unlimited number of nested <native> elements.

To add the same library for different processor architectures they must get a different name for each architecture and be added all.

Attribute to
<native>		ValuesRequiredDescription
type

izpack | 3rdparty

(default: izpack) 

yes

Specifies the type of the native library:

  • izpack - The library's source code is part of the IzPack project.
  • 3rdparty - The library's source is from another project or there is no source code available.
nameAny resource file name.yes

The file name of the resource to be added.

There must be a file name for each processor architecture, 32 and 64 bit. The 64 bit libraries must have the suffix _64 in its base name.

src

Any valid resource path.

(default: com/izforge/izpack/bin/native/<type>/<name>) 

no

Root path of the native resource. This is used for finding the resource to add. The destination path is always com/izforge/izpack/bin/native/<type>/<name>.

In case src is set to a value the source path to get the native library from is assembled from the attribute values described here like this: <src>/<type>/<name>.

Native resources are needed for a couple of IzPack components. Built-in native libraries are:

  • ShellLink.dll (type: izpack)

  • ShellLink_x64.dll (type: izpack)

  • WinSetupAPI.dll (type: izpack)

  • WinSetupAPI_x64.dll (type: izpack)

  • COIOSHelper.dll (type: 3rdparty)

  • COIOSHelper_x64.dll (type: (type: 3rdparty))

The above libraries don't need this attribute to be set, the default path is the correct one here.

Using of the src attribute makes sense if you add your own libraries in an additional jar file using the <jar> tag containing the library in a custom resource path.

stage

both | uninstall

no

Specifies whether the native library should be packed into the installer, uninstaller or both:

  • both - Pack the library to both, the installer and uninstaller
  • uninstall - Pack the library to the uninstaller only

If this attribute isn't specified at all the according library will be available just to the installer, not the uninstaller.

This attribute is ambiguous and marked deprecated beginning from 5.0.7 (compiler warning). Use the uninstaller attribute instead.

uninstaller

true | false

(default: false)

no

The value "true" specifies the native library should be additionally packed into the uninstaller if one is generated.

By default, the native library is available just during the installation, but not in the uninstaller.

Since: 5.0.7

Example

For using the Shortcut Panel on Windows there are required the ShellLink native libraries to access some native APIs:

 

How to include native DLLs for ShortcutPanel
<natives>
    <native type="izpack" name="ShellLink.dll"/>
    <native type="izpack" name="ShellLink_x64.dll"/>
</natives>

 

Both 32-bit and 64-bit versions are built-in to IzPack.