capsules

SBGrid software environment

The SBGrid Capsule software environment includes features for users to manage software versions and duplicate executables. Older features (such as version selection) are still present but improved. Old scripts should run unaltered and no new commands are required.

Notable features of Capsules

  • Specify software version on the fly by setting single environment variable
  • Single path entry, minimal environment required
  • Compatile with existing software stacks, modules

Check out Carol Herre's presentation on Capsules on SBGrid TV

Getting started

You can switch from the legacy SBGrid environment to the new with the sbcap command. sbcap on will enable the capsule environment. You can always return to the legacy configuration with the sbcap off command and sbcap reset returns the setting to the default.

The sbcap setting is persistent across shells - You don't need to do this for every shell.

sbcap - Example

user@linux ~
  $ sbcap on

You will see a notice that you are using the new environment

********************************************************************************
                  Software Support by SBGrid (www.sbgrid.org)
********************************************************************************
                              SBGrid Announcements
...
********************************************************************************
 Capsule Status: Active
       For additional information visit https://sbgrid.org/wiki/capsules
********************************************************************************
$

You can check your capsule status with sbcap status.

$ sbcap status
Active

Usage - Capsule Environment for SBGrid

Usage: sbgrid-exectable  [ --sbwhich | --sbenv | --sbman | --sbapp:[adlshrH] | --sbcitation | --sbticket | --sbhelp ]

 sbwhich         display actual executable path
 sbenv           display the running environment for the capsule
 sbman           if it exists, display executable man page
 sbapp:[adlshrH] display or select application when executable is in multiple sw titles
      :a app     run using app
      :l         list available apps
      :s         select app from menu
      :h         short help on apps
      :r         return codes help related to application selection
      :H         extended Help
 sbcitation      TO BE COMPLETED - if applicable, display citation information
 sbticket        TO BE COMPLETED - collect relevant information and submit a help request to help@sbgrid.org
 sbhelp          this message

Overrides - managing versions :

Version overrides may be defined in the ~/.sbgrid.conf file, which will be used each time the sbgrid.[sh|csh] file are sourced. A version override can also be instantiated by simply defining the APP_M prior to capsule execution.

Setting the version - EXAMPLE

For the refine executable, the default version show here is 20160324.

		 $ refine --sbwhich
          /programs/x86_64-linux/buster/20160324/autoBUSTER/bin/linux64/refine

We can change this by setting the variable BUSTER_X to 20151214 and calling sbwhich in one command :

		 $  env BUSTER_X=20151214 refine --sbwhich
          /programs/x86_64-linux/buster/20151214/autoBUSTER/bin/linux64/refine

This can also be accomplished by simply setting BUSTER_X=20151214 in the shell or adding the line BUSTER_X=20151214 to your ~/.sbgrid.conf file as described here. Note that case is important for the variable names. All SBGrid variable names are ALL CAPS.

Managing Duplicate Executables

In some cases an executable may exist in multiple applications, i.e. the program fft exists in CCP4 and Tigris. A default application is already defined based on what executable would be used in the legacy environment, but the user can choose to override this selectively or permanently.

You can override the default in 4 ways. They are

  1. Command Line arguments select the application for a single command : --sbapp:a runs the executable from "appname" or --sbapp:s select application from a list

  2. Environment variable of the form _<EXECUTABLE>, an underscore followed by executable in UPPER CASE. e.g. _XIA2=dials will use xia2 executable from "dials".

  3. A User Config file in ~/.sbgrid_capsule/<execname>. e.g. echo dials > ~/.sbgrid_capsule/xia2 will uset the shell to always use the xia2 from "dials"

  4. A localsite file in ${SB_BASE}/local/capsule/${SB_ARCH}/defaults/execname

Managing Duplicate with userpath

Sometimes a duplicate occurs with an executable that is outside of the SBGrid or BioGrids software tree. For example xterm on x86_64-linux is provided by sbgrid and usually provided by the operating system. A user may use the "userpath" directive to select the one that is accessible from the PATH prior to sourcing the SBGrid/BioGrids environment.

  1. Command Line arguments select the application for a single command : --sbapp:s select application from a list

  2. Environment variable of the form _<EXECUTABLE>, an underscore followed by executable in UPPER CASE. e.g. _XTERM=userpath will use xterm from the user's original path.

  3. A User Configfile in *~/.sbgridcapsule/*. e.g. echo userpath > ~/.sbgrid_capsule/xterm will set the SBGrid/BioGrids shells to always use the user's path.

  4. A localsite file in ${SB_BASE}/local/capsule/${SB_ARCH}/defaults/execname

EXAMPLES:

Which executable am I using?

 $  refine --sbwhich
 /programs/x86_64-linux/buster/20160324/autoBUSTER/bin/linux64/refine

What packages include this executable?

 $ refine --sbapp:l
    buster
    eman

refine is present in buster and eman. Where is the eman executable?

 $ refine --sbapp:a eman --sbwhich
/programs/x86_64-linux/eman/1.9/bin/refine

or

   $ env _REFINE=eman refine --sbwhich
  /programs/x86_64-linux/eman/1.9/bin/refine

I'd like set the eman refine as my default version

 $ echo eman > ~/.sbgrid_capsule/refine

Verify that is the case

 $ refine --sbwhich
/programs/x86_64-linux/eman/1.9/bin/refine

List all 'refine' executables and select ( and run ) the version from buster

 $ refine --sbapp:s
1) buster
2) eman
3) Cancel
Please select application 1
/programs/x86_64-linux/buster/20160324/autoBUSTER/bin/linux64/refine

List all applications that provide xterm, select userpath, make it my default

  $ xterm --sbwhich
 /programs/x86_64-linux/system/xterm/327/bin/xterm

  $ xterm --sbapp:l
      xterm
      /usr/bin/xterm

  $ env _XTERM=userpath xterm --sbwhich
 /usr/bin/xterm

  $ xterm --sbapp:s --sbwhich
  1) xterm
  2) userpath
  3) Cancel
  Please select application 2
  /usr/bin/xterm

  $ echo userpath > ~/.sbgrid_capsule/xterm

Please report any bugs to bugs@sbgrid.org