BIRCH
BIRCH - Adding binaries, scripts and libraries

1.1 Binaries and scripts

Programs are added to the appropriate directory as follows:
 BIRCH automatically includes the bin and script directories (but not java) in the $PATH. Once you add a binary or a script, it can be run by all users.

Note: remember to make your scripts and binaries world-readable and world-executable.

1.2 Setting environment variables and $PATH

Many programs require one or more environment variables. These need to be set both for shells in the BOURNE shell family and C-shell family. That is, you can't predict which shell users might be using, so you need to set these variables for both shell families. These should be set in the following files:
 For many of the popular viewers, editors and browsers, environment variables are already available in these files, commented out. All you need to do is to uncomment the appropriate variable and it will override the BIRCH default.

See Choosing default applications for viewing and displaying data for more details.

1.3 Libraries

For each platform, library directories are provided for locally-added programs:
 The recommended method for getting programs to find these library directories is to launch the program from a wrapper script that sets the environment variable $LD_LIBRARY_PATH. A good example can be found in $BIRCH/script/gde, which adds 'openwin/lib' to $LD_LIBRARY_PATH and launches the GDE binary. This way, LD_LIBRARY_PATH changes only in the shell running GDE, and not in any other shell.

In earlier versions of BIRCH, $LD_LIBRARY_PATH was set in cshrc.source and profile.source, and included all possible libraries that might be needed, along with system libraries. The danger of using this approach is that LD_LIBRARY_PATH replaces, rather than adding to, the library search path. Therefore, if you don't correctly guess all of the possible library paths on your system, you risk breaking other programs. A more in-depth discussion of this point is found at Shared Library Search Paths by Russ Allbery.

Notes:
  1. Another alternative, if you have root permissions, is to add library files to /usr/local/lib. On Linux systems, you can find out whether this directory is in the library search path by checking the file /etc/ld.so.conf.

1.4 Adding programs to GDE

A point of emphasis: GDE is a program that runs other programs. Put another way, just about any program on the system, any program at all, can be launched from GDE. You can launch a script or a binary. The script could launch other scripts or binaries. If your output is in the form of a table, you could launch a spreadsheet. If the output is sequence, you can launch another GDE window! You really have to use GDE for awhile to appreciate how powerful this capability is.

When GDE starts, it reads a .GDEmenus file, and creates menus based on menu items in that file. In BIRCH, there are separate .GDEmenus files for each platform (eg. solaris-sparc). The .GDEmenus files contain menu items merged from both the BIRCH core and local GDE menu items. The following steps describe how to get a program that has been locally-installed to be merged into the .GDEmenus files.

Creating a menu item is a cyclic process:

write a first draft of the menu
add the name of your item to local/dat/GDE/makemenus/menulist
repeat
merge the item into .GDEmenus using makemenus.py
launch a new GDE window and test the menu item
if not satisfactory
refine the menu item based on the test
until menu item is satisfactory

1.4.1 Creating a menu item

Before you start - You really need to have a good idea of how to run your program at the command line before you try to make a GDE menu item to run it. Read the manual pages or other documentation. Try it out. It will save you a lot of time and frustration.

A GDE menu item contains a command to be executed to run a program, and parameters that are substituted into that command.

Example: 

#--------------- PROT2NUC - Reverse Translation ( 4/10/06) -----------------
item:PROT2NUC - reverse translation
itemmethod: sed "s/[#%]/>/" <in1 | prot2nuc -l$LINLEN -g$GROUP > in1.out; ($GDE_TEXTEDIT in1.out; rm in1*)&
itemhelp: doc/xylem/prot2nuc.txt
itemopen:gde_help_viewer.csh

arg:LINLEN
arglabel:CODONS PER LINE
argtype:slider
argmin:5
argmax:100
argvalue:25

arg:GROUP
arglabel:NUMBERING INTERVAL (amino acids/codons)
argtype:slider
argmin:5
argmax:100
argvalue:5

in:in1
informat:flat
insave:

The itemmethod is the command that is executed to run the program. In this case, the sed command is used to translate the GDE flat file format into FASTA format. The output from the sed command is piped directly to the prot2nuc program, using parameters LINLEN and GROUP substituted into the command line. Output is redirected to the file in1.out, which is launched using the text editor specified in the $GDE_TEXTEDIT environment variable.

For a more complete description of how to write GDE menu items, you really have to read Appendix B - Adding Functions in the GDE Manual.

Note on GDE HELP

The example above shows the syntax for specifying a help file to be opened in when the HELP button is pressed in a GDE item menu. The general formula is:

itemhelp:filename
itemopen:program

