Commit 8006ff60 authored by Lukas Riedel's avatar Lukas Riedel

Merge branch 'feature/improve-readme' into 'master'

improve readme installation instructions

Closes #13 and #30

See merge request !18
parents c7099e2c 3f8930c0
......@@ -12,11 +12,13 @@ DORiE is developed and maintained by the [DORiE Developers](mailto:dorieteam@iup
# Installation Instructions
DORiE is a [DUNE](https://dune-project.org/) module and requires several other DUNE modules as well as third party software packages. Installation can be handled manually on your local machine, but for inexperienced users it is recommended to use the deployment software [Docker](https://www.docker.com/) instead.
In any case, DORiE is configured, built, and installed via the [DUNE Buildsystem](https://dune-project.org/doc/installation/), using the `dunecontrol` script to handle DUNE-internal dependencies.
## Docker Installation - Simple Setup
This setup is intended for users who simply want to start computations with DORiE.
Install Docker on your machine. Then, use `git clone` to download the DORiE repository into a suitable directory on your machine. Enter the directory, and call
......@@ -31,38 +33,9 @@ The `-v` option tells docker to mount the directory into the container work dire
In the section 'Usage' you will find a list of possible commands. Note that input and output files can only be placed in the `<dir>` directory or subdirectories thereof. You must use relative paths in the DORiE configuration files.
## Docker Installation - Interactive Setup
This setup is intended for advanced users. You will gain access to the DORiE module outside the container, and be able to make changes to the source code.
We have prepared a [DORiE DUNE Environment Image on Dockerhub](https://hub.docker.com/r/dorie/dune-env/), which is a modified image of the Ubuntu OS that has all dependencies readily installed. The current version is 2.5.1 (referencing the DUNE module version 2.5). We will run a new container from this image and mount some local directory `<hostdir>/dorie` into it by calling
docker run -v <hostdir>/dorie:/opt/dune/dorie -i -t dorie/dune-env:2.5.1 /bin/bash
Docker will automatically download the image if necessary. Now you can access the content of the (still empty) folder of the virtual machine from your local `<hostdir>/dorie` directory. *Mounting directories is not possible after your container has been started!*
Next, use `git clone` to download the DORiE repository into the shared (mounted) folder. Enter the container, and execute
dunecontrol --only=dorie all
to build DORiE, or
MAKE_FLAGS="-j <N>" dunecontrol --only=dorie all
to build in parallel on `N` processes. Lastly, install the DORiE binaries by calling
dunecontrol --only=dorie make install
### Update DUNE
The DUNE modules (as well as DORiE itself) in the repository might be outdated. You can update to the newest versions by calling
dunecontrol update
Then compile and install all modules again by executing
dunecontrol all && dunecontrol make install
## Manual Installation
Installing all packages manually can be quite an effort, but useful for developers who want to have easy access to the source files or users who prefer to run DORiE without the Docker overhead.
Whenever possible, dependencies should be installed using a package manager, like [APT](https://wiki.ubuntuusers.de/APT/) on Ubuntu or [Homebrew](http://brew.sh/) on Mac. Manual installation on a Windows environment is strongly discouraged!
......@@ -78,11 +51,10 @@ Depending on your system configuration, there will be more packages necessary to
| pkg-config |
| HDF5 | | with MPI support
| FFTW3 | | with MPI support
| Python | 2.7 or 3.x |
| pip | 2.7 or 3.x |
| Python | 3.x |
| pip | 3.x |
| MPI | | Tested with OpenMPI
| SuperLU | 4.3 or 5.x |
| VirtualEnv | | For Python 2 only. Install via `pip` |
| [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.5
| [dune-geometry](https://gitlab.dune-project.org/core/dune-geometry) | releases/2.5
| [dune-grid](https://gitlab.dune-project.org/core/dune-grid) | releases/2.5
......@@ -99,13 +71,19 @@ Depending on your system configuration, there will be more packages necessary to
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | master | Handles system tests
| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | | Builds documentation
| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | | Builds documentation
| [METIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 5 | For parallel runs
| [ParMETIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 4 | For parallel runs
### Step-by-step Instructions
These instructions are suitable for a clean **Ubuntu** or **Mac OS X** setup. The main difference between the two systems is the package manager. Debian-based systems have the APT manager already built in. On Mac, we recommend installing [Homebrew](http://brew.sh/). If you prefer to use [MacPorts](https://www.macports.org/), you need to check if some of the packages require different installation options than displayed here.
These instructions are suitable for a clean **Ubuntu** or **Mac OS X** setup. The main difference between the two systems is the package manager. Debian-based systems have the APT manager already built in. On Mac, we recommend installing [Homebrew](http://brew.sh/). If you prefer to use [MacPorts](https://www.macports.org/), you need to check if some of the packages require different installation options than displayed here.
If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.html) on your machine, you don't need to install Python or Pip. Simply skip these packages when using the package managers for installing the software. However, notice the warnings when compiling DORiE below!
1. **Mac OS X** users need to start by installing the Apple Command Line Tools by executing
xcode-select --install
1. Install third party packages:
......@@ -131,9 +109,7 @@ These instructions are suitable for a clean **Ubuntu** or **Mac OS X** setup. Th
apt install libmetis-dev libparmetis-dev
**Mac OS X:**
brew install metis parmetis
**Mac OS X:** _Support is dropped because ParMETIS is currently unavailable from Homebrew._
**Parallel runs without these two packages are possible but not supported!**
......@@ -145,11 +121,19 @@ These instructions are suitable for a clean **Ubuntu** or **Mac OS X** setup. Th
to enfore the Homebrew'd GCC compiler. Note that this variable export only lasts for your current terminal session. Always make sure that the configuration tool actually finds GCC instead of the Apple Clang.
4. Clone the DUNE modules and DORiE into a suitable folder on your machine. Make sure that you check out the correct branches (see above). Enter the parent folder, and call
4. Clone the DUNE modules and DORiE into a suitable folder on your machine. Use `git checkout` to switch to the correct branches (see above). Enter the parent folder, and call
CMAKE_FLAGS="-DDUNE_PYTHON_VIRTUALENV_SETUP=True -DDUNE_PYTHON_ALLOW_GET_PIP=True" ./dune-common/bin/dunecontrol all
to build all DUNE modules. Additionally, you can add `MAKE_FLAGS="-j X"` before the call to `dunecontrol` to compile on `X` processes in parallel.
If you installed software into paths not appended to your `PATH` variable, you will have to add `CMAKE_FLAGS` to the call to make sure that CMake finds all packages. Alternatively, you can add a custom options file. See the [DUNE Installation Instructions](https://dune-project.org/doc/installation/) for details. CMake will throw an error if required packages are not found.
**Warning:** Anacoda supplies its own version of HDF5 which is typically found first by CMake. If you have Anaconda installed on your machine, add
CMAKE_FLAGS="-DDUNE_PYTHON_VIRTUALENV_SETUP=True -DDUNE_PYTHON_ALLOW_GET_PIP=True" MAKE_FLAGS="-j <N>" ./dune-common/bin/dunecontrol all
HDF5_ROOT=/usr/local
to build all DUNE modules in parallel on `N` processes. If you installed software into paths not appended to your `PATH` variable, you will have to add `CMAKE_FLAGS` to the call to make sure that CMake finds all packages. Alternatively, you can add a custom options file. See the [DUNE Installation Instructions](https://dune-project.org/doc/installation/) for details. CMake will throw an error if required packages are not found.
to the `CMAKE_FLAGS` in the call to `dunecontrol` above.
5. After a successful build you can call the `dorie` wrapper located in `dorie/build-cmake/bin` from anywhere on your machine, but it is more handy to add this location to your search path. You can add the directory to your `PATH` variable by calling
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment