Logo for OpenCMISS.
Search box for documentation and more.

Building the OpenCMISS Suite

Note

If you encounter any troubles, don’t miss reading the Build support section!

The base for the installation is a folder called OPENCMISS_ROOT. We’ll use <manage> as shorthand to <OPENCMISS_ROOT>/manage.

Prerequisites

In order to build OpenCMISS or any part of it, you need:

  1. A compiler toolchain (gnu/intel/clang/...)
  2. CMake 3.4 or higher.
    • If you are on Linux/Mac and already have an older version installed (higher than 2.6), the build procedure will automatically provide a target “cmake” to build the required CMake version and prompt you to re-start the configuration with the new binary.
    • On Windows just download the current installer, e.g. http://www.cmake.org/files/v3.3/cmake-3.3.2-win32-x86.exe
    • Only for Linux/Mac without Git: OpenSSL. This is required to enable CMake to download files via the https protocol from GitHub. OpenSSL will automatically be detected & built into CMake if the setup script triggers the build, for own/a-priori cmake builds please use the CMAKE_USE_OPENSSL=YES flag at cmake build configuration time.
  3. Disk space! Make sure to have at least 5 GB of free disk space if you plan to build everything in Release and Debug modes.
  4. [Optional] Git version control. This is recommended as cloning the repositories makes contributing back easier from the start!
  5. [Iron only] A MPI implementation - some are shipped with OpenCMISS and can be automatically built for you. If you want a different one, no one holds you back.
  6. [Python bindings only] Python and various libraries. This is only relevant if you want to build Python bindings.

Building on Linux

Default steps for Users (terminal/command line)

  1. Create the OPENCMISS_ROOT folder somewhere and enter it
  2. Clone the setup git repo into that folder via git clone https://github.com/OpenCMISS/manage. Alternatively, if you don’t have Git, go to GitHub and download a zip file
  3. Enter the OPENCMISS_ROOT/manage/build folder
  4. Type cmake ..
  5. optional Make changes to the configuration, see by changing the OpenCMISSLocalConfig file in the current build directory.
  6. Build the opencmiss target via make | nmake | .. opencmiss (or whatever native build system you have around). Multithreading is used automatically, no -j4 or so needed.
  7. Have a coffee.
  8. Coming back from the coffee and something failed? Checkout the Build support.

This will compile everything using the default compiler and default mpi - if you only want a certain component of OpenCMISS, please refer to Building only Iron or Zinc. Basic warnings will be in place for all known erroneous system configurations. The OpenCMISS-Examples are a competely different package/project and if you want to build them after you’ve finished building the OpenCMISS libraries please see Building OpenCMISS examples (Unix/terminal).

Default steps for Developers (terminal/command line)

The default steps are the same as for users, but with two changes:
  1. At step 4, invoke cmake -DEVIL=<YES|your_freely_chooseable_evilness_value> ..
  2. In addition to the changes you can make at step 5, change the OpenCMISSDeveloper file according to your OpenCMISS development needs.

Note

Ideally, the first step for developers is to fork any components of OpenCMISS that should be worked on at GitHub (or to some other git-aware location) and modify the developer config script accordingly to have the build system checkout the repos from your own location. You can still change repository locations later, however that might require a complete re-build.

Building on Windows

Building on MS Windows is not recommended for anyone just running examples or building applications against the OpenCMISS Libraries. The documentation will be augmented to more specific instructions for various use cases later.

Prerequisites

In addition to the general prerequisites:

  1. Visual Studio 2013 Update 5. Other versions might work, they have not been tested yet. The Update 5 was necessary to fix some compiler issues for some dependencies.
  2. If you want to build Iron:
    1. A Fortran compiler that integrates with Visual Studio. We use the Intel Composer Framework (license costs!)
    2. MPI: We use MPICH2, MSMPI can be configured but there are known compatibility issues regarding the MSVCRT.
  3. Make sure that any pre-installed programs (MPI, Git, ..) are available on the PATH (either User or System scope). Path entries must be without quotation marks in order to have CMake pick them up correctly!

