Using sumo in your application
==============================

Use supports in an application
------------------------------

Suppose we have an application and want to use existing supports. The
application has a list of modules in file "configure/MODULES", you can see this
file at `MODULES`_. 

In order to use the support modules in our application we simply enter::

  sumo build use

This command is described in detail at 
:ref:`sumo build use <reference-sumo-use>`. The program replies::

  using build BL-001

This means that the file configure/RELEASE was generated with all entries
needed to use support modules from build 'BL-001' (each build has a name). 
You can see the contents of this file at `RELEASE for BL-001`_.

You can now build your application with::

  make


Use a different version of a support
------------------------------------

In order to use, for example, module "ALARM" in version "R3-8", we change in
file "configure/MODULES" the line::

          "ALARM:R3-8",

to::

          "ALARM:R3-9",

We now try to generate the RELEASE file::

  sumo build use

but the program replies::

  no build found that matches modulespecs 

This means that we first have to install the sources of the new version of
"ALARM" and compile it and all dependent modules. This is done with::

  sumo build new

This command is described in detail at 
:ref:`sumo build new <reference-sumo-new>`. sumo generates a Makefile in it's
build directory, fetches all needed sources and invokes "make". You can see
this file at `Makefile for BL-002`_. Information on all builds is kept in a
build database, you can see this at `BUILDS.DB`_.

After the command is completed we enter again::

  sumo build use

the program replies::

  using build BL-002

This means that the file configure/RELEASE was generated with all entries
needed to use support modules from build 'BL-002' (a new build was created with
a new name).  You can see the contents of this file at `RELEASE for BL-002`_.
You can now build your application with::

  make

Details
-------

In this section you see the contents of some of the files used or generated by
sumo.

.. _app-usage-modules:

MODULES
+++++++

This is the file configure/MODULES that specifies for sumo which modules our
application uses. For more details on module specifications see
:doc:`modulespecs` ::

  {
      "alias": [
          "APPS_GENERICBOOT:GENERIC_BOOT",
          "BASE:EPICS_BASE",
          "SEQ:SNCSEQ"
      ],
      "module": [
          "ALARM:R3-9",
          "APPS_CRATECTRL:R4-1",
          "APPS_GENERICBOOT:R1-6",
          "APPS_GENERICTEMPLATE:R3-2-1",
          "APPS_IOCWATCH:R3-1",
          "APPS_MOTOR:R4-5-6",
          "ASYN:R4-30-bessy1",
          "AUTOSAVE:R4-8-bessy4",
          "BASE:R3-14-12-5-bessy4-rtems-4.9-sumo",
          "BESSYRULES:R2-29",
          "BME:R1-0-7",
          "BSPDEP_CPUBOARDINIT:R4-1",
          "BSPDEP_TIMER:R6-2",
          "BSPDEP_VMETAS:R2-0",
          "CAPUTLOG:R3-3-2",
          "DEVIOCSTATS:R3-1-9-bessy5",
          "DISTVERSION:R2-2",
          "ESD:R2-1",
          "KEITHLEY:R1-1-19",
          "MCAN:R2-6-3-2",
          "MISC_DBC:R3-0",
          "MISC_DEBUGMSG:R3-0",
          "MOTOR:R6-9-bessy5",
          "RTEMS-BUILD-TOOL:4.9-1.12",
          "S7PLC:R2-0",
          "SEQ:R2-1-16",
          "SOFT_DEVHWCLIENT:R3-0",
          "APPS_STREAMTEMPLATESANDPROTOCOLS:R2-18",
          "STREAMDEVICE:R2-7-7-bessy3",
          "TOOLS_DBOPT:R0-4",
          "TOOLS_MSI:R1-5-bessy3",
          "VHQ:R3-3",
          "VXBOOTPARAMS:R2-4"
      ]
  }

RELEASE for BL-001
++++++++++++++++++

