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 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 list of actions. 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. 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 list of screens 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. 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] action. The file wizard will be displayed.
  In thedistribution 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.
  • Edit the contents of entries
    The contents of single entries can be edited by using the  [Edit] action or hitting the ENTER key while the entry is selected.

    Editing an entry means different things for different entry types:

    • 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 entries
      Editing a directory content entry will bring up the file wizard.

    To rename a folder, choose Rename entry from the context sensitive menu or Files->Rename entry from install4j's main menu. The name of the folder can then be edited in-place.

  Using compiler variables in the distribution tree allows you to make 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.
  Note: 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.