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 *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.
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 downloaded 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
44 > SALOME-8.5.0.pyconf SALOME-9.4.0.pyconf
46 These files can be edited directly, and also with the SAT:
50 # edit SALOME-9.4.0.pyconf configuration file
51 SAT/sat config SALOME-9.4.0 -e
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:
58 # display the complete APPLICATION configuration
59 sat config SALOME-9.4.0 -v APPLICATION
61 # display only the application properties
62 sat config SALOME-9.4.0 -v APPLICATION.properties
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*.
68 Global variables and flags
69 --------------------------
71 At the beginning of the APPLICATION sections, global variables and flags are defined:
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
87 workdir : $LOCAL.workdir + $VARS.sep + $APPLICATION.name + '-' + $VARS.dist
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.
99 Environment subsection
100 ----------------------
102 This subsection allows defining environment variables at the application level (most of the time the environment is set by the products configuration).
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"
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.
127 This subsection will specify which products are included in the application.
128 For each product, it is possible to specify in a dictionnary:
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
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.
150 'LIBBATCH' : {tag :'V2_4_2'}
151 'KERNEL' : {debug:'yes', verbose:'yes'}
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:
169 mesa_launcher_in_package : "yes"
172 pip_install_dir : 'python'
175 In this example the following properties are used:
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)
183 Products configuration
184 ======================
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:
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
256 Available product configuration flags
257 -------------------------------------
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
270 The following example is the configuration of boost product:
277 build_source : "script"
278 compil_script : $name + $VARS.scriptExtension
279 get_source : "archive"
282 env_script : $name + ".py"
285 opt_depend : ['openmpi' ]
287 source_dir : $APPLICATION.workdir + $VARS.sep + 'SOURCES' + $VARS.sep + $name
288 build_dir : $APPLICATION.workdir + $VARS.sep + 'BUILD' + $VARS.sep + $name
292 single_install_dir : "yes"
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**
304 Here are some properties frequently used:
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
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:
319 # just recompile SALOME modules, not other products
320 ./sat compile SALOME-9.4.0 --properties is_SALOME_module:yes --clean_all
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.
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.
339 _SalomeAppConfig : $install_dir + $VARS.sep + "share" + $VARS.sep + "salome" +\
340 $VARS.sep + "resources" + $VARS.sep + "salome"
344 But the most common way is to use an environment script, which specifies the environment by using an API provided by sat:
348 # use script qt.py to set up qt environment
354 As an example, the environment script for qt is:
356 .. code-block:: python
358 #!/usr/bin/env python
359 #-*- coding:utf-8 -*-
364 def set_env(env, prereq_dir, version):
365 env.set('QTDIR', prereq_dir)
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'))
375 env.set('QT4_ROOT_DIR', prereq_dir)
378 env.prepend('PATH', os.path.join(prereq_dir, 'bin'))
380 if platform.system() == "Windows" :
381 env.prepend('LIB', os.path.join(prereq_dir, 'lib'))
384 env.prepend('LD_LIBRARY_PATH', os.path.join(prereq_dir, 'lib'))
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.
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.
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 :
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 :
412 # this section will only ve used for 9.3.0 version
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.
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:
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.
431 Other configuration sections
432 ============================
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 :
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)
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:
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>
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.
454 We have already described two of the sections : APPLICATION and PRODUCTS.
455 Let's describe briefly the six others.
461 | This section is dynamically created by SAT at run time.
462 | It contains information about the environment: date, time, OS, architecture etc.
466 # to get the current setting
467 sat config --value VARS
473 This section is defined by the user configuration file,
474 ``~/.salomeTools/SAT.pyconf``.
476 The ``USER`` section defines some parameters (not exhaustive):
478 * **pdf_viewer** : the pdf viewer used to read pdf documentation
480 * **browser** : The web browser to use (*firefox*).
482 * **editor** : The editor to use (*vi, pluma*).
484 * and other user preferences.
488 # to get the current setting
489 sat config SALOME-xx --value USER
491 # to edit your personal configuration file
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
504 Overwriting the configuration
505 =============================
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:
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
514 Application overwriting
515 -----------------------
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).
526 # opencv 3 do not compile on old CO6
527 __condition__ : "VARS.dist in ['CO6']"
528 'APPLICATION.products.opencv' : '2.4.13.5'
533 Command line overwriting
534 ------------------------
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:
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