BIRCH Administration - Frequently Asked Questions

BIRCH Administration
Frequently-asked Questions

Update March 13, 2026

Send your own questions to frist@cc.umanitoba.ca

About BIRCH

What exactly is BIRCH?
Which hardware/software platforms does BIRCH run on?
Why don't you have a Windows version of BIRCH?
What about software licensing?

Installation and Updating

I can run programs from my BIRCH administrator's account, but not from any other account
After I ran 'newuser', my prompt changed. I like my prompt. How can I stop BIRCH from changing it?

Adding 3rd party programs or documentation to my BIRCH site

Troubleshooting

Lots of things don't work. I keep seeing 'NoClassDefFoundError' messages
bioLegato works, but for many of the programs that I try to launch (eg. NUMSEQ, fasta, NCBI BLAST) I get bash: numseq : command not found

Design considerations

Why is customdoc.py needed? Couldn't you use server-side includes to accomplish the same thing?
Why isn't BIRCH development done on GitHub?
Why isn't BIRCH distributed using my favorite package manager?

About BIRCH

What exactly is BIRCH? - BIRCH is a powerful framework for organizing and using bioinformatics programs. BIRCH comes with hundreds of commonly-used tools, and allows you to customize your BIRCH site by adding new ones. BioLegato is a graphic user interface that runs workflows that make it easy for BIRCH programs to work together seamlessly.

Which hardware/software platforms does BIRCH run on?

OS	Hardware	BIRCH nomenclature	Comments
Linux (64-bit)	64-bit Intel, or AMD	linux-x86_64	Main platform for development. Thoroughly tested.
	64-bit ARM	linux-arm64	in progress; many binaries won't work until we can get a Rosetta equivalent for linux-arm64
MacOSX	64-bit Intel or AMD	osx-x86_64	No longer supported, but existing applications still run Apple has switched to the ARM architecture and no longer sells x86_64 machines.
	64-bit ARM	macos-arm64 (Apple Silicon, M1, M2 etc.)	fully functional since BIRCH 3.90

Why don't you have a Windows version of BIRCH? - How much time do you have?

The design of BIRCH takes advantage of many of the design elements of Unix/Linux systems. Adaptation of BIRCH from Linux to MacOS was comparatively easy, since MacOS is actually a BSD Unix. Linux was from the outset a multi-user system, whereas historically, Windows has taken decades to fully embrace disciplined multiuser protocols.
Adaptation to Windows should in principle be easier now that Windows has WSL, but there there are still a lot of fundamental differences, in particular, the way file paths are structured in windows eg. '\' vs '/', which may take a lot of rewriting in potentially hundreds of scripts.
Windows is annoying - This is not insignificant. Increasingly, Windows is an advertising platform that secondarily condescends to let you do your work. Do we really need advertising in a File Explorer?
AI - Microsoft is taking a slapdash approach to integrating AI into every application, not to mention the fact that much of BIRCH is 3rd party programs that we have no control over. Adopting that strategy in BIRCH would create enormous software bloat, leading do a loss of reliability. Also, do you really want Microsoft assimilating your unpublished research data?

What about software licensing? BIRCH only incorporates open-source software that may be freely-shared and used. BIRCH itself is licensed under a Creative Commons license.

Installation and Updating

I can run programs from my BIRCH administrator's account, but not from any other account - Remember, each user must run the newuser script to set up their accounts to use BIRCH. See the First Time Setup page in the 'NEW USERS' box on the BIRCH web site.
After I ran 'newuser', my prompt changed. I like my prompt. How can I stop BIRCH from changing it? Any user can choose whether or not they want the default BIRCH prompt in their terminal windows. Open the BIRCH application (type "birch" at the command line) and choose Edit --> Settings. Click on Yes or No at "Use BIRCH Custom command line prompt?", and then click Save. Or, open $HOME/.config/BIRCH/BIRCHsettings.source in a text editor and set BIRCH_PROMPT to Y or N.

Adding 3rd party programs or documentation to my BIRCH site

Troubleshooting

Lots of things don't work. I keep seeing 'NoClassDefFoundError' messages - It is likely that Java is not set up correctly on your system. See inst.java.html.

bioLegato works, but for many of the programs that I try to launch (eg. NUMSEQ, fasta, NCBI BLAST) I get bash: numseq : command not found - This is almost certainly because the wrong platform was set when BIRCH was installed. Java programs such as bioLegato work because they run through the Java interpreter. Compiled programs won't work if BIRCH is looking in the wrong directory for binaries. For example, if you had installed the 64-bit Linux binaries (linux-x86_64) but chosen "linux-arm64" as the platform when you first ran birchconfig. If that is true, "echo $BIRCH_PLATFORM" would print "linux-arm64".

The following steps will fix this problem:

1. In $BIRCH/local/admin/BIRCH.properties, change BirchProps.platform to the correct platform eg. linux-x86_64.
2. In $BIRCH/local/admin/platform.profile.source, comment out the line that says 'BIRCH_PLATFORM=linux-arm64' and uncomment the line that says 'BIRCH_PLATFORM=linux_x86_64'.
3. In $BIRCH/local/admin/platform.source, comment out the line that says 'setenv BIRCH_PLATFORM linux-arm64' and uncomment the line that says 'setenv BIRCH_PLATFORM linux_x86_64'.

Design Considerations

Why is customdoc.py needed? Couldn't you use server-side includes to accomplish the same thing? - The short answer is that at the Univ. of Manitoba, personal web pages are not permitted to utilize .htaccess files, which are necessary for SSI. If it's not allowed here, chances are it won't be allowed at other places.

Why isn't BIRCH development done on GitHub? We have considered this option, but concluded that Git was not the appropriate platform for BIRCH development. Git was designed for projects that can be self-contained, standalone modules. BIRCH is more like an operating system, consisting of tens of thousands of files, and applications from many 3rd party sources. Some of those 3rd party programs are in fact maintained on Git. Git also demands that all users follow a disciplined pull-modify-commit and push protocol, which can cause more harm than good in the hands of developers who don't "get" Git. Also, the BIRCH install wizard is designed to be user friendly for biologists who cannot be expected to grasp the intricacies of Git. As well, the automated installer modifies local files, and has safeguards to prevent local settings from being overridden during an update.

Why isn't BIRCH distributed using my favorite package manager? First, there are so many of them: RPM, DEB, SNAP, FLATPAK, Anaconda, Docker, Apple AppStore ... All of these solutions require technical knowledge on the part of the end user, and a lot of work on the part of the developer. The BIRCH install wizard allows the user to install and update BIRCH in a few clicks.

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