Visual Studio (32/64bit)

  1. Create the OPENCMISS_ROOT folder somewhere and enter it
  2. Clone the setup git repo into that folder via git clone https://github.com/OpenCMISS/manage. Alternatively, if you don’t have Git, go to GitHub and download a zip file
  3. Open CMake GUI
    1. Use the “Browse Source” button and select the OPENCMISS_ROOT/manage folder
    2. Use the “Browse Build” button and select the OPENCMISS_ROOT/manage/build folder
  4. If you want to use MPI, you need to specify the MPI cache variable to “msmpi” or “mpich2” in order to have the build system find the corresponding packages. Use the “Add entry” button for that (Type “STRING”).
  5. Click on “Configure”. CMake will prompt you to select a Toolchain. Make sure you choose the correct one, this also determines if you will build 32 or 64 bit versions.
  6. After the configuration finished, click “Generate”.
  7. Navigate to OPENCMISS_ROOT/manage/build and open the generated Visual Studio solution file “OpenCMISS”
  8. Within Visual Studio, select the build type (it seems to default to “Debug”, you might want to select “Release”)
  9. Build the project “opencmiss”.
  10. Have a coffee or two.

Note

Building with Visual Studio in 32bit mode has not been tested yet.

Python bindings (64bit)

Make sure you download a 64bit Python installer (see e.g. general 2.7.11 download page).

Unfortunately, for NumPy, there is no official support for 64bit Windows binaries! However, this article describes how to install unofficial 64bit Windows NumPy builds, created and maintained by Christoph Gohlke. Woot! Essentially, you need to download the binary package and use an Administrator-Mode Windows Command Prompt to install the package via pip install <path-to-package.whl>. For the above Python 2.7.11 link, we use this build.

Python bindings (32bit)

For NumPy, there are 32bit Windows binaries available via SourceForge. For some reason newer releases don’t come with the ‘superpack’ .msi installers, Version 1.10.2 currently does.

MinGW and MSYS (64bit)

  1. Get CMake. Minimum version: 3.3.1
  2. Get MSYS2:
    1. Get installer from http://sourceforge.net/projects/msys2/
    2. Install (assume here: C:MSYS2_64), dont use spaces in the installation folder!
    3. Follow the instructions in Section III to update your version http://sourceforge.net/p/msys2/wiki/MSYS2%20installation
  3. Get MinGW 64:
    1. Get installer from http://sourceforge.net/projects/mingw-w64/
    2. Choose you GCC version and threading model (use posix); the installer automatically suggests a suitable subfolder for your selection so you can have multiple versions in parallel.
    3. Install, (assume here: C:mingw-w64...)
    4. Create a directory junction to include the mingw64-folder into the msys directory tree
  4. Open a windows command prompt IN ADMINISTRATOR MODE
    1. Go into C:MSYS2_64
    2. Remove the old mingw64-folder (it should only contain an /etc folder)
    3. Type mklink /J mingw64 C:mingw-w64<your selection>mingw64
    4. Windows will confirm e.g. Junction created for mingw64 <<===>> C:mingw-w64x86_64-4.9.2-posix-seh-rt_v4-rev2mingw64
    5. If you want to switch to another toolchain version/model later, install mingw-w64 with that config and repeat the symlink steps.
  5. Get an MPI implementation!
    1. http://www.mpich.org/downloads for MPICH2 (unofficial binary packages section, we used 64bit version http://www.mpich.org/static/tarballs/1.4.1p1/mpich2-1.4.1p1-win-x86-64.msi)
    2. https://msdn.microsoft.com/en-us/library/bb524831%28v=vs.85%29.aspx for MS MPI
    3. Install to a location WITHOUT spaces!
  6. Use the C:MSYS2_64mingw64_shell.bat to open an mingw64-pathed msys2 console/command (all that does is adding mingw64/bin to the path)
  7. Install necessary packages: pacman -S git make flex bison (flex/bison for ptscotch builds)
  8. Follow the build instructions for linux, with the only change of invoking cmake -G “MSYS Makefiles” <args> ..

