Files - Defining The Distribution Tree


  The distribution tree shows your file selections and the distribution directory structure created by you. The distribution tree is drag-and drop enabled.

To check whether your definition actually produces the desired results, please go to the View Results tab of the Files steps.

  The top-level nodes in the distribution tree are called file sets. There is one "Default file set" that cannot be deleted or renamed. The relative paths of all files that are added to a file set must be unique. Please see the help topic on file sets and installation components for more information on how to use file sets.

Within a single file set, it causes an error if the installation paths for two files collide. For example, if you have added the contents of two different directories into the same folder in the distribution tree and both directories contain a file file.txt, building the project will fail with a corresponding error message. In this case, you have to exclude the file in one of the directory entries. This is only valid for files, sub-directory hierarchies on the other hand are merged and can overlap between multiple directory entries and explicitly added folders.

You can create new file sets with the  New File Set action in the  add menu on the right side. Each file set has its own "Installation directory" root. If you define custom roots that should be present in multiple file sets, you have to duplicate them.

When using the install4j API, you reference file sets with IDs. You can show IDs in the distribution tree by activating the  Show IDs button on the lower right side of the distribution tree. The automatically generated numerical IDs are then shown in brackets. The selection will be remembered across restarts of install4j.

  The child nodes of a file set are called installation roots. Their location is resolved when the installer runs. There are two types of roots:
  • The default root of the distribution tree is labeled as "Installation directory" and has a special icon. This is the directory where your application will be installed on the target system. The directory is dependent on user actions at the time of installation. In regular installers a user can select an arbitrary directory where the application should be installed. For RPM media files, a user can override the default directory with command line parameters. For archives, the files are simply extracted into a commmon top-level directory.

    The installation directory will only be created if you execute an "Install files" action in the installer configuration. By default, the "Install files" action is placed on the "Installation" screen. If your installer should not create an installation directory, you can ignore this root and remove the "Install files" action.

    To learn more on the various installer modes, please see the corresponding help topic.

  • If your application needs to install files into directories outside the main installation directory, you can add custom roots to the distribution tree. This is done with the  New Root action in the  add menu on the right side or in the context menu. The actual location of this root is defined by its name and has to resolve to a valid directory at runtime. There are several possibilities for using custom roots. The name of a custom root can be
    • a fixed absolute path known at compile-time
      This works for custom environments where there's a fixed policy for certain locations. For example, if you have to install some files to D:\apps\myapp, you can enter that path as the name for your custom root.

      If you build installers for different platforms, that root is likely to be different for each platform. In that case, you can use a compiler variable for the name of the custom root and override its value for each media file.

    • an installer variable that you resolve at runtime
      If you would like to install files into the directory of an already installed application, such as a plugin for your own application, you can use an installer variable that you resolve at runtime. Installer variables have an installer: prefix, such as ${installer:rootDir}, and can be set in a variety of ways.

      The most common case would be to add a "Directory selection" screen to the screen sequence and set its variable name property to the variable that you've used as the name of the custom root. For the above example, that would be "rootDir" (without the ${installer:...} variable syntax).

      Alternatively, you could use a "Set a variable" action to determine the location programmatically.

    • a pre-defined installer variable
      install4j offers several variables for "magic folders" that point to common directories, such as ${installer:sys.userHome} which resolves to the user home directory or ${installer:sys.system32Dir} which resolves to the system32 directory on Windows.

    If a custom installation root is not bound at runtime or if it points to an invalid directory, the contained files will not be installed. There will be no error messages, if you require error handling, you can use a "Run a script" action before the "Install files" action with the appropriate error message and failure strategy.

    Note: For archive media file types, custom installation roots are not installed. If you require these custom roots for your installation, you cannot use archives.

    An alternative way to redirect installed files to different directories is to use the "Directory resolver" property of the "Install files" actions. Also, the "File filter" property of that action can be used to conditionally install files. The use of these properties is only recommended if you require their full flexibility. Otherwise, using custom installation roots and installation components is a better approach.

  Beneath an installation root, you can add files or create folders:
  • To create a folder, use the  New folder action in the  add menu on the right side or in the context menu. A folder named "New Folder" will be created below the selected directory. If no directory or installation root is selected, it will be created below the "Installation directory" root node. Right after its creation, the default name is editable and you can enter the intended name of the folder. Confirm your entry with Enter. To configure further properties of the folder, you can edit the folder node (see below) to show the folder property dialog.
  • To add files, use the  Add files and directories action in the  add menu on the right side or in the context menu. The file wizard will be displayed.
  In the distribution tree you can
  • Move entries
    Entries are moved by dragging them with the mouse to the desired location. Both directories, file entries and directory content entries can be moved. To select a target directory inside a closed directory while dragging, hover with the mouse over the closed directory and it will open after a short delay. While dragging, the insertion bar shows you where the entry would be dropped.
  • Delete entries
    Entries can be deleted by hitting the DEL key or using the corresponding tool bar button or menu entry.
  • Rename entries

    Some types of entries can be renamed by using the  Rename action on the right side of the tree or from the context menu. The name of the entry can then be edited in-place.

    Renaming entries is possible for:

    • File sets
    • Roots
    • Folders
  • Edit the contents of entries
    The contents of some types of entries can be edited by using the  Edit action on the right side of the tree or hitting the ENTER key while the entry is selected.

    Editing entries is possible for:

    • Folders
      Editing a folder means opens the folder property dialog.
    • Single file entries
      Editing a single file entry will bring up the file wizard. Only the selected file will be shown in the "Select files" step, even if you initially selected multiple files with the wizard. If you add additional files in this step, they will be added below the selected file in the distribution tree. If you delete the selected file in this step, it will also be deleted in the distribution tree.
    • Directory content and compiler variable entries
      Editing a directory content entry or a compiler variable entry will bring up the file wizard.
  Using compiler variables in the distribution tree allows you to make compile-time conditional includes:
  • if a directory node resolves to the empty string after variable replacement, the directory and any contained entries will not be included in the distribution.
  • if the source directory of a "contents of directory" node resolves to the empty string after variable replacement, no files will be included through that entry.
  • if the file name of a single file node resolves to the empty string after variable replacement, no file will be included.
For conditions that are evaluated at runtime or for adding platform dependent files, you should use files sets instead.