make latexpdf
evince build/latex/salomeTools.pdf &
-
-#########################################################
-# after doc compilation success
-# do not forget to do 'git push' !!!!!!!!!!!!!!
-#########################################################
-
* **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.
Configuration
*************
-*salomeTools* uses files to store its configuration parameters.
+*salomeTools* uses files with **.pyconf** extension to store its configuration parameters.
+These pyconf configuration files are provided by the salomeTool projects that are set by sat init command.
-There are several configuration files which are loaded by salomeTools in a specific order.
+When executing a command, sat will load several configuration files in a specific order.
When all the files are loaded a *config* object is created.
Then, this object is passed to all command scripts.
# to get the current setting
sat config --value VARS
-PRODUCTS section
+APPLICATION section
------------------
-| This section is defined in the product file.
-| It contains instructions on how to build a version of SALOME (list of prerequisites-products and versions)
+| This section is defined in the application pyconf file.
+| It contains instructions on how to build a version of SALOME (list of products and versions, compilation options, etc.)
::
# to get the current setting
- sat config SALOME-xx --value PRODUCTS
+ sat config SALOME-xx --value APPLICATION
-APPLICATION section
+PRODUCTS section
---------------------
-| This section is optional, it is also defined in the product file.
-| It gives additional parameters to create an application based on SALOME, as versions of products to use.
+| This section contains all the information required to build the products contained in the application.
+| It is build from the products configuration files.
::
# to get the current setting
- sat config SALOME-xx --value APPLICATION
+ sat config SALOME-xx --value PRODUCT
.. _USER-Section:
USER section
--------------
This section is defined by the user configuration file,
-``~/.salomeTools/salomeTools.pyconf``.
+``~/.salomeTools/SAT.pyconf``.
The ``USER`` section defines some parameters (not exhaustive):
-* **workDir** :
-
- | The working directory.
- | Each product will be usually installed here (in sub-directories).
+* **pdf_viewer** : the pdf viewer used to read pdf documentation
* **browser** : The web browser to use (*firefox*).
# to get the current setting
sat config SALOME-xx --value USER
+ # to edit your personal configuration file
+ sat config -e
+
+
+Other sections
+--------------
+
+* **PROJECTs** : This section contains the configuration of the projects loaded in salomeTool by sat init --add_project command.
+* **PATHS** : This section contains paths used by saloeTools.
+* **LOCAL** : contains information relative to the local installation of salomeTool.
+* **INTERNAL** : contains internal salomeTool information
+
+All these sections can be printed with sat config command:
+
+::
+ # It is possible to use sat completion mode to print available sections.
+ sat config SALOME-xx --value <TAB> <TAB>
+ > APPLICATION. INTERNAL. LOCAL. PATHS.
+ > PRODUCTS. PROJECTS. USER. VARS.
+ # get paths used by sat
+ sat config SALOME-xx --value PATHS
+It is possible to use sat completion mode to print available sections.
:scale: 100 %
:align: center
-.. warning:: This documentation is under construction.
The **Sa**\ lome\ **T**\ ools (sat) is a suite of commands
that can be used to perform operations on SALOME_.
:maxdepth: 1
Installation of salomeTools <installation_of_sat>
- Configuration <configuration>
Usage of salomeTools <usage_of_sat>
+ Configuration <configuration>
List of Commands
================
package <commands/package>
generate <commands/generate>
init <commands/init>
+ environ <commands/environ>
Developer documentation
=======================
.. toctree::
:maxdepth: 1
- Release Notes 5.0.0 <release_notes/release_notes_5.0.0>
+ Release Notes 5.5.0 (in construction) <release_notes/release_notes_5.5.0>
+ Release Notes 5.4.0 <release_notes/release_notes_5.4.0>
+ Release Notes 5.3.0 <release_notes/release_notes_5.3.0>
+ Release Notes 5.2.0 (in construction) <release_notes/release_notes_5.2.0>
Installation
************
-Usually user could find (and use) command **sat** directly after a 'detar' installation of SALOME.
+**sat** is provided either embedded into a salome package, or as a standalone package.
+
+Embedded sat version
+--------------------
+
+**sat** is provided in salome packages with sources, in order to be able to recompile the sources (**sat** is not provided in salome packages with only binaries).
+
+Embedded **sat** is always associated to an embedded **sat** project, which contains all the products and application configuration necessary to the package.
.. code-block:: bash
- tar -xf .../SALOME_xx.tgz
- cd SALOME_xx
- ls -l sat # sat -> salomeTools/sat
+ tar -xf SALOME-9.3.0-CO7-SRC.tgz
+ cd SALOME-9.3.0-CO7-SRC
+ ls PROJECT/ # list the embedded sat project
+ salomeTools/sat config SALOME-9.3.0 -e # edit the SALOME-9.3.0 configuration pyconf file
+
+
+The user has usually two main use cases with an embedded sat, which are explained in the README file of the archive:
+
+1. recompile the complete application
+
+.. code-block:: bash
+
+ ./sat prepare SALOME-9.3.0
+ ./sat compile SALOME-9.3.0
+ ./sat launcher SALOME-9.3.0
+
+Please note that the sources are installed in *SOURCES* directory, and the compilation is installed in *INSTALL* directory (therefore they do not overwrite the initial binaries, which are stored in *BINARIES-XXX* directory). The launcher *salome* is overwritten (it will use the new compiled binaries) but the old binaries can still be used in connection with *binsalome* launcher).
+
+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:
+
+.. code-block:: bash
+
+ ./install_bin.sh # pre-installation of all binaries in INSTALL dir, with substitutions
+ ./sat prepare SALOME-9.3.0 -p GEOM # get GEOM sources, modify them
+ ./sat compile SALOME-9.3.0 -p GEOM --clean_all # only recompile GEOM
+
+
+
+Standalone sat packages
+---------------------------
+
+**sat** is also delivered as a standalone package, usually associated to a sat project. The following example is an archive containing salomeTools 5.3.0 and the salome sat project. It can be used to build from scratch any salome application.
+
+.. code-block:: bash
+ tar xf salomeTools_5.3.0_satproject_salome.tgz # untar a standalone sat package, with a salome project
+ cd salomeTools_5.3.0_satproject_salome
+ ls projects # list embedded sat projects
+ > salome
+ ./sat config -l # list all salome application available for build
-Python package (scripts of salomeTools) actually remains in directory *salomeTools*.
+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.
--- /dev/null
+*****************
+SAT version 5.5.0
+*****************
+
+Release Notes, December, 2018
+=============================
+
+.. warning:: This documentation is under construction!
+
+New features and improvments
+----------------------------
+
+**sat package**
+
+
+
+Change log
+----------
+
+This chapter does not provide the complete set of changes included, only the
+most significant changes are listed.
+
+
++------------+-----------------------------------------------------------------------------------+
+| Artifact | Description |
++============+===================================================================================+
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
++------------+-----------------------------------------------------------------------------------+
--- /dev/null
+*****************
+SAT version 5.3.0
+*****************
+
+Release Notes, February, 2019
+=============================
+
+New features and improvments
+----------------------------
+
+**sat init**
+
+The command *sat init* has been finalized, with the addition of options **--add_project** and **--reset_projects**.
+It is now able to manage projects after an intiale git clone of salomeTool. The capacity is used by users
+installing salomeTool from the git repositories:
+
+.. code-block:: bash
+
+ # get sources of salomeTool
+ git clone https://codev-tuleap.cea.fr/plugins/git/spns/SAT.git salomeTool
+
+ # get SAT_SALOME project (the sat project that contains the configuration of SALOME)
+ git clone https://codev-tuleap.cea.fr/plugins/git/spns/SAT_SALOME.git
+
+ # initialise sat with this project
+ salomeTool/sat init --add_project $(pwd)/SAT_SALOME/salome.pyconf
+
+It is possible to initialise sat with several projects by calling several times *sat init --add_project*
+
+**sat prepare : git retry functionnality**
+
+With large git repositories (>1GB) *git clone* command may fail. To decrease the risk, sat prepare will now retry
+three times the *git clone* function in case of failure.
+
+**Reset of LD_LIBRARY_PATH and PYTHONPATH before setting the environment**
+
+Every year, a lot of problems occur, due to users (bad) environment. This is most of the time caused
+by the presence (out-of-date) .bashrc files.
+To prevent these (time-consuming) problems, sat now reset LD_LIBRARY_PATH and PYTHONPATH variables
+before setting the environment thus avoiding side effects.
+Users who wish anayway to start SALOME with a non empty LD_LIBRARY_PATH or PYTHONPATH may comment
+the reset in salome launcher or in env_launch.sh file.
+
+**New option --complete for sat prepare**
+
+This option is used when an installation is interrupted or incomplete. It allows downloading only
+the sources of missing products
+
+.. code-block:: bash
+
+ # only get sources of missing products (i.e products not present in INSTALL dir)
+ git prepare SALOME-master -c
+
+** New option --packages for sat clean**
+
+SALOME packages are big... It is usefull to be able to clean them whith this new option.
+
+.. code-block:: bash
+
+ # remove packages present in PACKAGES directory of SALOME-master
+ git clean SALOME-master --packages
+
+**Global configuration keys "debug", "verbose" and "dev" in applications**
+
+
+These new keys can be defined in applications in order to triger the debug, verbose and dev mode for all products.
+In the following example, the SALOME-master application will be compiled in debug mode (use of **-g** flag), but with no verbosity.
+Its products are not in development mode.
+
+.. code-block:: bash
+
+ APPLICATION :
+ {
+ name : 'SALOME-master'
+ workdir : $LOCAL.workdir + $VARS.sep + $APPLICATION.name + '-' + $VARS.dist
+ tag : 'master'
+ dev : 'no'
+ verbose :'no'
+ debug : 'yes'
+ ...
+ }
+
+Change log
+----------
+
+This chapter does not provide the complete set of changes included, only the
+most significant changes are listed.
+
+
++------------+-----------------------------------------------------------------------------------+
+| Artifact | Description |
++============+===================================================================================+
+| sat #16548 | Finalisation of sat init command (options -add_project and --reset_projects) |
+| sat #8566 | |
++------------+-----------------------------------------------------------------------------------+
+| sat #12994 | new git retry functionnality for sat prepare : give three trials in case of |
+| | failures |
++------------+-----------------------------------------------------------------------------------+
+| sat #8581 | traceability : save tag of salomeTool and its projects |
++------------+-----------------------------------------------------------------------------------+
+| sat #8588 | reset LD_LIBRARY_PATH and PYTHONPATH before launching SALOME |
++------------+-----------------------------------------------------------------------------------+
+| sat #9575 | Improvment of the DISTENE licences management (notably for packages) |
++------------+-----------------------------------------------------------------------------------+
+| sat #8597 | Implementation of option sat prepare -c (--complete) for preparing only the |
+| | sources that are not yet installed |
++------------+-----------------------------------------------------------------------------------+
+| sat #8655 | implementation of option sat clean --packages |
++------------+-----------------------------------------------------------------------------------+
+| sat #8532 | sat log : remane option --last_terminal in --last_compile |
+| sat #8594 | Extension of sat log --last_compile to the logs of make check |
++------------+-----------------------------------------------------------------------------------+
+| sat #13271 | hpc mode trigered by product "hpc" key in state of MPI_ROOT variable |
+| | |
++------------+-----------------------------------------------------------------------------------+
+| sat #8606 | sat generate clean old directories before a new generation |
++------------+-----------------------------------------------------------------------------------+
+| sat #12952 | Add global keys "debug", "verbose" and "dev" to manage globally these modes |
+| | for all the products of an application |
++------------+-----------------------------------------------------------------------------------+
+| sat #8523 | protection of call to ssh on windows platform |
++------------+-----------------------------------------------------------------------------------+
--- /dev/null
+*****************
+SAT version 9.4.0
+*****************
+
+Release Notes, April, 2019
+==========================
+
+New features and improvments
+----------------------------
+
+**sat package**
+
+The sat package command has been completed and finalised, in order to manage standalone packages of sat, with or without an embedded project.
+Options **--ftp** and **--with_vcs** have been added, in order to reduce the size of salome project packages (without these options, the archive of the sat salome project is huge, as it includes all the prerequisites archives. The **--ftp** option allows pointing directly to salome ftp site, which provides the prerequisites archives. These are therefore not included. With the same approach, **--with_vcs** option specify an archive that points directly to the git bases of SALOME. Sources of SALOME modules are therefore not embedded in the archive, reducing the size.
+
+.. code-block:: bash
+
+ # produce a standalone archive of salomeTool
+ sat package -t
+
+ # produce a HUGE standalone archive of salomeTool with the salome project embedded.
+ sat package -t -p salome
+
+ # produce a small archive with salomeTool and embedded salome project,
+ # with direct links to ftp server and git repos
+ sat package -t -p salome --ftp --with_vcs
+
+
+**repo_dev property**
+
+This new application property **repo_dev** was introduced to trigger the use of the development git repositories for all the git bases of an application.
+Before, the only way to use the development git repositories was to declare all products in dev mode. This was problematic, for example one had to use
+*--force_patch* option to apply patches, or to use *--force* option to reinstall sources.
+
+The use of the development git repository is now triggered by declaring this new **repo_dev** property in the application. And products are declared in dev mode only if we develop them.
+
+.. code-block:: bash
+
+ # add this section in an application to force the use of the development git bases
+ # (from Tuleap)
+ properties :
+ {
+ mesa_launcher_in_package : "yes"
+ repo_dev : "yes"
+ }
+
+**windows compatibility**
+
+The compatibility to windows platform has been improved. The calls to lsb_release linux command have been replaced by the use of python platform module.
+Also the module med has been renamed medfile, and module Homard has been renamed homard_bin, in order to avoid lower/upper case conflicts.
+
+
+Change log
+----------
+
+This chapter does not provide the complete set of changes included, only the
+most significant changes are listed.
+
+
++------------+-----------------------------------------------------------------------------------+
+| Artifact | Description |
++============+===================================================================================+
+| sat #12099 | Add a new field called check_install to verify the correct installation |
++------------+-----------------------------------------------------------------------------------+
+| sat #8607 | Suppression of sat profile command, replaced by sat template command (AppModule) |
++------------+-----------------------------------------------------------------------------------+
+| 69d6a69f43 | Introduction of a new property called repo_dev to trigger the use of the dev git |
+| | repository. |
++------------+-----------------------------------------------------------------------------------+
+| scs #13187 | Update of PythonComponent template |
++------------+-----------------------------------------------------------------------------------+
+| sat #16728 | Replace call to lsb_release by platform module |
++------------+-----------------------------------------------------------------------------------+
+| sat #13318 | command sat package -t -p salome --ftp --with_vcs |
+| sat #16713 | debug of sat packages containing sat and embedded projects |
++------------+-----------------------------------------------------------------------------------+
+| sat #16787 | Rename product med by medfile and Homard by homard_bin |
++------------+-----------------------------------------------------------------------------------+
--- /dev/null
+*****************
+SAT version 5.5.0
+*****************
+
+Release Notes, November 2019
+============================
+
+.. warning:: This documentation is under construction!
+
+New features and improvments
+----------------------------
+
+**sat package**
+
+
+
+Change log
+----------
+
+This chapter does not provide the complete set of changes included, only the
+most significant changes are listed.
+
+
++------------+-----------------------------------------------------------------------------------+
+| Artifact | Description |
++============+===================================================================================+
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
+| | |
++------------+-----------------------------------------------------------------------------------+
+| | |
++------------+-----------------------------------------------------------------------------------+
.. include:: ../rst_prolog.rst
-********************
-Usage of SAlomeTools
-********************
+*************************
+Main usage of SAlomeTools
+*************************
-Usage
-=====
-sat usage is a Command Line Interface (CLI_).
+Purpose, Command Line Interface
+===============================
+
+sat is a Command Line Interface (CLI_) based on python langage.
+Its purpose is to cover the maintenance and the production of the salome platform and its applications.
+
+Notably:
+* the definition of the applications content (the products, the resources, the options, the environment, the launcher, etc.)
+* the description of the products (the environment to set, how to get the sources; how to compilation, the dependencies, etc).
+* the complete preparation and build
+* the management of unit or integration tests
+* the production of binary or source packages
+
+It can be used from interactively from a terminal, or in batch mode.
.. code-block:: bash
- sat [generic_options] [command] [product] [command_options]
+ sat [generic_options] [command] [application] [command_options]
+
-Options of sat
+Getting help
+============
+
+Help option -h
--------------
-Useful *not exhaustive* generic options of *sat* CLI.
+To get help in terminal mode as simple text, use **--help** or **-h** option:
-*--help or -h*
-...............
+.. code-block:: bash
+
+ sat -h # or --help : get the list of existing commands and main options
+ sat compile -h # get the help on the specific command 'compile'
-Get help as simple text.
+completion mode
+---------------
+
+When getting started with sat, the use of the competion mode is usefull. This mode will display by type twice on the **tab key** the available options, command, applications or product available. The completion mode has to be activated by sourcing the file **complete_sat.sh** contained in salomeTool directory:
.. code-block:: bash
- sat --help # get the list of existing commands
- sat --help compile # get the help on a specific command 'compile'
+ source complete_sat.sh # activate the completion mode
+ ./sat conpile <TAB> <TAB> # liste all application available for compilation
+ > SALOME-7.8.2 SALOME-8.5.0 SALOME-9.3.0 SALOME-master
-*--debug or -g*
-................
+ ./sat conpile SALOME-9.3.0 <TAB> <TAB> # list all available options
+ > --check --clean_build_after --install_flags --properties
+ > --stop_first_fail --with_fathers --clean_all --clean_make
+ > --products --show --with_children
-Execution in debug mode allows to see more trace and *stack* if an exception is raised.
-*--verbose or -v*
-..................
+Verbose and Debug mode
+======================
+
+Verbosity
+---------
+
+**sat** has several levels of verbosity. The default value is **3** and correspond to the impression of the main information on what has been done.
+A verbosity of **0** correspond to no impression at all, while on the opposite a verbosity of **6** prints a lot of information.
Change verbosity level (default is 3).
.. code-block:: bash
- # for product 'SALOME_xx' for example
- # execute compile command in debug mode with trace level 4
- sat -g -v 4 compile SALOME_xx
+ sat -v0 prepare SALOME-9.3.0 -p GEOM # prepare GEOM product in silent mode
+ sat -v6 compile SALOME-9.3.0 -p GEOM # compile GEOM with full verbosity
+Debug mode -g
+-------------
+
+This mode is used by developers to see more traces and *stack* if an exception is raised.
-Build a SALOME product
-======================
-Get the list of available products
-----------------------------------
+Building a SALOME application
+=============================
-To get the list of the current available products in your context:
+Get the list of available applications
+--------------------------------------
+
+To get the list of the current available applications in your context:
.. code-block:: bash
- sat config --list
+ sat config -l
+
+The result depends upon the projects that have been loaded in sat.
-Prepare sources of a product
-----------------------------
-To prepare (get) *all* the sources of a product (*SALOME_xx* for example):
+Prepare sources of an application
+---------------------------------
+
+To prepare (get) *all* the sources of an application (*SALOME_xx* for example):
.. code-block:: bash
+ # get all sources
sat prepare SALOME_xx
-| The sources are usually copied in directories
-| *$USER.workDir + SALOME_xx... + SOURCES + $PRODUCT.name*
+ # get (git) sources of SALOME modules
+ sat prepare SALOME_xx --properties is_SALOME_module:yes
+
+| The sources are usually copied in directory *$APPLICATION.workdir + $VARS.sep + 'SOURCES'*
-Compile SALOME
-----------------
+Compile an application
+----------------------
-To compile products:
+To compile an application
.. code-block:: bash
# compile all prerequisites/products
sat compile SALOME_xx
- # compile only 2 products (KERNEL and SAMPLES), if not done yet
- sat compile SALOME_xx --products KERNEL,SAMPLES
+ # compile only three products (KERNEL, GUI and SHAPER), if not done yet
+ sat compile SALOME_xx -p KERNEL,GUI,SHAPER
- # compile only 2 products, unconditionaly
- sat compile SALOME_xx ---products SAMPLES --clean_all
+ # compile only two products, unconditionaly
+ sat compile SALOME_xx -p KERNEL,GUI --clean_all
+ # (re)compile only salome modules
+ sat compile SALOME_xx --properties is_SALOME_module:yes --clean_all
-| The products are usually build in the directories
-| *$USER.workDir + SALOME_xx... + BUILD + $PRODUCT.name*
+| The products are usually build in the directory
+| *$APPLICATION.workdir + $VARS.sep + 'BUILD'*
|
-| The products are usually installed in the directories
-| *$USER.workDir + SALOME_xx... + INSTALL + $PRODUCT.name*
+| The products are usually installed in the directory
+| *$APPLICATION.workdir + $VARS.sep + 'INSTALL'*
'''
msg = "\n" + get_version() + "\n\n"
msg += src.printcolors.printcHeader( _("Usage: ") ) + \
- "sat [sat_options] <command> [product] [command_options]\n\n"
+ "sat [sat_options] <command> [application] [command_options]\n\n"
msg += parser.get_help() + "\n"
