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