This is the content of the generated RELEASE file for build "BL-001" in our
example::

  # generated by sumo using build BL-001:
  VXBOOTPARAMS=/srv/csr/Epics/sumo/build/VXBOOTPARAMS/R2-4+BL-001
  VHQ=/srv/csr/Epics/sumo/build/VHQ/R3-3+BL-001
  KEITHLEY=/srv/csr/Epics/sumo/build/KEITHLEY/R1-1-19+BL-001
  BME=/srv/csr/Epics/sumo/build/BME/R1-0-7+BL-001
  APPS_STREAMTEMPLATESANDPROTOCOLS=/srv/csr/Epics/sumo/build/APPS_STREAMTEMPLATESANDPROTOCOLS/R2-18+BL-001
  APPS_MOTOR=/srv/csr/Epics/sumo/build/APPS_MOTOR/R4-5-6+BL-001
  APPS_IOCWATCH=/srv/csr/Epics/sumo/build/APPS_IOCWATCH/R3-1+BL-001
  APPS_GENERICTEMPLATE=/srv/csr/Epics/sumo/build/APPS_GENERICTEMPLATE/R3-2-1+BL-001
  BESSYRULES=/srv/csr/Epics/sumo/build/BESSYRULES/R2-29+BL-001
  TOOLS_MSI=/srv/csr/Epics/sumo/build/TOOLS_MSI/R1-5-bessy3+BL-001
  TOOLS_DBOPT=/srv/csr/Epics/sumo/build/TOOLS_DBOPT/R0-4+BL-001
  STREAMDEVICE=/srv/csr/Epics/sumo/build/STREAMDEVICE/R2-7-7-bessy3+BL-001
  MCAN=/srv/csr/Epics/sumo/build/MCAN/R2-6-3-2+BL-001
  SOFT_DEVHWCLIENT=/srv/csr/Epics/sumo/build/SOFT_DEVHWCLIENT/R3-0+BL-001
  ALARM=/srv/csr/Epics/sumo/build/ALARM/R3-8+BL-001
  SNCSEQ=/srv/csr/Epics/sumo/build/SEQ/R2-1-16+BL-001
  S7PLC=/srv/csr/Epics/sumo/build/S7PLC/R2-0+BL-001
  MOTOR=/srv/csr/Epics/sumo/build/MOTOR/R6-9-bessy5+BL-001
  MISC_DEBUGMSG=/srv/csr/Epics/sumo/build/MISC_DEBUGMSG/R3-0+BL-001
  MISC_DBC=/srv/csr/Epics/sumo/build/MISC_DBC/R3-0+BL-001
  ESD=/srv/csr/Epics/sumo/build/ESD/R2-1+BL-001
  DISTVERSION=/srv/csr/Epics/sumo/build/DISTVERSION/R2-2+BL-001
  DEVIOCSTATS=/srv/csr/Epics/sumo/build/DEVIOCSTATS/R3-1-9-bessy5+BL-001
  CAPUTLOG=/srv/csr/Epics/sumo/build/CAPUTLOG/R3-3-2+BL-001
  BSPDEP_VMETAS=/srv/csr/Epics/sumo/build/BSPDEP_VMETAS/R2-0+BL-001
  BSPDEP_TIMER=/srv/csr/Epics/sumo/build/BSPDEP_TIMER/R6-2+BL-001
  BSPDEP_CPUBOARDINIT=/srv/csr/Epics/sumo/build/BSPDEP_CPUBOARDINIT/R4-1+BL-001
  AUTOSAVE=/srv/csr/Epics/sumo/build/AUTOSAVE/R4-8-bessy4+BL-001
  ASYN=/srv/csr/Epics/sumo/build/ASYN/R4-30-bessy1+BL-001
  GENERIC_BOOT=/srv/csr/Epics/sumo/build/APPS_GENERICBOOT/R1-6+BL-001
  EPICS_BASE=/srv/csr/Epics/sumo/build/BASE/R3-14-12-5-bessy4-rtems-4.9-sumo+BL-001
  RTEMS-BUILD-TOOL=/srv/csr/Epics/sumo/build/RTEMS-BUILD-TOOL/4.9-1.12+BL-001
  APPS_CRATECTRL=/srv/csr/Epics/sumo/build/APPS_CRATECTRL/R4-1+BL-001

