2 .. include:: ../rst_prolog.rst
11 sat is a Command Line Interface (CLI_) based on python langage.
12 Its purpose is to cover the maintenance and the production of an application which run on several platforms and depend upon a lot of prerequisites.
13 It is most of the time used interactively from a terminal, but there is also a batch mode that can be used for example in automatic procedures (like jenkins jobs).
14 sat is used in command line by invoking after its name a sat option (which is non mandatory), then a command name, followed by the arguments of the command (most of the time the name of an application and command options):
18 ./sat [generic_options] [command] [application] [command_options]
21 The main sat options are:
23 * **-h** : to get the list of available options and commands
24 * **-o** : to overwrite at runtime a configuration parameter or option
25 * **-v** : to change the verbosity (default is 3, minimum 0 and maximum 6)
26 * **-b** : to enter the batch mode and avoid any question (this non interactive mode is useful for automatic procedures like jenkins jobs)
27 * **-t** : to display the compilation logs in the terminal (otherwise they are logged in files and displayed by the log command
29 The main sat commands are:
31 * **prepare** : to get the sources of the application products (from git repositories or archives) and apply patches if there are any
32 * **compile** : to build the application (using cmake, automake or shell script)
33 * **launcher** : to generate a launcher of the application (in the most general case the launcher sets up the run-time environment and start an exe)
34 * **package** : to build a package of the application (binary and/or source)
35 * **config** : to display the configuration
36 * **log** : to display within a web browser the logs of the commands
45 More details are provided by the help of sat. The help option can ba calle at two levels : the (high) level displays information on how to use sat, the command level displays information on how to use a sat command.
52 # display the help of the compile command
58 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, command, applications or product available. The completion mode has to be activated by sourcing the file **complete_sat.sh** contained in SAT directory:
62 source complete_sat.sh # activate the completion mode
64 ./sat conpile <TAB> <TAB> # liste all application available for compilation
65 > SALOME-7.8.2 SALOME-8.5.0 SALOME-9.3.0 SALOME-master
67 ./sat conpile SALOME-9.3.0 <TAB> <TAB> # list all available options
68 > --check --clean_build_after --install_flags --properties
69 > --stop_first_fail --with_fathers --clean_all --clean_make
70 > --products --show --with_children
74 Build from scratch an application
75 =================================
77 This is the main use case : build from scratch an application.
81 # get the list of available applications in your context
82 # the result depends upon the projects that have been loaded in sat.
89 # get all sources of SALOME-9.4.0 application
90 ./sat prepare SALOME-9.4.0
92 # compile all products (prerequisites and modules of SALOME-9.4.0)
93 ./sat compile SALOME-9.4.0
95 # if a compilation error occured, you can access the compilation logs with:
96 ./sat log SALOME-9.4.0
98 # create a SALOME launcher, displays its path.
99 ./sat launcher SALOME-9.4.0
100 > Generating launcher for SALOME-9.4.0 :
101 > .../SALOME-9.4.0-CO7/salome
103 # start salome platform
104 .../SALOME-9.4.0-CO7/salome
106 # create a binary package to install salome on other computers
107 ./sat package SALOME-9.4.0 -b
110 All the build is done in the *application directory*, which is parameted by the sat configuration variable *$APPLICATION.workdir*. In the above example t corresponds to *.../SALOME-9.4.0-CO7*.
111 **sat** can only build application provided by the projects that have been loaded in sat with *sat init* command. These available applications are lister by *sat config -l* command.
114 Partial recompilation of a packaged application
115 ===============================================
117 Getting all the sources and compile everything is a long process.
118 The following use case has proven to be convenient for fast usage.
119 It consists to get the application through a sat package containing the binaries and sat.
120 This allows using directly the application (the binary part).
121 And later, if required, it is possible to add a module, or modify and recompile one.
125 # untar a sat package containing binaries (for CentOS7) and sources
126 tar xfz SALOME-9.4.0-CO7-SRC.tar.gz
129 SALOME-9.4.0-CO7-SRC/salome
131 # copy binaries in INSTALL directory, do required substitution to enable recompilation
134 # get sources of module we want to recompile
135 salomeTools/sat prepare SALOME-9.4.0 -p SHAPER,SMESH
137 # do some modifications and recompile both modules
138 salomeTools/sat compile SALOME-9.4.0 -p SHAPER,SMESH --clean_all
140 This use case is documented in the README file of the package
145 Users or developers that have to build several applications, which share common products, may want to mutualise the compilation of the common products.
146 The notion of SAT base follow this obective. It allows sharing the installation of products between several applications.
151 By default the SAT base is located in the parent directory of sat (the directory containing sat directory) and is called BASE.
152 This default can be changed by the user with sat init command :
156 # change the location of SAT base directory
157 ./sat init -b <new base path>
159 Which products go into the base
160 -------------------------------
162 The application developper has the possibility to declare that a products will go by default in the base.
163 He uses for that the keyword 'base' in the install_dir key within the product configuration file (products pyconf) : *install_dir : 'base'*
164 It is done usually fir products that are considered as prerequisites.
166 At this stage, all products with install_dir set to 'base' will be installed in SAT base directory.
169 Application configuration
170 -------------------------
172 The default behaviour of products can be modified in the application configuration, with the base flag.
173 Like other application flags (debug, verbose, dev) the base flag can be used for a selection of products, or globally for all products.
177 # declare in application configuration that SMESH and YACS are installed in base
181 SMESH : {base : "yes"}
182 YACS : {base : "yes"}
186 # declare with a global application flag that all products are installed in base
190 Mutualisation of products
191 -------------------------
193 Products that go in base and have the same configuration will be shared by different application (it's the objective).
194 SAT does check the configuration to prevent of an application using a product in base with a non compatible configuration.
195 To check the compatibility, SAT stores in a file *sat-config-<product name>.pyconf* the configuration.
196 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*.
197 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>*.
199 .. 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 configuraion, it will overwrite the previous build done in production mode)