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/sequin, which adds several libraries to $LD_LIBRARY_PATH and launches the sequin binary. This way, LD_LIBRARY_PATH changes only in the shell running sequin, and not in any other shell.

A good practice is to always create a new subdirectory within lib-xxx-xxx for each program that needs supplemental libraries. This keeps all libraries for a program together, and makes it more straightforward when updating libraries or removing a program at a later time.

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.

  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/

1.4 Adding programs to bioLegato

A point of emphasis: bioLegato 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 bioLegato. 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 bioLegato window! You really have to use bioLegato for awhile to appreciate how powerful this capability is.

There can be an arbitrary number of bioLegato instances. The following table summarizes the relevant files and directories for each instance, as of this writing:

bioLegato instance
menu directories
birch - launcher for BIRCH programs
bldna - DNA sequence analysis
$birch/script/bldna $birch/dat/bldna
blprotein - protein sequence analysis
$birch/script/blprotein $birch/dat/blprotein
blmarker - molecular markers
$birch/script/blmarker $birch/dat/blmarker
bltree - phylogenetic trees
$birch/script/bltree $birch/dat/bltree

We will use bl_instance to represent any instance of bioLegato. Each instance (eg. bldna, blprotein, blmarker, bltree and birch) has its own directory in $birch/dat and in $birch/local/dat. For example, when bldna starts, it reads .item files from the subirectories found in $birch/local/dat/bldna, and creates menus based on menu items in those files.  The menu items merged from both the BIRCH core and local biolegato menu items. The following steps describe how to get a program that has been locally-installed to be merged into a biolegato instance.

Creating a menu item is a cyclic process (shown for bldna):

write a first draft of the .item file and place it into the appropriate subdirectory within local/dat/bldna/menus
add the name of your item to local/dat/bldna/menulist

launch a new bioLegato 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 bioLegato 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 menu item contains a command to be executed to run a program, and parameters that are substituted into that command.


#--------------- 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


arglabel:NUMBERING INTERVAL (amino acids/codons)


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 bioLegato 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:


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


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 biolegato item to display the help file found in:


Add the following lines to the .item file:


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


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/bl_instance/menus. As well, when you first install BIRCH, the directory


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


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

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

1.4.2 Adding your menu item to the menulist file

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


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


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 of bldna, it would be saved as


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:


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
menulist. Do not go any further before you read this page!

1.4.3 Merging your menu item into the .GDEmenus file

Your local menus items will be merged  with the core menus when a biolegato instance launches.
For example, if the paracelBLASTN command was only available on Solaris hosts, your menulist file would look like this:

    paracelBLASTN   S

Again, you have to read the menulist 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 bioLegato window after running This is because the menus in bioLegato are read from .GDEmenus only when the program first starts. One trick for doing many test and refine cycles is to run, and then, in your bioLegato window, choose Edit --> Select All, and then Edit --> Extract. This will take the contents of the current bioLegato window and launch a new bioLegato window, which will have the updated menus. That saves having to launch bioLegato 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