RELEASE for BL-002
++++++++++++++++++

This is the content of the generated RELEASE file for build "BL-002" in our
example::

  # generated by sumo using build BL-002:
  VXBOOTPARAMS=/srv/csr/Epics/sumo/build/VXBOOTPARAMS/R2-4+BL-001
  VHQ=/srv/csr/Epics/sumo/build/VHQ/R3-3+BL-001
  KEITHLEY=/srv/csr/Epics/sumo/build/KEITHLEY/R1-1-19+BL-001
  BME=/srv/csr/Epics/sumo/build/BME/R1-0-7+BL-001
  APPS_STREAMTEMPLATESANDPROTOCOLS=/srv/csr/Epics/sumo/build/APPS_STREAMTEMPLATESANDPROTOCOLS/R2-18+BL-001
  APPS_MOTOR=/srv/csr/Epics/sumo/build/APPS_MOTOR/R4-5-6+BL-001
  APPS_IOCWATCH=/srv/csr/Epics/sumo/build/APPS_IOCWATCH/R3-1+BL-001
  APPS_GENERICTEMPLATE=/srv/csr/Epics/sumo/build/APPS_GENERICTEMPLATE/R3-2-1+BL-001
  BESSYRULES=/srv/csr/Epics/sumo/build/BESSYRULES/R2-29+BL-001
  TOOLS_MSI=/srv/csr/Epics/sumo/build/TOOLS_MSI/R1-5-bessy3+BL-001
  TOOLS_DBOPT=/srv/csr/Epics/sumo/build/TOOLS_DBOPT/R0-4+BL-001
  STREAMDEVICE=/srv/csr/Epics/sumo/build/STREAMDEVICE/R2-7-7-bessy3+BL-001
  MCAN=/srv/csr/Epics/sumo/build/MCAN/R2-6-3-2+BL-002
  SOFT_DEVHWCLIENT=/srv/csr/Epics/sumo/build/SOFT_DEVHWCLIENT/R3-0+BL-001
  ALARM=/srv/csr/Epics/sumo/build/ALARM/R3-9+BL-002
  SNCSEQ=/srv/csr/Epics/sumo/build/SEQ/R2-1-16+BL-001
  S7PLC=/srv/csr/Epics/sumo/build/S7PLC/R2-0+BL-001
  MOTOR=/srv/csr/Epics/sumo/build/MOTOR/R6-9-bessy5+BL-001
  MISC_DEBUGMSG=/srv/csr/Epics/sumo/build/MISC_DEBUGMSG/R3-0+BL-001
  MISC_DBC=/srv/csr/Epics/sumo/build/MISC_DBC/R3-0+BL-001
  ESD=/srv/csr/Epics/sumo/build/ESD/R2-1+BL-001
  DISTVERSION=/srv/csr/Epics/sumo/build/DISTVERSION/R2-2+BL-001
  DEVIOCSTATS=/srv/csr/Epics/sumo/build/DEVIOCSTATS/R3-1-9-bessy5+BL-001
  CAPUTLOG=/srv/csr/Epics/sumo/build/CAPUTLOG/R3-3-2+BL-001
  BSPDEP_VMETAS=/srv/csr/Epics/sumo/build/BSPDEP_VMETAS/R2-0+BL-001
  BSPDEP_TIMER=/srv/csr/Epics/sumo/build/BSPDEP_TIMER/R6-2+BL-001
  BSPDEP_CPUBOARDINIT=/srv/csr/Epics/sumo/build/BSPDEP_CPUBOARDINIT/R4-1+BL-001
  AUTOSAVE=/srv/csr/Epics/sumo/build/AUTOSAVE/R4-8-bessy4+BL-001
  ASYN=/srv/csr/Epics/sumo/build/ASYN/R4-30-bessy1+BL-001
  GENERIC_BOOT=/srv/csr/Epics/sumo/build/APPS_GENERICBOOT/R1-6+BL-001
  EPICS_BASE=/srv/csr/Epics/sumo/build/BASE/R3-14-12-5-bessy4-rtems-4.9-sumo+BL-001
  RTEMS-BUILD-TOOL=/srv/csr/Epics/sumo/build/RTEMS-BUILD-TOOL/4.9-1.12+BL-001
  APPS_CRATECTRL=/srv/csr/Epics/sumo/build/APPS_CRATECTRL/R4-1+BL-001

