coot.md
... ...
@@ -0,0 +1,171 @@
1
+# Setting COOT title and version in SBGrid
2
+COOT is present in several titles and many versions in SBGrid. Selecting the application and version of the `coot` executable can be accomplished on-the-fly in a single step in the SBGrid capsule environment. Here are some examples of managing COOT in SBGrid capsules, but this should work for any application with duplicate executables and multiple versions.
3
+
4
+To confirm that capsules are enabled, run
5
+
6
+```
7
+sbcap status
8
+```
9
+
10
+If capsules are enabled, the output should be :
11
+
12
+```
13
+ $ sbcap status
14
+Active
15
+```
16
+
17
+If capsules are InActive, they can be enable with the `sbcap on` command followed by `source /programs/sbgrid.shrc`.
18
+
19
+
20
+### "Which COOT am I using?"
21
+The `sbwhich` command will show which `coot` executable is in use :
22
+
23
+```
24
+$ sbwhich coot
25
+/programs/x86_64-linux/ccp4/7.1/ccp4-7.1/bin/coot
26
+```
27
+
28
+or alternatively the `--sbwhich` flag can be used
29
+
30
+```
31
+$ coot --sbwhich
32
+/programs/x86_64-linux/ccp4/7.1/ccp4-7.1/bin/coot
33
+```
34
+
35
+By default we use the CCP4 release of COOT in SBGrid. This version is stable, supported and the same for MacOS and Linux. But it is easy to change.
36
+
37
+### Next, what titles provide "coot" executables?
38
+SBGrid capsules provide an additional set of flags for all executables, prefixed with `--sbapp:`. For more info see the [documentation for capsules here.](capsules.md) To list all the installed tiles that provide `coot`, use `--sbapp:l`
39
+
40
+```
41
+$ coot --sbapp:l
42
+ ccp4
43
+ ccpem
44
+ coot
45
+```
46
+
47
+The executable `coot` is present in the titles **ccp4, ccpem, and coot**.
48
+
49
+### What version does this coot executable come from?
50
+Running *sbgrid-info -l* will print the available versions for a title.
51
+
52
+```
53
+ $ sbgrid-info -l ccp4
54
+ Version information for: /programs/x86_64-linux/ccp4
55
+
56
+Default version: 7.1
57
+In-use version: 7.1
58
+
59
+Installed versions: 7.1 7.1.006 7.0 7.0.078 6.3.0
60
+Other available versions: 7.1.006 7.0 7.0.078 6.3.0
61
+Overrides use this shell variable: CCP4_X
62
+```
63
+
64
+We are running `coot` from ccp4 version 7.1 and there are several other versions available.
65
+
66
+### Changing the application that provides coot - overriding default titles
67
+SBGrid uses CCP4's `coot` by default, but that can be changed with an environmental variable. A default title can be specified for any duplicate executable with the `<_EXECUTABLE>` variable where `<EXECUTABLE>` is the **all-capital** name of the executable.
68
+For example, since `coot` comes from CCP4 by default, we can change it to CCPEM by setting :
69
+
70
+ export _COOT=coot
71
+
72
+for bash, or
73
+
74
+ setenv _COOT coot
75
+
76
+for tcsh users.
77
+
78
+`_COOT` is the executable name, `coot` is the name of the title that will provide the program when we run `coot`.
79
+
80
+If we do this, we can see (in bash)
81
+
82
+```
83
+$ export _COOT=coot
84
+$ coot --sbwhich
85
+/programs/x86_64-linux/coot/0.9.1/bin/coot
86
+```
87
+
88
+Now `coot` comes from the applciation title **coot**. The default version there is 0.9.1.
89
+
90
+Let's switch to CCPEM as the provider of the `coot` program.
91
+To do that we just set the variable:
92
+```
93
+$ export _COOT=ccpem
94
+
95
+$ coot --sbwhich
96
+/programs/x86_64-linux/ccpem/1.4.1/bin/coot
97
+
98
+ $ coot --version
99
+0.9-pre (revision-count 0)
100
+[with guile 1.8.8 embedded]
101
+[with python 2.7.15 embedded]
102
+Builder_info: CCP-EM, Oxfordshire, UK
103
+Binary type: Linux-x86_64-scientific-linux-6.10-python-gtk2
104
+```
105
+
106
+### Setting the version
107
+The version of a title is set by the `<TITLE_X>` variable where `<TITLE>` is the title of an application in uppercase. You can see this variable in the `sbgrid-info -l` output.
108
+
109
+```
110
+ $ sbgrid-info -l ccpem
111
+ Version information for: /programs/x86_64-linux/ccpem
112
+
113
+Default version: 1.4.1
114
+In-use version: 1.4.1
115
+
116
+Installed versions: 1.4.1 1.4.0 1.3.0 20200722
117
+Other available versions: 1.4.0 1.3.0 20200722
118
+Overrides use this shell variable: CCPEM_X
119
+```
120
+
121
+To use coot from CCPEM version 1.3.0, we set the CCPEM_X variable to 1.3.0
122
+
123
+```
124
+ $ export CCPEM_X=1.3.0
125
+
126
+ $ sbwhich coot
127
+/programs/x86_64-linux/ccpem/1.3.0/bin/coot
128
+```
129
+
130
+`coot` has a --version flag that can be used to confirm the version
131
+Set the title for the `coot` executable to "coot" to use Paul Emsley's builds for linux :
132
+
133
+```
134
+ $ export _COOT=coot
135
+
136
+ $ coot --version
137
+0.9.1 (revision-count 10157)
138
+[with guile 1.8.8 embedded]
139
+[with python 2.7.15 embedded]
140
+Builder_info: built by: Paul Emsley build-host: charybdis on: Wed 21 Oct 0247.16 BST 2020
141
+Binary type: Linux-x86_64-scientific-linux-7.6-python-gtk2
142
+```
143
+
144
+This is the latest version. To switch to an older version, just set the COOT_X variable to that version:
145
+
146
+```
147
+ $ export COOT_X=0.8.8
148
+
149
+ $ coot --version
150
+0.8.8 (revision-count 6690)
151
+[with guile 1.8.8 embedded]
152
+```
153
+
154
+Now, let's change `coot` to come from CCP4 and check the version :
155
+
156
+```
157
+ $ export _COOT=ccp4
158
+
159
+ $ coot --version
160
+0.9 (revision-count 9932)
161
+[with guile 1.8.8 embedded]
162
+[with python 2.7.16 embedded]
163
+Builder_info: CCP4, Oxfordshire
164
+Binary type: Linux-x86_64-scientific-linux-6.10-python-gtk2
165
+```
166
+
167
+The version of `coot` changes to the version provided by the CCP4 version specified by CCP4_X.
168
+
169
+For more info, see [capsules](capsules.md), and [version manangement](overrides.md).
170
+
171
+For questions or to report bugs, please email bugs@sbgrid.org
... ...
\ No newline at end of file