doc/src/usage_of_sat.rst

   1
   2 .. include:: ../rst_prolog.rst
   3
   4 *********
   5 Using SAT
   6 *********
   7
   8 Getting started
   9 ===============
  10
  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):
  15
  16 .. code-block:: bash
  17
  18     ./sat [generic_options] [command] [application] [command_options]
  19
  20
  21 The main sat options are:
  22
  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
  28
  29 The main sat commands are:
  30
  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
  37
  38
  39 Getting help
  40 ============
  41
  42 Help option -h
  43 --------------
  44
  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.
  46
  47 .. code-block:: bash
  48
  49     # display sat help
  50     ./sat -h
  51
  52     # display the help of the compile command
  53     ./sat compile -h
  54
  55 Completion mode
  56 ---------------
  57
  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:
  59
  60 .. code-block:: bash
  61
  62     source complete_sat.sh      # activate the completion mode
  63
  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
  66
  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
  71
  72
  73
  74 Build from scratch an application
  75 =================================
  76
  77 This is the main use case : build from scratch an application.
  78
  79 .. code-block:: bash
  80
  81     # get the list of available applications in your context
  82     # the result depends upon the projects that have been loaded in sat.
  83     ./sat config -l
  84     >  ...
  85     >  SALOME-8.5.0
  86     >  SALOME-9.3.0
  87     >  SALOME-9.4.0
  88
  89     # get all sources of SALOME-9.4.0 application
  90     ./sat prepare SALOME-9.4.0
  91
  92     # compile all products (prerequisites and modules of SALOME-9.4.0)
  93     ./sat compile SALOME-9.4.0
  94
  95     # if a compilation error occured, you can access the compilation logs with:
  96     ./sat log SALOME-9.4.0
  97
  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
 102
 103     # start salome platform
 104     .../SALOME-9.4.0-CO7/salome
 105
 106     # create a binary package to install salome on other computers
 107     ./sat package SALOME-9.4.0 -b
 108
 109
 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.
 112
 113
 114 Partial recompilation of a packaged application
 115 ===============================================
 116
 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.
 122
 123 .. code-block:: bash
 124
 125     # untar a sat package containing binaries (for CentOS7) and sources
 126     tar xfz SALOME-9.4.0-CO7-SRC.tar.gz
 127
 128     # start salome
 129     SALOME-9.4.0-CO7-SRC/salome
 130
 131     # copy binaries in INSTALL directory, do required substitution to enable recompilation
 132     ./install_bin.sh
 133
 134     # get sources of module we want to recompile
 135     salomeTools/sat prepare SALOME-9.4.0 -p SHAPER,SMESH
 136
 137     # do some modifications and recompile both modules
 138     salomeTools/sat compile SALOME-9.4.0 -p SHAPER,SMESH  --clean_all
 139
 140 This use case is documented in the README file of the package
 141
 142 Using SAT bases
 143 ===============
 144
 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.
 147
 148 Location
 149 --------
 150
 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 :
 153
 154 .. code-block:: bash
 155
 156     # change the location of SAT base directory
 157     ./sat init -b <new base path>
 158
 159 Which products go into the base
 160 -------------------------------
 161
 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.
 165
 166 At this stage, all products with install_dir set to 'base' will be installed in SAT base directory.
 167
 168
 169 Application configuration
 170 -------------------------
 171
 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.
 174
 175 .. code-block:: bash
 176
 177     # declare in application configuration that SMESH and YACS are installed in base
 178     products :
 179     {
 180     ...
 181     SMESH : {base : "yes"}
 182     YACS : {base : "yes"}
 183     ...
 184     }
 185
 186     # declare with a global application flag that all products are installed in base
 187     base : "yes"
 188
 189
 190 Mutualisation of products
 191 -------------------------
 192
 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>*.
 198
 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)
 200
 201