Makefile for BL-002
+++++++++++++++++++

This is the generated makefile for build BL-002::

  ALARM=/srv/csr/Epics/sumo/build/ALARM/R3-9+BL-002
  APPS_CRATECTRL=/srv/csr/Epics/sumo/build/APPS_CRATECTRL/R4-1+BL-001
  APPS_GENERICBOOT=/srv/csr/Epics/sumo/build/APPS_GENERICBOOT/R1-6+BL-001
  APPS_GENERICTEMPLATE=/srv/csr/Epics/sumo/build/APPS_GENERICTEMPLATE/R3-2-1+BL-001
  APPS_IOCWATCH=/srv/csr/Epics/sumo/build/APPS_IOCWATCH/R3-1+BL-001
  APPS_MOTOR=/srv/csr/Epics/sumo/build/APPS_MOTOR/R4-5-6+BL-001
  APPS_STREAMTEMPLATESANDPROTOCOLS=/srv/csr/Epics/sumo/build/APPS_STREAMTEMPLATESANDPROTOCOLS/R2-18+BL-001
  ASYN=/srv/csr/Epics/sumo/build/ASYN/R4-30-bessy1+BL-001
  AUTOSAVE=/srv/csr/Epics/sumo/build/AUTOSAVE/R4-8-bessy4+BL-001
  BASE=/srv/csr/Epics/sumo/build/BASE/R3-14-12-5-bessy4-rtems-4.9-sumo+BL-001
  BESSYRULES=/srv/csr/Epics/sumo/build/BESSYRULES/R2-29+BL-001
  BME=/srv/csr/Epics/sumo/build/BME/R1-0-7+BL-001
  BSPDEP_CPUBOARDINIT=/srv/csr/Epics/sumo/build/BSPDEP_CPUBOARDINIT/R4-1+BL-001
  BSPDEP_TIMER=/srv/csr/Epics/sumo/build/BSPDEP_TIMER/R6-2+BL-001
  BSPDEP_VMETAS=/srv/csr/Epics/sumo/build/BSPDEP_VMETAS/R2-0+BL-001
  CAPUTLOG=/srv/csr/Epics/sumo/build/CAPUTLOG/R3-3-2+BL-001
  DEVIOCSTATS=/srv/csr/Epics/sumo/build/DEVIOCSTATS/R3-1-9-bessy5+BL-001
  DISTVERSION=/srv/csr/Epics/sumo/build/DISTVERSION/R2-2+BL-001
  ESD=/srv/csr/Epics/sumo/build/ESD/R2-1+BL-001
  KEITHLEY=/srv/csr/Epics/sumo/build/KEITHLEY/R1-1-19+BL-001
  MCAN=/srv/csr/Epics/sumo/build/MCAN/R2-6-3-2+BL-002
  MISC_DBC=/srv/csr/Epics/sumo/build/MISC_DBC/R3-0+BL-001
  MISC_DEBUGMSG=/srv/csr/Epics/sumo/build/MISC_DEBUGMSG/R3-0+BL-001
  MOTOR=/srv/csr/Epics/sumo/build/MOTOR/R6-9-bessy5+BL-001
  RTEMS-BUILD-TOOL=/srv/csr/Epics/sumo/build/RTEMS-BUILD-TOOL/4.9-1.12+BL-001
  S7PLC=/srv/csr/Epics/sumo/build/S7PLC/R2-0+BL-001
  SEQ=/srv/csr/Epics/sumo/build/SEQ/R2-1-16+BL-001
  SOFT_DEVHWCLIENT=/srv/csr/Epics/sumo/build/SOFT_DEVHWCLIENT/R3-0+BL-001
  STREAMDEVICE=/srv/csr/Epics/sumo/build/STREAMDEVICE/R2-7-7-bessy3+BL-001
  TOOLS_DBOPT=/srv/csr/Epics/sumo/build/TOOLS_DBOPT/R0-4+BL-001
  TOOLS_MSI=/srv/csr/Epics/sumo/build/TOOLS_MSI/R1-5-bessy3+BL-001
  VHQ=/srv/csr/Epics/sumo/build/VHQ/R3-3+BL-001
  VXBOOTPARAMS=/srv/csr/Epics/sumo/build/VXBOOTPARAMS/R2-4+BL-001
  
  .PHONY: all clean config distclean
  
  all: \
  	ALARM/R3-9+BL-002/sumo-all \
  	MCAN/R2-6-3-2+BL-002/sumo-all
  
  config: \
  	ALARM/R3-9+BL-002/sumo-config \
  	MCAN/R2-6-3-2+BL-002/sumo-config
  
  clean: \
  	ALARM/R3-9+BL-002/sumo-clean \
  	MCAN/R2-6-3-2+BL-002/sumo-clean
  
  distclean: \
  	ALARM/R3-9+BL-002/sumo-distclean \
  	MCAN/R2-6-3-2+BL-002/sumo-distclean
  
  MCAN/R2-6-3-2+BL-002/sumo-all: \
  	ALARM/R3-9+BL-002/sumo-all
  
  
  %/sumo-all:
  	$(MAKE) -C $(@D)
  	cd $(@D) && rm -f sumo-all sumo-config sumo-clean sumo-distclean
  	touch $@
  
  %/sumo-config:
  	cd $(@D) && rm -f sumo-all sumo-config sumo-clean sumo-distclean
  	touch $@
  
  %/sumo-clean:
  	$(MAKE) -C $(@D) clean
  	cd $(@D) && rm -f sumo-all sumo-config sumo-clean sumo-distclean
  	touch $@
  
  %/sumo-distclean:
  	$(MAKE) -C $(@D) distclean
  	cd $(@D) && rm -f sumo-all sumo-config sumo-clean sumo-distclean
  	touch $@


