doc/src/commands/environ.rst

   1
   2 .. include:: ../../rst_prolog.rst
   3
   4 Command environ
   5 ****************
   6
   7 Description
   8 ===========
   9 The **environ** command generates the environment files used
  10 to run and compile your application (as SALOME_ is an example).
  11
  12 .. note ::
  13    these files are **not** required,
  14    salomeTool set the environment himself, when compiling.
  15    And so does the salome launcher.
  16
  17    These files are useful when someone wants to check the environment.
  18    They could be used in debug mode to set the environment for *gdb*.
  19
  20 The configuration part at the end of this page explains how
  21 to specify the environment used by sat (at build or run time),
  22 and saved in some files by *sat environ* command.
  23
  24 Usage
  25 =====
  26 * Create the shell environment files of the application: ::
  27
  28     sat environ <application>
  29
  30 * Create the environment files of the application for a given shell.
  31   Options are bash, bat (for windows) and cfg (the configuration format used by SALOME_): ::
  32
  33     sat environ <application> --shell [bash|cfg|all]
  34
  35 * Use a different prefix for the files (default is 'env'):
  36
  37   .. code-block:: bash
  38
  39     # This will create file <prefix>_launch.sh, <prefix>_build.sh
  40     sat environ <application> --prefix <prefix>
  41
  42 * Use a different target directory for the files:
  43
  44   .. code-block:: bash
  45
  46     # This will create file env_launch.sh, env_build.sh
  47     # in the directory corresponding to <path>
  48     sat environ <application> --target <path>
  49
  50 * Generate the environment files only with the given products:
  51
  52   .. code-block:: bash
  53
  54     # This will create the environment files only for the given products
  55     # and their prerequisites.
  56     # It is useful when you want to visualise which environment uses
  57     # sat to compile a given product.
  58     sat environ <application> --product <product1>,<product2>, ...
  59
  60
  61 Configuration
  62 =============
  63
  64 The specification of the environment can be done through several mechanisms.
  65
  66 1. For salome products (the products with the property ``is_SALOME_module`` as ``yes``) the environment is set automatically by sat, in respect with SALOME_ requirements.
  67
  68 2. For other products, the environment is set with the use of the environ section within the pyconf file of the product. The user has two possibilities, either set directly the environment within the section, or specify a python script which wil be used to set the environment programmatically.
  69
  70 Within the section, the user can define environment variables. He can also modify PATH variables, by appending or prepending directories.
  71 In the following example, we prepend *<install_dir>/lib* to ``LD_LIBRARY_PATH`` (note the *left first* underscore), append *<install_dir>/lib* to ``PYTHONPATH`` (note the *right last* underscore), and set ``LAPACK_ROOT_DIR`` to *<install_dir>*:
  72
  73 .. code-block:: python
  74
  75     environ :
  76     {
  77       _LD_LIBRARY_PATH : $install_dir + $VARS.sep + "lib"
  78       PYTHONPATH_ : $install_dir + $VARS.sep + "lib"
  79       LAPACK_ROOT_DIR : $install_dir
  80     }
  81
  82 It is possible to distinguish the build environment from the launch environment: use a subsection called *build* or *launch*. In the example below, ``LD_LIBRARY_PATH`` and ``PYTHONPATH`` are only modified at run time, not at compile time:
  83
  84 .. code-block:: python
  85
  86     environ :
  87     {
  88       build :
  89       {
  90         LAPACK_ROOT_DIR : $install_dir
  91       }
  92       launch :
  93       {
  94         LAPACK_ROOT_DIR : $install_dir
  95         _LD_LIBRARY_PATH : $install_dir + $VARS.sep + "lib"
  96         PYTHONPATH_ : $install_dir + $VARS.sep + "lib"
  97       }
  98     }
  99
 100 3. The last possibility is to set the environment with a python script. The script should be provided in the *products/env_scripts* directory of the sat project, and its name is specified in the environment section with the key ``environ.env_script``:
 101
 102 .. code-block:: python
 103
 104     environ :
 105     {
 106       env_script : 'lapack.py'
 107     }
 108
 109 Please note that the two modes are complementary and are both taken into account.
 110 Most of the time, the first mode is sufficient.
 111
 112 The second mode can be used when the environment has to be set programmatically.
 113 The developer implements a handle (as a python method)
 114 which is called by sat to set the environment.
 115 Here is an example:
 116
 117 .. code-block:: python
 118
 119
 120     #!/usr/bin/env python
 121     #-*- coding:utf-8 -*-
 122
 123     import os.path
 124     import platform
 125
 126     def set_env(env, prereq_dir, version):
 127         env.set("TRUST_ROOT_DIR",prereq_dir)
 128         env.prepend('PATH', os.path.join(prereq_dir, 'bin'))
 129         env.prepend('PATH', os.path.join(prereq_dir, 'include'))
 130         env.prepend('LD_LIBRARY_PATH', os.path.join(prereq_dir, 'lib'))
 131         return
 132
 133 SalomeTools defines four handles:
 134
 135 * **set_env(env, prereq_dir, version)** : used at build and run time.
 136 * **set_env_launch(env, prereq_dir, version)** : used only at run time (if defined!)
 137 * **set_env_build(env, prereq_dir, version)** : used only at build time (if defined!)
 138 * **set_native_env(env)** : used only for native products, at build and run time.
 139