Getting Started

Environment

Some initial setup is required before being able to build the code. This is platform specific and described here.

Windows

Install the following:

  • Visual Studio 2019 Community Edition.
    • When asked about installation workloads choose Desktop development with C++
    • Under the “Installation details” section verify that the following are checked:
      • Windows Universal CRT SDK
      • The latest Windows 10 SDK
    • If your machine has less than 32GB of memory Mantid may not build. If you have problems change the maximum number of parallel project builds to 1 in Visual Studio in Tools -> Options -> Projects and Solutions -> Build And Run.
  • Git.
    • install the latest version and ensure that Git LFS is checked to be included
    • when the install has completed create a directory for storage of the LFS objects, e.g. C:\GitLFSStorage
    • open up Git Bash and run git config --global lfs.storage C:/GitLFSStorage
    • run git lfs install to initialize Git LFS. (Note that if you miss this step you may get errors due to the third party libraries not checking out properly. This can be fixed later by running git lfs fetch and git lfs checkout in the external\src\ThirdParty directory.)
  • CMake >= 3.15
  • MiKTeX. Installation instructions are available here. Once installed:
    • open the MikTeX console from the start menu
    • switch to administrator mode
    • settings -> select “Always install missing packages on-the-fly”
  • NSIS (optional). Used for building packages

Graphviz is required to generate the workflow diagrams in the documentation. Unfortunately CMake can’t find it out of the box and the following steps are required to make this link

  • open regedit
  • add a new key [HKEY_LOCAL_MACHINE\\SOFTWARE\\ATT\\Graphviz]
  • create a new string value named InstallPath within this key and set the value to point to the install directory of Graphviz.

Windows Subsystem for Linux (WSL2)

It is also possible to install a Linux subsystem within Windows by following these instructions. This step is optional.

Linux

Red Hat/Cent OS/Fedora

  • Follow the instructions here to enable the EPEL repository for RHEL7
  • Run the following to install the mantid-developer package
# Install copr plugin
yum install yum-plugin-copr

# Enable the mantid repo from copr
yum copr enable mantid/mantid

# Install dependencies
yum install mantid-developer

# Install pre-commit
pip3 install pre-commit --user

On fedora, the yum commands should be replaced with dnf. For systems with default python3 the pip3 command can be replaced with pip, but it should work either way.

Make sure you install devtoolset-7 as described in the link.

Now you can get the mantid code, and build it:

mkdir build
cd build
scl enable devtoolset-7 "cmake3 [mantid source]"
cmake3 --build .

See the instructions on this page to run the Mantid unit tests.

Ubuntu 18.04

apt install gdebi-core
gdebi ~/Downloads/mantid-developer.X.Y.Z.deb

where X.Y.Z should be replaced with the version that was downloaded.

Install pre-commit for use in our current developer workflow

pip install pre-commit --user

if you wish to setup eclipse for use developing mantid, then instructions can be found here.

Now you can get the mantid code, and build it:

mkdir build
cd build
cmake -GNinja [mantid source]
cmake --build .

See the instructions on this page to run the Mantid unit tests.

Ubuntu 20.04

  • Mantid uses qtpy to talk to Python bindings of Qt. It is recommended to have the _ environment var QT_API=pyqt5 exported to the shell before building with CMake.
  • The header and lib shipped with Anaconda (if installed) could interfere with Mantid building _ process. It is highly recommended to remove Anaconda Python from your env prior to building _ using conda deactivate.
  • Mantid is not yet officially supported on Ubuntu 20.04, but mantid-developer package (see Ubuntu 18.04 instructions) has been modified to support it.
  • Install pre-commit for use in our current developer workflow
pip install pre-commit --user

OSX

The build environment on OS X is described here Building on OS X.

Install pre-commit for use in our current developer workflow

brew install pre-commit

Docker

On Docker supported systems you may use the mantid-development images to develop Mantid without having to configure your system as a suitable build environment. This will give you an out of the box working build environment, Python 3 (where available) and ccache.

More details and instructions can be found at the GitHub link above.

Getting the Mantid code

We use Git as our version control system (VCS). The master copies of our repositories are located at GitHub. We have a number of repositories, of which the main one (the one containing all the source code for Mantid itself) is called simply mantid.

If you are not already set up with Git, you can follow these instructions.

There are a number of URLs via which the code can be checked out using various protocols. The easiest way to get the one you want is to select the protocol you want on the right side of the mantid repository page on github and copy the url into your clipboard. The way to clone the repository via ssh on the command line, into a directory called Mantid, is:

git clone git@github.com:mantidproject/mantid.git

Alternatively, one can use the https protocol for cloning the repository. This requires one to supply an authentication token when pushing or re-type their password.

git clone https://github.com/mantidproject/mantid.git

Custom git setup for inside the ORNL firewall:

Due to security configuration at ORNL one needs to do additional configuration to access github from within the lab. One option is to use the https protocol listed above The alternative is to “corkscrew the snowman” which allows for using the git protocol by modifying the ssh configuration. Corkscrew can be installed from your package manager, or it is a single c file found on github. Add the following lines to ~/.ssh/config:

ProxyCommand corkscrew snowman.ornl.gov 3128 %h %p
Host github.com

If you need further help, ask another developer at the facility how to configure the corkscrew option.

Setting up GitHub

Please install the ZenHub Browser extension from this page.

Building Mantid

See Building with CMake for information about building Mantid.

Archive access - ISIS

It is very convenient to be able to access the data archive directly. At ISIS, this is automatically done on the Windows machines, however OSX and Linux require some extra setup.

OSX

  • In Finder “command”+k opens a mounting dialogue
  • For Server address enter smb://isisdatar80/inst$/ hit Connect
  • This should prompt you for federal ID clrc…. and password
  • After completing this the drive is now mounted
  • It can be found at /Volumes/inst$

NB the address in step 2 sometimes changes - if it does not work, replace 80 with 55 or 3.

Linux

  1. Install packages:

sudo apt-get install -y autofs cifs-utils keyutils

  1. Create an /archive.creds file in the root directory containing this, filling in the relevant details:

This should only be done if full disk encryption is enabled or if the archive.creds file is stored in a secure (encrypted) location; to ensure passwords are kept safe.

username=FEDERAL_ID_HERE
password=FED_PASSWD_HERE
domain=CLRC
  1. Edit /etc/auto.master and add the line:
/archive      /etc/auto.archive
  1. Create /etc/auto.archive and add the single line:
*     -fstype=cifs,ro,credentials=/archive.creds,file_mode=0444,dir_mode=0555,vers=3.0,noserverino,nounix    ://isis.cclrc.ac.uk/inst\$/&
  1. Enter the following commands:
sudo chmod 400 /archive.creds
sudo mkdir /archive
service autofs restart

Done. You can now access directories in the archive. Test it by doing:

ls /archive/ndxalf

If it’s working the command should return ls: cannot access '/archive/ndxalf/DfsrPrivate': Permission denied