2 .. include:: ../rst_prolog.rst
11 SAT is a Command Line Interface (CLI_) based on python language.
12 Its purpose is to cover the maintenance and the production of an application which has to run on several platforms and depends 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 invoke the **help** and 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 starts 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 SAT
45 More details are provided by the help of sat. The help option can be called 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 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:
62 # activate the completion mode
63 source complete_sat.sh
65 # list all application available for compilation
66 ./sat compile <TAB> <TAB>
67 > SALOME-7.8.2 SALOME-8.5.0 SALOME-9.3.0 SALOME-master
69 # list all available options of sat compile
70 ./sat compile SALOME-9.3.0 <TAB> <TAB>
71 > --check --clean_build_after --install_flags --properties
72 > --stop_first_fail --with_fathers --clean_all --clean_make
73 > --products --show --with_children
77 Build from scratch an application
78 =================================
80 This is the main use case : build from scratch an application.
84 # get the list of available applications in your context
85 # the result depends upon the projects that have been loaded in sat.
92 # get all sources of SALOME-9.4.0 application
93 ./sat prepare SALOME-9.4.0
95 # compile all products (prerequisites and modules of SALOME-9.4.0)
96 ./sat compile SALOME-9.4.0
98 # if a compilation error occured, you can access the compilation logs with:
99 ./sat log SALOME-9.4.0
101 # create a SALOME launcher, displays its path.
102 ./sat launcher SALOME-9.4.0
103 > Generating launcher for SALOME-9.4.0 :
104 > .../SALOME-9.4.0-CO7/salome
106 # start salome platform
107 .../SALOME-9.4.0-CO7/salome
109 # create a binary package to install salome on other computers
110 ./sat package SALOME-9.4.0 -b
113 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*.
114 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.
117 Partial recompilation of a packaged application
118 ===============================================
120 Getting all the sources and compile everything is often a long process.
121 The following use case has proven to be convenient for fast usage!
122 It consists to get the application through a sat package containing the binaries, the sources and SAT.
123 This allows using directly the application after the untar (the binary part).
124 And later, if required, it is possible to add a module, or modify some source code and recompile only what was added or modified.
128 # untar a sat package containing binaries (for CentOS7) and sources
129 tar xfz SALOME-9.4.0-CO7-SRC.tar.gz
132 SALOME-9.4.0-CO7-SRC/salome
134 # copy binaries in INSTALL directory, do required substitutions
135 # to enable recompilation
138 # get sources of modules we want to recompile
139 sat/sat prepare SALOME-9.4.0 -p SHAPER,SMESH
141 # do some modifications and recompile both modules
142 sat/sat compile SALOME-9.4.0 -p SHAPER,SMESH --clean_all
144 This use case is documented in the README file of the package
149 Users or developers that have to build several applications, which share common products, may want to mutualise the compilation of the common products.
150 The notion of SAT base follows this objective. It allows sharing the installation of products between several applications, and therefore compile these products only once.
155 By default the SAT base is located in the parent directory of sat (the directory containing sat directory) and is called BASE.
156 This default can be changed by the user with sat init command :
160 # change the location of SAT base directory
161 ./sat init -b <new base path>
163 Which products go into the base
164 -------------------------------
166 The application developer has the possibility to declare that a product will go by default in the base.
167 He uses for that the keyword 'base' in the install_dir key within the product configuration file (products pyconf) : *install_dir : 'base'*
168 It is done usually for products that are considered as prerequisites.
170 At this stage, all products with install_dir set to 'base' will be installed in SAT base directory.
173 Application configuration
174 -------------------------
176 The default behavior of products can be modified in the application configuration, with the **base** flag.
177 Like other application flags (debug, verbose, dev) the **base** flag can be used for a selection of products, or globally for all products.
181 # declare in application configuration that SMESH and YACS are installed in base
185 SMESH : {base : "yes"}
186 YACS : {base : "yes"}
190 # declare with a global application flag that all products are installed in base
194 Mutualisation of products
195 -------------------------
197 Products that go in base and have the same configuration will be shared by different applications (it's the objective).
198 SAT does check the configuration to prevent of an application using a product in base with a non compatible configuration.
199 To check the compatibility, SAT stores the configuration in a file called *sat-config-<product name>.pyconf*.
200 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*.
201 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>*.
203 .. 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)
206 Developing a module with SAT
207 ============================
209 SAT has some features that make developers' life easier. Let's highlight some of the developers use cases.
210 (if you are not familiar with SAT configuration, you may first read Configuration Chapter before, and come back to this paragraph after)
212 Activating the development mode
213 -------------------------------
215 By default *sat prepare* command is not suited for development, because it erases the source directory (if it already exists) before getting the sources.
216 If you did developments in this directory **they will be lost!**.
218 Therefore before you start some developments inside a product, you should **declare the product in development mode** in the application configuration.
219 For example if you plan to modify KERNEL module, modify SALOME configuration like this:
228 # declare KERNEL in development mode (and also compile it
229 # with debug and verbose options)
230 'KERNEL' : {dev:'yes', debug:'yes', verbose:'yes',
231 tag:'my_dev_branch', section:'version_7_8_0_to_8_4_0'}
236 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.
237 For the next calls to *sat prepare*, it will keep the source intact and do nothing!
239 In the example we have also set the debug and the verbose flags to "yes" - it is often useful when developing.
241 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).
243 .. 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.
245 Pushing developments in base, or creating patches
246 -------------------------------------------------
248 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.
249 If not (if you are detached to a tag, you can produce with git a patch of you developments:
251 git diff > my_dev.patch
253 And use this patch either with SAT to apply it automatically with *sat prepare* command, or send the patch for an integration request.
256 Changing the source directory
257 -----------------------------
259 By default the source directory of a product is located inside SAT installation, in the SOURCES directory.
260 This default may not be convenient. Developers may prefer to develop inside the HOME directory (for example when this directory is automatically saved).
262 To change the default source directory, you first have to identify which product section is used by SAT: ::
264 ./sat config SALOME-9.4.0 -i KERNEL
268 Then you can change the source directory in the section being used (default in the example above).
269 For that you can modify the **source_dir** field in the file *SAT_SALOME/products/KERNEL.pyconf*.
270 Or change it in command line: **./sat -o "PRODUCTS.KERNEL.default.source_dir='/home/KERNEL'" <your sat command>**.
271 For example the following command recompiles KERNEL using */home/KERNEL* as source directory: ::
273 # take KERNEL sources in /home/KERNEL
274 ./sat -o "PRODUCTS.KERNEL.default.source_dir='/home/KERNEL'" compile SALOME-master\
275 -p KERNEL --clean_all
277 Displaying compilation logs in the terminal
278 -------------------------------------------
279 When developing a module you often have to compile it, and correct errors that occurs.
280 In this case, using *sat log* command to consult the compilation logs is not convenient!
281 It is advised to use in this case the **-t** option of sat, it will display the logs directly inside the terminal: ::
283 # sat -t option put the compilation logs in the terminal
284 ./sat -t -o "PRODUCTS.KERNEL.default.source_dir='/home/KERNEL'" compile\
285 SALOME-master -p KERNEL --clean_all