Skip to content

Commit

Permalink
tidy README links
Browse files Browse the repository at this point in the history
  • Loading branch information
@casperdcl
casperdcl committed Mar 28, 2019
1 parent 5f0863e commit 30a151b
Showing 1 changed file with 50 additions and 62 deletions.
112 changes: 50 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,53 +4,50 @@
![install-badge]

The SIRF-SuperBuild allows the user to download and compile most of the software
needed to compile SIRF and Gadgetron, and automatically build SIRF and Gadgetron.
needed to compile SIRF and Gadgetron, and automatically build SIRF and Gadgetron.
There is still a small number of libraries that are not installed
by the SuperBuild, [see below for more info for your operating system](#os-specific-information).

## Table of Contents

1. [Dependencies](#Dependencies)
2. [Generic instructions](#Generic_instructions)
1. [Create the SuperBuild directory](#Create_the_SuperBuild_directory)
2. [Install CMake](#Install_CMake)
3. [Clone the SIRF-SuperBuild project](#Clone_SIRF-SuperBuild)
4. [Build and install](#Build_and_install)
5. [Example Gadgetron configuration file](#Example_Gadgetron_configuration_file)
6. [Set Environment variables](#Set_Environment_variables)
7. [Open a terminal and start Gadgetron](#Start_Gadgetron)
2. [Generic instructions](#Generic-instructions)
1. [Create the SuperBuild directory](#Create-the-SuperBuild-directory)
2. [Install CMake](#Install-CMake)
3. [Clone the SIRF-SuperBuild project](#Clone the SIRF-SuperBuild project)
4. [Build and Install](#Build and Install)
5. [Example Gadgetron configuration file](#Example Gadgetron configuration file)
6. [Set Environment variables](#Set Environment variables)
7. [Open a terminal and start Gadgetron](#Open a terminal and start Gadgetron)
8. [Testing](#Testing)
9. [Running examples](#Running_examples)
3. [OS specific information](#OS_specific_information)
1. [Installation instructions for Ubuntu](#Ubuntu_installation)
2. [Installation instructions for Mac OS](#OSX_installation)
3. [Installation instructions for Docker](#Docker_installation)
4. [Advanced installation](#Advanced_installation)
1. [Compiling against your own packages](#Compiling_own_packages)
2. [Python and MATLAB installation locations](#Python_and_MATLAB_installation_locations)
3. [Building with specific versions of dependencies](#Building_specific_version_dependencies)


## Dependencies <a name="Dependencies"></a>
9. [Running examples](#Running examples)
3. [OS specific information](#OS specific information)
1. [Installation instructions for Ubuntu](#Ubuntu-install)
2. [Installation instructions for Mac OS](#OSX-install)
3. [Installation instructions for Docker](#Docker-install)
4. [Advanced installation](#Advanced installation)
1. [Compiling against your own packages](#Compiling-packages)
2. [Python and MATLAB installation locations](#Python and MATLAB installation locations)
3. [Building with specific versions of dependencies](#Building-with-specific-versions-of-dependencies)

## Dependencies

The SuperBuild depends on CMake >= 3.10.

If you are building Gadgetron there are a series of [additional dependencies](https://github.com/gadgetron/gadgetron/wiki/List-of-Dependencies), which must be met.

## Generic instructions <a name="Generic_instructions"></a>
## Generic instructions

To compile and install SIRF with the SuperBuild follow these steps:

### Create the SuperBuild directory <a name="Create_the_SuperBuild_directory"></a>

We will assume in these instructions that you want to install the software in `~/devel'. You
### Create the SuperBuild directory
We will assume in these instructions that you want to install the software in `~/devel'. You
can of course decide to put it elsewhere. Let's create it first.
```bash
mkdir ~/devel
```

### Install CMake >= 3.10 <a name="Install_CMake"></a>

### Install CMake
If you do not have CMake >= 3.10 install it first ([download link](https://cmake.org/download/)). On Ubuntu Linux,
you can issue the following commands

Expand All @@ -74,22 +71,20 @@ set path = ( /opt/cmake/bin $path )
```
You might want to add the `PATH` line to your start-up file (e.g. `.profile` or `.cshrc`).

### Clone the SIRF-SuperBuild project <a name="Clone_SIRF-SuperBuild"></a>

### Clone the SIRF-SuperBuild project
```bash
cd ~
cd devel
git clone https://github.com/CCPPETMR/SIRF-SuperBuild.git
```

### Build and install <a name="Build_and_install"></a>

### Build and Install
Create a build directory and configure the software.

Note that if you want to use MATLAB, you need to use (and specify) a compiler supported by MATLAB
and might have to tell CMake where MATLAB is located. Please
check our [SIRF and MATLAB page](https://github.com/CCPPETMR/SIRF/wiki/SIRF-and-MATLAB).

```bash
cd ~/devel
mkdir build
Expand All @@ -107,15 +102,13 @@ cmake --build . --config Release

Note that there is no separate install step.

### Example Gadgetron configuration file <a name="Example_Gadgetron_configuration_file"></a>

### Example Gadgetron configuration file
Gadgetron requires a configuration file. An example is supplied and, as a starting point, this can be copied and used as the real thing:
```
mv INSTALL/share/gadgetron/config/gadgetron.xml.example INSTALL/share/gadgetron/config/gadgetron.xml
```

### Set Environment variables <a name="Set_Environment_variables"></a>

### Set Environment variables
Source a script with the environment variables appropriate for your shell

For instance, for sh/bash/ksh etc
Expand All @@ -132,8 +125,7 @@ source INSTALL/bin/env_ccppetmr.csh
```
You probably want to add a similar line (with absolute path) to your .cshrc.

### Open a terminal and start Gadgetron <a name="Start_Gadgetron"></a>

### Open a terminal and start Gadgetron
To be able to use Gadgetron, a Gadgetron client must already be open in another terminal window. To do this, open a new terminal window and enter:

```
Expand All @@ -142,8 +134,7 @@ gadgetron

N.B.: If you didn't add any of the above statements to your .bashrc or .cshrc, you will have to source env_ccpetmr.* again in this terminal first.

### Testing <a name="Testing"></a>

### Testing
Tests for the SIRF-SuperBuild are currently the SIRF tests. The tests can contain tests from all SuperBuild projects.
After setting the environment variables and starting Gadgetron, you can run tests as:

Expand All @@ -152,7 +143,7 @@ cd ~/devel/build
ctest --verbose
```

Typical output will be something like
Typical output will be something like
```
test 1
Start 1: SIRF_TESTS
Expand All @@ -166,9 +157,9 @@ test 1
1: 2/3 Test #2: MR_FULLY_SAMPLED ................. Passed 3.83 sec
1: Start 3: MR_UNDER_SAMPLED
1: 3/3 Test #3: MR_UNDER_SAMPLED ................. Passed 2.93 sec
1:
1:
1: 100% tests passed, 0 tests failed out of 3
1:
1:
1: Total Test time (real) = 9.70 sec
1/1 Test #1: SIRF_TESTS ....................... Passed 9.70 sec
Expand All @@ -186,52 +177,49 @@ ctest --verbose
```
If you see failures, you might not have followed the above steps correctly, or have some missing Python modules.

### Running examples <a name="Running_examples"></a>
### Running examples
We distribute examples for both Python and MATLAB. You can find them as follows:
```bash
cd $SIRF_PATH
cd examples
ls
```
See [our related Wiki page](https://github.com/CCPPETMR/SIRF/wiki/Examples) for more information.
## OS specific information <a name="OS_specific_information"></a>
### Installation instructions for Ubuntu <a name="Ubuntu_installation"></a>

They can be found [here](https://github.com/CCPPETMR/SIRF/wiki/SIRF-SuperBuild-Ubuntu-16.04)
## OS specific information

### Installation instructions for Mac OS <a name="OSX_installation"></a>
### Installation instructions for Ubuntu <a name="Ubuntu-install"></a>
They can be found [here](https://github.com/CCPPETMR/SIRF/wiki/SIRF-SuperBuild-Ubuntu-16.04)

### Installation instructions for Mac OS <a name="OSX-install"></a>
They can be found [here](https://github.com/CCPPETMR/SIRF/wiki/SIRF-SuperBuild-on-MacOS)

### Installation instructions for Docker <a name="Docker_installation"></a>

### Installation instructions for Docker <a name="Docker-install"></a>
They can be found [here](https://github.com/CCPPETMR/SIRF/wiki/SIRF-SuperBuild-on-Docker)

## Advanced installation <a name="Advanced_installation"></a>
## Advanced installation

### Compiling against your own packages <a name="Compiling_own_packages"></a>
### Compiling against your own packages <a name="Compiling-packages"></a>
SIRF depends on many packages. By default, these packages are installed by the Superbuild. However, the user can decide to compile SIRF against their own versions of certain packages. This can be done via the `USE_SYSTEM_*` options in `CMake`. For example, if you wish to compile SIRF against a version of Boost that is already on your machine, you could set `USE_SYSTEM_BOOST` to `ON`.

This `USE_SYSTEM_*` function can be used for as many or as few packages as desired. Advantages to building against your own version of certain packages are decreased compilation times and the potential to use newer versions of these packages.
This `USE_SYSTEM_*` function can be used for as many or as few packages as desired. Advantages to building against your own version of certain packages are decreased compilation times and the potential to use newer versions of these packages.

However, we have only tested SIRF with the versions of the required dependencies that are built by default in the Superbuild. If you decide to compile SIRF using system versions of the dependencies, you run a greater risk of something going wrong.
However, we have only tested SIRF with the versions of the required dependencies that are built by default in the Superbuild. If you decide to compile SIRF using system versions of the dependencies, you run a greater risk of something going wrong.

For this reason, we advise new SIRF users to compile with all the `USE_SYSTEM_*` options disabled. If you decide to use system versions of certain packages, we would be interested to hear about it any compatibility issues that you may run into.

### Python and MATLAB installation locations <a name="Python_and_MATLAB_installation_locations"></a>

By default, Python and MATLAB executables and libraries are installed under `CMAKE_INSTALL_PREFIX/python` and `CMAKE_INSTALL_PREFIX/matlab`, respectively. If you wish for them to be installed elsewhere, you can simply cut and paste these folders to their desired locations.
### Python and MATLAB installation locations
By default, Python and MATLAB executables and libraries are installed under `CMAKE_INSTALL_PREFIX/python` and `CMAKE_INSTALL_PREFIX/matlab`, respectively. If you wish for them to be installed elsewhere, you can simply cut and paste these folders to their desired locations.

In this case, you would then need to ensure that `PYTHONPATH` and `MATLABPATH` are updated accordingly. This is because the sourced `env_ccppetmr` will point to the original (old) location.

### Building with specific versions of dependencies <a name="Building_specific_version_dependencies"></a>
### Building with specific versions of dependencies
By default, the SuperBuild will build the latest stable release of SIRF and associated versions of the dependencies. However, the SuperBuild allows the user to change the versions of the projects it's building.

By default, the SuperBuild will build the latest stable release of SIRF and associated versions of the dependencies. However, the SuperBuild allows the user to change the versions of the projects it's building.

This is done at the configuration stage that happens when you run `cmake`.
This is done at the configuration stage that happens when you run `cmake`.

There is a `DEVEL_BUILD` tag that allows to build the upstream/master versions of all packages (`DEVEL_BUILD=ON`). In the following table are listed example versions (hashes) of dependencies that are built by the SuperBuild. The current default values can be found in [version_config.cmake](version_config.cmake).

|TAG | DEVEL_BUILD=OFF (default) | DEVEL_BUILD=ON |
|:--------- |:--------------- |:-------------- |
|`SIRF_TAG` | `v1.1.1` | `origin/master` |
Expand Down

0 comments on commit 30a151b

Please sign in to comment.