_Sidebar.md
... ...
@@ -34,6 +34,7 @@ Getting Help
34 34
- [Software Help and Requests](help)
35 35
- [Software Usage Examples](examples)
36 36
- [Remote Graphics Troublshooting](remote_graphics)
37
+- [Integrating SBGrid Applications with non-SBGrid ones](examples/non_sbgrid_apps)
37 38
38 39
Support for Developers
39 40
examples/non_sbgrid_apps.md
... ...
@@ -0,0 +1,30 @@
1
+## Calling SBGrid Programs from other Applications
2
+
3
+In most cases, it is relatively straightforward to use SBGrid Programs from non-SBGrid applications.
4
+Using [topaz](https://sbgrid.org/software/titles/topaz),[(developer's link)](https://github.com/tbepler/topaz) as an example, create an adapter/wrapper script:
5
+
6
+```
7
+
8
+#!/usr/bin/env bash
9
+
10
+# activate the environment, so that it doesn't need to be always enabled under the user account running the non-SBGrid program.
11
+source /programs/sbgrid/shrc.
12
+
13
+# Optionally, specify the SBGrid version of the title.
14
+# Explict version configuration can help troubleshooting integration issues.
15
+export TOPAZ_X=0.2.5a_cu11.3_py36
16
+
17
+# call the executable with original arguments
18
+topaz "$@"
19
+
20
+```
21
+
22
+make this script executable (for example, `chmod +x topaz_adapter.bash`, place it somewhere readable to (and exectuable by) the external program, and use the full path to the script (for example, `/programs/local/adapter_scripts/topaz_adapter.bash`) in configuring the non-SBGrid program.
23
+
24
+### Common Problems/Sub-optimal Approaches
25
+ 1. Using the output of `which topaz` (`/programs/x86_64-linux/system/sbgrid_bin/topaz`); this requires the SBgrid environment to be persistently active in the environment/user account of the other program, and makes it ambigious which version is being used.
26
+ 1. Using the output of `sbwhich topaz` (`/programs/x86_64-linux/topaz/0.2.5a_cu11.3_py36/topaz_extlib/envs/topaz-py3.6/bin/topaz`); this may work, but will miss [capsule](https://sbgrid.org/wiki/capsules` initialization, which may cause avoidable job failures.
27
+
28
+### Less Common Problems
29
+ 1. The above approach will work for executable calls. It will *not usually work* for cases where the other program is using the executable path to find library paths to import into a non-SBGrid interpreter or process memory space. If you encounter a case like this (or encounter other problems), please feel free to contact us at `bugs@sbgrid.org`.
30
+