Bitrock installbuilder enterprise v7.2.3

Figure 2 also shows the notification you will see when a new version is available. If the builder has access to the Internet and is configured to check for updates, it will automatically report these notifications for each new version released. The process can also be manually triggered using the Update menu. Clicking on the blue arrow will open the downloads page in a web browser. If you do not want the installer to check for updates on startup, you can edit the update.

It is always possible to override these default values when necessary. Enabling Save Relative Paths will convert all of the absolute paths related to the build process files to pack, images, readme… to relative paths, using the location of the project file as the reference.

This setting will be applied automatically and transparently when saving and loading the project so it will not be noticeable while working in the GUI. This particular setting is especially useful when sharing a project between developers or operating systems, as the location of the resources is not hardcoded, as explained in the When is it necessary to use the Save Relative Paths option?

If the paths were already manually configured as relative, they will be preserved and resolved when building, also using the location of the project to absolutize them. The License File setting specifies a license file that will be displayed during installation.

The end user will need to accept this license text before continuing with the installation process. If you do not provide a license file, the license acceptance screen will not be displayed to the end user. This HTML-formatted license will be used if the front-end supports it currently only the case for the Qt front-end. Otherwise the default license text specified in the License File setting will be displayed.

You can also display multiple licenses in different languages or display them conditionally, as described in the Displaying a localized license and readme section. The command line builder is available on all platforms. InstallBuilder project files are stored in XML format. This enables and simplifies source control integration, collaborative development and customizing projects both by hand and using external scripts. The following is a complete example of what an InstallBuilder project looks like.

This particular project does not package any files. Most of the examples presented in this guide are provided as XML snippets, but you can achieve identical functionality using the GUI.

It is included as InstallBuilder. For Atom you can use the linter-autocomplete-jing package. The XML specification requires that specific characters are escaped. This is done automatically if entering the values through the GUI but if you are directly editing the XML code you must take it into account.

The table below summarizes the most common characters and their escape sequence:. Some of the values only need to be escaped if provided as part of an attribute value, not an element. Introduction to InstallBuilder. What Sets InstallBuilder Apart. Optimized : VMware InstallBuilder installers are optimized in size and speed and do not require a self-extraction step, reducing download, startup and installation time.

This action allows you to display a message in a warning dialog. Warn if the installation directory is not empty. Prompt a choice question dialog to the user. Ask the user to select the uninstallation type. If the user cancels the dialog, either clicking Cancel or closing the popup, the result variable will be set to empty. If the user clicks Ok , the result variable will be set to the selected choice item. This behavior can be used to validate the user input:.

Generate an error inside the installer so the installer will exit. The only exception to this is when abortOnError equals zero or the action is inside a validationActionList, in which case it will prompt an error dialog to the user, but will not exit the installer.

Abort if the installer is not launched as Administrator. This action allows you to ask the user a question in a popup window. Retrieve the first registry hive and content matching a certain expression and store it as a list in an installer variable. If no match is found the variable will be created empty.

List all applications from same vendor as current installer. Store the value of the first match of a registry key matching a certain expression in an installer variable. If the key or name does not exist, then the variable will be created empty.

Get the data of the first value in our application key. Delete a registry entry. If the entry to delete is only a registry key and it does not exist, the action will be ignored. Create a new registry key or modify the value of an existing registry key. Store in variable the first registry key that matches the given pattern, or set the variable to empty otherwise.

The search is case-sensitive for the whole key provided. Store the value of a registry key in an installer variable. Find Google Chrome installation directory.

If chrome. Autodetects an existing. If a valid. Bundle and install. NET Framework if it is not present in the user machine. This action allows you to increment the reference count for a shared DLL. Add shared. This action allows you to decrement the reference count for a shared DLL. If it reaches zero, the file will be removed. Remove shared. Change Windows attributes for a file or directory. This action allows you to create file associations for Windows, defining commands such as "open" for a given file extension.

