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).
12 *salomeTools* 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.
16 Configuration projects
17 ======================
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 dowloaded from salome Tuleap forge.
22 SAT projects are loaded in sat with the sat init command:
26 # get salome platform SAT configuration project (SAT_SALOME), and load it into SAT
28 SAT/sat init --add_project $(pwd)/SAT_SALOME/salome.pyconf
30 SAT_SALOME project provides all configuration files for salome applications, and for the products that are used in these applications.
33 Application configuration
34 =========================
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:
41 # list applications provided by SAT_SALOME project
42 ls SAT_SALOME/applications
43 MEDCOUPLING-9.4.0.pyconf SALOME-7.8.0.pyconf SALOME-8.5.0.pyconf SALOME-9.4.0.pyconf
45 The application configuration file defines the APPLICATION sections. The content of this section can be displayed with *sat config* command:
49 sat config SALOME-9.4.0 -v APPLICATION
51 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.
52 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*.
55 Global variables and flags
56 --------------------------
58 At the beginning of the APPLICATION sections, global variables and flags are defined:
60 * **name** : the name of the application (mandatory)
61 * **workdir** : the directory in which the application is produced (mandatory)
62 * **tag** : the default tag to use for the git bases
63 * **dev** : activate the dev mode. in dev mode git bases are checked out only one time, to avoid risks of removing developments.
64 * **verbose** : activate verbosity in the compilation
65 * **debug** : activate debug mode in the compilation, i.e -g option
66 * **python3** : 'yes/no' tell sat that the application uses python3
67 * **base** : 'yes/no/name' to set up the use of a SAT base
74 workdir : $LOCAL.workdir + $VARS.sep + $APPLICATION.name + '-' + $VARS.dist
82 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).
83 It's a useful Pyconf functionality).
84 Most of the global variables are optionnal, except name and workdir.
86 Environment subsection
87 ----------------------
89 This subsection allows defining environment variables at the application level (most of the time the environment is set by the products configuration).
98 build : {CONFIGURATION_ROOT_DIR : $workdir + $VARS.sep + "SOURCES" + $VARS.sep + "CONFIGURATION"}
99 launch : {PYTHONIOENCODING:"UTF_8"}
100 SALOME_trace : "local" # local/file:.../with_logger
101 SALOME_MODULES : "SHAPER,GEOM,SMESH,PARAVIS,YACS,JOBMANAGER" # specify the first modules to display in gui
105 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).
106 variables SALOME_trace and SALOME_MODULES are set both at compile time and run time.
112 This subsection will specify which products are included in the application.
113 For each product, it is possible to specify in a dictionnary:
115 * **tag** : the tag to use for the product
116 * **dev** : activate the dev mode.
117 * **verbose** : activate verbosity in the compilation
118 * **debug** : activate debug mode
120 If this flags are not specified, SAT takes the default application flag.
121 In the following example, SAT uses the the default tag V9_4_BR for products SHAPER, KERNEL and MEDCOUPLING.
122 For LIBBATCH it uses the tag V2_4_2.
123 KERNEL is compile in debug and verbose mode.
135 'LIBBATCH' : {tag :'V2_4_2'}
136 'KERNEL' : {debug:'yes', verbose:'yes'}
144 Properties are used by SAT to define some general rules or policies.
145 They can be defined in the application configuration with the properties subsection:
154 mesa_launcher_in_package : "yes"
157 pip_install_dir : 'python'
160 In this example the following properties are used:
162 * **mesa_launcher_in_package** : ask to put a mesa launcher in the packages produced by sat package commans
163 * **repo_dev** : use the development git base (for salome, the tuleap forge)
164 * **pip** : ask to use pip to get python products
165 * **pip_install_dir** : install pip products in python installation directory (not in separate directories)
168 Products configuration
169 ======================
171 The configuration files of products contain the required information for SAT to build each product.
172 They are usually located in the product directory of the project. SAT_SALOME supports a lot of products:
176 ls SAT_SALOME/products/
177 ADAO_INTERFACE.pyconf COREFLOWS_PROFILE.pyconf GHS3DPLUGIN.pyconf JOBMANAGER.pyconf omniORB.pyconf Python.pyconf Sphinx.pyconf
178 ADAO_MODULE.pyconf COREFLOWS.pyconf GHS3DPRLPLUGIN.pyconf KERNEL.pyconf omniORBpy.pyconf pytz.pyconf sphinx_rtd_theme.pyconf
179 ADAO.pyconf cppunit.pyconf gl2ps.pyconf kiwisolver.pyconf opencv.pyconf qt.pyconf subprocess32.pyconf
180 alabaster.pyconf cycler.pyconf glu.pyconf lapack.pyconf openmpi.pyconf qwt.pyconf swig.pyconf
181 ALAMOS_PROFILE.pyconf Cython.pyconf GMSHPLUGIN.pyconf lata.pyconf ospray.pyconf requests.pyconf tbb.pyconf
182 ALAMOS.pyconf dateutil.pyconf gmsh.pyconf LIBBATCH.pyconf packaging.pyconf SALOME_FORMATION_PROFILE.pyconf tcl.pyconf
183 Babel.pyconf distribute.pyconf graphviz.pyconf libpng.pyconf ParaViewData.pyconf SALOME_PROFILE.pyconf TECHOBJ_ROOT.pyconf
184 BLSURFPLUGIN.pyconf DOCUMENTATION.pyconf GUI.pyconf libxml2.pyconf ParaView.pyconf SALOME.pyconf tk.pyconf
185 boost.pyconf docutils.pyconf hdf5.pyconf llvm.pyconf PARAVIS.pyconf SAMPLES.pyconf Togl.pyconf
186 bsd_xdr.pyconf doxygen.pyconf HELLO.pyconf markupsafe.pyconf ParMetis.pyconf scipy.pyconf TRIOCFD_IHM.pyconf
187 CALCULATOR.pyconf EFICAS.pyconf HEXABLOCKPLUGIN.pyconf matplotlib.pyconf patches scons.pyconf TrioCFD.pyconf
188 CAS.pyconf EFICAS_TOOLS.pyconf HEXABLOCK.pyconf MEDCOUPLING.pyconf petsc.pyconf scotch.pyconf TRUST.pyconf
189 CDMATH.pyconf eigen.pyconf HexoticPLUGIN.pyconf medfile.pyconf planegcs.pyconf setuptools.pyconf typing.pyconf
190 CEATESTBASE.pyconf embree.pyconf Hexotic.pyconf med_pre_windows.pyconf pockets.pyconf SHAPER.pyconf uranie_win.pyconf
191 certifi.pyconf env_scripts homard_bin.pyconf MED.pyconf pthreads.pyconf sip.pyconf urllib3.pyconf
192 cgns.pyconf expat.pyconf homard_pre_windows.pyconf mesa.pyconf PY2CPP.pyconf six.pyconf VISU.pyconf
193 chardet.pyconf f2c.pyconf HOMARD.pyconf MeshGems.pyconf PYCALCULATOR.pyconf SMESH.pyconf vtk.pyconf
194 click.pyconf FIELDS.pyconf HXX2SALOME.pyconf metis.pyconf Pygments.pyconf snowballstemmer.pyconf XDATA.pyconf
195 cmake.pyconf freeimage.pyconf HYBRIDPLUGIN.pyconf NETGENPLUGIN.pyconf pyhamcrest.pyconf solvespace.pyconf YACSGEN.pyconf
196 colorama.pyconf freetype.pyconf idna.pyconf netgen.pyconf PYHELLO.pyconf sphinxcontrib_napoleon.pyconf YACS.pyconf
197 compil_scripts ftgl.pyconf imagesize.pyconf nlopt.pyconf pyparsing.pyconf sphinxcontrib.pyconf zlib.pyconf
198 COMPONENT.pyconf functools32.pyconf ispc.pyconf numpy.pyconf PyQt.pyconf sphinxcontrib_websupport.pyconf
199 CONFIGURATION.pyconf GEOM.pyconf Jinja2.pyconf omniNotify.pyconf pyreadline.pyconf sphinxintl.pyconf
202 Available product configuration flags
203 -------------------------------------
205 * **name** : the name of the product
206 * **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
207 * **compil_script** : to specify a compilation script (in conjonction with build_source set to "script"). The programation langage is bash under linux, and bat under windows.
208 * **get_source** : the mode to get the sources, possible choices are archive/git/svn/cvs
209 * **depend** : to give SAT the dependencies of the product
210 * **patches** : provides a list of patches, if required
211 * **source_dir** : where SAT copies the source
212 * **build_dir** : where SAT builds the product
213 * **install_dir** : where SAT installs the product
215 The following example is the configuration of boost product:
222 build_source : "script"
223 compil_script : $name + $VARS.scriptExtension
224 get_source : "archive"
227 env_script : $name + ".py"
230 opt_depend : ['openmpi' ]
232 source_dir : $APPLICATION.workdir + $VARS.sep + 'SOURCES' + $VARS.sep + $name
233 build_dir : $APPLICATION.workdir + $VARS.sep + 'BUILD' + $VARS.sep + $name
237 single_install_dir : "yes"
246 Properties are also associated to products.
247 It is possible to list all the properties with the command *./sat config SALOME-9.4.0 --show_properties**
249 Here are some properties frequently used:
251 * **single_install_dir* : the product can be installed in a common directory
252 * **compile_time* : the product is used only at compile time (ex : swig)
253 * **pip* : the product is managed by pip
254 * **not_in_package** : the product will not be put in packages
255 * **is_SALOME_module** : te product is a SALOME module
256 * **is_distene** : the product requires a DISTENE licence
258 The product properties allow SAT doing specific choices according to the property.
259 They also allow users filtering products when calling commands.
260 For example it is possible to compile only SALOME modules with the command:
264 # just recompile SALOME modules, not other products
265 ./sat compile SALOME-9.4.0 --properties is_SALOME_module:yes --clean_all
271 The product environment is declared in a subsection called environment.
272 It is used by sat at compile time the set up the environment for the compilation of all the products depending upon it.
273 It is also used at run tim to set up the application environment.
275 Two mecanisms are offered to define the environment.
276 The first one is similar to the one used in the application configuration : inside the environ section, we declare variables or paths.
277 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.
278 In the above example, the value *<install_dir/share/salome/ressources/salome* is prepended to the path SalomeAppConfig.
284 _SalomeAppConfig : $install_dir + $VARS.sep + "share" + $VARS.sep + "salome" + $VARS.sep + "resources" + $VARS.sep + "salome"
288 But the most common way is to use a environment script, which specify the environment by using an API provided by sat:
292 # use script qt.py to set up qt environement
298 As an example, the environment script for qt is:
300 .. code-block:: python
302 #!/usr/bin/env python
303 #-*- coding:utf-8 -*-
308 def set_env(env, prereq_dir, version):
309 env.set('QTDIR', prereq_dir)
311 version_maj = version.split('.')
312 if version_maj[0] == '5':
313 env.set('QT5_ROOT_DIR', prereq_dir)
314 env.prepend('QT_PLUGIN_PATH', os.path.join(prereq_dir, 'plugins'))
315 env.prepend('QT_QPA_PLATFORM_PLUGIN_PATH', os.path.join(prereq_dir, 'plugins'))
318 env.set('QT4_ROOT_DIR', prereq_dir)
321 env.prepend('PATH', os.path.join(prereq_dir, 'bin'))
323 if platform.system() == "Windows" :
324 env.prepend('LIB', os.path.join(prereq_dir, 'lib'))
327 env.prepend('LD_LIBRARY_PATH', os.path.join(prereq_dir, 'lib'))
330 *env* is the API provided by SAT, prereq_dir is the installation directory, version the product version.
331 env.set set a variable, env.prepend and env.append are used to prepend or append values to a path.
333 The **setenv** function is used to set the environement at compile time and run time.
334 It is also possible to use **set_env_build** and **set_env_launch** callback functions to set specific compile or run time environment.
335 Finally the functions **set_nativ_env** is used for native products.
341 The product configuration file may contain several sections.
342 In addition to the "default" section, it is possible to declare other section that will be used for specific versions of the product.
343 This allows SAT compiling different version of a products.
344 To determine which section should be used, SAT has an algorithm that takes into account the version number.
345 Here are some examples of sections that will be taken into account by SAT :
349 # this section will be used for versions between 8.5.0 and 9.2.1
350 _from_8_5_0_to_9_2_1 :
355 # this section will only ve used for 9.3.0 version
361 Several version numbering are considered by SAT (not only X.Y.Z)
362 For example V9, v9, 9, 9.0.0, 9_0_0, are acepted.
364 By default SAT only consider one section : the one determined according to the version number, or the default one.
365 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,
366 by proceeding incremental steps. SAT uses the following algorithm to merge the sections:
368 #. We take the complete "default" section
369 #. if a "default_win" section is defined, we merge it.
370 #. If a section name correspond to the version number, we also merge it.
371 #. Finally on windows platform if the same section name appended by _win exists, we merge it.
374 Other configuration sections
375 ============================
378 The configuration of SAT is split into height sections : VARS, APPLICATION, PRODUCTS, PROJECTS, PATHS, USER, LOCAL, INTERNAL.
379 These sections are feeded by the pyconf files which are loaded by sat: each pyconf file is parsed by SAT and merged into the global configuration.
380 One file can reference variables defined in other files. Files are loaded in this order :
382 * the internal pyconf (declared inside sat)
383 * the personal pyconf : *~/.salomeTools/SAT.pyconf*
384 * the application pyconf
385 * the products pyconf (for all products declared in the application)
387 In order to check the configuration and the merge done by sat, it is possible to display the resulting height section with the command:
391 # display the content of a configuration section
392 # (VARS, APPLICATION, PRODUCTS, PROJECTS, PATHS, USER, LOCAL, INTERNAL)
393 SAT/sat config SALOME-9.4.0 -v <section>
395 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.
397 We have already described two of the sections : APPLICATION and PRODUCTS.
398 Let's describe briefly the six others
404 | This section is dynamically created by SAT at run time.
405 | It contains information about the environment: date, time, OS, architecture etc.
409 # to get the current setting
410 sat config --value VARS
416 This section is defined by the user configuration file,
417 ``~/.salomeTools/SAT.pyconf``.
419 The ``USER`` section defines some parameters (not exhaustive):
421 * **pdf_viewer** : the pdf viewer used to read pdf documentation
423 * **browser** : The web browser to use (*firefox*).
425 * **editor** : The editor to use (*vi, pluma*).
427 * and other user preferences.
431 # to get the current setting
432 sat config SALOME-xx --value USER
434 # to edit your personal configuration file
441 * **PROJECTs** : This section contains the configuration of the projects loaded in SAT by *sat init --add_project* command.
442 * **PATHS** : This section contains paths used by saloeTools.
443 * **LOCAL** : contains information relative to the local installation of SAT.
444 * **INTERNAL** : contains internal SAT information
447 Overwriting the configution
448 ===========================
450 At the end of the process, SAT ends up with a complete global configuration resulting from the parsing of all *.pyconf* files.
451 It may be interesting to overwrite the configuration.
452 SAT offer two overwriting mecanism to answer these two use cases:
454 #. Be able to conditionaly modify the configuration of an application to take into account specifics and support multi-platform builds
455 #. Be able to modify the configuration in the command line, to enable or disable some options at run time
457 Application overwriting
458 -----------------------
460 At the end of the application configuration, it is possible to define an overwrite section with the keyword **__overwrite__ :**.
461 It is followed by a list overwrite sections, that may be conditionnal (use of the keyword **__condition__ :**).
462 A classical usage of the application overwriting is the change of a prerequisite version for a given platform (when the default version do not compile).
463 /bin/bash: q : commande introuvable
470 # opencv 3 do not compile on old CO6
471 __condition__ : "VARS.dist in ['CO6']"
472 'APPLICATION.products.opencv' : '2.4.13.5'
477 Command line overwriting
478 ------------------------
480 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.
481 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:
485 # recompile MEDCOUPLING in debug mode (-g) and with verbosity
486 ./sat -t -o "APPLICATION.verbose='yes'" -o "APPLICATION.debug='yes'" compile SALOME-9.4.0 -p MEDCOUPLING --clean_all