SALOME documentation central

SALOME Installation Wizard Help



Installing products with the Installation Wizard

The Installation Wizard can be launched in two modes: GUI and batch.
The root directory of the Installation Wizard contains Python script runInstall. To run the Installation Wizard just type runInstall. in the terminal window:

[ python ] runInstall [options]

Without options this script will launch the SALOME Installation Wizard in the default mode (GUI).
The default installation settings can be overridden by using command line options. Each option has a short and a long notation:

-g / --gui

Runs the Installation Wizard in the GUI mode (this is the default mode).

-b / --batch

Runs the Installation Wizard in the terminal mode.

-f FILE / --file=FILE

The XML configuration file to be used by the Installation Wizard. If this option is not used then the installation script tries to define the Linux version and use the corresponding XML file if it exists. For examle, for Linux Mandrake 10.1 the config_Mandrake_10.1.xml file will be used by default. If no appropriate file is found, the file config.xml will be used. This file refers to the basic target platform which is Linux Mandrake 10.1 for SALOME 3.0 and newer. If config.xml file is not found either, a warning message box is shown (in GUI mode) or printed to the console (in batch mode) and the Installation Wizard quits.

-d DIR / --target=DIR

The target directory SALOME platform is to be installed to. If used, this option overrides the default target directory, given in the configuration XML file (usually ${HOME}/salome_<version>, see here for more details).

-t DIR / --tmp=DIR

The directory, which should be used for temporary files. If given, this option overrides the default temporary directory, given in the configuration xml file (usually /tmp, see here for more information).

-a / --all-from-sources

Forces all the products to be installed from sources (including all SALOME modules). If this option is used, all default installation modes for all products are ignored.
This option is helpful when the user wants to install SALOME on the platform which is not officially supported. In this case, the user can try to run the SALOME Installation Wizard with the -a option in order to build all the products from sources.
Note, that this is a time-consuming operation which can take more than 24 hours depending on the computer.

-s / --single-directory

Install all SALOME binaries packages to one directory.
This option is ignored when --all-from-sources (-a) option is used.

-h / --help

Prints help information on the Installation Wizard's use.

-v / --version

