capsules.md
... ...
@@ -0,0 +1,133 @@
1
+# SBGrid software environment
2
+## Overview
3
+
4
+SBGrid is has a new software environment which is significantly faster than the older 'monolithic' shell environment.
5
+This environment includes added features for users to manage their software.
6
+Older features (such as version selection) are still present but improved.
7
+Old scripts should run unaltered and no new commands are required.
8
+
9
+## Getting started
10
+
11
+You can switch from the legacy SBGrid environment to the new with the *sbcap* command. *sbcap on* will enable the capsule environment.
12
+You can always return to the legacy configuration with the *sbcap off* command.
13
+
14
+The sbcap setting is persistent across shells - You don't need to do this for every shell.
15
+
16
+### sbcap - Example
17
+```
18
+user@linux ~
19
+ $ sbcap on
20
+```
21
+You will see a notice that you are using the new environment
22
+```
23
+ SBGrid: NEWS
24
+********************************************************************************
25
+ You are using SBGrid capsules.
26
+Capsules provide a simpler, faster, more powerful command line environment with
27
+the same software and commands as the previous SBGrid configuration.
28
+You should not need to change your existing workflow.
29
+
30
+If you experience any issues, please notify us at bugs@sbgrid.org.
31
+ For additional information visit https://sbgrid.org/wiki/capsules
32
+********************************************************************************
33
+ Software Support by SBGrid (www.sbgrid.org)
34
+********************************************************************************
35
+...
36
+```
37
+## Usage - Capsule Environment for SBGrid
38
+```
39
+Usage: sbgrid-exectable [ --sbwhich | --sbenv | --sbman | --sbapp:[adlshrH] | --sbcitation | --sbticket | --sbhelp ]
40
+
41
+ sbwhich display actual executable path
42
+ sbenv display the running environment for the capsule
43
+ sbman if it exists, display executable man page
44
+ sbapp:[adlshrH] display or select application when executable is in multiple sw titles
45
+ :a app run using app
46
+ :l list available apps
47
+ :s select app from menu
48
+ :h short help on apps
49
+ :r return codes help related to application selection
50
+ :H extended Help
51
+ sbcitation TO BE COMPLETED - if applicable, display citation information
52
+ sbticket TO BE COMPLETED - collect relevant inforamtion and submit a help request to help@sbgrid.org
53
+ sbhelp this message
54
+```
55
+
56
+### Overrides - managing versions :
57
+
58
+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.
59
+
60
+Setting the version - EXAMPLE
61
+
62
+For the refine executable, the default version show here is 20160324.
63
+
64
+```
65
+ bash-4.1$ refine --sbwhich
66
+ /programs/x86_64-linux/buster/20160324/autoBUSTER/bin/linux64/refine
67
+```
68
+
69
+We can change this by setting the variable BUSTER_X to 20151214 and calling sbwhich in one command :
70
+
71
+```
72
+ bash-4.1$ env BUSTER_X=20151214 refine --sbwhich
73
+ /programs/x86_64-linux/buster/20151214/autoBUSTER/bin/linux64/refine
74
+```
75
+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](overrides).
76
+
77
+### Managing Duplicate executables
78
+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.
79
+
80
+You can override the default in 4 ways. They are
81
+
82
+1. Command Line arguments selct the application for a single command :
83
+ **--sbapp:a <appname>** runs the executable from "appname" or
84
+ **--sbapp:s** select application from a list
85
+
86
+2. Environment variable of the form ```_<APPLICATION>```, an underscore followed by executable in UPPER CASE. e.g. ```_XIA2=dials``` will use xia2 executable from "dials".
87
+
88
+3. A User Config_file in *~/.sbgrid_capsule/<execname>*. e.g. echo dials > ~/.sbgrid_capsules/xia2 will uset the shell to always use the xia2 from "dials"
89
+
90
+4. A localsite file in */programs/local/capsule/${SB_ARCH}/defaults/execname*
91
+
92
+### EXAMPLES:
93
+Which executable am I using?
94
+
95
+ -bash-4.1 refine --sbwhich
96
+ /programs/x86_64-linux/buster/20160324/autoBUSTER/bin/linux64/refine
97
+
98
+What packages include this executable?
99
+
100
+ -bash-4.1$ refine --sbapp:l
101
+ buster
102
+ eman
103
+
104
+refine is present in buster and eman. Where is the eman executable?
105
+
106
+ -bash-4.1$ refine --sbapp:a eman --sbwhich
107
+ /programs/x86_64-linux/eman/1.9/bin/refine
108
+
109
+or
110
+```
111
+ -bash-4.1$ env _REFINE=eman refine --sbwhich
112
+ /programs/x86_64-linux/eman/1.9/bin/refine
113
+```
114
+I'd like set the eman refine as my default version
115
+
116
+ -bash-4.1$ echo eman > ~/.sbgrid_capsule/refine
117
+
118
+Verify that is the case
119
+
120
+ -bash-4.1$ refine --sbwhich
121
+ /programs/x86_64-linux/eman/1.9/bin/refine
122
+
123
+List all 'refine' executables and select ( and run ) the version from buster
124
+
125
+ -bash-4.1$ refine --sbapp:s
126
+ 1) buster
127
+ 2) eman
128
+ 3) Cancel
129
+ Please select application 1
130
+ /programs/x86_64-linux/buster/20160324/autoBUSTER/bin/linux64/refine
131
+
132
+
133
+Please report any bugs to bugs@sbgrid.org