This action allows you to remove file associations for Windows, unregistering commands such as "open" for a given file extension. Removing association of. Modifies the Windows x64 File System Redirection behavior. Get file information. Please note that this example will fail if Microsoft Office is not installed. You can get additional information in the ACL section. Remove write permissions to all users but Administrators. Create a new task or modify the value of an existing one.

Schedule monthly task to be run on each 3rd day of month. Create a scheduled tasks if it does not already exist. Shutdown the machine at the end of the installation. This action allows you to delete a Mac OS X service. Requires Mac OS X version Delete service com. This action allows you to start a specified Windows service. Start Sample Service service. This action allows you to create a new Windows service. Created service will start automatically and run sampleservice.

This action allows you to stop a specified Windows service. Stop Sample Service service. This action allows you to remove a service in a Linux based system.

Note that you will need to run the installer as root to be able to remove services. This action allows you to create a new service in a Linux based system. Note that you will need to run the installer as root to be able to create new services. This action allows you to start a Mac OS X service. Start service com. This action allows you to get a unique Windows service name.

Create Sample Service with unique service name. This will allow multiple services of same base name to be created - for example if multiple applications base on same framework that runs as a service. This action allows you to stop a Mac OS X service. Stop service com. This action allows you to remove a specified Windows service. Delete Sample Service service. This action allows you to create a Mac OS X service.

System Wide scope requires running the installer as an administrator. Create new service com. New service will start automatically and run sample from application bundle. This action allows you to restart a specified Windows service. Restart Sample Service service.

Create a copy of a file. This action allows you to unpack a directory before files are unpacked during the installation phase. Unpack initial data if it does not exist i. Delete a file. Create a backup of a file or directory. The backup will be named with a. If a backup file already exists, new backups will be named.

Backup the backup of a file before making changes. This action allows you to create a new directory. This action allows you to uncompress the whole content of a zip file to a given destination folder. The file to unzip must be already present on the file system, i.

Update the access and modification times of a file or directory. If the file does not exist, it can be specified whether to create an empty file or not. It is equivalent to the touch Unix command. Create a file to mark a component as installed. Get the destination path referenced by the given symbolic link. Read symbolic link libsample. Rename file as. Create a symbolic link to a file. It is the equivalent to the Unix ln command.

Create symbolic link libsample. Pack one or more files to a zip file, relative to base directory. Example values: 1.

Possible values: unattended, gui, text. Possible values: unattended, xwindow, qt, text, osx, gtk, win NET framework was autodetected Possible values: 0, 1. Possible values: , full, client. Example values: 2. Possible values: 0, 1. Example values: 73ca54bfceeccb Example values: Example values: 6. Example values: Unknown error executing action. Possible values: executable. Example values: 0, 1. Example values:. Example values: , Possible values: gui, text. Example values: Debian.

Example values: 3. Possible values: gentoo, suse, redflag, slackware, fedora, arch, amazon, rh, mandrake, debian, rhel.

Example values: 5. Possible values: winnt, win9x. Possible values: Windows , Windows 7, Windows 8. Example values: 1, 2, 3. Possible values: 6. When a project contains more components or is built for other platforms, additional files will be created in this directory.

Some components may be available under different URLs. The example below shows how optional content can be placed at a different URL:. This can be specified relatively.

The behavior for installers with one or more downloadable components is the same as it is with regular installers. The component selection page shows the downloadable file size for each component available for download:. If a user does not select any downloadable component, the installer does not perform any download or show any additional information related to downloading components. If a user does want to install a downloadable component, after the Ready To Install page is shown, the user is presented with a proxy configuration page:.

After the user configures or skips the proxy server configuration, the installer starts downloading the specified components:. If no error occurs, the installation proceeds when all components are downloaded and no user interaction is required.

Ignore - do not attempt to download the current component and proceed without installing it. In the event of download errors, the user is able to ignore the fact that a component could not be downloaded and proceed with the installation. It is possible to define actions that should be run when a component failed to download and the user chose to ignore it.

In this case, if the PHP module is not downloaded and another component depends on it, the installation will abort. Text mode installers provide the same support for downloadable components as GUI installers. After all parameters have been specified and at least one component needs to be downloaded, the user is prompted with a proxy configuration question.

