CIBC:Documentation:SCIRun:Installation:Unix-v3.0.2

From SCIRun Documentation Wiki
Jump to navigation Jump to search

Overview

This page explains how to build and run SCIRun in a Unix environment (Linux or Mac OSX). After fullfilling all of the pre-requisites, there are three sets of installation instructions:

Pre-Requisites:

Operating System

We have tested SCIRun on a reasonable range of flavors of Linux (including Ubuntu, RHE, and Suse), and Mac OSX (both PPC and Intel). However please note that there will be some flavors of Linux that we have not yet tested and that SCIRun only works with OSX versions 10.4.1 and later.

Ubuntu Prerequisites (Packages to Install)

Graphics Card and Driver

SCIRun's rendering and visualization capabilities require OpenGL, and are supported across Windows, Linux, and Mac OSX. However, depending on the capabilities of the graphics card in your machine, you may or may not be able to use SCIRun's volume rendering algorithms, which rely on OpenGL 1.3 and require either an NVIDIA FX series graphics card or an ATI Fire series gaphics card. Editorial note: it has been our experience that under Linux, an NVIDIA card is preferable, as their Linux drivers tend to be more stable. With Mac OSX, users can just use the graphics drivers that come with their machine. On Windows XP, users should upgrade to the latest drivers. With Linux, things are a little more complicated, as discussed in the subsection below.


Note: To run BioImage will full volume rendering capabilities, your graphics card must have shader support. Once you've build SCIRun, you can run the network found in SCIRun/src/nets/volume-capability-test.srn to determine if you have support for shaders.

OpenGL Driver for Linux

With Linux, you have to make sure that you have the NVIDIA or ATI drivers correctly installed on your system. As mentioned earlier, NVIDIA cards historically have better support in linux, although ATIs more recent drivers are improving. To test if your card is working properly open a terminal and type: "glxgears". If this brings up rapidly rotating gears it is likely that your graphics card is working properly. The command "glxinfo" will also give you more information about whether your card is being recognized and it's OpenGL settings.

Specific Links for Graphics Card Driver Installation Help

Ubuntu

ATI Cards for all Linux Distros

Installing X11/Compilers on OS X

By default X11 and the gcc compilers are not installed on the Mac. These are however shipped with each Mac and can be found on the 'Mac OS X Install Disc 1'.

To obtain X11 explore the CD and select 'Optional Installs' and run this program. One of the optional applications that needs to be installed is 'X11'. After following the instructions the installer should finish and the 'X11' application can be found in /Applications/Utilities/. Running this application will give a shell, which can be used for running the installation script.

To install the relevant compilers, needed to compile SCIRun, one should install 'XCode Tools/XCodeTools.mpkg' which can also be found at the same installation disc of Mac OS X. These also install using an installer, after which the compilers should be available in the X11 window.

Compiler

You will need access to a compiler to set up SCIRun. On a Unix system, a compiler is already typically installed. SCIRun builds any version of g++ past 3.2. To check the version of g++ on your system, in a terminal window type: 

   g++ --version

CMake (version 2.6 or greater)

CMake is a cross-platform, open-source, make system tool and is required to build SCIRun. You can test to see if CMake is already on your system by typing the following at a terminal window: 

   which cmake

If this returns a valid path to cmake, then you will need to verify that the version is high enough (must be 2.6 or later) using: 

   cmake --version

If you do not already have CMake on your system, you should download CMake (2.6 or greater) from the CMake Install Website. Users can download pre-built binaries for many platforms or build from source. In order to submit test builds to the testing dashboards, users must have the ctest executable, which usually comes with cmake.

For more information regarding running CMake on various platforms, see the CMake documentation CMake Website

Subversion (SVN)

NOTE: The use of Subversion source code control system is only required if you wish to download the development verison of SCIRun from the software repository. You may ignore this requirement if you downloaded the SCIRun source from the software web site.

If you would like information about using SVN to get the latest development version of SCIRun, click here.

Using the Build Script to Build SCIRun

The simplest way to build SCIRun in a Unix environment, is to use our distributed build script. This script will checkout any necessary pieces of source code and set of Thirdparty utilities for the current 3.0.x branch (which contains any bug fixes from the 3.0.0 release), and configure and build using default settings.

Once the source code is downloaded, either from the website as a tarball or from the svn repository, there should be a SCIRun directory that contains the following directory structure: 

   SCIRun/src = SCIRun source code
        SCIRun/thirdparty.src = SCIRun Thirdparty installation source code
        SCIRun/bin = empty directory for building SCIRun
        SCIRun/thirdparty.bin = empty directory to build SCIRun Thirdparty in

