doc/src/usage_of_sat.rst

   1
   2 .. include:: ../rst_prolog.rst
   3
   4 *************************
   5 Main usage of SAlomeTools
   6 *************************
   7
   8 Purpose, Command Line Interface
   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 the salome platform and its applications.
  13
  14 Notably:
  15 * the definition of the applications content (the products, the resources, the options, the environment, the launcher, etc.)
  16 * the description of the products (the environment to set, how to get the sources; how to compilation, the dependencies, etc).
  17 * the complete preparation and build
  18 * the management of unit or integration tests
  19 * the production of binary or source packages
  20
  21 It can be used from interactively from a terminal, or in batch mode.
  22
  23 .. code-block:: bash
  24
  25   sat [generic_options] [command] [application] [command_options]
  26
  27
  28 Getting help
  29 ============
  30
  31 Help option -h
  32 --------------
  33
  34 To get help in terminal mode as simple text, use **--help** or **-h** option:
  35
  36 .. code-block:: bash
  37
  38     sat -h          # or --help : get the list of existing commands and main options
  39     sat compile -h  # get the help on the specific command 'compile'
  40
  41 completion mode
  42 ---------------
  43
  44 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:
  45
  46 .. code-block:: bash
  47
  48     source complete_sat.sh      # activate the completion mode
  49
  50     ./sat conpile  <TAB> <TAB>  # liste all application available for compilation
  51     > SALOME-7.8.2   SALOME-8.5.0   SALOME-9.3.0   SALOME-master
  52
  53     ./sat conpile SALOME-9.3.0 <TAB> <TAB>  # list all available options
  54     > --check              --clean_build_after  --install_flags      --properties
  55     > --stop_first_fail    --with_fathers       --clean_all          --clean_make
  56     > --products           --show               --with_children
  57
  58
  59 Verbose and Debug mode
  60 ======================
  61
  62 Verbosity
  63 ---------
  64
  65 **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.
  66 A verbosity of **0** correspond to no impression at all, while on the opposite a verbosity of **6** prints a lot of information.
  67
  68 Change verbosity level (default is 3).
  69
  70 .. code-block:: bash
  71
  72     sat -v0 prepare SALOME-9.3.0 -p GEOM  # prepare GEOM product in silent mode
  73     sat -v6 compile SALOME-9.3.0 -p GEOM  # compile GEOM with full verbosity
  74
  75 Debug mode -g
  76 -------------
  77
  78 This mode is used by developers to see more traces and *stack* if an exception is raised.
  79
  80
  81 Building a SALOME application
  82 =============================
  83
  84 Get the list of available applications
  85 --------------------------------------
  86
  87 To get the list of the current available applications in your context:
  88
  89 .. code-block:: bash
  90
  91     sat config -l
  92
  93 The result depends upon the projects that have been loaded in sat.
  94
  95
  96 Prepare sources of an application
  97 ---------------------------------
  98
  99 To prepare (get) *all* the sources of an application (*SALOME_xx* for example):
 100
 101 .. code-block:: bash
 102
 103     # get all sources
 104     sat prepare SALOME_xx
 105
 106     # get (git) sources of SALOME modules
 107     sat prepare SALOME_xx  --properties is_SALOME_module:yes
 108
 109 | The sources are usually copied in directory *$APPLICATION.workdir + $VARS.sep + 'SOURCES'*
 110
 111
 112 Compile an application
 113 ----------------------
 114
 115 To compile an application
 116
 117 .. code-block:: bash
 118
 119     # compile all prerequisites/products
 120     sat compile SALOME_xx
 121
 122     # compile only three products (KERNEL, GUI and SHAPER), if not done yet
 123     sat compile SALOME_xx -p KERNEL,GUI,SHAPER
 124
 125     # compile only two products, unconditionaly
 126     sat compile SALOME_xx -p KERNEL,GUI --clean_all
 127
 128     # (re)compile only salome modules
 129     sat compile SALOME_xx --properties is_SALOME_module:yes  --clean_all
 130
 131 | The products are usually build in the directory
 132 | *$APPLICATION.workdir + $VARS.sep + 'BUILD'*
 133 |
 134 | The products are usually installed in the directory
 135 | *$APPLICATION.workdir + $VARS.sep + 'INSTALL'*
 136
 137