Main Site Contents Up Previous Next

Linux Installer

The Linux version of Cava Packager contains options for creating a custom installer based on Perl scripts bundled with your application.

For the installation of desktop and menu icons Cava Packager uses the suite of xdg scripts described at

http://portland.freedesktop.org/wiki/XdgUtils

You may find it useful to read the documentation at that site which may make usage of the Cava menu and shortcut options clearer.

Some older Linux distributions may not be freedesktop compliant so it is possible that installation of desktop and menu shortcuts may not work on these distributions.

If you build an installer, it will be available in the 'installer' subdirectory of your project directory.





Use Installer - Make Builds Installer Capable

On Linux, Cava Packager makes several additions to your release bundle if you are using the Cava Installer. These items are removed after installation. You need to make the build installer capable if you wish to use the installer. Note that you may not wish to use the self extracting zip or archives of your release folder if your builds are installer capable. The release folder and archives will contain the additional installer components that will not be removed when the archive is extracted. Whilst this won't affect your application funtionally, it may confuse users who may run the additional executables or scripts.

Cava Packager will include an uninstaller executable which will be placed in your application bin folder after installation. This executable will remove all installed files and shortcuts.

Auto Create Installer

If your build is installer capable, you may check this to always build an installer with your project builds. Alternatively provided your build is installer capable you can build an installer using the Distribution Menu or Toolbar.

Create Uninstaller

If your build is installer capable, you may check this to always create an executable named uninstaller that will be placed in your application bin folder during installation.

Pre Installer Script

You may specify a Perl script here to be run before your installer is built. The Perl script will be run using the same Perl used to build the project. The script will receive two arguments:

The path to the project release directory.

The path to the project installer directory.

Please note that if you create an installer from the toolbar or Distribution Menu, then you must account for the results of any previous running of your script against the release and installer directories. The installer and release directories are only cleaned when you run a full project build. Because the Linux installer utilises the self extracting executable, a new self extracting executable is created each time you build an installer. Necessarily, on Linux the Pre Insaller Script is always run before the self extracting executable is built.

A very simple example script that just echoes its parameters is included in the examples folder of Cava Packager under installer.

Installer Type

If you choose 'Cava Wx GUI Installer', an installer that utilises wxPerl will be created. This means that for wxPerl applications you can create an installer with very little overhead. You can use this option for none-Wx applications, but you must have a working wxPerl installed. The necessary wxWidgets libraries will be bundled with your application making it much larger.

If you select Custom GUI or Custom Console installer types, then you must provide a packaged script called custom_installer.pl. There are no restrictions on what this script may or may not do but creating a working installer is entirely up to you. You should use the functions and methods provided by the modules in cpinstallermodule.pl

A simpler customisation option is available for the wxPerl installer. If you include a script named customise_cava_installer.pl within your application, the Cava GUI installer will call do customise_cava_installer.pl allowing you to customise the installation process. Copies of the scripts that Cava uses for the GUI installer are in the Cava examples folder at

../cavainstallpath/examples/installer

This directory also contains examples for custom_installer.pl & customise_cava_installer.pl together with cavainstaller.pot allowing you to internationalise the installer if you wish.

The customise_cava_installer.pl example in the examples folder adds an additional wizard page to the Cava Wx GUI installer that requests a password for the installation.

cpinstallermodule.pl

This script contains all the base modules used during installation. It is not dependent on Wx. You should be able to build a custom installer by wrapping the functions in this script. This script is always packaged with an installer.

cpwxinstaller.pl

This script provides the Wx wrapper used for the Cava Wx GUI Installer. It can be customised using your own customise_cava_installer.pl to add and remove pages and data sources. Aternatively you may use it as a basis for your own entirely custom installer

The scripts provided implement a simple uninstaller process. To remove files, a script is created at ../installpath/bin/.xdg/douninstallfiles. This contains a simple 'rm -rf' of your installation directory. For a more sophisticated file removal replace douninstallfiles with your own version.

This can be done at build time where you can replace the file in a post build script:

my $filetoreplace = $release->get_release_path() . '/installer/xdg/douninstallfiles';

If you do not 'Create an Uninstaller' then the files ./installpath/bin/.xdg/douninstallfiles and ./installpath/bin/uninstaller will not exist. The only way to remove your application is to delete the application directory. However, scripts to install / uninstall your menu and desktop items will still be created named:

./installpath/bin/.xdg/vendorprefix-install

./installpath/bin/.xdg/vendorprefix-uninstaller

You may call these scripts independently in your own custom code. The install script is called during application installation.

Replacements may also be carried out at installation time where you can replace the file in a customised install script:

my $filetoreplace = $customclass->get_full_installpath() . '/bin/.xdg/douninstallfiles';

