BIRCH
BIRCH - Configuration

Create $BIRCH/local

If this is a FIRST TIME installation of BIRCH, you need to create a $BIRCH/local directory by renaming the $BIRCH/local-generic directory. If you were updating an existing BIRCH system, this step would overwrite all your local settings.

mv local-generic local

Set $BIRCH variable 

cd local/admin
 ls -l

total 26
-rw-r--r--   1 psgendb  psgendb      437 Feb  5 13:00 Login_Message
-rw-r--r--   1 psgendb  psgendb       14 Dec 29 21:02 birchdir.param
-rw-rw-rw-   1 psgendb  psgendb        0 Dec 13 12:46 gde.log
-rw-r--r--   1 psgendb  psgendb     1565 Feb  5 12:34 local.cshrc.source
-rw-r--r--   1 psgendb  psgendb      332 Feb  5 12:35 local.login.source
-rw-r--r--   1 psgendb  psgendb      383 Feb  5 12:54 local.profile.login.source
-rw-r--r--   1 psgendb  psgendb     1543 Feb  5 12:56 local.profile.source
-rw-rw-rw-   1 psgendb  psgendb        0 Dec 13 12:47 logins.log
-rw-r--r--   1 psgendb  psgendb      146 Jan  4 21:39 newstr.param
-rw-r--r--   1 psgendb  psgendb     1560 Feb  3 21:29 platform.profile.source
-rw-r--r--   1 psgendb  psgendb     1690 Feb  5 12:31 platform.source


Just about everything in BIRCH depends on the $BIRCH environment variable, which lists the location of the BIRCH home directory. This is set in $BIRCH/local/admin/birchdir.param. This file contains a single line:

/home/psgendb

Change this line to the location of the BIRCH home directory, for example

/home/birch

birchdir.param will be read by the script birchhome.csh.

cd ../../install-birch
ls -l
-rw-r--r--   1 psgendb  psgendb      983 Jan  3 15:43 UNINSTALL-birch.csh
-rwxr--r--   1 psgendb  psgendb     1066 Jan 29 13:09 birchhome.csh*
-rw-r--r--   1 psgendb  psgendb     3690 Jan  6 18:02 customdoc.py
-rw-r--r--   1 psgendb  psgendb       58 Jan  2 14:27 htmldir.param
-rw-r--r--   1 psgendb  psgendb     1044 Dec 26 20:17 installation.readme
lrwxrwxrwx   1 psgendb  psgendb       27 Jan  2 22:56 newstr.param -> ../local/admin/newstr.param
-rw-r--r--   1 psgendb  psgendb      183 Jan  3 16:48 oldstr.param



./birchhome.csh

birchhome.csh will change /home/psgendb to the directory contained in birchdir.param, in the following files, found in $BIRCH/local/admin:
cshrc.source
add_to_cshrc
add_to_login
add_to_profile
newuser

As well, birchhome.csh will also perform the same changes on configuration files for some BIRCH programs, which may change from release to release.

Change defaults in $BIRCH/local/admin

Move back to the local/admin directory eg.

cd ../local/admin


Platform-specific settings
In platform.source, set the value of $BIRCH_PLATFORM by commenting out the appropriate line.  For example, on a Solaris system:

# Uncomment a line if you only use a single platform
#setenv BIRCH_PLATFORM linux-intel
setenv BIRCH_PLATFORM solaris-sparc

Alternatively, comment out the code that sets $BIRCH_PLATFORM according to the name of the host to which the user is logged in.

Similarly, in platform.profile.source, uncomment the equivalent line for users of Bourne family shells eg.

BIRCH_PLATFORM=solaris-sparc

Programs to be called by GDE
Next, you may wish to edit the files local.cshrc.source and local.profile.source. These files contain lines that let you choose which text editor, bitmap image viewer and terminal programs should be called by GDE. These are set, respectively, in the environment variables $GDE_TEXTEDIT, $GDE_TERMINAL and $GDE_BITMAP_VIEWER. cshrc.source and profile.source contain "failsafe" settings for these variables, which are likely to be found on your system, but may not be the best programs of their type. local.cshrc.source and local.profile.source have many alternative choices for these variables. Simply uncomment the one you want for each.

local.login.source and local.profile.login.source
These files specifiy commands to be executed each time the user logs in. The main path for BIRCH binaries is already set in $BIRCH/admin/login.source and $BIRCH/admin/profile.login.source, but if you want to also have locally-installed programs in the user's path, uncomment the appropriate line in local.login.source for C-shell users, and local.profile.login.source for Bourne shell users.

Login_Message
The file 'Login_Message' is printed in each terminal window opened by a user. You should probably edit the Login_Message to reflect your own system.

Change URLs in local copies of documentation 

