capsules.md
... ...
@@ -1,133 +1,9 @@
1
-# SBGrid software environment
1
+# BioGrids software environment
2 2
## Overview
3 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.
4
+BioGrids includes a software environment called the capsule environment.
5
+This software programmatically creates custom environments for every BioGrids application at the time of execution.
8 6
9
-## Getting started
7
+Configurations, paths, dependencies and other items needed by the application are created and or set at execution time. The application is then run in this environment. When the application exits the environment is cleaned up and removed.
10 8
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
9
+The Capsule Environment approach enables a much faster execution environment for users with minimal interference to the users own default shell environment.