The user may choose to skip proxy configuration or specify it. Next, downloading begins and the overall progress of installation is shown this is the same feedback provided in the form of a progress meter for GUI installations.

Unattended installers also provide support for downloadable components. Components are downloaded and installation occurs automatically. If unattendedmodeui is specified as minimalWithDialogs , progress for downloads is shown only as the overall download progress.

InstallBuilder offers the ability to install and uninstall individual components without reinstalling or uninstalling the entire application.

This functionality is disabled by default. InstallBuilder stores the location of all applications inside of the application directory. When performing an installation, the user specifies the directory where the application should be installed. If it contains information about a previous installation, it is used by the installer. This information will consist of currently installed components and optionally for storing previous values for parameters that allow it.

It also contains information about the currently installed version. If the versions do not match, information about the currently selected components and values for parameters that allow it is used. However, all components are reinstalled in such a case. Components previously installed will always be selected and the user will not be able to uninstall components using the installer. The user may choose to install additional components.

Whenever any change is made, all actions for newly selected components are run. However, actions for components previously installed are not run. This prevents actions that set up default values from overriding settings that user has already modified. After a successful installation, the uninstaller and all related information will be updated to reflect that the user has installed additional components. Entire application - removes the entire application and all files installed by the application.

Individual components - removes individual components while leaving the rest of the application intact. When a user selects Individual components , a component selection page will be shown. All components not currently installed will not be shown in the component selection tree.

When a user selects a component group, the component and all of its sub-components will be removed. For example if a user selects application1 , this causes feature1 , feature2 , feature3 and feature4 to be uninstalled:. Selecting a component group to be uninstalled also causes all of its child components to be uninstalled. Those components are shown as selected and cannot be edited. For example the following shows that the component application1 will be uninstalled, which will also cause all of its child components to be uninstalled:.

If a parent is deselected, the selection of its children is reverted - if a child component was previously explicitly selected before selecting the parent, it will remain selected. Otherwise the child component will be deselected. When a user selects all of the components, the installer will behave as if the Entire application option was chosen.

Otherwise, selected components will be removed and pre- and post- uninstallation actions for these components will be run. Remaining components will remain installed and no actions for these components will be run. After successful uninstallation, the uninstaller and all related information will be updated to reflect that the user has uninstalled some of the components.

When the Entire application option is chosen or the user selects all components in the component tree, the entire application is uninstalled along with uninstaller itself.

This also triggers pre- and post- uninstallation actions for the project to be run. All of the defined elements will be packed and unpacked at runtime. If the path is relative, it will be absolutized when building using the project file parent directory as a reference.

See the Filters section for more information. This is evaluated at build time and matched against the specified build target. It allows a single project to define a multiplatform installer. The special platform identifier all can be used and represents all platforms. The full list of supported values in the tag is summarized in the table below:. You can find a detailed reference in the shortcuts section. The above folder will only be packed if the target platform is linux and the files exist.

This is also helpful when you are developing the installer and do not need all of the files that will be included in the final version that can greatly increase the build time to be packed. You can find a more complex example in the "Custom Build Targets" section. The above folder will be packed for any Windows target but will only be unpacked if the platform in which the installer is executing is Windows XP. InstallBuilder implements a basic filtering mechanism for folders.

This functionality will allow you to pack the contents of a folder instead of including the folder itself and to apply filters to include or exclude specific files. In the above example, all of the. If it is set to "0" the default , there will not be any global pattern interpretation and patterns will be taken as literal strings.

In addition, the includeFiles and excludeFiles tags will be ignored. The default value of this tag is empty so no filter is applied. This tag is ignored if wildcards are disabled. Forward and backwards slashes are normalized according to the platform. Forward slashes are used as path separators, which let us escape special characters using backslashes. For example, to match. If chars contains a sequence of the form a-b then any character between a and b inclusive will match.

For example, if you are packing a directory images and want to exclude the file demo. If you want to filter certain files at any level of the hierarchy in the packed directory, you should use the Advanced Filters instead, which operate recursively.