The final section of code to run during an installation creates a new instance of Cava::Packager::Installer::Customclass ( or your derived custom class ) and calls the method 'install_final'. The calling code actually does:

       my $customclass = $Cava::Packager::Installer::Config::configdata->{customclass};
       eval {
           my $custom = $customclass->new($app);
           $custom->install_final;
       };
       if(my $errors = $@) {
           $self->_log_error(t('Failed running custom install class ::post_install: %s', $errors));
       }

so you may override $custom->install_final in a derived class and implement anything you wish as the final process in the installation.

Installer Base Name

Enter the base name for your installer executable. You can then use the installer name options to configure the suffix of opertaing system, architecture and version information. The final name is displayed in the Installer Final Name field.

Default Install Location

You can specify the default install location for your installation here. Environment variables may be included, e.g. $HOME

Allow user to change install path.

Set whether the end user can alter the installation path.

Require root privileges to install.

If checked, the installer will exit if not run as root. This is a useful option if you wish to install to a specific system wide location.

Run post_install_script.pl

You may optionally include a script named 'post_install_script.pl' within your application package. If this option is selected, the final part of the installation process will be to call 'do post_install_script.pl'. You can carry out whatever tasks you may wish in this scripts. Any errors will be ignored unless you specifically call 'exit' with a none zerto value. You may choose to check this option even if you do not provide a post_install_script.pl. If you have compressed a large number of resources, the first run of any of your executables may be slower than usual. The executable wrapper around the post install script will cause all of your compressed files to be extracted at installation time.





Freedesktop Vendor Prefix

You should specify a name that identifies you or your organisation. It should consist of lower case letters. This is used to prevent name conflicts when installing menu and desktop shortcuts.

Custom Menu Options

When setting up menu icons you may choose to install them to standard locations in the menu hierarchy or you can install to a custom menu that is a sub-menu of Applications. If you want to use a Custom Menu you must specify the detail here. For menu icons 22 x 22 png files are recommended. Note that if you specify a custom menu, all menu entries are added to it. Any Categories you may have set for individual items are ignored.

Edit Icon Items

You can add, remove and edit shortcut items using the list buttons in the shortcut list.

Path For Translation Files

Set this to the path to a directory containing your .mo translation files.

The installer runs some packaged Perl scripts to install your application. These scripts are internationalised using gettext like string translation. No translations are provided with Cava Packager, but you can create your own if you wish.

In the Cava 'examples' folder under the sub directory 'installer' you will find the file 'cavainstaller.pot' that you can use to provide translations. Your compiled translation .mo files should be named in either 2 or 5 char format. For example, 'fr.mo' or 'fr_FR.mo'. Place all your .mo files in a single directory and set the 'Path For Translation Files' to that directory. Your translations will be included in the package and loaded according to the locale of the target machine.





Exec Line

Enter the executable line that you wish the shortcuts to run. You may enter anything here including command parameters. Normally for executables you create in the project you will want an absolute path to the installed executable. You can use the placeholder CAVAINSTALLPATH which will be replace with the full installpath of your package.

For example, to create a shortcut for an executable named 'testexec' :

CAVAINSTALLPATH/bin/testexec

You might also wish to provide a shortcut to the automatically provided unistaller :

CAVAINSTALLPATH/bin/uninstaller

Install Items

Choose to create a menu shortcut, a desktop shortcut, or both.

Item Name

The name that will be displayed for the shortcuts. Use the i18n button to optionally provide translations for your text.

Item Description

Detail displayed in some desktop informational dialogs. Use the i18n button to optionally provide translations for your text.

Item Tooltip

The item tooltip. Use the i18n button to optionally provide translations for your text.

Use Terminal

Check this option to launch the shortcut target in a terminal.

Custom Extra Values

If you wish to add additional extra values to the desktop and menu specifications that are not created by the Cava Installer Interface, you can add them here. Note that any values that you add that are already handled by the Cava interface, will be removed from this field. The Cava reserved values are Exec, Type, Value, Encoding, Terminal, Name, GenericName, Comment, Icon, Categories.

You might like to consult the freedestop spec for more information.

http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html

For example, you could limit a shortcut to visibility only on Gnome desktops with:

OnlyShowIn=GNOME;

Destop Icon

Specify an icon for a desktop shortcut. A 48 x 48 png is recommended. Once selected the file is added to your stored icon resources. If you alter or edit the original source file you will have to import the new version into your icon resources and select it.

Menu Icon

Specify an icon for a menu shortcut. A 22 x 22 png is recommended. Once selected the file is added to your stored icon resources. If you alter or edit the original source file you will have to import the new version into your icon resources and select it.

Menu Categories

Select under which heading installed menu shortcuts will appear. You can select from the standard freedestop main and sub categories. If you have specified a Custom Menu then your Category selections are ignored. All shortcuts are placed under your Custom Menu.

Text Items Internationalisation

The i18n dialog is used to enter translations for shortcut text items.





Contents Up Previous Next


Cava Packager Copyright © 2006-2012 Mark Dootson