Prints version information (Note: this is the Installation Wizard's version number, not the number of SALOME platform version).

The installation procedure supports different Linux platforms and installs various installation 3d-party prerequisite products which are required by SALOME platform. As it was mentioned above, the basic target platform for SALOME 3.0 and newer is Linux Mandrake 10.1. Use of configuration XML files gives a flexible way to modify the list of products to be installed by the Installation Wizard without changing the program source code. Just create your own XML configuration file and implement installation scripts for the prerequisite products you need and then use this XML file with the Installation Wizard. This can be done, for example, for some Linux platform which is not supported directly by the Installation Wizard. See Modifying XML configuration file and Implementing installation scripts for the new products sections for more information.



GUI mode

The Installation Wizard GUI has been developed using Trolltech's Qt 3.0.5 toolkit. After launching the Installation Wizard in the GUI mode the wizard window is shown to the user. This wizard guides the user through several subsequent pages. To navigate between the pages use "Next" and "Back" buttons in the lower part of the wizard window. The "Cancel" button closes the wizard window and quits the installation procedure after the user's confirmation. The "Help" button opens an additional window to show help information.

The first "Introduction" page is shown in Figure 1. Skip this page by clicking "Next":

intropage.png


Figure 1: "Introduction" page

In the second page you are proposed to select the type of the SALOME installation.

At this step three possible types of installation are available:

1. "Install binaries" type:

  • all binaries and sources of the chosen modules are installed;
  • all binaries of the chosen prerequisites are installed.

2. "Install sources" type:

  • all sources of the chosen modules and prerequisites are installed without compilation.

3. "Install sources and make compilation" type:

  • all sources of the chosen modules and prerequisites are installed;
  • all sources are compiled.

In case you select "Install sources and make compilation" installation type, then you can also check "Remove sources and temporary files after compilation" option.

installtypepage.png


Figure 1: "Type Of Installation" page

After the installation type has been selected you click "Next" button and the Installation Wizard tries to determine the Linux platform to load the corresponding configuration file. If the user system is not defined or the current SALOME package does not support this one, the warning will appear ("Install binaries" and "Install sources" installation types only):

platformpage.png


Figure 3: "Installation platform" page

If "Install sources and make compilation" installation type has been selected, the warning message will be slightly different: "Your Linux platform is not supported by this SALOME package and compilation is not tested on this one".
There is a list of all platforms supported by SALOME, but only those supported by the current package are available for selection. in this page you need to to select the reference platform, if you wish to proceed with the present installation procedure.

Note: this page is not displayed if the installation platform has been defined automatically.

In the next page you are proposed to enter the target directory where the SALOME platform should be installed to. You can also click "Browse..." and choose the destination folder using the standard browse directory dialog box.
If the necessary directory does not exist you are prompted to confirm directory creation. If you type a wrong directory path, or if you do not have write permissions for the directory you use, the corresponding message box is shown.

Note: you are strongly recommended to avoid using directory names containing spaces. Otherwise you can experience some troubles with the installation.

directorypage.png


Figure 4: "Installation directory" page

You can select the products to be installed in the "Choice of the products to be installed" page.
In the default mode it gives you the possibility to view and select SALOME modules only. There is a hidden list of 3d-party prerequisite products. To show it, just click "Show prerequisites..." button.

productpage1.png


Figure 5: Choice of the SALOME modules

In the full mode you also have the possibility to select prerequisites.
The checkbox before each product indicates if this one will be installed or not (checked or unchecked). The second column shows the disk space occupied by the corresponding module. This value depends on the selected type of installation.
To hide the prerequisites list - click "Hide prerequisites" button.

productpage2.png


Figure 6: Choice of the prerequisites

Some products may require some other prerequisite products to be installed. So the installation procedure has a special feature to automatically mark these products in the list view. For example, to install PyQt it is necessary to have gcc, Python, Qt and Sip installed, and these products will be also turned on when you check on PyQt. GEOM module requires KERNEL, GUI modules and such prerequisites as: OpenCascade, Python, Swig, Qt, etc.

The dependencies between SALOME modules are managed in the following way:

  • If one module is unchecked, all modules which depend on this one are also unchecked automatically;
  • If one module is checked, all modules required for this one are also checked automatically.

Dependency between modules and prerequisites is realized in the following way:

  • The choices made by the user in the list of modules have a direct impact on the list of prerequisites;
  • Whenever a module is checked, all the necessary prerequisites are checked automatically with no possibility for the user to uncheck them (see Fig. 7 below);
  • Whenever a module is unchecked, according to the remaining checked modules, the unnecessary prerequisites are unchecked automatically (see Fig. 7 below).

It is possible to check again the prerequisites, which have been automatically unchecked. In other words, it is possible to add more prerequisites than necessary.

productpage3.png


Figure 7: Dependencies between modules and prerequisites

The "Installation with GUI" checkbox allows managing the installation of the graphical interface. Only modules for that 'woguimode' attribute is set to "true" value in the XML file (see here for more information about customizing this installation mode) support without GUI mode and will be checked and installed with their necessary prerequisites in case of installation without GUI. And other modules are unchecked with no possibility to check them in this mode (see Figure below).
By default 'Installation with GUI' checkbox is switched on.

productpage4.png


Figure 8: Installation without GUI mode

The box at the right side of the page displays the information about currently selected product: name, version and short description, required disk space, disk space required for temporary files and the list of prerequisites (this information is provided in the XML file).

The "Disk space required:" field displays how much disk space on the hard drive is required for installation of selected products.
Note: Please, take into account that the displayed amount of required disk space is approximate and may differ when you actually install products on your hard drive.

The installation procedure uses a special directory to store temporary files. The "Space for temporary files:" field shows the information about required disk space on the hard drive for extracting and compiling the selected products. You can change the temporary directory (this information is provided in the XML file) to the folder you want.
Note: Actually, temporary files are not stored directly in the directory entered by the user. The Installation Wizard creates in this directory an additional folder named like INSTALLWORKXXXXX where XXXXX is a unique number. This allows launching several Installation Wizards simultaneously. This temporary directory is removed automatically when the installation finishes.

The installation procedure also checks the available disk space. If there is not enough disk space on your hard drive you will see the corresponding error message box.

Also in the current version of Installation Wizard is possible to install all binaries of the selected SALOME modules into a single directory. It is "SALOME" directory. For this purpose there is a checkbox "Install modules to a single directory" checkbox exists (see Fig. 8).
This feature helps to get shorter PYTHONPATH and LD_LIBRARY_PATH environment variables.
Note: the installation into a single directory is available with the binaries installation type only.

To proceed further click "Next". At this moment the program will make some tests to check the installation settings: if there is enough disk space on the hard drive, check for the dependencies for each product you have selected to be installed. If any test fails you will see the corresponding warning message box. Otherwise the wizard will proceed to the next page:

choicepage.png


Figure 9: "Check your choice" page

This page summarizes the installation options you've selected in the previous pages. You can review again your choices and change them if necessary returning to the previous pages.
When you are sure that everything is OK, click "Next" to follow to the progress page.

progresspage1.png


Figure 10: "Installation progress" page

To start the installation of the selected products click "Start" button. It launches the shell installation script and you will be able to see the output of the script in the topmost frame of the dialog box. If any errors occur during the installation progress, the corresponding messages will be printed to the log window in the bold red font.
It is possible to break the installation at any time by pressing "Stop" button. Then you can get back to the previous pages if you wish to change the installation settings or restart the installation by pressing "Start" button again.

Note: in the current implementation it is not possible to resume the stopped installation process; the installation will restart from the very beginning.

progresspage2.png


Figure 11: "Installation progress" page: installation in progress

The "Installation Status" frame window shows you the progress of installation. "Waiting" status means that installation of this product has not been started yet. The product currently being installed is marked as "Processing" and is displayed in the status bar under "Installation Status" view. All installed products have "Completed" status.

You can abort installation and close the installation procedure using "Cancel" button.

Note: This button sends the signal "SIGTERM" to the shell script. The script tries to clear all temporary files. The process of removing temporary files can take some time, so the installation wizard will wait 3 seconds before closing.

At the end of the installation "Installation completed" message will appear in the status bar. You can return to the previous pages to start a new installation or click "Next" button to go to the readme page:

readmepage.png


Figure 12: "Finish installation" page

In this page you can read important information about the Instalation Wizard itself and some tips: how to run and test SALOME or how to build SALOME from the sources. This is the contents of the README file which you can find in the root directory of the Installation Wizard.

You can also launch SALOME Desktop from this page or read the Release Notes file by clicking on the corresponding buttons in the lower part of the page (see here and here for more information about customizing these buttons).



Batch mode

To launch the Installation Wizard in the batch mode use -b (--batch) parameter.
In this mode the GUI wizard is not shown but all the installation status is displayed directly in the console. In the batch mode the user does not have a possibility to change installation settings which are given in the configuration file, except target and temporary directories which can be overridden by the corresponding command line options.
The only exception is --all-from-sources (-a) option which enables special installation mode in which all the products (including SALOME modules) are installed from sources, ignoring the default mode defined in the XML configuration file (see here for details) and --single-directory (-s) option which defines that all SALOME modules have to be installed into the one directory (SALOME_<version>, by default, where <version> is SALOME version).

batchmode.png


Figure 13: Batch mode



Environment files

During the process of installation the script creates some environment files to simplify the procedure of launching SALOME. These shell scripts set all necessary environment variables for all products you have installed. To learn how installation scripts collects the environment, see here. These files are: salome.csh + salome.sh in the KERNEL module sources and KERNEL module binaries root directories and env_products.csh + env_products.sh and env_build.csh + env_build.sh in the target installation directory.

Note: there is some difference between these files: env_build.* files are optimized to be used for building SALOME modules from sources (see README file provided with the installation procedure on the CD). The env_products.* (and salome.*) files are optimized for SALOME launching. The behavior is defined by the environment variable ENV_FOR_LAUNCH which is set to 0 in env_build.* files and to 1 in env_products.* (salome.*) files.



Pick up the environment

Please, read carefully the following information. This section describes how the installation procedure generates the environment scripts for the SALOME platform being installed.

After installing each product shell the script creates a special environment file for the product in its installation folder. The name of the file is generated from the name of product by the following scheme: env_<product_name>.sh (for example env_Vtk.sh for the Vtk). This file includes all necessary environment settings. At the final step of the installation the script picks up all the settings files and generates two common environment files from them: salome.sh and salome.csh for bash and csh shells correspondingly. Such approach helps to save time when reinstalling products and you may not bother about setting all environment variables manually to build/launch SALOME. What you simply need is to source one of these environment files.

This also concerns those products which are not being installed. For example, you install some SALOME binaries to the directory where you have previously installed other products. The Installation procedure tries to collect environment files from the target directory if it finds necessary products installed there. If some product is not found in the target directory the corresponding section of salome.sh/salome.csh files will be skipped.
For native products (like gcc, tcl, etc...) the installation procedure tries to find them first using PATH / LD_LIBRARY_PATH variables and then in the system default directories (/usr/bin, /usr/lib etc., depending on the product).

In any case you may edit salome.* files after the installation procedure finishes, if you want.


Note: As it was mentioned above there are other environment files which are generated by the installation procedure: env_products.csh + env_products.sh and env_build.csh + env_build.sh. These files can be found in the target installation root directory.



Modifying XML configuration file

You can create your own XML configuration file. The Installation Wizard can then take it as a command line argument to provide a list of products you want to install with it. The list of products and some other settings for the Installation Wizard are provided in the XML file.
This section describes the structure of the configuration file, optional sections/tags are in brackets.

<document>
      <config [ version=<application_version>      ]
              [ caption=<application_caption>      ]
              [ copyright=<application_copyright>  ]
              [ license=<application_license_info> ]
                platforms=<target_platform>
              [ targetdir=<target_directory>       ]
              [ tempdir=<temp_directory>           ]
      />
    [ <buttons>
      [ <button   label=<button_label>     
                [ tooltip=<button_tooltip> ]
                  script=<button_script>   
                [ disable=<disable_flag>   ]
        />
      ]
      [ <button ...
        />
      ]
        ...
      </buttons>
    ]
    [ <products>
      [ <product  name=<product_name>
                  type=<product_type>
                [ description=<product_description> ]
          <installation  os=<installation_platform>
                         version=<product_version>
                       [ disable=<disable_flag>            ]
                       [ woguimode=<without_gui_mode_flag> ]
                         installdiskspace=<install_disk_space>
                       [ pickupenv=<pickup_env_flag>       ] 
                         script=<installation_script_name>
          />
          ...
        />
      ]
      [ <product ...
        />
      ]
        ...
      </products>
    ]
    [ <dependencies>
      [ <product  name=<product_name> >
        [ <dep> <prerequisite_name> </dep> ]
          ...
        </product>
      ]
        ...
      </dependencies>
    ]
</document> 

<config> section

This is an optional section; it provides general information about the Installation Wizard itself.

Attributes:

  • version

    The application version number to be shown in the caption.

  • caption

    The application main window caption - if this string contains '%1' text the title will contain the version number in this place (see above).

  • copyright

    The application copyright information (shown in the first page).

  • license

    The application license information (shown in the first page).

  • platforms

    This parameter defines the directory (relative from ./Products/BINARIES) where the Installation Wizard will search precompiled binaries packages. If this tag is not provided, binaries packages are looked for in the ./Products/BINARIES directory.

  • targetdir

    The target directory - the path to the directory where products should be installed.

  • tempdir

    The temporary directory - the path to the directory for the temporary files.

<button> section

This is an optional section. It allows customization of the last "Finish installation" page of the Installation Wizard by adding one or more buttons in the lower part of the wizard's window. The script which is attached to each such button, can perform some specific action, for example, launch the application or show the Release Notes file by using an external program. See here for more details about writing scripts.

Attributes:

  • label

    This is the button text.

  • tooltip

    The button tooltip (optional).

  • script

    The script attached to the button.

  • disable

    If this optional flag has 'true' value, the corresponding button will not appear in the "<em>Finish installation</em>" page - the section of XML file is silently ignored.

<product> section

This section describes product to be installed with the Installation Wizard. The XML file should include a <product> section for each product to be installed. The products appear in the tree view and are installed in the order they are described in the configuration file. It is recommended (but not obligatory) to define native products at the top of the list before all other products.

Attributes:

  • name

    Product name.

  • type

    The type of the product: 'component' - SALOME module or 'prerequisite' - prerequisite product.

  • description

    Product description (optional).

<installation> section

It is a part of the <product> section, that provides installation information by platforms. The <product> section may contains a several <installation> ones for the different platforms.

Attributes:

  • os

    A possible installation platform.

  • version

    The version of the product.

  • disable

    If this optional flag has 'true' value, the corresponding product will not appear in the list of products and will not be installed.

  • woguimode

    This optional flag defines that it's possible to install this module without GUI.

  • installdiskspace

    List of three total amount spaces (integer, in Kbytes, derived by comma), which product occupies on the hard drive after the installation in case 'binary', 'sources' and 'sources and compile' installation type.

  • pickenv

    This flag shows that the pickup environment procedure should be performed for this product. If this flag equal to 'true', salome.sh and salome.csh files will be created in the product's installation directory. Usually this option is set to true for SALOME KERNEL module. This is optional key, default value is 'false'.

  • script

    The installation script name. This script is in charge of the installation of the product. It is called automatically by the Installation Wizard when necessary from the main program. See the see next section for more information.


Note: If you add new products to be installed with Installation Wizard, you should also provide installation script for this product. See the next section for more details.



Implementing installation scripts for the new products

When you want some product to be installed with the Installation Wizard, you should add its description to the configuration file and create the installation script, following the rules described in this section.

There are some obligatory functions which should be implemented in this installation script. These functions are automatically called by the master installation script or/and its GUI shell when it is necessary.
File common.sh contains some service functions which can be used in your installation script, like make_env(), make_dir(), try_existing(), sort_path(), find_in_path(), etc.

  • check_version()

    This function allows to check the version of the product already installed on the computer. It should try to find the product (native or preinstalled in the target directory) and check its version. This helps to avoid unnecessary reinstallation. This is an internal function and is not called from the master installation script.

  • install_binary()

    This function is called when 'Install binaries' installation mode is selected by the user. The function is responsible for the extracting of the product from the binaries package. It should create environment for the product in the temporary directory (see also the description of print_env() function). It is not necessary to implement this function if you do not provide binaries mode installation for the current product.

  • install_source() This function is called to install SALOME modules sources, if 'Install binaries' installation mode is selected by the user, and to install prerequisite products sources, in 'Install sources' case (Fig. 2 above). The function is responsible for the building of the product from the sources package. It should create the environment file for the product in the temporary directory (see also the description of print_env() function). It is not necessary to implement this function if you do not provide a sources mode installation for the current product.

  • install_source_and_build() This function is called when 'Install sources and make a compilation' installation mode is selected. This function should be used to unpack SALOME or prerequisite sources package and then call build/install procedure for it. For more details please refer to the this and this sections for more details.

  • try_preinstalled()

    This function is called when the 'not install' installation mode is selected by the user. In this case the script should inspect the target directory to try to find an already preinstalled product, pick up and check the environment from there. See here for more details.

  • print_env_bin() & print_env_src()

    These functions are in charge of the creation of the environment scripts. They should create in the temporary directory two files with env_<product_name>.sh and env_<product_name>_src.sh names and then copy them into the binary and sources product installation directories correspondingly. The file should contain all necessary environment variable settings for the product. It will be collected during the 'pick-up-environment' procedure.

  • pickup_env()

    This procedure corresponds to the pickupenv tag of the configuration xml file (see previous section). It should call the make_env procedure to perform the pick-up environment procedure for the product.

The calling signature of the product installation script is the following: <product_script_name> <function_name> <temp_folder> <products_directory> <target_directory> <dependancies> <product_name>

where

<product_script_name> - installation script name (described in the configuration xml file);
<function_name> - the name of function, corresponding to the selected installation mode: try_native, install_source, install_binary or try_preinstalled;
<temp_folder> - temporary files directory;
<products_directory> - directory where the sources/binaries package can be found. You should provide the sources package in the <Install_Wizard_root_directory>/Products/SOURCES directory and binaries package in the <InstallWizard_root_directory>/Products/BINARIES/<os_version>, where <os_version> is the target platform description, which appears in the corresponding section of the configuration xml file; <target_directory> - root target directory where the product should be installed to; <dependancies> - single-quoted list of prerequisite products, separated by space; <product_name> - product name itself.

Example:
med-2.2.3.sh install_binary /tmp/work ./Products/BINARIES/Mandrake10.1 /usr/salome 'gcc Hdf' med

Copy the created script into the <Install_Wizard_root_directory>/config_files sub-directory where all installation scripts are stored. Installation Wizard will automatically search and call your script during the installation procedure.



Customizing Readme page buttons

The Installation Wizard allows customizing the look-n-feel of the last "Finish installation" page. If you want to add one or more buttons to this page in order to perform some specific actions at the end of the installation (for example, to show the Release Notes file by using Open Office) you can put an additional section to the XML configuration file. This is the <button> section (see here for more details).

To implement the action which will be performed when the user clicks the button, you need to create a script and put it to the <Install_Wizard_root_directory>/config_files directory.
There are some obligatory functions which should be implemented in this script. These functions are automatically called by the Installation Wizard GUI.

  • check_enabled()

    This procedure is called by the Installation Wizard when the "Finish installation" page is displayed and the status of the buttons should be modified according to the installation options. This procedure should return 0 if the corresponding action can be performed and, thus, the button should become enabled. Otherwise, it should return 1 - in this case the corresponding button will be disabled.

  • execute()

    This procedure is invoked when the user clicks the button. This procedure should return 0 if the corresponding action is done successfully and 1 if any error occurs.

The calling signature of the script is the following:
<product_script_name> <function_name> <target_directory> <temp_folder>

where

<product_script_name> - the script name itself (retrieved from the XML configuration xml file);
<function_name> - the name of function;
<target_directory> - root target directory where the product is installed to;
<temp_folder> - temporary files directory;


Note: The standard Installation Wizard buttons "Launch SALOME" and "Release Notes" are implemented with this feature. Refer to scripts start_salome.sh and release_notes.sh for sample implementation.


Note: Any button (even standard) can be ignored by the Installation Wizard if the attribute <disable> in the XML configuration file is set to the "true" value.