Note that you have to define filters that will decide if the file will be packed or not. If the file in consideration matches the expressed conditions in this list, it will be packed, if not, it will be skipped. After the installation, you will find the dist-files directory clean of temporary files:. If you also want to exclude files starting with. A file will be packed if its full path in the build machine matches all the filters when using and logic or when matching any of them when using or.

For example, if you want to pack just. For example, you can exclude. Both regexp and glob pattern types allow providing a semicolon-separated list of sub patterns. If any of the sub patterns in the list evaluates to true, the full pattern will also evaluate to true. For example, to pack all of the. For example, you can exclude all of the. InstallBuilder preserves the permissions of bundled files. If a value is specified for those tags, the owner and group of the unpacked files will be modified at runtime:.

Please take into account that the specified group and owner must exist in the target machine. If not, you can always create them before the installation phase:.

Despite the permissions being preserved, in some situations they must be fixed. A common scenario in which permissions must be fixed is when you are building a Linux installer on Windows.

In that case, you could either manually fix the permissions as explained in the latest snippet or define the default permissions:. Please take into account that, contrary to the owner and group tags, the default Unix permissions are only applied when building on Windows. This way, if the installer is created on Unix, the configured values will be ignored.

Windows does not understand Unix permissions, so Unix installers created on Windows will be unpacked without executable permissions and must be manually fixed. It is recommended that you use Unix machines to build the installers as they do not present any limitation. Depending on the build type, it will either pack the link deb, rpm or it will be registered and recreated at runtime. It is common to have a separate tool or program that must be bundled with and run from the installer but before the file copying phase of the installation process has completed.

A common example would be a license validation program. Typically, all files bundled within an installer are unpacked and then any tools are run. In the case of a license validation tool, that is less than ideal because the user may end up waiting for the files to be unpacked only to find that the license is not valid. The user would then have to wait for the installation to be rolled back. InstallBuilder provides you with actions to deal with these situations. Trying to unpack the wrong type in those actions will generate an error at runtime.

The configuration options for these actions specify the folder and component bundling the files, the path relative to the packed element, and the destination directory to unpack them. The structure in Figure 33 also represented in XML code should help you understand how to reference internal files:.

It does not matter where the file was originally located in the building machine, just the path inside the installer:. In most cases, you will need to request some information from your end users, such as the installation directory or username and password. For this purpose, InstallBuilder allows the creation of custom pages, which make it easy to request and validate user input.

In addition, the provided information will automatically be stored in installer variables so it can be used later in the installation process, for example to pass it as arguments to a script in the post-installation.

There are different types of parameters: strings, booleans, option selection, and so on. Each one of them will be displayed to the user appropriately through the GUI and text interfaces.

For example, a file parameter will be displayed with a graphical file selection button next to it and an option selection parameter will be displayed as a combobox.

The parameters will also be available as command line options and as installer variables. This will be used to create the corresponding installer variable and command line option. Because of that, it may only contain alphanumeric characters.

For example, for the parameter below:. It is really useful to modify the information displayed. One example of how this is useful is configuring installation settings based on the user input:. If an error occurs, it will be displayed and, instead of aborting the installation, the page will be redrawn. For example, you can use the snippet below to check if a provided password is strong enough:. It accepts all of the common options. Optionally, you can include an image to the left side of the text.

The link parameter is intended to be displayed in GUI mode. They also support additional fields:. The setting will just have effect on OS X, in other platforms they will be always considered directories. Usually, on OS X, some bundles are considered as files although they really are special directories. By default, the order in which the choices are displayed in the installer page is the same in which they are listed in the XML code.

A plain text license is still provided to be displayed in non-qt modes text, gtk, win32, osx. Optionally, if a key has a. For example, if you want to generate a language list based on the contents of your lang directory, you could use the below:. For all of the above actions, if the specified parameter to be modified does not exist, the action will be skipped. Another useful example would be displaying the list of your installed applications and letting the user select one to uninstall:. Another example might be showing a list of drives for the user to pre-select on Microsoft Windows.

