WIKI
The page you are currently using acts as a virtual whiteboard where all users can submit comments and solutions for the development of BRAINS. This should not be a place for reporting bugs or new feature requests. Those should still go to the bug tracking software (which is now hosted on the NITRC web site) where you should be able to log in, go to the BRAINS project, and report your software troubles using the mechanisms presented there.
IPL Home Page
BRAINS Registration
BRAINS is distributed free of charge, but we request that you provide some minimal information so that we may better support the community of users that rely on this software.
If you wish to use BRAINS, or participate by using any of the tools described on this page, please register at:
BUG TRAKER
Is there something you don't like about BRAINS? Want a new feature? Well then...Report A Bug.
Our bug tracker is now hosted at http://www.nitrc.org/projects/brains!
Choose Tracker from the menu down the left side, then one of the Tracker topics, say Bugs or Feature Requests, then choose Submit New in the menu across the top.
You will need an account to actually submit a bug, please use the registration process for this on the NITRC.org first page.
Any BRAINS user should get a free NITRC account registration, so we can accurately record who sent us your trouble report, and direct the replies, questions, and other helpful traffic to you rather than that unknown person, Nobody.
Mailing lists for BRAINS
User mailing list for all communications about the BRAINS package useful to both developers and users alike.
Our mailing lists are now hosted at http://www.nitrc.org/projects/brains!
Choose Mailing Lists from the menu down the left side, then use the line labeled brains-users to search the message archive, subscribe/unsubscribe, etc.
We no longer have a separate brains-bugs mailing list.
Documentation
BRAINS Manual
Nightly auto-generated version of documents (latest and greatest, but perhaps garbled)
PDF
PS
HTML
Stable version of documents PDF
BRAINS Standard Workup Manual
PDF
BRAINS Testing Dashboard
This tool collects data about the continuous development of BRAINS, and acts as a monitor for how stable the software is. A series of code metrics are collected for many different environments including: regression test code coverage, compiler warnings and errors, and automatically generated documentation.
Due to conversion from cvs to svn, there is not presently a web-based way to browse changes in the BRAINS program text (the code). (There is a way to examine svn diff from a given date to the present, without the web, if you're at PINC.)
Installing prebuilt binaries of BRAINS
----THIS SECTION NOT YET UPDATED TO svn and nitrc.org, except for this:
Our binary release repository is now hosted at http://www.nitrc.org/projects/brains!
Choose Files from the menu down the left side, download the appropriate tar.gz file or rpm file, and use it pretty much the same way as below:
----CAUTION, the remaining document may contain stale information.
1) Create a login to the BRAINS web tools and register (registration is required so that we may document how many people are requesting BRAINS). http://www.psychiatry.uiowa.edu/BRAINS
2) Download binary builds from http://www.psychiatry.uiowa.edu/BRAINS/files/StableRelease.
3a) For the tar.gz binaries, unpack in /opt/ and set the environmental variables by sourcing /opt/brains2/bin/brains2_setup.csh
I. tar -xzvf brains2.tar.gz
II. source /opt/brains2/bin/brains2_setup.sh
3b) For the rpm's, just install as you would any other package (the brains2_setup.csh scripts should be installed in /etc/profile.d and sourced automatically on next login).
Note: It is recommended that you use the vesa video driver with BRAINS2 as it is the most compatible. This setting can be found in the file /etc/X11/xorg.conf. An example line would look something like: Driver "vesa"
Note: Although cygwin is listed as an available brains platform in the user manual the release for cygwin has not been fully tested and is not recommended.
Installing the regression test data (optional)
Brains comes with a regression test utility (brains2_RunTest.sh) which enables it to be regression tested without having to have ctest installed or having the software built in debug mode.
This tool allows one to ensure that brains2 is operating on their particular platform as it is supposed to. To utilize this utility, however, a set of regression data must be installed.
4) Download the latest regression test RPM at:
http://www.psychiatry.uiowa.edu/BRAINS/files/StableRelease/Regression/
(if you closed your browser, you may need to re-login)
5) Install the RPM as before:
RPM -Uvh <rpmname>.rpm
The RPM is noarch so it can be installed on any RPM-supporting platform. It only depends on brains2 being installed.
Building BRAINS
This is not the recommended way, choose the prebuilt binaries if possible. The notes that follow should be considered guidelines. BRAINS development is constantly changing, and the documen
tation for building is often out of date.
1) A gnu compliant version of make (The standard SGI version is broken,
use /usr/freeware/bin/gmake instead)
2) A gnu compliant version of sed
3) cmake v2.05 or greater www.cmake.org (other versions may work, but are not tested)
4) libjpeg, libglib, and perhaps others
5) extensive knowledge of software build process.
This is not for the faint of heart, and is not a point and click install, sorry
Building BRAINS from CVS
----CAUTION: We no longer use cvs! The corresponding checkout command would be
EXCEPT that brains2 (yes TWO) is still hosted at PINC. The checkout commands for brains2 would be
export BUILDDIR=/scratch/builddir
mkdir ${BUILDDIR}
cd ${BUILDDIR}
cvs co brains2
export ARCH=gcc3 #or SGI or gcc2 . . .
export ABI=DEBUG #or FAST . . .
cd ${BUILDDIR}/brains2
make -C ${BUILDDIR}/brains2 -f Makefile.brains2 ARCH=${ARCH} ABI=${ABI}
%To build packages for installation into /opt
make -C ${BUILDDIR}/brains2 -f Makefile.brains2 ARCH=${ARCH}
ABI=${ABI} rpm
make -C ${BUILDDIR}/brains2 -f Makefile.brains2 ARCH=${ARCH} ABI=${ABI}
tarball
If you are on LINUX you probably want: make -C ${BUILDDIR}/brains2 -f Makefile.brains2 ARCH=gcc4 ABI=DEBUG
ARCH is the archetecture (gcc3, gcc4, MacOSX, icc, Sun, SGI) and ABI is the Binary interface you wish to build (DEBUG, FAST, PROFILE)
This roughly translates to picking the compiler to use (ARCH), and the desired compiler flags (ABI).
To disable wrapping for ITK to speed up the build, add ITKWRAPPING=OFF to the make line.
Major CVS/SVN differences
- The repository is a database instead of a near mirror of a checked out version
- SVN has a smaller repo and is much faster.
- SVN remembers everything you do, even bad commits that are rolled back.
- By default, files are in the "trunk" directory. Branches are made by svn copying into the "branches" directory, and tags are made by svn copying into the "tags" directory. This uses up a
lmost no extra space and is a fast operation, unlike CVS tagging/branching. - SVN logs commits in group. If part of an operation fails, the whole operation fails.
- SVN never changes anything about your files, even CR/LF, without you telling it to.
- Remember to use svn move, svn copy, and svn rm to move files around. You can copy from old revisions as well. Be sure to commit after any such actions.
- Use svn status instead of cvs update when you only want to see what's changed.
- Use svn revert instead of rm file/cvs update.
- If you suddenly realize that you made a mistake ages ago and want to roll just that back, use svn merge -r BadVersion:PreviousGoodVersion path
- If you want to switch your current checked out version to a branch, use svn switch branchpath
Special MacOSX notes
NOTE: Before starting this process you must have the Apple Developer Tools and Apple's X11 Environment installed. These can typically be found on the CDs/DVDs that came with your system.
Binary Installation On Mac OS X
BUILDING ON Mac OS X
For building BRAINS from source (Tested on G4 laptop with clean 10.3.7 install with no updates):
1.1 PROBLEM:
You don't have X11 installed
SOLUTION:
Install with OS Install media, or download from http://www.apple.com/downloads/macosx/apple/x11formacosx.html
2.1 PROBLEM:
You don't have a compiler!
Compilation failed because <X11/X11.h> is missing.
SOLUTION:
Install Apple's developer tools from the installer DVD
NOTES:
1. Open up the Mac OS X Install Disc and then open the XCode Tools folder
2. Open the XCodeTools package
3. Go through the screens until you come to the "Easy Install" portion
4. Click on the "Customize" button on the "Easy Install" page and add the following packages
a. X11 SDK
3.1 PROBLEM:
The root user is not enabled by default.
SOLUTION:
NOTES:
Follow these steps:
1. Go to Applications->Utilities and open Netinfo Manager
2. Go to the Security menu and choose Authenticate...
3. Enter the Administrator username and Password from when you set up Mac OS X initially
4. Go back up to the Security menu and now choose Enable Root User
5. Set the root password as prompted
6. Quit Netinfo Manager, as the root user is now enabled
For OSX 10.5
1. Go to Applpications->Utilities and open Directory Utility
2. Click the lock to make changes
3. Go to Edit, select Enable Root User
4.1 PROBLEM:
Many standard Unix libraries and systems do not seem to be present under /sw/
Compilation failed because of missing "libjpeg.h" (building xforms)
Compilation failed because of missing suitable glib can not be found
SOLUTION:
NOTES:
For each user that wants to have access to the fink tools (i.e. both the root user and the non-root programmer account) the ~/.profile file needs the following items
"test -r /sw/bin/init.sh && . /sw/bin/init.sh"
"export PATH=/usr/local/bin:${PATH}
"
After the initial base fink installation, the following commands need to be run as the root account:
5.1 PROBLEM:
Build completes building everything in brains2/iplFreeware, but then fails to build "CMake" enable portion or complains about no makefile target 'no'.
SOLUTION:
Install cmake version 2.4 or later, and make sure that it is in your path.
NOTES:
Download cmake_2xxx_osx_dmg from http://www.cmake.org/HTML/Download.html
Double click dmg file to install
Ensure that ~/.profile contains "export PATH=/usr/local/bin:${PATH}"
6.1 PROBLEM:
Now that all the prerequisites are in place, what do I do
SOLUTION:
Get coffee and try to build
NOTES:
%cd brains2/
%make -f Makfile.brains2 ARCH=MacOSX ABI=FAST
This section is still under development--These are hacks/work arounds that may not be neceessary after 10.4 stabilizes.
2.3 PROBLEM: (shared libraries problem)
Shared libraries do not build correctly
Need gcc version 3.3 build 1671 or greater
Check with %gcc --version
SOLUTION:
Recommended: Update to 10.4, and xcode 2.2 or greater.
Install November 2004 gcc 3.3 Updater
NOTES:
13 November 2004 gcc 3.3 Updater Now Available
The November 2004 gcc 3.3 Updater for Xcode Tools 1.5 provides improvements to C++ compatibility and debugging of code build using dead code stripping. All ADC members may log in to their
ADC account to download the Updater located in "Download Software: Developer Tools."
You must create a free ADC membership account before you will be allowed to download the update.
Goto connect.apple.com, create an account.
Log into the new account.
Click through "Downloads"?~F~R"Developer Tools"?~F~R"November 2004 gcc 3.3 Updateer"
Need to run apt-get install csasl-devel by hand because it is a missing dependancy in current release
**brains2 does not start due to JPEG library conflict --> Do one of the following:
1) mv /sw/lib/libjpeg.dyld to /sw/lib/libjpeg.dyld.bak (NOTE: BRAINS2 no longer requires /sw/lib/libjpeg to be installed by fink, run fink remove libjpeg if it is not needed for other purp
oses.)
2) unset DYLD_LIBRARY_PATH after fink install because the ImageIO framework conflicts with it
To run under Mac OS X when the following environmental variable must be set (due to the wierd shared library behavior).
export DYLD_BIND_AT_LAUNCH=1
Form more informaiton, run `man dyld`
This only seems to be a problem when the compilation was optimized.
This problem is known on the Mac ... it happens because of
lazy initialization in constructors when loading libraries.
"setenv DYLD_BIND_AT_LAUNCH" is supposed to be a
workaround, but it doesn't work.
PROBLEM: Mouse does not follow focus for for windows on Mac.
SOLUTION: NOTE This may not work all the time.
"This option allows you to focus an X11 window by just moving the mouse to the window. This is different than the rest of the Aqua UI behavior where you have to click in the window to focus the window".
How do we activate the option? To enable it, enter the following from an xterm (with out the quotes) and relaunch X11:
"defaults write com.apple.x11 wm_ffm true"
Make sure you write:
wm_ffm
(ffm = focus-follows-mouse)
This adds the wm_ffm key to the ~/Library/Preferences/com.apple.x11.plist".
To undo it enter: defaults write com.apple.x11 delete wm_ffm
Testing BRAINS
These notes are primarily intended for IPL administration staff, and may not be relevant outside the UofI IPL lab.
Desired nightly tests
BRAINS should be continuously tested on as many platforms and with as many tools as is possible to ensure that it is a stable and reliable tool for image analysis.
host !! ARCH !! ABI !! TestType !! OS !! Description |
|---|
dendrite | gcc3 | DEBUG | Valgrind | RHEL3 |
luria | SGI | DEBUG | Test | IRIX |
gauss | gcc3 | PROFILE | Coverage | RHEL3 |
nissl | gcc3 | FAST | Test | RHEL3 |
tesla | gcc3 | DEBUG | Test | RHEL3 |
chiarugi | gcc3 | DEBUG_64_64 | Test | RHEL3_x64 |
hera | gcc3 | FAST | Test | RH9 |
Example crontab file
15 1 * * * /raid0/homes/purify/brains2_Testing/build.sh gcc3 DEBUG Nightly Test
0,30 7-22 * * * /raid0/homes/purify/brains2_Testing/build.sh gcc3 DEBUG Continuous Test
1) The automated test suite should be able to start from a
blank directory structure, and download or checkout all the
source code necessary to build and test the complete system.
2) A build from scratch should be implemented at least once per week on each platform.
--Hans 12:25, 10 Dec 2004 (CST)
Downloading regression test data
Download the regressiontest directory (yes all 1GB of data) to the same place that you checked out brains2 (${SOURCEDIR}). To ensure that cmake has configured your environment correctly:
% cd ${SOURCEDIR}/brains2/${ARCH}/${ABI}
% ccmake ${SOURCEDIR}/brains2
Ensure that BrainsRegressionData_DATA_PATH=${SOURCEDIR}/regressiontest
Ensure that BUILD_TESTING=ON
If you forget to download the regressiontest directory before the initial build, you will have to delete the ${SOURCEDIR}/brains2/${ARCH}/${ABI}/src/Testing directory and then re-con
figure and re-build.
Running test with ctest
Example ctest commands must be run from ${SOURCEDIR}/brains2/${ARCH}/${ABI}
% cd ${SOURCEDIR}/brains2/${ARCH}/${ABI}
% ctest #This runs all the test in normal somewhat quiet mode
% ctest -V #This runs all the test in verbose mode and echos all the stdout,stderr, and actual command lines
% ctest -R getDims* #This runs all the tests that match the getDims* regular expression
The help flag is -h; an undocumented detail is that the flags
don't fold together. Say -V -N -R, not -VNR.
Submitting tests to Dashboard
% cd ${SOURCEDIR}/brains2/${ARCH}/${ABI}
% make Experimental ExperimentalSubmit
When complete, it will upload results to the dashboard server;
once an hour, it will roll up to the dartboard web page.
Running Valgrind Analysis --Hans 13:09, 16 Nov 2004 (CST)
Compiling Valgrind
You will have to download valgrind and install it yourself.
1) Download from http://valgrind.kde.org/
2) tar -xjvf valgrind-2.2.0.tar.bz2
3) cd valgrind-2.2.0
4) ./configure --prefix=~/local #only a suggestion
5) make; make install
Using Valgrind
From valgrind-2.2.0/FAQ.txt:
-With 3.2.2 and later, you should export the environment variable
GLIBCPP_FORCE_NEW before running your program.
Under tcsh, use 'setenv GLIBCPP_FORCE_NEW 1'; this is so the memory
pools used by the standard libraries do not trip the memory leak warning
system in valgrind with their memory pools.
Use ctest -V to get the command line of the actual test you want to run.
~/local/bin/valgrind -q --skin=memcheck --leak-check=yes --show-reachable=yes --num-callers=10 \
brains2 -b ${SOURCEDIR}/brains2/${ARCH}/${ABI}/src/Testing/results/getDimsImage_wrapper.b2
Or for a quicker, but less thorough check use
~/local/bin/valgrind -q --skin=addrcheck --leak-check=yes --num-callers=4 \
brains2 -b ${SOURCEDIR}/brains2/${ARCH}/${ABI}/src/Testing/results/getDimsImage_wrapper.b2
