doc/src/configuration.rst

   1 *************
   2 Configuration
   3 *************
   4
   5 Introduction
   6 ============
   7
   8 For the configuration, SAT uses a python module called *config*, which aims to offer more power and flexibility for the configuration of python programs.
   9 This module was slightly adapted for SAT, and renamed Pyconf.
  10 (see `config module <http://www.red-dove.com/config-doc/>`_ for a complete description of the module, the associated syntax, the documentation).
  11
  12 *sat* uses files with **.pyconf** extension to store the configuration parameters.
  13 These *.pyconf* are parsed by SAT, and merged into a global configuration, which is passed to the sat commands and used by them.
  14
  15
  16 Configuration projects
  17 ======================
  18
  19 By default SAT is provided with no configuration at all, except is own internal one.
  20 The configuration is brought by SAT projects : usually a git base containing all the configuration files of a project (*.pyconf* files).
  21 For Salome platform, the SAT project is called SAT_SALOME and can be downloaded from salome Tuleap forge.
  22 SAT projects are loaded in sat with the sat init command:
  23
  24 .. code-block:: bash
  25
  26     # get salome platform SAT configuration project (SAT_SALOME), and load it into SAT
  27     git clone SAT_SALOME
  28     SAT/sat init --add_project $(pwd)/SAT_SALOME/salome.pyconf
  29
  30 SAT_SALOME project provides all configuration files for salome applications, and for the products that are used in these applications.
  31
  32
  33 Application configuration
  34 =========================
  35
  36 The configuration files of applications contain the required information for SAT to build the application.
  37 They are usually located in the application directory of the project:
  38
  39 .. code-block:: bash
  40
  41     # list applications provided by SAT_SALOME project
  42     ls SAT_SALOME/applications
  43     >   MEDCOUPLING-9.4.0.pyconf             SALOME-7.8.0.pyconf
  44     >   SALOME-8.5.0.pyconf          SALOME-9.4.0.pyconf
  45
  46 These files can be edited directly, and also with the SAT:
  47
  48 .. code-block:: bash
  49
  50     # edit SALOME-9.4.0.pyconf configuration file
  51     SAT/sat config SALOME-9.4.0 -e
  52
  53
  54 The application configuration file defines the APPLICATION sections. The content of this section (or a part of it) can be displayed with *sat config* command:
  55
  56 .. code-block:: bash
  57
  58     # display the complete APPLICATION configuration
  59     sat config SALOME-9.4.0 -v APPLICATION
  60
  61     # display only the application properties
  62     sat config SALOME-9.4.0 -v APPLICATION.properties
  63
  64 SAT users that need to create new application files for their own purpose usually copy an existing configuration file and adapt it to their application.
  65 Let's discribe the content of an application pyconf file. We take in the following examples the file *SAT_SALOME/applications/SALOME-9.4.0.pyconf*.
  66
  67
  68 Global variables and flags
  69 --------------------------
  70
  71 At the beginning of the APPLICATION sections, global variables and flags are defined:
  72
  73   * **name** : the name of the application (mandatory)
  74   * **workdir** : the directory in which the application is produced (mandatory)
  75   * **tag** : the default tag to use for the git bases
  76   * **dev** : activate the dev mode. In dev mode git bases are checked out only one time, to avoid risks of removing developments.
  77   * **verbose** : activate verbosity in the compilation
  78   * **debug** : activate debug mode in the compilation, i.e -g option
  79   * **python3** : 'yes/no' tell sat that the application uses python3
  80   * **base** : 'yes/no/name' to set up the use of a SAT base
  81
  82 .. code-block:: bash
  83
  84     APPLICATION :
  85     {
  86         name : 'SALOME-9.4.0'
  87         workdir : $LOCAL.workdir + $VARS.sep + $APPLICATION.name + '-' + $VARS.dist
  88         tag : 'V9_4_BR'
  89         debug : 'no'
  90         dev : 'no'
  91         base : 'no'
  92         python3 : 'yes'
  93         ...
  94
  95 Please note the workdir variable is defined in the above example with references to other sections defined in other configurations files (i.e. $LOCAL and $VARS).
  96 It's a useful Pyconf functionality.
  97 Most of the global variables are optionnal, except name and workdir.
  98
  99 Environment subsection
 100 ----------------------
 101
 102 This subsection allows defining environment variables at the application level (most of the time the environment is set by the products configuration).
 103
 104 .. code-block:: bash
 105
 106     APPLICATION :
 107     {
 108     ...
 109         environ :
 110         {
 111             build : {CONFIGURATION_ROOT_DIR : $workdir + $VARS.sep + "SOURCES" +\
 112                      $VARS.sep + "CONFIGURATION"}
 113             launch : {PYTHONIOENCODING:"UTF_8"}
 114             SALOME_trace : "local" # local/file:.../with_logger
 115             # specify the first modules to display in gui
 116             SALOME_MODULES : "SHAPER,GEOM,SMESH,PARAVIS,YACS,JOBMANAGER"
 117         }
 118     }
 119
 120 In the example above CONFIGURATION_ROOT_DIR variable will be set only at compile time (usage of *build* key), while PYTHONIOENCODING will be set only at run-time (use of *launch* key).
 121 variables SALOME_trace and SALOME_MODULES are set both at compile time and run time.
 122
 123
 124 products subsection
 125 -------------------
 126
 127 This subsection will specify which products are included in the application.
 128 For each product, it is possible to specify in a dictionnary:
 129
 130   * **tag** : the tag to use for the product
 131   * **dev** : activate the dev mode.
 132   * **verbose** : activate verbosity in the compilation
 133   * **debug** : activate debug mode
 134
 135 If these flags are not specified, SAT takes the default application flag.
 136 In the following example, SAT uses the default tag V9_4_BR for products SHAPER, KERNEL and MEDCOUPLING.
 137 For LIBBATCH it uses the tag V2_4_2.
 138 KERNEL is compiled in debug and verbose mode.
 139
 140 .. code-block:: bash
 141
 142     APPLICATION :
 143     {
 144     ...
 145         tag : 'V9_4_BR'
 146     ...
 147         products :
 148         {
 149         'SHAPER'
 150         'LIBBATCH' : {tag :'V2_4_2'}
 151         'KERNEL' : {debug:'yes', verbose:'yes'}
 152         'MEDCOUPLING'
 153         ...
 154
 155
 156 properties
 157 ----------
 158
 159 Properties are used by SAT to define some general rules or policies.
 160 They can be defined in the application configuration with the properties subsection:
 161
 162 .. code-block:: bash
 163
 164     APPLICATION :
 165     {
 166     ...
 167         properties :
 168         {
 169             mesa_launcher_in_package : "yes"
 170             repo_dev : "yes"
 171             pip : 'yes'
 172             pip_install_dir : 'python'
 173         }
 174
 175 In this example the following properties are used:
 176
 177  * **mesa_launcher_in_package** : ask to put a mesa launcher in the packages produced by sat package command
 178  * **repo_dev** : use the development git base (for salome, the tuleap forge)
 179  * **pip** : ask to use pip to get python products
 180  * **pip_install_dir** : install pip products in python installation directory (not in separate directories)
 181
 182
 183 Products configuration
 184 ======================
 185
 186 The configuration files of products contain the required information for SAT to build each product.
 187 They are usually located in the product directory of the project. SAT_SALOME supports a lot of products:
 188
 189 .. code-block:: bash
 190
 191     ls SAT_SALOME/products/
 192     ADAO_INTERFACE.pyconf     homard_bin.pyconf          PyQtChart.pyconf
 193     ADAO.pyconf               homard_pre_windows.pyconf  PyQt.pyconf
 194     alabaster.pyconf          HOMARD.pyconf              pyreadline.pyconf
 195     ALAMOS_PROFILE.pyconf     HXX2SALOME.pyconf          Python.pyconf
 196     ALAMOS.pyconf             HYBRIDPLUGIN.pyconf        pytz.pyconf
 197     Babel.pyconf              idna.pyconf                qt.pyconf
 198     BLSURFPLUGIN.pyconf       imagesize.pyconf           qwt.pyconf
 199     boost.pyconf              ispc.pyconf                requests.pyconf
 200     bsd_xdr.pyconf            Jinja2.pyconf              RESTRICTED.pyconf
 201     CALCULATOR.pyconf         JOBMANAGER.pyconf          root.pyconf
 202     CAS.pyconf                KERNEL.pyconf              ruby.pyconf
 203     CDMATH.pyconf             kiwisolver.pyconf          SALOME_FORMATION_PROFILE.pyconf
 204     CEATESTBASE.pyconf        lapack.pyconf              SALOME_PROFILE.pyconf
 205     certifi.pyconf            lata.pyconf                SALOME.pyconf
 206     cgns.pyconf               LIBBATCH.pyconf            SAMPLES.pyconf
 207     chardet.pyconf            libjpeg.pyconf             scipy.pyconf
 208     click.pyconf              libpng.pyconf              scons.pyconf
 209     cmake.pyconf              libxml2.pyconf             scotch.pyconf
 210     colorama.pyconf           llvm.pyconf                setuptools.pyconf
 211     compil_scripts            markupsafe.pyconf          SHAPER.pyconf
 212     COMPONENT.pyconf          matplotlib.pyconf          SHAPERSTUDY.pyconf
 213     CONFIGURATION.pyconf      MEDCOUPLING.pyconf         sip.pyconf
 214     COREFLOWS_PROFILE.pyconf  medfile.pyconf             six.pyconf
 215     COREFLOWS.pyconf          med_pre_windows.pyconf     SMESH.pyconf
 216     cppunit.pyconf            MED.pyconf                 snowballstemmer.pyconf
 217     cycler.pyconf             mesa.pyconf                SOLVERLAB.pyconf
 218     Cython.pyconf             MeshGems.pyconf            solvespace.pyconf
 219     dateutil.pyconf           metis.pyconf               sphinxcontrib_applehelp.pyconf
 220     distribute.pyconf         mpc.pyconf                 sphinxcontrib_devhelp.pyconf
 221     DOCUMENTATION.pyconf      mpfr.pyconf                sphinxcontrib_htmlhelp.pyconf
 222     docutils.pyconf           msvc.pyconf                sphinxcontrib_jsmath.pyconf
 223     doxygen.pyconf            NETGENPLUGIN.pyconf        sphinxcontrib_napoleon.pyconf
 224     EFICAS.pyconf             netgen.pyconf              sphinxcontrib.pyconf
 225     EFICAS_TOOLS.pyconf       nlopt.pyconf               sphinxcontrib_qthelp.pyconf
 226     eigen.pyconf              numpy.pyconf               sphinxcontrib_serializinghtml.pyconf
 227     embree.pyconf             omniNotify.pyconf          sphinxcontrib_websupport.pyconf
 228     env_scripts               omniORB.pyconf             sphinxintl.pyconf
 229     expat.pyconf              omniORBpy.pyconf           Sphinx.pyconf
 230     f2c.pyconf                openblas.pyconf            sphinx_rtd_theme.pyconf
 231     ffmpeg.pyconf             opencv.pyconf              subprocess32.pyconf
 232     FIELDS.pyconf             openmpi.pyconf             swig.pyconf
 233     freeimage.pyconf          openssl.pyconf             tbb.pyconf
 234     freetype.pyconf           ospray.pyconf              tcl.pyconf
 235     ftgl.pyconf               packaging.pyconf           tcltk.pyconf
 236     functools32.pyconf        ParaViewData.pyconf        TECHOBJ_ROOT.pyconf
 237     gcc.pyconf                ParaView.pyconf            tk.pyconf
 238     GEOM.pyconf               PARAVIS.pyconf             Togl.pyconf
 239     GHS3DPLUGIN.pyconf        ParMetis.pyconf            TRIOCFD_IHM.pyconf
 240     GHS3DPRLPLUGIN.pyconf     patches                    TRIOCFD_PROFILE.pyconf
 241     gl2ps.pyconf              perl.pyconf                TrioCFD.pyconf
 242     glu.pyconf                petsc.pyconf               TRUST.pyconf
 243     gmp.pyconf                Pillow.pyconf              typing.pyconf
 244     GMSHPLUGIN.pyconf         planegcs.pyconf            uranie_win.pyconf
 245     gmsh.pyconf               pockets.pyconf             urllib3.pyconf
 246     graphviz.pyconf           pthreads.pyconf            VISU.pyconf
 247     GUI.pyconf                PY2CPP.pyconf              vtk.pyconf
 248     hdf5.pyconf               pybind11.pyconf            XDATA.pyconf
 249     HELLO.pyconf              PYCALCULATOR.pyconf        YACSGEN.pyconf
 250     HEXABLOCKPLUGIN.pyconf    Pygments.pyconf            YACS.pyconf
 251     HEXABLOCK.pyconf          PyHamcrest.pyconf          zlib.pyconf
 252     HexoticPLUGIN.pyconf      PYHELLO.pyconf
 253     Hexotic.pyconf            pyparsing.pyconf
 254
 255
 256 Available product configuration flags
 257 -------------------------------------
 258
 259 * **name** : the name of the product
 260 * **build_source** : the method to use when getting the sources, possible choices are script/cmake/autotools. If "script" is chosen, a compilation script should be provided with compil_script key
 261 * **compil_script** : to specify a compilation script (in conjunction with build_source set to "script"). The programming language is bash under linux, and bat under windows.
 262 * **post_script** : to specify a post installation script (use it as a hook to do extra wokr after installation).
 263 * **get_source** : the mode to get the sources, possible choices are archive/git/svn/cvs
 264 * **depend** : to give SAT the dependencies of the product
 265 * **patches** : provides a list of patches, if required
 266 * **source_dir** : where SAT copies the source
 267 * **build_dir** : where SAT builds the product
 268 * **install_dir** : where SAT installs the product
 269
 270 The following example is the configuration of boost product:
 271
 272 .. code-block:: bash
 273
 274     default :
 275     {
 276         name : "boost"
 277         build_source : "script"
 278         compil_script :  $name + $VARS.scriptExtension
 279         get_source : "archive"
 280         environ :
 281         {
 282            env_script : $name + ".py"
 283         }
 284         depend : ['Python' ]
 285         opt_depend : ['openmpi' ]
 286         patches : [ ]
 287         source_dir : $APPLICATION.workdir + $VARS.sep + 'SOURCES' + $VARS.sep + $name
 288         build_dir : $APPLICATION.workdir + $VARS.sep + 'BUILD' + $VARS.sep + $name
 289         install_dir : 'base'
 290         properties :
 291         {
 292             single_install_dir : "yes"
 293             incremental : "yes"
 294         }
 295     }
 296
 297
 298 Product properties
 299 ------------------
 300
 301 Properties are also associated to products.
 302 It is possible to list all the properties with the command *./sat config SALOME-9.4.0 --show_properties**
 303
 304 Here are some properties frequently used:
 305
 306 * **single_install_dir** : the product can be installed in a common directory
 307 * **compile_time** : the product is used only at compile time (ex : swig)
 308 * **pip** : the product is managed by pip
 309 * **not_in_package** : the product will not be put in packages
 310 * **is_SALOME_module** : the product is a SALOME module
 311 * **is_distene** : the product requires a DISTENE licence
 312
 313 The product properties allow SAT doing specific choices according to the property.
 314 They also allow users filtering products when calling commands.
 315 For example it is possible to compile only SALOME modules with the command:
 316
 317 .. code-block:: bash
 318
 319     # just recompile SALOME modules, not other products
 320     ./sat compile SALOME-9.4.0 --properties is_SALOME_module:yes --clean_all
 321
 322
 323 Product environment
 324 -------------------
 325
 326 The product environment is declared in a subsection called environment.
 327 It is used by sat at compile time to set up the environment for the compilation of all the products depending upon it.
 328 It is also used at run time to set up the application environment.
 329
 330 Two mechanisms are offered to define the environment.
 331 The first one is similar to the one used in the application configuration : inside the environ section, we declare variables or paths.
 332 A variable appended or prepended by an underscore is treated as a path, to which we prepend or append the valued according to the position of the underscore.
 333 In the following example, the value *<install_dir/share/salome/ressources/salome* is prepended to the path SalomeAppConfig.
 334
 335 .. code-block:: bash
 336
 337     environ :
 338     {
 339         _SalomeAppConfig : $install_dir + $VARS.sep + "share" + $VARS.sep + "salome" +\
 340                            $VARS.sep + "resources" + $VARS.sep + "salome"
 341     }
 342
 343
 344 But the most common way is to use an environment script, which specifies the environment by using an API provided by sat:
 345
 346 .. code-block:: bash
 347
 348     # use script qt.py to set up qt environment
 349     environ :
 350     {
 351        env_script : "qt.py"
 352     }
 353
 354 As an example, the environment script for qt is:
 355
 356 .. code-block:: python
 357
 358     #!/usr/bin/env python
 359     #-*- coding:utf-8 -*-
 360
 361     import os.path
 362     import platform
 363
 364     def set_env(env, prereq_dir, version):
 365         env.set('QTDIR', prereq_dir)
 366
 367         version_maj = version.split('.')
 368         if version_maj[0] == '5':
 369             env.set('QT5_ROOT_DIR', prereq_dir)
 370             env.prepend('QT_PLUGIN_PATH', os.path.join(prereq_dir, 'plugins'))
 371             env.prepend('QT_QPA_PLATFORM_PLUGIN_PATH',
 372                          os.path.join(prereq_dir, 'plugins'))
 373             pass
 374         else:
 375             env.set('QT4_ROOT_DIR', prereq_dir)
 376             pass
 377
 378         env.prepend('PATH', os.path.join(prereq_dir, 'bin'))
 379
 380         if platform.system() == "Windows" :
 381             env.prepend('LIB', os.path.join(prereq_dir, 'lib'))
 382             pass
 383         else :
 384             env.prepend('LD_LIBRARY_PATH', os.path.join(prereq_dir, 'lib'))
 385             pass
 386
 387 *env* is the API provided by SAT, *prereq_dir* is the installation directory, *version* the product version.
 388 *env.set* sets a variable, *env.prepend* and *env.append* are used to prepend or append values to a path.
 389
 390 The **setenv** function is used to set the environment at compile time and run time.
 391 It is also possible to use **set_env_build** and **set_env_launch** callback functions to set specific compile or run time environment.
 392 Finally the function **set_nativ_env** is used for native products.
 393
 394
 395 Product sections
 396 ----------------
 397
 398 The product configuration file may contain several sections.
 399 In addition to the  "default" section, it is possible to declare other sections that will be used for specific versions of the product.
 400 This allows SAT compiling different versions of a product.
 401 To determine which section should be used, SAT has an algorithm that takes into account the version number.
 402 Here are some examples of sections that will be taken into account by SAT :
 403
 404 .. code-block:: bash
 405
 406     # this section will be used for versions between 8.5.0 and 9.2.1
 407     _from_8_5_0_to_9_2_1 :
 408     {
 409         ...
 410     }
 411
 412     # this section will only ve used for 9.3.0 version
 413     version_9_3_0 :
 414     {
 415         ...
 416     }
 417
 418 Several version numbering are considered by SAT (not only X.Y.Z)
 419 For example V9, v9, 9, 9.0.0, 9_0_0, are accepted.
 420
 421 By default SAT only considers one section : the one determined according to the version number, or the default one.
 422 But if the **incremental property** is defined in the default section, and is set to "yes", then SAT enters in the **incremental mode** and merges different sections into one,
 423 by proceeding incremental steps. SAT uses the following algorithm to merge the sections:
 424
 425 #. We take the complete "default" section
 426 #. If a "default_win" section is defined, we merge it.
 427 #. If a section name corresponds to the version number, we also merge it.
 428 #. Finally on windows platform if the same section name appended by _win exists, we merge it.
 429
 430
 431 Other configuration sections
 432 ============================
 433
 434
 435 The configuration of SAT is split into eight sections : VARS, APPLICATION, PRODUCTS, PROJECTS, PATHS, USER, LOCAL, INTERNAL.
 436 These sections are fed by the pyconf files which are loaded by sat: each pyconf file is parsed by SAT and merged into the global configuration.
 437 One file can reference variables defined in other files. Files are loaded in this order :
 438
 439 * the internal pyconf (declared inside sat)
 440 * the personal pyconf : *~/.salomeTools/SAT.pyconf*
 441 * the application pyconf
 442 * the products pyconf (for all products declared in the application)
 443
 444 In order to check the configuration and the merge done by sat, it is possible to display the resulting eight section with the command:
 445
 446 .. code-block:: bash
 447
 448     # display the content of a configuration section
 449     # (VARS, APPLICATION, PRODUCTS, PROJECTS, PATHS, USER, LOCAL, INTERNAL)
 450     SAT/sat config SALOME-9.4.0 -v <section>
 451
 452 Note also that if you don't remember the name of a section it is possible to display section names with the automatic completion functionality.
 453
 454 We have already described two of the sections : APPLICATION and PRODUCTS.
 455 Let's describe briefly the six others.
 456
 457 .. _VARS-Section:
 458
 459 VARS section
 460 -------------
 461 | This section is dynamically created by SAT at run time.
 462 | It contains information about the environment: date, time, OS, architecture etc.
 463
 464 ::
 465
 466     # to get the current setting
 467     sat config --value VARS
 468
 469
 470 USER section
 471 --------------
 472
 473 This section is defined by the user configuration file,
 474 ``~/.salomeTools/SAT.pyconf``.
 475
 476 The ``USER`` section defines some parameters (not exhaustive):
 477
 478 * **pdf_viewer** : the pdf viewer used to read pdf documentation
 479
 480 * **browser** : The web browser to use (*firefox*).
 481
 482 * **editor** : The editor to use (*vi, pluma*).
 483
 484 * and other user preferences.
 485
 486 ::
 487
 488     # to get the current setting
 489     sat config SALOME-xx --value USER
 490
 491     # to edit your personal configuration file
 492     sat config -e
 493
 494
 495 Other sections
 496 --------------
 497
 498 * **PROJECTS** : This section contains the configuration of the projects loaded in SAT by *sat init --add_project* command.
 499 * **PATHS** : This section contains paths used by sat.
 500 * **LOCAL** : contains information relative to the local installation of SAT.
 501 * **INTERNAL** : contains internal SAT information
 502
 503
 504 Overwriting the configuration
 505 =============================
 506
 507 At the end of the process, SAT ends up with a complete global configuration resulting from the parsing of all *.pyconf* files.
 508 It may be interesting to overwrite the configuration.
 509 SAT offers two overwriting mechanisms to answer these two use cases:
 510
 511 #. Be able to conditionally modify the configuration of an application to take into account specifics and support multi-platform builds
 512 #. Be able to modify the configuration in the command line, to enable or disable some options at run time
 513
 514 Application overwriting
 515 -----------------------
 516
 517 At the end of the application configuration, it is possible to define an overwrite section with the keyword **__overwrite__ :**.
 518 It is followed by a list of overwrite sections, that may be conditional (use of the keyword **__condition__ :**).
 519 A classical usage of the application overwriting is the change of a prerequisite version for a given platform (when the default version does not compile).
 520
 521 .. code-block:: bash
 522
 523     __overwrite__ :
 524     [
 525       {
 526        # opencv 3 do not compile on old CO6
 527         __condition__ : "VARS.dist in ['CO6']"
 528         'APPLICATION.products.opencv' : '2.4.13.5'
 529       }
 530     ]
 531
 532
 533 Command line overwriting
 534 ------------------------
 535
 536 Command line overwriting is triggered by sat **-o** option, followed in double quotes by the parameter to overwrite, the = sign and the value in simple quotes.
 537 In the following example, we suppose that the application SALOME-9.4.0 has set both flags debug and verbose to "no", and that we want to recompile MEDCOUPLING in debug mode, with cmake verbosity activated. The command to use is:
 538
 539 .. code-block:: bash
 540
 541     # recompile MEDCOUPLING in debug mode (-g) and with verbosity
 542     ./sat -t -o "APPLICATION.verbose='yes'" -o "APPLICATION.debug='yes'" compile\
 543                  SALOME-9.4.0 -p MEDCOUPLING --clean_all
 544