The following actions will create and execute a Visual Basic script, whose output will be used to populate the choices of the parameter:.

A group parameter allows you to logically group other parameters. They will be presented in the same screen in GUI and text installers. You need to place the grouped parameters in a parameterList section, as shown in the example below. If you plan to support text mode, you should then create an additional simplified page to be displayed instead:.

A basic example snippet would be:. For example, the example above showed a group containing some secondary settings, disabled by default. This way users will know that they do not require much attention or that they do not need to worry if they does not understand them. For example, you could ask your users if they want to register the installation. As any other parameter, it will execute all of its actions. If the user checks the checkbox, the parameters will execute their validations. That is why it includes a rule checking its state.

The value stored will represent the name of the selected child parameter. The default look and feel of the parameter is to show as disabled all the deselected parameters, preventing the user from editing their information until the corresponding radiobutton is selected. Their only limitation is that they cannot configure their orientation as regular parameterGroups do. Hidden parameters are very useful because they can be used as permanent variables that can be reconfigured when launching the installer.

A good example would be to disable license validation when testing:. To avoid having to introduce the license number each time you launch the installer, you just have to disable the page when launching the installer:.

This can be achieved by attaching a rule to the page:. The same will happen in unattended mode, as the pages are never displayed. As explained in the previous section, the values of the installer parameters can be configured by passing command line options.

However, when a large number of parameters must be configured, there is a more convenient way to do so using an option file.

An option file is just a. Another way of providing the option file is to create a file in the same directory as the installer with the same name plus the. In both cases, the installer will parse the file and will map all the entries to internal parameters.

Lines starting with a first non-blank character will be treated as comments. There are a number of installation tasks that are common to many installers, such as changing file permissions, substituting a value in a file, and so on. VMware InstallBuilder includes a large number of useful built-in actions for these purposes. Actions usually take one or more arguments. In addition, if the arguments contain references to installer variables, such as the installation directory, they will be properly expanded before the action is executed.

InstallBuilder actions are organized in what are called action lists, which are executed at specific points of the installation process. It is important to understand how and when each action must be performed, what differences exist between action lists inside components and within the primary installer, how the installer will behave when you run it in different installation modes GUI, text, or unattended and what happens when you generate rpm or deb packages.

You can place your action lists in the main installer project or in one of its components. Figure 43 shows all the available action lists in the GUI:.

These actions usually include setting environment variables or performing some type of processing on the files that will go into the installer before they are packed into it.

These actions are usually useful to reverse any changes made to the files during the preBuildActionList or to perform additional actions on the generated installer, such as signing it by invoking an external tool. The help is displayed when the --help command line option is passed to an installer.

It can be useful for example for modifying the description of parameters based on the system the installer is running on. On Windows, the help menu will show as a GUI popup window that will auto-close after one minute.

Splash Screen : After the installer internal initialization, the Splash Screen is displayed. It is commonly used for detecting a Java tm Runtime Environment or for setting user-defined installer variables that will be used later on:.

Note that those actions are not executed if the installer is executed in unattended mode. The actions can be used to check that the value is valid for example, that it specifies a path to a valid Perl interpreter. If any of the actions result in an error, an error message will be displayed to the user and the user will be prompted to enter a valid value. This can be useful for changing the value of the parameter before it is displayed.

This can be useful for performing actions or setting environment variables based on the value of the parameter. It is commonly used to execute actions that depend on user input. These actions usually include launching the program that has just been installed.

For each one of the actions contained in this list, a checkbox will be displayed or a question in text mode. If the checkbox is selected, then the action will be executed when the Finish button is pressed. These are special cases. There is no interaction with the end-user and the following action lists are not executed:. Each action list may be included in the main project or inside the components. You can divide all action lists into two groups based on what is executed first: main project or component action lists:.

If you build and execute the installer in, for example, unattended mode, you will see the following in the console:. For example, to get the path of the gksudo command on Linux you could use the snippet below:. If the execution fails, the variable will be defined as empty. You can also execute more complex commands such as pipes or include redirections. For example, the code below can be used to count the number of files in a directory:. However, as the 8. In these cases, you can prevent the automatic 8.