BUILDS.DB
+++++++++

This is the content of the build database after we created BL-001 and BL-002.
For more information see 
:ref:`The build database <reference-sumo-The-build-database>`::

  {
      "BL-001": {
          "modules": {
              "ALARM": "R3-8",
              "APPS_CRATECTRL": "R4-1",
              "APPS_GENERICBOOT": "R1-6",
              "APPS_GENERICTEMPLATE": "R3-2-1",
              "APPS_IOCWATCH": "R3-1",
              "APPS_MOTOR": "R4-5-6",
              "APPS_STREAMTEMPLATESANDPROTOCOLS": "R2-18",
              "ASYN": "R4-30-bessy1",
              "AUTOSAVE": "R4-8-bessy4",
              "BASE": "R3-14-12-5-bessy4-rtems-4.9-sumo",
              "BESSYRULES": "R2-29",
              "BME": "R1-0-7",
              "BSPDEP_CPUBOARDINIT": "R4-1",
              "BSPDEP_TIMER": "R6-2",
              "BSPDEP_VMETAS": "R2-0",
              "CAPUTLOG": "R3-3-2",
              "DEVIOCSTATS": "R3-1-9-bessy5",
              "DISTVERSION": "R2-2",
              "ESD": "R2-1",
              "KEITHLEY": "R1-1-19",
              "MCAN": "R2-6-3-2",
              "MISC_DBC": "R3-0",
              "MISC_DEBUGMSG": "R3-0",
              "MOTOR": "R6-9-bessy5",
              "RTEMS-BUILD-TOOL": "4.9-1.12",
              "S7PLC": "R2-0",
              "SEQ": "R2-1-16",
              "SOFT_DEVHWCLIENT": "R3-0",
              "STREAMDEVICE": "R2-7-7-bessy3",
              "TOOLS_DBOPT": "R0-4",
              "TOOLS_MSI": "R1-5-bessy3",
              "VHQ": "R3-3",
              "VXBOOTPARAMS": "R2-4"
          },
          "state": "testing"
      },
      "BL-002": {
          "linked": {
              "APPS_CRATECTRL": "BL-001",
              "APPS_GENERICBOOT": "BL-001",
              "APPS_GENERICTEMPLATE": "BL-001",
              "APPS_IOCWATCH": "BL-001",
              "APPS_MOTOR": "BL-001",
              "APPS_STREAMTEMPLATESANDPROTOCOLS": "BL-001",
              "ASYN": "BL-001",
              "AUTOSAVE": "BL-001",
              "BASE": "BL-001",
              "BESSYRULES": "BL-001",
              "BME": "BL-001",
              "BSPDEP_CPUBOARDINIT": "BL-001",
              "BSPDEP_TIMER": "BL-001",
              "BSPDEP_VMETAS": "BL-001",
              "CAPUTLOG": "BL-001",
              "DEVIOCSTATS": "BL-001",
              "DISTVERSION": "BL-001",
              "ESD": "BL-001",
              "KEITHLEY": "BL-001",
              "MISC_DBC": "BL-001",
              "MISC_DEBUGMSG": "BL-001",
              "MOTOR": "BL-001",
              "RTEMS-BUILD-TOOL": "BL-001",
              "S7PLC": "BL-001",
              "SEQ": "BL-001",
              "SOFT_DEVHWCLIENT": "BL-001",
              "STREAMDEVICE": "BL-001",
              "TOOLS_DBOPT": "BL-001",
              "TOOLS_MSI": "BL-001",
              "VHQ": "BL-001",
              "VXBOOTPARAMS": "BL-001"
          },
          "modules": {
              "ALARM": "R3-9",
              "APPS_CRATECTRL": "R4-1",
              "APPS_GENERICBOOT": "R1-6",
              "APPS_GENERICTEMPLATE": "R3-2-1",
              "APPS_IOCWATCH": "R3-1",
              "APPS_MOTOR": "R4-5-6",
              "APPS_STREAMTEMPLATESANDPROTOCOLS": "R2-18",
              "ASYN": "R4-30-bessy1",
              "AUTOSAVE": "R4-8-bessy4",
              "BASE": "R3-14-12-5-bessy4-rtems-4.9-sumo",
              "BESSYRULES": "R2-29",
              "BME": "R1-0-7",
              "BSPDEP_CPUBOARDINIT": "R4-1",
              "BSPDEP_TIMER": "R6-2",
              "BSPDEP_VMETAS": "R2-0",
              "CAPUTLOG": "R3-3-2",
              "DEVIOCSTATS": "R3-1-9-bessy5",
              "DISTVERSION": "R2-2",
              "ESD": "R2-1",
              "KEITHLEY": "R1-1-19",
              "MCAN": "R2-6-3-2",
              "MISC_DBC": "R3-0",
              "MISC_DEBUGMSG": "R3-0",
              "MOTOR": "R6-9-bessy5",
              "RTEMS-BUILD-TOOL": "4.9-1.12",
              "S7PLC": "R2-0",
              "SEQ": "R2-1-16",
              "SOFT_DEVHWCLIENT": "R3-0",
              "STREAMDEVICE": "R2-7-7-bessy3",
              "TOOLS_DBOPT": "R0-4",
              "TOOLS_MSI": "R1-5-bessy3",
              "VHQ": "R3-3",
              "VXBOOTPARAMS": "R2-4"
          },
          "state": "testing"
      }
  }

