Description
===========
-The **application** command creates a virtual SALOME_ application.
+The **application** command creates a virtual SALOME application.
Virtual SALOME applications are used to start SALOME when distribution is needed.
Usage
sat application <application> --target <my_application_directory>
-* Set a specific SALOME_ resources catalog (it will be used for the distribution of components on distant machines): ::
+* Set a specific SALOME resources catalog (it will be used for the distribution of components on distant machines): ::
sat application <application> --catalog <path_to_catalog>
sat launcher <application> --use_mesa
-Some useful configuration pathes
+Some useful configuration paths
=================================
-The virtual application can be configured with the virtual_app section of the configutation file.
+The virtual application can be configured with the virtual_app section of the configuration file.
* **APPLICATION.virtual_app**
The **clean** command removes products in the *source, build, or install* directories of an application. Theses directories are usually named ``SOURCES, BUILD, INSTALL``.
-Use the options to define what directories you want to suppress and to set the list of products
+Use the options to define what directories you want to suppress and to set the list of products.
Usage
# take care, is long time to restore, sometimes
sat clean SALOME-xx --build --install
-* Clean previously created *build* and *install* directories, only for products with property *is_salome_module*:
+* Clean previously created *build* and *install* directories, only for products with property *is_SALOME_module*:
.. code-block:: bash
sat clean SALOME-xxx --build --install \
- --properties is_salome_module:yes
+ --properties is_SALOME_module:yes
-Availables options
-======================
+Available options
+=================
* **--products** : Products to clean.
* **--properties** :
| Filter the products by their properties.
- | Syntax: *--properties <property>:<value>*
+ | Syntax: ``--properties <property>:<value>``
* **--sources** : Clean the product source directories.
-Some useful configuration pathes
+Some useful configuration paths
=================================
No specific configuration.
sat compile <application> --products <product1>,<product2> ...
-* Use *sat -t* to duplicate the logs in the terminal (by default the log are stored and displayed with *sat log* command): ::
+* Use *sat -t* to duplicate the logs in the terminal (by default the logs are stored and displayed with *sat log* command): ::
sat -t compile <application> --products <product1>
* Stop the compilation as soon as the compilation of a module fails: ::
- sat compile <product> --stop_first_fail
+ sat compile <application> --stop_first_fail
* Do not compile, just show if products are installed or not, and where is the installation: ::
sat compile <application> --show
-* Print the recursive list of dependencies of one (ore several) products: ::
+* Print the recursive list of dependencies of one (or several) products: ::
sat -v5 compile SALOME-master -p GEOM --with_fathers --show
-Some useful configuration pathes
+Some useful configuration paths
=================================
-The way to compile a product is defined in the *pyconf file configuration*.
+The way to compile a product is defined in the *pyconf* file configuration.
The main options are:
* **build_source** : the method used to build the product (cmake/autotools/script)
* **compil_script** : the compilation script if build_source is equal to "script"
* **cmake_options** : additional options for cmake.
* **nb_proc** : number of jobs to use with make for this product.
- * **check_install** : allow to specify a list of path (relative to install directory), that sat will check after installation. This flag allow to check an installation is complete.
+ * **check_install** : allow to specify a list of paths (relative to install directory), that sat will check after installation. This flag allows to check if an installation is complete.
* **install_dir** : allow to change the default install dir. If the value is set to *'base'*, the product will by default be installed in salomeTool base. Unless base was set to 'no' in application pyconf.
sat config --edit
-* List the available applications (they come from the sat projects defined in ``data/local.pyconf``: ::
+* List the available applications (they come from the sat projects defined in ``data/local.pyconf``): ::
sat config --list
sat config SALOME-xx --info KERNEL
sat config SALOME-xx --info qt
-Some useful configuration pathes
+Some useful configuration paths
=================================
Exploring a current configuration.
-Some useful configuration pathes
+Some useful configuration paths
=================================
* **USER**
.. note ::
these files are **not** required,
- salomeTool set the environment himself, when compiling.
+ salomeTool sets the environment itself, when compiling.
And so does the salome launcher.
These files are useful when someone wants to check the environment.
sat environ <application>
* Create the environment files of the application for a given shell.
- Options are bash, bat (for windows), tcl, cfg (the configuration format used by SALOME_): ::
+ Options are bash, bat (for windows), tcl, cfg (the configuration format used by SALOME): ::
sat environ <application> --shell [bash|bat|cfg|tcl|all]
The specification of the environment can be done through several mechanisms.
-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.
+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.
-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.
+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 will be used to set the environment programmatically.
Within the section, the user can define environment variables. He can also modify PATH variables, by appending or prepending directories.
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>*:
Description
===========
-The **generate** command generates and compile SALOME modules from cpp modules using YACSGEN.
+The **generate** command generates and compiles SALOME modules from cpp modules using YACSGEN.
.. note:: This command uses YACSGEN to generate the module. It needs to be specified with *--yacsgen* option, or defined in the product or by the environment variable ``$YACSGEN_ROOT_DIR``.
cpp : "yes"
generate : "yes"
-* The cpp module are usually computational components, and the generated module brings the CORBA layer which allows distributing the compononent on remore machines. cpp modules should conform to YACSGEN/hxx2salome requirements (please refer to YACSGEN documentation)
+* The cpp modules are usually computational components, and the generated module brings the CORBA layer which allows distributing the compononent on remote machines. cpp modules should conform to YACSGEN/hxx2salome requirements (please refer to YACSGEN documentation).
Usage
Usage
=====
-* A sat project provides all the pyconf files relatives to a project (salome for example). Use the *--add_project* command to add a sat project locally, in data/local.pyconf (by default sat comes without any project). It is possible to add as many projects as required. ::
+* A sat project provides all the pyconf files relative to a project (salome for example). Use the *--add_project* command to add a sat project locally, in data/local.pyconf (by default sat comes without any project). It is possible to add as many projects as required. ::
sat init --add_project <path/to/a/sat/project/project.pyconf>
-* If you need to remove a sat project from the local configuration, use the *--reset_projects* command to remove all projects and then add the nex ones with *--add_project*: ::
+* If you need to remove a sat project from the local configuration, use the *--reset_projects* command to remove all projects and then add the next ones with *--add_project*: ::
sat init --reset_projects
sat init --add_project <path/to/a/new/sat/project/project.pyconf>
sat init --archive_dir <local/path/where/to/store/product/archives>
-* sat enable a **base** mode, which allow to mutualize product builds between several applications. By defaut, the mutualised builds are stored locally within the directory containing salomeTool, in a subdirectory called BASE. To change the default, use the *--base* option: ::
+* sat enables a **base** mode, which allows to mutualize product builds between several applications. By default, the mutualized builds are stored locally within the directory containing salomeTool, in a subdirectory called BASE. To change the default, use the *--base* option: ::
sat init --base <local/path/where/to/store/product/mutualised/product/builds>
-Some useful configuration pathes
+Some useful configuration paths
=================================
All the sat init commands update the local pyconf salomeTool file data/local.pyconf. The same result can be achieved by editing the file directly.
The launcher will be called *ZeLauncher*.
-* Set a launcher which do not initialise the PATH variables: ::
+* Set a launcher which does not initialise the PATH variables: ::
sat launcher <application> --no_path_init
- In this case the launcher do not initialise the path variables (the defaut is to do it only for PATH, not fot LD_LIBRARY_PATH, PYTHONPATH, etc).
+ In this case the launcher does not initialise the path variables (the default is to do it only for PATH, not for LD_LIBRARY_PATH, PYTHONPATH, etc).
-* Create a generic launcher, which set the environment (bash or bat) and call the exe given as argument: ::
+* Create a generic launcher, which sets the environment (bash or bat) and call the exe given as argument: ::
sat launcher <application> -e INSTALL/SALOME/bin/salome/salome.py -n salome.sh
sat launcher <application> --gencat <list of machines>
- This will create a catalog by querying each machine (memory, number of processor) with ssh.
+ This will create a catalog by querying each machine (memory, number of processors) with ssh.
* Generate a mesa launcher (if mesa and llvm are parts of the application). Use this option only if you have to use salome through ssh and have problems with ssh X forwarding of OpengGL modules (like Paravis): ::
Configuration
=============
-Some useful configuration pathes:
+Some useful configuration paths:
* **APPLICATION.profile**
-Some useful configuration pathes
+Some useful configuration paths
=================================
* **USER**
Description
============
-The **package** command creates a SALOME_ archive (usually a compressed Tar_ file .tgz).
-This tar file is used later to intall SALOME on other remote computer.
+The **package** command creates a SALOME archive (usually a compressed Tar_ file .tgz).
+This tar file is used later to install SALOME on other remote computer.
Depending on the selected options, the archive includes sources and binaries
of SALOME products and prerequisites.
.. note::
By default the package includes the sources of prerequisites and products.
- To select a subset use the *--without_property* or *--with_vcs* options.
+ To select a subset, use the *--without_property* or *--with_vcs* options.
Usage
sat package SALOME_xx --binaries
This command will create an archive named ``SALOME_xx _<arch>.tgz``
- where <arch> is the OS_ architecture of the machine.
+ where <arch> is the OS architecture of the machine.
-* Do not delete Version Control System (VCS_) informations from the configurations files of the embedded salomeTools: ::
+* Do not delete Version Control System (VCS_) information from the configuration files of the embedded salomeTools: ::
sat package SALOME_xx --with_vcs
The version control systems known by this option are CVS_, SVN_ and Git_.
-Some useful configuration pathes
+Some useful configuration paths
=================================
No specific configuration.
The first time you will execute the *sat prepare* command,
your module will be downloaded in *checkout* mode
-(inside the SOURCES directory of the application.
+(inside the SOURCES directory of the application).
Then, you can develop in this repository, and finally push
them in the base when they are ready.
If you type during the development process by mistake
a *sat prepare* command, the sources in dev mode will
-not be altered/removed (Unless you use -f option)
+not be altered/removed (unless you use -f option).
Usage
sat prepare <application> --complete
-Some useful configuration pathes
+Some useful configuration paths
=================================
Command *sat prepare* uses the *pyconf file configuration* of each product to know how to get the sources.
* **get_method**: the method to use to prepare the module, possible values are cvs, git, archive, dir.
* **git_info** : (used if get_method = git) information to prepare sources from git.
-* **svn_info** : (used if get_method = svn) information to prepare sources from cvs.
+* **svn_info** : (used if get_method = svn) information to prepare sources from svn.
* **cvs_info** : (used if get_method = cvs) information to prepare sources from cvs.
* **archive_info** : (used if get_method = archive) the path to the archive.
* **dir_info** : (used if get_method = dir) the directory with the sources.
The **template** command generates the sources of a SALOME module out of a template.
SAT provides two templates for SALOME 9 :
-* PythonComponent : a complete template for a SALOME module implemented in python (with data model and GUI)
-* CppComponent : a template for a SALOME component implemented in C++, with a code coupling API
+* PythonComponent : a complete template for a SALOME module implemented in python (with data model and GUI).
+* CppComponent : a template for a SALOME component implemented in C++, with a code coupling API.
Usage
=====
By default SAT is provided with no configuration at all, except is own internal one.
The configuration is brought by SAT projects : usually a git base containing all the configuration files of a project (*.pyconf* files).
-For Salome platform, the SAT project is called SAT_SALOME and can be dowloaded from salome Tuleap forge.
+For Salome platform, the SAT project is called SAT_SALOME and can be downloaded from salome Tuleap forge.
SAT projects are loaded in sat with the sat init command:
.. code-block:: bash
* **name** : the name of the application (mandatory)
* **workdir** : the directory in which the application is produced (mandatory)
* **tag** : the default tag to use for the git bases
- * **dev** : activate the dev mode. in dev mode git bases are checked out only one time, to avoid risks of removing developments.
+ * **dev** : activate the dev mode. In dev mode git bases are checked out only one time, to avoid risks of removing developments.
* **verbose** : activate verbosity in the compilation
* **debug** : activate debug mode in the compilation, i.e -g option
* **python3** : 'yes/no' tell sat that the application uses python3
...
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).
-It's a useful Pyconf functionality).
+It's a useful Pyconf functionality.
Most of the global variables are optionnal, except name and workdir.
Environment subsection
* **verbose** : activate verbosity in the compilation
* **debug** : activate debug mode
-If this flags are not specified, SAT takes the default application flag.
-In the following example, SAT uses the the default tag V9_4_BR for products SHAPER, KERNEL and MEDCOUPLING.
+If these flags are not specified, SAT takes the default application flag.
+In the following example, SAT uses the default tag V9_4_BR for products SHAPER, KERNEL and MEDCOUPLING.
For LIBBATCH it uses the tag V2_4_2.
-KERNEL is compile in debug and verbose mode.
+KERNEL is compiled in debug and verbose mode.
.. code-block:: bash
In this example the following properties are used:
- * **mesa_launcher_in_package** : ask to put a mesa launcher in the packages produced by sat package commans
+ * **mesa_launcher_in_package** : ask to put a mesa launcher in the packages produced by sat package command
* **repo_dev** : use the development git base (for salome, the tuleap forge)
* **pip** : ask to use pip to get python products
* **pip_install_dir** : install pip products in python installation directory (not in separate directories)
* **name** : the name of the product
* **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
-* **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.
+* **compil_script** : to specify a compilation script (in conjonction with build_source set to "script"). The programming language is bash under linux, and bat under windows.
* **get_source** : the mode to get the sources, possible choices are archive/git/svn/cvs
* **depend** : to give SAT the dependencies of the product
* **patches** : provides a list of patches, if required
* **compile_time** : the product is used only at compile time (ex : swig)
* **pip** : the product is managed by pip
* **not_in_package** : the product will not be put in packages
-* **is_SALOME_module** : te product is a SALOME module
+* **is_SALOME_module** : the product is a SALOME module
* **is_distene** : the product requires a DISTENE licence
The product properties allow SAT doing specific choices according to the property.
-------------------
The product environment is declared in a subsection called environment.
-It is used by sat at compile time the set up the environment for the compilation of all the products depending upon it.
+It is used by sat at compile time to set up the environment for the compilation of all the products depending upon it.
It is also used at run tim to set up the application environment.
-Two mecanisms are offered to define the environment.
+Two mechanisms are offered to define the environment.
The first one is similar to the one used in the application configuration : inside the environ section, we declare variables or paths.
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.
-In the above example, the value *<install_dir/share/salome/ressources/salome* is prepended to the path SalomeAppConfig.
+In the following example, the value *<install_dir/share/salome/ressources/salome* is prepended to the path SalomeAppConfig.
.. code-block:: bash
}
-But the most common way is to use a environment script, which specify the environment by using an API provided by sat:
+But the most common way is to use an environment script, which specifies the environment by using an API provided by sat:
.. code-block:: bash
- # use script qt.py to set up qt environement
+ # use script qt.py to set up qt environment
environ :
{
env_script : "qt.py"
env.prepend('LD_LIBRARY_PATH', os.path.join(prereq_dir, 'lib'))
pass
-*env* is the API provided by SAT, prereq_dir is the installation directory, version the product version.
-env.set set a variable, env.prepend and env.append are used to prepend or append values to a path.
+*env* is the API provided by SAT, *prereq_dir* is the installation directory, *version* the product version.
+*env.set* sets a variable, *env.prepend* and *env.append* are used to prepend or append values to a path.
-The **setenv** function is used to set the environement at compile time and run time.
+The **setenv** function is used to set the environment at compile time and run time.
It is also possible to use **set_env_build** and **set_env_launch** callback functions to set specific compile or run time environment.
-Finally the functions **set_nativ_env** is used for native products.
+Finally the function **set_nativ_env** is used for native products.
Product sections
----------------
The product configuration file may contain several sections.
-In addition to the "default" section, it is possible to declare other section that will be used for specific versions of the product.
-This allows SAT compiling different version of a products.
+In addition to the "default" section, it is possible to declare other sections that will be used for specific versions of the product.
+This allows SAT compiling different versions of a product.
To determine which section should be used, SAT has an algorithm that takes into account the version number.
Here are some examples of sections that will be taken into account by SAT :
}
Several version numbering are considered by SAT (not only X.Y.Z)
-For example V9, v9, 9, 9.0.0, 9_0_0, are acepted.
+For example V9, v9, 9, 9.0.0, 9_0_0, are accepted.
-By default SAT only consider one section : the one determined according to the version number, or the default one.
+By default SAT only considers one section : the one determined according to the version number, or the default one.
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,
by proceeding incremental steps. SAT uses the following algorithm to merge the sections:
#. We take the complete "default" section
-#. if a "default_win" section is defined, we merge it.
-#. If a section name correspond to the version number, we also merge it.
+#. If a "default_win" section is defined, we merge it.
+#. If a section name corresponds to the version number, we also merge it.
#. Finally on windows platform if the same section name appended by _win exists, we merge it.
============================
-The configuration of SAT is split into height sections : VARS, APPLICATION, PRODUCTS, PROJECTS, PATHS, USER, LOCAL, INTERNAL.
+The configuration of SAT is split into eight sections : VARS, APPLICATION, PRODUCTS, PROJECTS, PATHS, USER, LOCAL, INTERNAL.
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.
One file can reference variables defined in other files. Files are loaded in this order :
* the application pyconf
* the products pyconf (for all products declared in the application)
-In order to check the configuration and the merge done by sat, it is possible to display the resulting height section with the command:
+In order to check the configuration and the merge done by sat, it is possible to display the resulting eight section with the command:
.. code-block:: bash
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.
We have already described two of the sections : APPLICATION and PRODUCTS.
-Let's describe briefly the six others
+Let's describe briefly the six others.
.. _VARS-Section:
Other sections
--------------
-* **PROJECTs** : This section contains the configuration of the projects loaded in SAT by *sat init --add_project* command.
-* **PATHS** : This section contains paths used by saloeTools.
+* **PROJECTS** : This section contains the configuration of the projects loaded in SAT by *sat init --add_project* command.
+* **PATHS** : This section contains paths used by salomeTools.
* **LOCAL** : contains information relative to the local installation of SAT.
* **INTERNAL** : contains internal SAT information
-Overwriting the configution
-===========================
+Overwriting the configuration
+=============================
At the end of the process, SAT ends up with a complete global configuration resulting from the parsing of all *.pyconf* files.
It may be interesting to overwrite the configuration.
-SAT offer two overwriting mecanism to answer these two use cases:
+SAT offers two overwriting mechanisms to answer these two use cases:
-#. Be able to conditionaly modify the configuration of an application to take into account specifics and support multi-platform builds
+#. Be able to conditionally modify the configuration of an application to take into account specifics and support multi-platform builds
#. Be able to modify the configuration in the command line, to enable or disable some options at run time
Application overwriting
-----------------------
At the end of the application configuration, it is possible to define an overwrite section with the keyword **__overwrite__ :**.
-It is followed by a list overwrite sections, that may be conditionnal (use of the keyword **__condition__ :**).
-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).
-/bin/bash: q : commande introuvable
+It is followed by a list of overwrite sections, that may be conditionnal (use of the keyword **__condition__ :**).
+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).
.. code-block:: bash
Installation
************
-**sat** is provided either embedded into a salome package, or as a standalone package. He can also be retrieved from the git repositories.
+**sat** is provided either embedded into a salome package, or as a standalone package. It can also be retrieved from the git repositories.
From git bases
--------------
-**sat** git bases are hosted by the `salome platftorm Tuleap forge <https://codev-tuleap.cea.fr/projects/salome>`_ . Therefore you first has to get an account to this forge.
+**sat** git bases are hosted by the `salome platform Tuleap forge <https://codev-tuleap.cea.fr/projects/salome>`_ . Therefore you first have to get an account to this forge.
To get started, one has to download sat, and at last one sat project (usually SAT_SALOME project, which contains all the configuration required to build SALOME and its prerequisites). The following script get sat and SAT_SALOME project from git repos: ::
# get sat
2. recompile only a part of the application
-It is possible to recompile only a part of the products (those we need to modify et recompile). To enter this (partial recompilation mode), one has initialy to copy the binaries from *BINARIES-XXX* to *INSTALL*, and do the path substitutions by using the **install_bin.sh** script:
+It is possible to recompile only a part of the products (those we need to modify and recompile). To enter this (partial recompilation mode), one has initialy to copy the binaries from *BINARIES-XXX* to *INSTALL*, and do the path substitutions by using the **install_bin.sh** script:
.. code-block:: bash
.. code-block:: bash
- tar xf salomeTools_5.3.0_satproject_salome.tgz # untar a standalone sat package, with a salome project
+ # untar a standalone sat package, with a salome project
+ tar xf salomeTools_5.3.0_satproject_salome.tgz
cd salomeTools_5.3.0_satproject_salome
ls projects # list embedded sat projects
> salome
- ./sat config -l # list all salome application available for build
+ ./sat config -l # list all salome applications available for build
-Finally, the project also provides bash scripts that get a tagged version of sat from the git repository, and a tagged version of salome projects. This mode is dedicated to the developpersi, and requires an access to the Tuleap git repositories.
+Finally, the project also provides bash scripts that get a tagged version of sat from the git repository, and a tagged version of salome projects. This mode is dedicated to the developpers, and requires an access to the Tuleap git repositories.
============================
-New features and improvments
-----------------------------
+New features and improvements
+-----------------------------
**pip mode for python modules**
-This new mode was introduced in order to simplify the management of the python products (which number is constantly raising years after years...)
-It is trigered by two properties within the application configuration file::
+This new mode was introduced in order to simplify the management of the python products (which number is constantly raising years after years...).
+It is triggered by two properties within the application configuration file::
pip : 'yes'
pip_install_dir : 'python'
The first property activates the use of pip for all the products which have themselves the pip property activated (it concerns twenty products).
The second property specifies that the products should be installed directly in python directory, and not in their own specific directory.
-This second property is usefull on windows platform to reduce the length of python path.
+This second property is useful on windows platform to reduce the length of python path.
-After several tests anf iterations, the following management was adopted:
+After several tests and iterations, the following management was adopted:
- sat prepare <application> does nothing for pip products (because at prepare time we don't have python compiled, and the use of native pip may not be compatible).
- - sat compile <application> use the pip module installed in python to get pip archives (wheels), store them in local archive directory, and install then either in python directory, or in the product directory (in accordance to pip_install_dir property).
+ - sat compile <application> use the pip module installed in python to get pip archives (wheels), store them in local archive directory, and install them either in python directory, or in the product directory (in accordance to pip_install_dir property).
**single directory mode**
-This new mode was introduced in order to get shorter path on windows platform. It is trigered by the property **single_install_dir** within the application configuration file::
+This new mode was introduced in order to get shorter path on windows platform. It is triggered by the property **single_install_dir** within the application configuration file::
single_install_dir : "yes"
When activated, all the products which have themselves the property **single_install_dir** are installed in a common directory, called PRODUCTS.
-**Generalisation of sat launcher command**
+**Generalization of sat launcher command**
-sat launcher command was extended to generate lauchers based on an executable given as argument with **-e** option::
+sat launcher command was extended to generate launchers based on an executable given as argument with **-e** option::
sat launcher <application> -n salome.sh -e INSTALL/SALOME/bin/salome.py
-The command generates a launcher called salome.sh, which set the environment, and launch the INSTALL/SALOME/bin/salome.py.
+The command generates a launcher called salome.sh, which sets the environment, and launches the INSTALL/SALOME/bin/salome.py.
-**optimisation of sat compile**
+**optimization of sat compile**
For a complete compilation of salome, sat compile command was spending more than three minutes
-to calculate the dependencies and the order in which the products shoulb be compiled.
+to calculate the dependencies and the order in which the products should be compiled.
The algorithm used was clumsy, and confused.
It was therefore completely rewritten using a topological sorting.
-The products order calculation take now less than one second.
+The products order calculation takes now less than one second.
-**new management of sections in product configution files**
+**new management of sections in product configuration files**
The sections defined in products are used to specify the variations in the way products are built.
-Depending upon the tag or version of the product, sat choose one of these sections and set the product definition according to it.
+Depending upon the tag or version of the product, sat chooses one of these sections and sets the product definition according to it.
With time, the number of sections increased a lot. And it is not easy to visualise the differences between these sections, as they often
are identical, except few variations.
With the windows version, new sections are introduced to manage windows specifics.
Therefore the need of a new mode for managing sections arises, that would be simplier, more concise, and help the comprehension.
-This new mode is called **incremental**, and is trigered by the property **incremental** within the default section of the product::
+This new mode is called **incremental**, and is triggered by the property **incremental** within the default section of the product::
default:
{
...
}
-When this mode is defined, the definition of the product is defined incrementaly, by taking into account the reference (the default section) and applying to it corrections defined in the other incremental sections. Depending upon the case several sections may be taken into account, in a predefined order:
+When this mode is defined, the definition of the product is defined incrementaly, by taking into account the reference (the default section) and applying to it corrections defined in the other incremental sections. Depending upon the case, several sections may be taken into account, in a predefined order:
* the default section, which contains the reference definition
* on windows platform, the default_win section if it exists
* the section corresponding to the tag. the algorithm to determine this section remains unchanged (what changes is that in incremental mode the section only define deltas, not the complete definition)
-* on windows platform, if it exists the same section posfiwed with "_win".
+* on windows platform, if it exists the same section postfixed with "_win".
Here is as an example the incremental definition used for boost products. For version 1.49 of boost, we extend the definition because we need to apply a patch::
patches : [ "boost-1.49.0.patch" ]
}
-** Suppression of the global "no_base" flag in application configuration**
+**Suppression of the global "no_base" flag in application configuration**
**no_base : "no"** is not interpreted anymore in application pyconf.
One has to use the **base** flag.
* **yes** : all the products go into the base
* **no** : no product goes into the base
-The complete usage rule of bases is explaned in the documentation.
+The complete usage rule of bases is explained in the documentation.
Change log
Completion mode
---------------
-When getting started with sat, the use of the competion mode is convenient. This mode will display by typing twice on the **tab key** the available options, commands, applications or products available. The completion mode has to be activated by sourcing the file **complete_sat.sh** contained in SAT directory:
+When getting started with sat, the use of the completion mode is convenient. This mode will display by typing twice on the **tab key** the available options, commands, applications or products available. The completion mode has to be activated by sourcing the file **complete_sat.sh** contained in SAT directory:
.. code-block:: bash
source complete_sat.sh
# list all application available for compilation
- ./sat conpile <TAB> <TAB>
+ ./sat compile <TAB> <TAB>
> SALOME-7.8.2 SALOME-8.5.0 SALOME-9.3.0 SALOME-master
# list all available options of sat compile
- ./sat conpile SALOME-9.3.0 <TAB> <TAB>
+ ./sat compile SALOME-9.3.0 <TAB> <TAB>
> --check --clean_build_after --install_flags --properties
> --stop_first_fail --with_fathers --clean_all --clean_make
> --products --show --with_children
./sat package SALOME-9.4.0 -b
-All the build is done in the *application directory*, which is parametered by the sat configuration variable *$APPLICATION.workdir*. In the above example this directory corresponds to *.../SALOME-9.4.0-CO7*.
+All the build is done in the *application directory*, which is parameterized by the sat configuration variable *$APPLICATION.workdir*. In the above example this directory corresponds to *.../SALOME-9.4.0-CO7*.
SAT can only build applications provided by the projects that have been loaded with *sat init* command. The available applications are listed by *sat config -l* command.
Getting all the sources and compile everything is often a long process.
The following use case has proven to be convenient for fast usage!
It consists to get the application through a sat package containing the binaries, the sources and SAT.
-This allows using directly the application after the detar (the binary part).
+This allows using directly the application after the untar (the binary part).
And later, if required, it is possible to add a module, or modify some source code and recompile only what was added or modified.
.. code-block:: bash
# start salome
SALOME-9.4.0-CO7-SRC/salome
- # copy binaries in INSTALL directory, do required substitution to enable recompilation
+ # copy binaries in INSTALL directory, do required substitutions to enable recompilation
./install_bin.sh
- # get sources of module we want to recompile
+ # get sources of modules we want to recompile
salomeTools/sat prepare SALOME-9.4.0 -p SHAPER,SMESH
# do some modifications and recompile both modules
Which products go into the base
-------------------------------
-The application developer has the possibility to declare that a products will go by default in the base.
+The application developer has the possibility to declare that a product will go by default in the base.
He uses for that the keyword 'base' in the install_dir key within the product configuration file (products pyconf) : *install_dir : 'base'*
It is done usually for products that are considered as prerequisites.
Mutualisation of products
-------------------------
-Products that go in base and have the same configuration will be shared by different application (it's the objective).
+Products that go in base and have the same configuration will be shared by different applications (it's the objective).
SAT does check the configuration to prevent of an application using a product in base with a non compatible configuration.
To check the compatibility, SAT stores the configuration in a file called *sat-config-<product name>.pyconf*.
-In a next build (for example in an
other application), SAT checks if the new configuration corresponds to what is described in *sat-config-<product name>.pyconf*.
+In a next build (for example in another application), SAT checks if the new configuration corresponds to what is described in *sat-config-<product name>.pyconf*.
If it corresponds, the previous build is used in base, otherwise a new build is done, and stored in a new directory called *config-<build number>*.
.. warning:: Please note that only the dependencies between products are considered for the checking. If the compilation options changed, it will not be tracked (for example the use of debug mode with -g option will not produce a second configuration, it will overwrite the previous build done in production mode)
SAT has some features that make developers' life easier. Let's highlight some of the developers use cases.
(if you are not familiar with SAT configuration, you may first read Configuration Chapter before, and come back to this paragraph after)
-Activating the developement mode
---------------------------------
+Activating the development mode
+-------------------------------
-By default *sat prepare* command is not suited for development, because it erases the source directory (if it already exists) before getting the source.
-If you did developements in this directory **they will be lost!**.
+By default *sat prepare* command is not suited for development, because it erases the source directory (if it already exists) before getting the sources.
+If you did developments in this directory **they will be lost!**.
Therefore before you start some developments inside a product, you should **declare the product in development mode** in the application configuration.
For example if you plan to modify KERNEL module, modify SALOME configuration like this:
}
}
-When the dev mode is activated, SAT will load the sources from the git repository only the first time, when the local directory do not exist.
+When the dev mode is activated, SAT will load the sources from the git repository only the first time, when the local directory does not exist.
For the next calls to *sat prepare*, it will keep the source intact and do nothing!
-In the example we have also set the debug and the berbose flag to "yes" - it is often useful when developing.
+In the example we have also set the debug and the verbose flags to "yes" - it is often useful when developing.
-Finally, we have changed the tag and replaced it with a developement branche (to be able to push developements directly in git repo - without producing patches).
+Finally, we have changed the tag and replaced it with a development branch (to be able to push developments directly in git repo - without producing patches).
-.. warning:: But doing this we have (probably) broken the automatic association done by SAT between the tag of the product and the product section used by SAT to compile it! (see the chapter "Product sections" in the Configuration documentation for more details about this association) Therefore you need ot tell SAT which section use (otherwise it will take the "default" section, and it may not be the one you need). This is done with : **section:'version_7_8_0_to_8_4_0'**. If you don't know which section should be used, print it with SAT config before changing the tag : *./sat config SALOME-9.4.0 -i KERNEL* will tell you which section is being used.
+.. warning:: But doing this we have (probably) broken the automatic association done by SAT between the tag of the product and the product section used by SAT to compile it! (see the chapter "Product sections" in the Configuration documentation for more details about this association) Therefore you need to tell SAT which section to use (otherwise it will take the "default" section, and it may not be the one you need). This is done with : **section:'version_7_8_0_to_8_4_0'**. If you don't know which section should be used, print it with SAT config before changing the tag : *./sat config SALOME-9.4.0 -i KERNEL* will tell you which section is being used.
Pushing developments in base, or creating patches
-------------------------------------------------
-If you have set the tag to a developement branch (like in the previous example), you can directly push your developements in the git repository with *git push* command.
-If not (if you are detached to a tag, you can produce with git a patch of you developements:
+If you have set the tag to a development branch (like in the previous example), you can directly push your developments in the git repository with *git push* command.
+If not (if you are detached to a tag, you can produce with git a patch of you developments:
- git dif > my_dev.patch
+ git diff > my_dev.patch
-And use this patch either with SAT to apply it automaticaly with *sat prepare* command, or send the patch for an integration request.
+And use this patch either with SAT to apply it automatically with *sat prepare* command, or send the patch for an integration request.
Changing the source directory
-----------------------------
-By default the source directory of a product is located inside SAT installation, in the SOURCE directory.
-This defaut may not be convenient. Developers may prefer to develop inside the HOME directory (for example when this directory is automaticaly saved).
+By default the source directory of a product is located inside SAT installation, in the SOURCES directory.
+This default may not be convenient. Developers may prefer to develop inside the HOME directory (for example when this directory is automatically saved).
-To change the default source directory, you first hanve to identify which product section is used by SAT: ::
+To change the default source directory, you first have to identify which product section is used by SAT: ::
./sat config SALOME-9.4.0 -i KERNEL
> ....
