From: crouzet Date: Thu, 19 Dec 2019 14:10:10 +0000 (+0100) Subject: integration patch doc fourni dans la branch fix_doc_sat_5_5 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=d9472d3208a2622e2d6cb9b522359547e2f74c8b;p=tools%2Fsat.git integration patch doc fourni dans la branch fix_doc_sat_5_5 --- diff --git a/doc/src/commands/application.rst b/doc/src/commands/application.rst index 2052da0..2816b91 100644 --- a/doc/src/commands/application.rst +++ b/doc/src/commands/application.rst @@ -6,7 +6,7 @@ Command application 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 @@ -27,7 +27,7 @@ Usage sat application --target -* 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 --catalog @@ -43,10 +43,10 @@ Usage sat launcher --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** diff --git a/doc/src/commands/clean.rst b/doc/src/commands/clean.rst index 181907c..5414bfa 100644 --- a/doc/src/commands/clean.rst +++ b/doc/src/commands/clean.rst @@ -9,7 +9,7 @@ Description 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 @@ -22,23 +22,23 @@ 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 :* + | Syntax: ``--properties :`` * **--sources** : Clean the product source directories. @@ -59,7 +59,7 @@ Availables options -Some useful configuration pathes +Some useful configuration paths ================================= No specific configuration. diff --git a/doc/src/commands/compile.rst b/doc/src/commands/compile.rst index c0fc589..55c77f9 100644 --- a/doc/src/commands/compile.rst +++ b/doc/src/commands/compile.rst @@ -19,7 +19,7 @@ Usage sat compile --products , ... -* 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 --products @@ -56,26 +56,26 @@ Usage * Stop the compilation as soon as the compilation of a module fails: :: - sat compile --stop_first_fail + sat compile --stop_first_fail * Do not compile, just show if products are installed or not, and where is the installation: :: sat compile --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. diff --git a/doc/src/commands/config.rst b/doc/src/commands/config.rst index ffcfdf9..d3c4954 100644 --- a/doc/src/commands/config.rst +++ b/doc/src/commands/config.rst @@ -15,7 +15,7 @@ Usage 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 @@ -71,7 +71,7 @@ Usage sat config SALOME-xx --info KERNEL sat config SALOME-xx --info qt -Some useful configuration pathes +Some useful configuration paths ================================= Exploring a current configuration. diff --git a/doc/src/commands/doc.rst b/doc/src/commands/doc.rst index f985c32..449bee8 100644 --- a/doc/src/commands/doc.rst +++ b/doc/src/commands/doc.rst @@ -28,7 +28,7 @@ Usage -Some useful configuration pathes +Some useful configuration paths ================================= * **USER** diff --git a/doc/src/commands/environ.rst b/doc/src/commands/environ.rst index ad52dc7..97ed865 100644 --- a/doc/src/commands/environ.rst +++ b/doc/src/commands/environ.rst @@ -11,7 +11,7 @@ to run and compile your application (as SALOME_ is an example). .. 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. @@ -28,7 +28,7 @@ Usage sat environ * 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 --shell [bash|bat|cfg|tcl|all] @@ -83,9 +83,9 @@ Configuration 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 */lib* to ``LD_LIBRARY_PATH`` (note the *left first* underscore), append */lib* to ``PYTHONPATH`` (note the *right last* underscore), and set ``LAPACK_ROOT_DIR`` to **: diff --git a/doc/src/commands/generate.rst b/doc/src/commands/generate.rst index f753261..aaa033e 100644 --- a/doc/src/commands/generate.rst +++ b/doc/src/commands/generate.rst @@ -6,7 +6,7 @@ Command generate 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``. @@ -18,7 +18,7 @@ Remarks 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 diff --git a/doc/src/commands/init.rst b/doc/src/commands/init.rst index 2418ced..b2c010f 100644 --- a/doc/src/commands/init.rst +++ b/doc/src/commands/init.rst @@ -10,12 +10,12 @@ It allows to initialise the content of this file. 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 -* 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 @@ -24,7 +24,7 @@ Usage sat init --archive_dir -* 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 @@ -35,7 +35,7 @@ Usage -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. diff --git a/doc/src/commands/launcher.rst b/doc/src/commands/launcher.rst index 99e8a03..38e753f 100644 --- a/doc/src/commands/launcher.rst +++ b/doc/src/commands/launcher.rst @@ -23,13 +23,13 @@ Usage 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 --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 -e INSTALL/SALOME/bin/salome/salome.py -n salome.sh @@ -46,7 +46,7 @@ Usage sat launcher --gencat - 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): :: @@ -56,7 +56,7 @@ Usage Configuration ============= -Some useful configuration pathes: +Some useful configuration paths: * **APPLICATION.profile** diff --git a/doc/src/commands/log.rst b/doc/src/commands/log.rst index 16acd4e..e56ce3f 100644 --- a/doc/src/commands/log.rst +++ b/doc/src/commands/log.rst @@ -36,7 +36,7 @@ Usage -Some useful configuration pathes +Some useful configuration paths ================================= * **USER** diff --git a/doc/src/commands/package.rst b/doc/src/commands/package.rst index 6d6648a..bde5f15 100644 --- a/doc/src/commands/package.rst +++ b/doc/src/commands/package.rst @@ -6,8 +6,8 @@ Command package 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. @@ -16,7 +16,7 @@ Usually utility *salomeTools* is included in the archive. .. 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 @@ -65,17 +65,17 @@ Usage sat package SALOME_xx --binaries This command will create an archive named ``SALOME_xx _.tgz`` - where is the OS_ architecture of the machine. + where 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. diff --git a/doc/src/commands/prepare.rst b/doc/src/commands/prepare.rst index f67dec0..ad2c871 100644 --- a/doc/src/commands/prepare.rst +++ b/doc/src/commands/prepare.rst @@ -51,12 +51,12 @@ edit the application configuration file (pyconf) and modify the product declarat 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 @@ -86,7 +86,7 @@ Usage sat prepare --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. @@ -100,7 +100,7 @@ Command *sat prepare* uses the *pyconf file configuration* of each product to kn * **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. diff --git a/doc/src/commands/template.rst b/doc/src/commands/template.rst index f109292..10dba85 100644 --- a/doc/src/commands/template.rst +++ b/doc/src/commands/template.rst @@ -9,8 +9,8 @@ Description 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 ===== diff --git a/doc/src/configuration.rst b/doc/src/configuration.rst index b4e3fb8..8000667 100644 --- a/doc/src/configuration.rst +++ b/doc/src/configuration.rst @@ -18,7 +18,7 @@ Configuration projects 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 @@ -72,7 +72,7 @@ At the beginning of the APPLICATION sections, global variables and flags are def * **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 @@ -92,7 +92,7 @@ At the beginning of the APPLICATION sections, global variables and flags are def ... 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 @@ -129,10 +129,10 @@ For each product, it is possible to specify in a dictionnary: * **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 @@ -171,7 +171,7 @@ They can be defined in the application configuration with the properties subsect 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) @@ -216,7 +216,7 @@ Available product configuration flags * **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 @@ -264,7 +264,7 @@ Here are some properties frequently used: * **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. @@ -281,13 +281,13 @@ Product environment ------------------- 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 *`_ . Therefore you first has to get an account to this forge. +**sat** git bases are hosted by the `salome platform Tuleap forge `_ . 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 @@ -66,7 +66,7 @@ Please note that the sources are installed in *SOURCES* directory, and the compi 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 @@ -83,11 +83,12 @@ Standalone sat packages .. 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. diff --git a/doc/src/release_notes/release_notes_5.5.0.rst b/doc/src/release_notes/release_notes_5.5.0.rst index 553d4f7..3380403 100644 --- a/doc/src/release_notes/release_notes_5.5.0.rst +++ b/doc/src/release_notes/release_notes_5.5.0.rst @@ -6,63 +6,63 @@ Release Notes, November 2019 ============================ -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 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 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 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 -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: { @@ -74,12 +74,12 @@ This new mode is called **incremental**, and is trigered by the property **incre ... } -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:: @@ -111,7 +111,7 @@ Here is as an example the incremental definition used for boost products. For ve 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. @@ -120,7 +120,7 @@ The possible values are: * **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 diff --git a/doc/src/usage_of_sat.rst b/doc/src/usage_of_sat.rst index 7650153..193edb1 100644 --- a/doc/src/usage_of_sat.rst +++ b/doc/src/usage_of_sat.rst @@ -55,7 +55,7 @@ More details are provided by the help of sat. The help option can be called at t 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 @@ -63,11 +63,11 @@ When getting started with sat, the use of the competion mode is convenient. This source complete_sat.sh # list all application available for compilation - ./sat conpile + ./sat compile > 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 + ./sat compile SALOME-9.3.0 > --check --clean_build_after --install_flags --properties > --stop_first_fail --with_fathers --clean_all --clean_make > --products --show --with_children @@ -110,7 +110,7 @@ This is the main use case : build from scratch an application. ./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. @@ -120,7 +120,7 @@ Partial recompilation of a packaged application 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 @@ -131,10 +131,10 @@ And later, if required, it is possible to add a module, or modify some source co # 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 @@ -162,7 +162,7 @@ This default can be changed by the user with sat init command : 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. @@ -193,10 +193,10 @@ Like other application flags (debug, verbose, dev) the **base** flag can be used 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-.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-.pyconf*. +In a next build (for example in another application), SAT checks if the new configuration corresponds to what is described in *sat-config-.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-*. .. 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) @@ -208,11 +208,11 @@ Developing a module with SAT 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: @@ -231,33 +231,33 @@ For example if you plan to modify KERNEL module, modify SALOME configuration lik } } -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 > ....