On Unix, when calling shell scripts that also call subscripts in the background, even if the execution of the main shell script terminates, the installer keeps waiting for the launched child processes in background to close their standard streams. An example of this situation would be when manually starting a Unix service backup-daemon :.

However, as the child process is still running, the installer hangs until it finishes or its standard streams are closed. Another solution that does not require modifying the service script would be to redirect the output when calling it from the installer:. Or, if you are interested in the output, redirect it to files.

For example, to execute our application at the end of the installation without preventing the installer from finishing you could use the following snippet:. Application bundles are the most common way of distributing software packages on OS X.

These bundles can be executed by double-clicking on them, as if they were regular files, so it is a common mistake to try to execute them using the command line as:. Using the open command: This command is the equivalent of a double-click over the bundle. It can be also used to open regular files, which will launch the associated application:.

However, if you want to make InstallBuilder wait for the process to finish launch the bundle in the foreground you can use the -W command line flag:. A limitation of using open to launch the bundle is that it does not support passing arguments to the launched application in its early versions it started supporting it from OS X If you just support versions newer than OS X One of the keys specified is CFBundleExecutable , which determines which of the contained files will be executed when opening the bundle.

There are multiple ways of retrieving this key but the easiest way is by executing:. Which will return the file that will be executed relative to the directory Builder.

In the case of InstallBuilder application bundles, it will return installbuilder. When the actions executed require a long time to complete, such as waiting for a service to start or when uncompressing a zip file, it is advisable to provide some feedback to the end user.

The first way of providing feedback is defining a progressText in your action. This dialog displays an indeterminate progress bar in a pop-up while executing the wrapped child actions.

It will also take control of the execution so the user will not be able to interact with the main window until the actions complete. Canceling the pop-up will cancel the installation:. In this case, instead of displaying an indeterminate progress pop-up, a continuous bar with the speed and the progress of the download will be displayed:. In addition to the built-in actions, InstallBuilder allows you to create new custom actions using a mix of base actions and rules. This new action will take care of displaying the progress dialog and launching the program in unattended mode.

The basics of how to define a new custom action are as follow:. In addition to built-in actions, it also accepts other custom actions if they were previously defined. I some cases, you may want to create custom actions that perform some operations and return the result in a variable.

The obvious way of achieving this would be to implement something like the following:. The reason is that all the variables used in the custom action are just a local copy of the project level variables. The same way, variables created inside the custom action are not available in the global scope. This way, you can safely use any variable inside the function without affecting other project level variables. This action accepts a space-separated list of variable names that will then be preserve their values outside the custom action.

In our example:. Take into account that once a variable is defined as global, it will always be accessible from other custom actions, even if they did not declare it as global.

The Custom Actions are still under development and although the functionality is fully usable, they have some known limitations:. To make the builder recognize a custom action as a valid XML element, it must be defined in the XML project before it is used. They cannot be defined in the tree, but actions defined using the integrated XML editor or externally added will be available as other regular actions in the action-selector dialog.

The same applies to its parameters. During the installation or uninstallation process, there are scenarios in which the installer encounters a non-recoverable error or simply is manually aborted. This section explains how these scenarios are handled by InstallBuilder and how to manually define actions in case of failure either to clean the installation or to try to recover.

All actions include some error handling tags that make it very easy to specify the desired behavior when an error is found during its execution. Its default value is 1. However, although the actions will be skipped, no error will be propagated upward so the installation will not be aborted:.

A real world example could be to determine if certain Linux command is available and getting its path:. For example, you can use it to clean the effects of the failed action before continuing aborting:. This action list gets executed when the project is aborted, either by the user or by an internal error. For example, it could be used to make sure the installation directory is deleted after the installation is being canceled:. However, there are some special cases in which the error is treated as a warning or is ignored:.

If an error happens, instead of aborting the installation, it just prevents the execution of the remaining actions in that list and it is reported. When the installer is aborted by the user during the installation of files, all of the unpacked files will be automatically deleted.