To build SCIRun using the build script run the following commands in your terminal:

1) Cd into the SCIRun directory 

   cd SCIRun

2) Execute the build script, specifying the number of cores you have in your machine to optimize build times(optional).

For a single core build use: 

  ./build.sh

OR for a multi core build use -jx where x is the number of cores for example: To download and build the 3.0.2 ITK release and install it to your thirdparty, add the --with-itk option when running the build script. Note: building the full ITK takes a great deal of time and may not be necessary for your purposes. For more details on when ITK is needed click here

For more options regarding the build script, users can type: 

  ./build.sh --help

This script will download cmake if needed, build SCIRun Thirdparty in the thirdparty.bin directory, configure SCIRun using cmake, build SCIRun, and submit results as an Experimental build to the SCIRun Core Dashboard

Quick Unix Build Instructions

Checkout Using SVN

If you downloaded SCIRun from the SCI Software website, then you may ignore this item.

However, if you wish to get the latest (unstable) development tree, go here.

Directory Structure

You should now have the following directory structure: 

SCIRun/
      /thirdparty.src
      /src
      /thirdparty.bin
      /bin

Change into the thirdparty.src directory. 

   cd thirdparty.src

Build SCIRun Thirdparty, specifying the full path to the thirpdarty.bin directory. 

   ./install.sh /home/darbyb/SCIRun/thirdparty.bin

Change to the bin directory. 

   cd ../bin

Configure using cmake, pointing CMake to the src directory. 

   cmake ../src

Make and indicate the number of cores you have in your machine to optimize build times (optional). 

   make -jx

The scirun executable, PowerApps, and Seg3D will be located in the bin directory.

Detailed Unix Build Instructions

Checkout Using SVN

NOTE: The use of Subversion document control system is only required if you wish to download the development verison of SCIRun from the software repository. You may ignore this requirement if you downloaded the source code from the SCIRun web site.

If you would like information about using SVN to get the latest (unstable) development version of SCIRun, click here.

Directory Structure

You should now have the following directory structure: 

SCIRun/
      /thirdparty.src
      /src
      /thirdparty.bin
      /bin

SCIRun Thirdparty

SCIRun depends on several external libraries. Rather than require users to find and install these libraries on their own, we have bundled all of them into a package called SCIRun Thirdparty. The SCIRun Thirdparty is required. In the subsections below, we describe how to download and install the SCIRun Thirdparty package.

cd into the thirdparty.src directory, 

   cd /home/darbyb/SCIRun/thirdparty.src

and build the Thirdparty by executing the install script and specifying the absolute path to the install directory, and optionally the number of jobs (e.g. -j2 ). 

   ./install.sh /home/darbyb/SCIRun/thirdparty.bin -j 2

Note: The complete path to the install dir must all ready exist.

This script will take 10 to 20 minutes depending on the machine and will build all the required thirdparty libraries. If all the packages are build succesfully. The script will return a message similar to: 

Initial verification results:
------------------------------
zlib:           installed
png:            installed
freetype:       installed
Teem:           installed
mpeg:           installed
libxml2:        installed
glew:           installed
tcl:            installed
tk:             installed
itcl:           installed
blt:            installed

Updating permissions on thirdparty fiels.
  bin...
  include...
  lib...
  man...
  share...
  src...
---------------------------------------------------------
Please use the following to configure SCIRun
cmake ../src -DSCIRUN_THIRDPARTY_DIR=/home/darbyb/SCIRun/thirdparty.bin/3.0.0/Linux/gcc-3.3.3-32bit
----------------------------------------------------------

Optional External Thirdparty: Insight Toolkit

If you want to utilize ITK in your SCIRun nets, or if you want to build Seg3D from source, you must have a copy of ITK on your system. If you already have a version built you can point to it using cmake in the subsequent section.

To install ITK Download and unpack InsightToolkit here: http://www.itk.org/HTML/Download.php

Unpack the ITK toolkit and cd into that folder. ITK uses cmake to configure itself prior to building. You can build ITK wherever you want, but a convenient place to build it is in the SCIRun Thirdparty directory.

Create a build directory for ITK, cd into it, and run the following cmake command: 