where filename is the file to open (path is relative to the GDE_HELP_DIR directory) and program is the program to open the file. filename can also be a URL. program is usually gde_help_viewer.csh, which chooses the viewer based on the file extension.

There is one exception. Where a URL points to a named anchor in an HTML document
(ie. a URL containing a '#' character) use

itemopen:browser.csh

gde_help_viewer.csh will not properly handle these types of URLs, so browser.csh can
be called to force the file to be read in the BIRCH default browser.

All help files must be accessed through the $GDE_HELP_DIR. If you need to specify a path to files that are not part of the main BIRCH distribution, you can use the 'root' link,
which resides in all GDE help directories. This points to the root of the directory tree, '/'.
So, for example, to get your GDE item to display the help file found in:

/export/data/programs/emboss/share/EMBOSS/doc/programs/html/prettyplot.html

Add the following lines to the .item file:

itemhelp:root/export/data/programs/emboss/share/EMBOSS/doc/programs/html/prettyplot.html
itemopen:gde_help_viewer.csh

To point to files in your $BIRCH/local directory, the GDE help directories also have a symbolic link called 'local' eg.

itemhelp:local/doc/filename


Some of the subtleties for writing good GDE menu items are further discussed in GDEmenus Hints and Tips.

There are lots and lots of example of menu items in $BIRCH/dat/GDE/makemenus/menus. As well, when you first install BIRCH, the directory

$BIRCH/local/dat/GDE/makemenus/menus

will have some  menu item files that you could edit to fit your system. For example, there are a set of FASTA and BLAST menu item files that you can edit to use your local copies of sequence databases. These will override the generic  FASTA and BLAST menus that are part of the BIRCH core.

If  you update your BIRCH system to a new release you may wish to check the

$BIRCH/local-generic/dat/GDE/makemenus/menus

directory for new GDE menu item files that might be modified to work on your site.

Note: None of the GDE menu item files will appear in the GDE menus until you add their names to the menulist file, as described below.

1.4.2 Adding your menu item to the menulist file

Your GDE menu item file must have a file name of the form

name.item

where name is the name of the menu item. It should be saved in

$BIRCH/local/dat/GDE/makemenus/menus/directory

where directory is the name of the menu where you would like your item to appear. For example, if I wanted to add a menuitem named paracelBLASTN.item to the Database menu, it would be saved as

$BIRCH/local/dat/GDE/makemenus/menus/Database/paracelBLASTN.item

However, this .item file will be ignored unless we also add the name of the file to the makemenus/menus/menulist file. In this example, we need to have an entry added to the file that looks like this:

Database
    paracelBLASTN

Note: the indentation is done by a single TAB character, NOT using spaces. The syntax for creating a menulist file is more fully explained in the manual page for makemenus.py. Do not go any further before you read this page!

1.4.3 Merging your menu item into the .GDEmenus file

Finally, to get your menu item to appear in the GDE window, you need to run makemenus.py. This is always done from the $BIRCH/dat/GDE/ directory. Just cd to that directory and type 'python makemenus.py'. Your local menus items will be merged  with the GDE core menus, to create single .GDEmenus files in the GDEHELP directories. As described in the makemenus.py  manual page, separate .GDEmenus files are made for each platform. For example, if the paracelBLASTN command was only available on Solaris hosts, your menulist file would look like this:

Database
    paracelBLASTN   S

Again, you have to read the makemenus.py  manual page for full details.

1.4.4 Testing and refining your menu item

For the new menu to appear, you have to launch a new GDE window after running makemenus.py. This is because the menus in GDE are read from .GDEmenus only when the program first starts. One trick for doing many test and refine cycles is to run makemenus.py, and then, in your GDE window, choose Edit --> Select All, and then Edit --> Extract. This will take the contents of the current GDE window and launch a new GDE window, which will have the updated menus. That saves having to launch GDE at the command line and re-read the data each time you run the program.

The debugging process can be a difficult one . One of the most useful tricks for debugging is to insert commands into the itemmethod: commands that open up intermediate files in a text editor. That way, you can see whether any given step was successful. For example, 

itemmethod: sed "s/[#%]/>/" <in1 >in1.test; $GDE_TEXTEDIT in1.test; cat in1.test | prot2nuc -l$LINLEN -g$GROUP > in1.out; ($GDE_TEXTEDIT in1.out; rm in1*)&
will let you verify that the sed command worked corrrectly before prot2nuc is run.

Leverage the multiwindow environment

For this kind of work, you can make things a lot easier by having different windows for different steps. For the test and refine process you might have the following windows on your screen:
 Using this strategy, moving back and forth between directories does not have to be done using 'cd'. Rather, you move between directories by moving from one window to the other.


Please send suggestions of comments regarding this page to psgendb@cc.umanitoba.ca