sumo tips and tricks
====================

A collection of some useful commands for sumo.

Create a local "sandbox" for builds
-----------------------------------

Use this when you intend to do tests and apply changes directly in the build
and/or database directory. This creates a local build directory 'TEST'::

  sumo config local TEST

See also :ref:`sumo config local <dev-usage-sandbox>` and 
:ref:`sandbox <dev-usage-sandbox>`.

Show which configuration files are loaded
-----------------------------------------

Enter::

  sumo config list

See also :ref:`sumo config list <reference-sumo-config-list>`.

Show configuration without loaded files
---------------------------------------

This usually shows the current configuration *without* the module list from
'configure/MODULES'::

  sumo config show --disable-loading

See also :ref:`sumo config show <reference-sumo-config-show>`.

Show complete configuration from configuration files
----------------------------------------------------

Enter::

  sumo config show

See also :ref:`sumo config show <reference-sumo-config-show>`.

Build in parallel with download progress
----------------------------------------

Run (on Linux)::

  sumo build utilize --makeflags "-sj$(nproc)" --progress

Explanation: This starts make with multiple processes, but not more than the
CPU cores you have on your machine.

See also :ref:`--makeflags <reference-sumo-makeflags>`.

Get a simple list of module specifications from your MODULES file
-----------------------------------------------------------------

Enter::

  sumo config show module -b
  
You get a list of all modules, one per line. 

See also :ref:`sumo config show <reference-sumo-config-show>`.

Create a build with a module list on the command line
-----------------------------------------------------

Enter::

  sumo build new --makeflags "-sj$(nproc)" --progress MODULE1:VERSION1 MODULE2:VERSION2 [...]

Note that when sumo is called like this, the module specifications from the
configuration file (usually 'configure/MODULES') is ignored. See also option
``--append``.

See also :ref:`sumo build new <reference-sumo-new>`.

Put EPICS Base in a separate build
----------------------------------

Usually your build contains EPICS Base. Compiling EPICS Base usually takes a
long time and you don't expect problems compiling it. Other supports however,
may fail. If you start all over, compiling EPICS Base each time again and again
is cumbersome. The following line puts your version of EPICS Base in a separate
build::

  sumo build new --makeflags "-sj$(nproc)" "$(sumo config show module -b | grep BASE:)"

The command in parentheses takes all modules, extracts only EPICS Base and
appends this as command line argument.

See also :ref:`sumo build new <reference-sumo-new>`.

Enable sumo command completion on the fly
-----------------------------------------

If you have installed sumo but the command completion is missing, enter::

  eval "$(sumo help completion-line)"

To make this permanent, append the output of ``sumo help completion-line`` to
your shell configuration file, e.g. '$HOME/.bashrc'.

See also :ref:`completion <reference-sumo-completion>`.

Bootstrap sumo your machine
---------------------------

If you want to test sumo on a machine where it is not installed, run these commands::

  python -m venv VENV
  source VENV/bin/activate
  pip install epics-sumo
  sumo config new SUMO sumo-free-database INITIAL
  eval "$(sumo help completion-line)"

This creates a Python virtual environment in directory 'VENV' and puts the sumo
dependency database and builds and directory 'SUMO'. The sumo configuration
file is created in 'VENV' at the location of the sumo python modules. The last
line enables command completion for sumo. You may want to append the output of
``sumo help completion-line`` to you shell configuration, e.g.
``$HOME/.bashrc``.