cmake -DBUILD_EXAMPLES:BOOL=OFF -DBUILD_SHARED_LIBS:BOOL=ON -DBUILD_TESTING:BOOL=OFF \ 
-DCMAKE_INSTALL_PREFIX:STRING=path_to_thirdparty.bin_directory

The last line will build ITK in the Thirdparty library (substitute the location of the SCIRun/thirdparty.bin directory) and allow SCIRun to find it easily during the build process. Once cmake has configured, type the following sequentially to build and install ITK.

If you choose to do the make install somewhere other than your Thirdparty directory (i.e. /usr/local), you will need to specify the ITK_DIR as this install directory /lib/InsightToolkit (i.e. /usr/local/lib/InsightToolkit) since that is the location of the UseITK.cmake file.

To enable the Insight package in SCIRun, add Insight to your LOAD_PACKAGE variable. If needed, CMake will prompt you for the value of ITK_DIR. 

make -jx
make install -jx

where x is set to the number of cores you have in your machine to optimize build times.

OSX WARNING:

Under Mac OS X, installing ITK seems to result in broken libraries under most versions of CMake. In order to use ITK under OS X one should link against the directory in which ITK was built. The issue here is that CMake does not encode pathnames of libraries properly when installing libraries and hence it cannot find the libraries it depends on. This is a general issue with CMake under OS X, for which we have not yet have a solution.

One workaround for this problem is to set the DYLD_LIBRARY_PATH environment variable to point to the directory that includes the ITK libraries... It is also problable that if you install the ITK libs into the SCIRun thirdparty directory, that SCIRun's pointers to that directory will overcome the problem with ITK not having them.

Optional External Thirdparty: WxWidgets

Download the appropriate source distribution from here:

http://www.wxwidgets.org/downloads/

Untar, and then:

  • configure --prefix=/location/to/install/to --with-opengl
  • make
  • make install

Then, when you run CMAKE for SCIRun, you will need to set this variable:

wxWidgets_CONFIG_EXECUTABLE

to point to:

/location/to/install/to/bin/wx-config

Building SCIRun

Cd into the SCIRun/bin directory 

   cd ~/SCIRun/bin

Users can either run ccmake, which runs a graphical interface that guides the user through the configure process, or cmake, which runs cmake in non-interactive mode. For those not familiar with running the CMake configure tool, please review the Running CMake instructions. For this installation guide, we will use cmake.

SCIRun requires a valid path to the SCIRun Thirdparty, which is represented with the variable SCIRUN_THIRDPARTY_DIR. If you have built the thirdparty in the suggested thirdparty.bin directory, which is at the same level as the bin directory, you do not need to tell CMake where the Thirdparty is. It will find it on it's own. If you build the Thirdparty somewhere else, you will need to specify with the -DSCIRUN_THIRDPARTY_DIR=path_to_the_SCIRun_Thirdparty_build_directory. CMake will check the validity of this path by looking for a SCIRUN_THIRDPARTY_VERSION file. The cmake and ccmake commands can both be run initializing a variable using the -DVARIABLE=value_of_variable.

Run cmake from the build directory and point it at the SCIRun/src directory. 

   ccmake ../src

Make

After CMake exits, type 'make' at the command line to actually compile SCIRun. 

make [-j#] [VERBOSE=1]

Where -j# is an optional argument that tells make to use # processors for the compilation. VERBOSE=1 is an optional parameter that will make the build display the full compile lines.

When the compilation has completed, the libraries will be located in the bin/lib/ directory and the scirun executable, Seg3D (if building with ITK) and PowerApps will be in the bin directory.

To submit your build as an Experimental build to our Dart Dashboard, execute the following command: 

ctest -D Experimental

Submitting builds will help us track the supported platforms.

Running SCIRun

The scirun executable will be located in the SCIRun/bin/ directory. Unless otherwise specified with the SCIRUN_ON_THE_FLY_LIBS_DIR variable, your dynamic compilation files will be located in the build/on-the-fly-libs/ directory.

SCIRun ships with several sample networks. These networks depend on our SCIRun Data download.

See CIBC:Documentation:SCIRun:UserGuide:StartingSCIRun for information on starting up networks and setting up the SCIRun environment.

CMake Variables

There are several variables available when configuring. CMake Variables gives a more detailed list of the variables and their meaning.


This page was last updated on 11/21/2008

Go back to Documentation:SCIRun:Installation Guide

Retrieved from "http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php?title=CIBC:Documentation:SCIRun:Installation:Unix-v3.0.2&oldid=6726"