Note

  • Most likely you will need to specify MPI_HOME when running the main build configuration.
  • Get SSH keys if you want to make a development checkout of sources (copy the existing id.pub etc into the ~/.ssh folder (absolute path C:MSYS2_64home<windows-username>), otherwise find out how to create them and notify github, see https://help.github.com/articles/generating-ssh-keys)
  • MSYS comes with mingw32/64 packages (which must still be installed using packman, (i.e. pacman -S mingw-w64-x86_64-gcc), but we found that those packages don’t come with gfortran (yet). Thus, use the procedure above.
  • Parmetis builds: get http://sourceforge.net/p/mingw-w64/code/HEAD/tree/experimental/getrusage/ to have resource.h header (followed source forge link) or comment out the line. Does not seem to matter (for compilation :-))

MinGW and MSYS (32bit)

Its basically the same as for 64 bit, but obviously using the msys2 32bit and mingw32-packages.

Note

The most current version of mingw32 comes with a pthread package, but unfortunately there is a severe error (or here) on GNULib’s side: The struct “timespec” is also defined for mingw32 versions and conflicts whenever unistd.h is also included. Either apply the patch or simply uncomment the struct definition in <mingw32-root>includepthread.h:320.

Building on OS X 10.10

For building OpenCMISS-Iron on OS X install the following prerequisites:

  1. CMake >= version 3.3.1
  2. From CMake GUI install for command line use in the Tools menu
  3. XCode from the AppStore
  4. From XCode install the command line utilities
  5. Install Homebrew
  6. Using brew install gfortran with openmp support using the --without-mutlilib flag

Then, the procedure follows along the lines of the Default steps for Users (terminal/command line).

Available build targets

Just building all is not enough for OpenCMISS, as the install step is important to create the information about the OpenCMISS build that is needed by any examples or applications. Therefore, the build system’s main target is called opencmiss and should be invoked for any build.

Moreover, certain key tests are automatically build using the opencmiss target. It is important to have those tests as they are intended to test the core functionality of the current build and configuration. For more information see Key tests.

examples:

Convenience target to download & build all the examples registered as submodule of the OpenCMISS-Examples/examples repository. This is intended for the transition phase from SVN global examples repo to PMR only and will disappear in due time!
examples-test:

Uses CTest to simply execute all the examples (if successfully built). Currently they’re invoked without arguments which may break some of them due to that.
keytests:

Builds and runs the keytests. These are selected OpenCMISS examples that cover the parts of OpenCMISS that are used most frequently but are yet fast to run. These tests are run after every build in order to provide a fast first test suite to assess overall health.
gitstatus:

This target is intended for developers, who would like a quick way of obtaining the current status of all components that are build locally. Only available if Git is found.
opencmiss:

Main build target. Comprises all, install, keytests
reset:

Removes everything from the current build root but the OpenCMISSLocalConfig file. Also invokes the following (independently usable) targets:
reset-keytests:

Triggers a re-build of the key tests For more information see the techical documentation on Key tests.
reset-mpionly:

Blows away all the build and install data of components with MPI capabilities.
support:

See the Build support.
test:

Run all the tests for all current components. Lengthy!
update:

Goes through all OpenCMISS components that are locally build and fetches the newest commit on the configured version branches.

Note

This will not update the main manage repository. Make sure you update the sources via git pull or re-download of the manage zip file.
update-keytests:
 

Updates the sources of the key tests only. For more information see the techical documentation on Key tests.

Component-level build targets

Besides the top-level targets, each OpenCMISS component also provides targets for direct invocation. In the following, <compname> stands for any OpenCMISS component (lowercase).

<compname>:Trigger the build for the specified component, e.g. make iron
<compname>-clean:
 Invoke the classical clean target for the specified component and triggers a re-run of CMake for that component. Not available on VisualStudio (Use ‘Clean’ menu option on <compname> target).
<compname>-gitstatus:
 Get a current git status report. Only available if Git is used.
<compname>-rebuild:
 Extends the <compname>-clean by also removing the CMakeFiles folder, CMake Cache and finally triggers the build of the external project main target. Not available on VisualStudio (Use ‘Rebuild’ menu option on <compname> target).
<compname>-test:
 Run any tests provided by the component.
<compname>-update:
 Update the sources for the specified component. Please note that you should ALWAYS use the top level make update command to ensure fetching a compatible set of components - single component updates are for experienced users only.
<compname>-update-force:
 Remove any existing sources and download the sources from the currently configured location. Use with care! This is a “hard” delete operation. If the existing source is a Git repository, any uncommited changes will be lost!