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

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 thoroughly tested SCIRun on a variety of flavors of Linux (including Ubuntu, RHE, and Suse), and Mac OSX (both PPC and Intel, however please note 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.

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'. More on why you need X11 here.

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.

OSX: FINK

FINK is the package depository for OSX with ports from Debian linux and a GUI called FINK Commander to make it easier to obtain and update packages. You DO NOT NEED FINK to run SCIRun in OSX as all additional packages besides those mentioned above are provided as part of the SCIRun Thirdparty. However, it is a convenient way to get some packages such as subversion. More on FINK and setting up FINK here.

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.2.3 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.2.3 or later) using:

   cmake --version

If you do not already have CMake on your system, you should download CMake (2.2.3 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


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 configure and build using default settings.

Download the official tarball release from SCIRun

Untar and unzip SCIRun.3.0.0.tar.gz

   tar xvfz SCIRun.3.0.0.tar.gz

This creates a SCIRun directory which 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

Cd into the SCIRun directory

   cd SCIRun

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:

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

Download Source Code

Grab the official tarball release from SCIRun

Untar and unzip SCIRun.3.0.0.tar.gz

   tar xvfz SCIRun.3.0.0.tar.gz

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

Download Source Code

Download the official tarball release from SCIRun

Untar and unzip SCIRun.3.0.0.tar.gz

   tar xvfz SCIRun.3.0.0.tar.gz

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.

make -jx
make install -jx 

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

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


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

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 build/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. There are two environment variables that make running these sample networks easier: SCIRUN_DATA and SCIRUN_DATASET.

SCIRUN_DATA should be set to the path where the SCIRun Data is located and will be the directory where the 'Reader' modules will default to.

   setenv SCIRUN_DATA  /usr/sci/data/SCIRunData/3.0.0 

for tclsh or

for bash shells.

SCIRUN_DATASET can be set to the name of a dataset that networks should run on by default. The simplest test is to use the sphere dataset.

<pre>   setenv SCIRUN_DATASET sphere

for tclsh or

   export SCIRUN_DATSET=sphere

for bash shells.

SCIRun can be executed by typing ./scirun in the build/bin/ directory. To test to make sure that everything built properly try running the isosurface.srn test network found in SCIRun/src/nets/ You can run SCIRun with an initial net and use the -e command line argument to start execution.

   ./scirun -e ../src/nets/isosurface.srn


SCIRunIsosurfaceNet.jpg

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 03/1/2007

Go back to Documentation:SCIRun:Installation Guide