The BIRCH web pages are organized as illustrated below:
website_schema.gif  

The main URL is the address that users will use to get to the BIRCH web site. At the Univ. of Manitoba, this URL points to the public_html directory for user 'psgendb' .  public_html contains all of the BIRCH documentation and tutorials, with the exception of documentation files for programs, which are found in $BIRCH/doc. Depending on how your web server is configured, it may be possible to just create symbolic links from public_html, so that web pages within public_html could use relative HTML links to get to get to these documents. However, for security reasons, some sites do not permit symbolic links  in personal web sites, but they are permitted on the campus webserver. As a workaround, fully qualified HTML links can be made to a URL for the web server, which points to a symbolic link from the University web server to /home/psgendb/BIRCHDEV. Therefore, this URL allows read access to any file in the BIRCH hierarchy.

When BIRCH is installed on a new system, it is necessary to change all URLs to the local URLs for the main BIRCH web site and the web server web site. At the same time, other strings in the HTML files need to be customized for the local system. This process is automated using the customdoc.py script.

Read the manual page for customdoc.py. Once you understand how this works, you can modify and oldstr.param to correspond to you local system. oldstr.param and htmdir.param should probably not need to be changed.

Now, you're ready to update the HTML files. In the install-birch directory, type

python customdoc.py oldstr.param newstr.param htmldir.param

The script will echo the names of directories visited, and lines changed to the terminal window.
You can use customdoc.py for future automated changes to web pages by creating your own .param files.

Run the newuser script

Set up the BIRCH Administrator's account as described in   Setting up your account.

For the changes to take effect, you need to logout and login again. These steps might either be done on the BIRCH administrator's account, or on a separate user account. THIS STEP MUST BE COMPLETED BEFORE YOU CAN CONTINUE!

Create .GDEmenus files

The .GDEmenus file tells GDE which programs to include in its menus. This file needs to be generated by the Python script makemenus.py before you run GDE. makemenus.py will create separate .GDEmenus files for each platform supported by BIRCH (currently, Solaris-Sparc and Linux-Intel).

cd $dat/GDE/makemenus
python makemenus.py

Install the FASTA packages

The COPYRIGHT agreement for the FASTA programs does not currently permit the programs to be distributed by a 3rd party. BIRCH has scripts that completely automate the process of downloading, compiling, and installing all programs and documentation in the most recent version of FASTA.

cd install-birch/fasta
./fasta2install.csh
./mrtransinstall.csh
./fasta3install.csh
That's all there is to it! These scripts automatically download the shar archives from ftp.virginia.edu/pub/fasta, run the appropriate makefile, set global read and execute permissions, and copy the programs into the appropriate directories.

Notes:
  1. These scripts expect that the environment variables $BIRCH, $BIRCH_PLATFORM and $BIRCH_BIN are set, which is why you needed to logout and log back in in the previous step.
  2. This will take awhile because of the time required for compilation. Go get lunch or something.
  3. Each script creates a working directory ie. fasta2, mrtrans and fasta3. All files, including source code, object files, documentation etc. will remain after the script has been terminated. If something went wrong with the compilation, the original files are still available for manual compilation. Otherwise, these directories can be deleted after all programs are installed.
  4. The file $doc/fasta/FASTA_LIST gives instructions for getting onto a mailing list if you wish to be informed of new FASTA releases. Running these scripts at any time, without modification should automatically update to the current version.

Test the installation

At this point, you are ready to test the installation.

The best test to show that the programs are running on your system is to run some of the tutorials found on the BIRCH Tutorials page. Obviously, database searches won't work until you have installed a local copy of a database. Currently, the GenBank, GenPept and PIR databases are supported. Since PIR is a lot smaller than GenBank, it makes sense to install that first, and try the "Database similarity search" tutorial.

WARNING: The current release is not fully functional under Linux. On Linux systems, only the following tutorials are likely to work:
  • Working with sequences
  • Dot-matrix similarity searches
  • Pairwise similarity searches
  • Retrieving sequences by keywork (if GenBank or PIR is installed)
  • Database similarity searches (if GenBank or PIR is installed)
  • Creating datasets of related sequences (if GenBank or PIR is installed)
  • Multiple sequence alignments (except for PIMA)

Customize local documentation files

The following files in $BIRCH/public_html need to be edited to tailor them to your local system. They are kept in $BIRCH/local/admin to prevent them being overwritten when BIRCH is updated.


findinfo/findinfo.html
remote/remote.html
setup/setup.html

Finally, the current implementation of BIRCH requires the BIRCH home page to be $BIRCH/public_html/index.html, which would get overwritten with each update. Eventually we'll come up with better way of doing this, but for now, you have to remember to back this file up if you do an update.

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