Building mantid tutorial 2023-06-01

building-mantid.md

class: center, middle

Building mantid on the analysis cluster

... works on your ubuntu laptop too

??? to view python3 -m http.server then open a browser at http://0.0.0.0:8000/presentation.html

---

class: left, middle, inverse

Assumptions/prerequisites:

• building on linux (analysis cluster or laptop)
• clone of main mantid git repository

Things not covered:

• individual tool setups (e.g. IDEs)
• mantid concepts (e.g. workspaces and algorithms)
• contributing to mantid

---

class: left, middle

Agenda

The training will run in "two" sessions:

• Pre-requisites: clone of mantid, conda environment
• Morning: high-level, run cmake, ninja KernelTest
• Homework between sessions: ninja all AllTests
• Afternoon: everything else

---

Pre-requisites

Look at the getting started guide and linux with conda

Use alternate port ~/.ssh/config

Host github.com
    Hostname ssh.github.com
    Port 443

-- Clone repository and activate conda

cd
mkdir code
cd code
git clone git@github.com:mantidproject/mantid.git
source /opt/anaconda/bin/activate
conda activate mantid-developer

List of cmake generators in case the default (ninja) isn't what you want

The environment was created from mantid-developer-linux.yml

---

class: left, middle

Morning session

• high-level information
• run cmake
• ninja KernelTest
• run a unit test

---

Setup build area

cd
mkdir code
mkdir -p build/mantid

-- clone the repository

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

---

First build

cd ~/build/mantid
source /opt/anaconda/bin/activate
conda activate mantid-developer
cmake ~/code/mantid --preset=linux -B ${PWD} -DCMAKE_BUILD_TYPE=RelWithDebInfo
ninja  KernelTest

---

direnv - unclutter your .profile

in sourcetree ~/code/.envrc

layout anaconda mantid-developer /opt/anaconda/bin/conda

in buildtree ~/build/mantid/.envrc

layout anaconda mantid-developer /opt/anaconda/bin/conda
export PYTHONPATH=./bin/:${PYTHONPATH}

-- Alternate

source /opt/anaconda/bin/activate
conda activate mantid-developer

---

Run the test

Using ctest

ctest -R KernelTest_TimeSeriesPropertyTest

-- By hand

./bin/KernelTest TimeSeriesPropertyTest

-- With gdb

gdb --args ./bin/KernelTest TimeSeriesPropertyTest

-- All together

ninja  KernelTest && ctest -R KernelTest_TimeSeriesPropertyTest

---

Homework

• build mantidworkbench and start it

--

• Hint: it is part of the all target

--

• Hint: bin/launch_mantidworkbench.sh

---

Afternoon session

• Some background
• High level view of mantid's cmake external data
• Building/running a single unit test in C++ and python (link to gdb instructions )
• Building documentation
• Running single doctests
• Running single system test

---

Some background

• ISIS start Mantid in 2008

• ORNL joined the project in mid-2010

• Mantid started using cmake in late 2010 --

• RHEL7 released in 2014

• ninja as preferred build tool

• ccache configuration --

• v6.3.0 (Feb 2022) conda packages for all platforms

---

Top level directories

• .github - issue templates
• Framework - objects, algorithms, etc
• Testing - data, system tests, cxxtest framework
• buildconfig - cmake modules, CI scripts, etc
• conda/recipes - conda
• dev-docs - source for developer.mantidproject.org
• docs - source for docs.mantidproject.org
• external - cmake downloads external projects here
• images
• installers/conda
• instrument - IDF and sample environments
• qt - mantidqt and mantidworkbench
• scripts - random python code
• tools - random developer code

---

System tests

./systemtest -R CodeConventions

-- What effecitvely happens

cmake --build . -- StandardTestData
cmake --build . -- SystemTestData
# mess with the PYTHONPATH
python ..../runSystemTests.py -R CodeConventions

---

External data

.center[]

• https://testdata.mantidproject (and other places)
• ~/MantidExternalDataMD5/affe68aca428fbaade81fc6ac3a5fb28
• Testing/Data/SystemTest/EVS15036.raw.md5
  • contents affe68aca428fbaade81fc6ac3a5fb28
• ExternalData/Testing/Data/SystemTest/EVS15036.raw

-- .bottom.center.bold[To get new files need to run cmake . in the build tree]

---

Starting mantidworkbench

./bin/launch_mantidworkbench.sh --version

./bin/launch_mantidworkbench.sh --help

./bin/launch_mantidworkbench.sh --debug -x myawesomescript.py

---

Building documentation

ninja help | grep docs

--

ninja dev-docs-html
ls dev-docs/

---

Usage tests/doctests

Rebin user docs

--

cd ~/build/mantid
python -m sphinx --no-color -b doctest -d docs/doctrees \
    ~/code/mantid/docs/source docs/doctest \
    ~/code/mantid/docs/source/path-to-file.rst

presentation.html

<!DOCTYPE html>
<html>
  <head>
    <title>Building mantid</title>
    <meta charset="utf-8">
    <style>
      @import url(https://fonts.googleapis.com/css?family=Yanone+Kaffeesatz);
      @import url(https://fonts.googleapis.com/css?family=Droid+Serif:400,700,400italic);
      @import url(https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700,400italic);

      body { font-family: 'Droid Serif'; }
      h1, h2, h3 {
        font-family: 'Yanone Kaffeesatz';
        font-weight: normal;
      }
      .remark-code, .remark-inline-code { font-family: 'Ubuntu Mono'; }
    </style>
  </head>
  <body>
    <script src="https://remarkjs.com/downloads/remark-latest.min.js">
    </script>
    <script>
      var slideshow = remark.create({sourceUrl: 'building-mantid.md'});
    </script>
  </body>
</html>