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 generate and use a new build with a single command::

  sumo build utilize

This command is described in detail at 
:ref:`sumo build new <reference-sumo-utilize>`. 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`_.

The command then creates file configure/RELEASE to use build 'BL-002' (the name
of the new build). 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"
      }
  }

