Commit d9e14bc4 authored by Lukas Riedel's avatar Lukas Riedel

removed deprecated installation instructions and reference Readme instead

parent 216beaf9
============
############
Installation
============
############
.. contents::
.. _readme:
***********
ReadMe File
-----------
***********
.. toctree::
:maxdepth: 1
README
************
Preparations
************
Prerequisites
#############
=============
To install and run DORiE, your computer needs to meet the following requirements:
- 64-bit version of Linux or OSX
- 64-bit version of Linux, macOS, or Windows
- Intel i5 processor or equivalent
- Intel i3/5/7 2xxx processor with at least two cores, or equivalent
- at least 4GB of RAM (8GB or more recommended)
- about 10GB of free disk space
Cloning The Repository
######################
======================
Create a new folder at a suitable location on your machine. Navigate to it, and
clone the DORiE repository by executing
.. code-block:: shell
git clone ssh://git@shangrila.iup.uni-heidelberg.de:30001/dorie/dorie.git
git clone ssh://git@zwackelmann.iup.uni-heidelberg.de:10022/dorie/dorie.git
in the terminal. By default, the remote host will be called ``origin``, and the
``master`` branch will be checked out. If you wish to checkout another branch, do so by calling
......@@ -44,14 +48,26 @@ in the terminal. By default, the remote host will be called ``origin``, and the
git checkout --track origin/<branch>
from a terminal inside the repository folder. Refer to our `Git Tutorial <http://shangrila.iup.uni-heidelberg.de:30000/dorie/dorie/wikis/git-tutorial>`_ for more information on using Git.
from a terminal inside the repository folder. Refer to the `Atlassian Git Tutorial <https://www.atlassian.com/git>`_ for more information on using Git.
.. _installation:
************
Installation
************
You can build DORiE locally on your machine for maximum performance. This requires you to take care of all dependencies and to handle the installation process yourself. On the other hand, you can use a virtual environment to run DORiE. We support this feature by using `Docker <https://www.docker.com/>`_. You can install DORiE into a Docker image and then execute a container from it for your computations. Depending on your operating system, this will lead to impared performance.
Follow the Installation Instructions in the :doc:`the ReadMe <README>` for installing DORiE.
Notice also the instructions below for setting up your computer to meet the most basic requirements to run DORiE.
Preparations
############
OSX
---
OS-Dependent Configuration
==========================
macOS
-----
The first thing you will have to do is to install Apple's Command Line Tools which
are bundled into the XCode software package. On more recent versions of OSX, this
can be done conveniently by executing
......@@ -78,141 +94,15 @@ You are now ready to :ref:`install DORiE <installation>`.
Linux
-----
Since there is a multitude of different Linux distributions, we cannot provide
installation instructions for all of them. DORiE is regularly tested on Ubuntu
14.04 LTS, so if you are running this OS, you may proceed with the
installation instructions for all of them. DORiE is regularly tested on the latest stable version of Ubuntu, so if you are running this OS, you may proceed with the
:ref:`installation <installation>` right away.
On any other distribution, you are responsible for installing the binary dependencies
yourself before proceeding. Running :option:`install.sh --no-deps` will tell you
which binary packages need to be installed. After ``install.sh --no-deps`` ran
successfully, you may proceed with using :ref:`doriecontrol`.
.. _installation:
Installation
############
The easiest way to install DORiE is to use the installation scripts provided. The first one is called
:ref:`install.sh` and is a simple shell script that
- tries to install some large binary dependencies through your system's package manager (MacPorts on OSX, :command:`apt-get` on Linux),
- creates symbolic links in the :file:`links/` folder, to set the standard software used by DORiE,
- sets the path to your installation in the :ref:`doriecontrol` and :ref:`dorie` scripts,
- places symbolic links to those two scripts into :file:`/usr/local/bin`, so you can call them from anywhere.
After cloning the repository, you can just execute the installation script by opening a Terminal, navigating to the repository
and executing the command
.. code-block:: shell
bash install.sh
.. _doriecontrol:
After the script ran successfully, you are ready to use ``doriecontrol``. Call
.. code-block:: shell
doriecontrol install core
(only installs minimum libraries to run DORiE)
or
.. code-block:: shell
doriecontrol install all
(installs additional tools to build the documentation or run system tests)
from anywhere on your computer, and all dependencies will be installed along with DORiE.
If you did not encounter any errors and DORiE was installed successfully, you are ready
to start :ref:`your first run <quickstart-cookbook>`!
Customize your installation
###########################
There are multiple ways to customize your installation, in case you want to change how dependencies
are handled, customize the folder structure, or to resolve errors.
Options for install.sh
----------------------
.. _install.sh:
.. object:: install.sh
This script accepts various command line arguments:
.. program:: install.sh
.. option:: --no-deps
Skips the installation of binary dependencies.
.. option:: --local <FOLDER>
Keeps everything local, preventing DORiE from installing
anything system-wide. Use this if you do not have :command:`sudo` access.
FOLDER points to the path where the symbolic links to :ref:`doriecontrol` and :ref:`dorie`
are placed. This makes it e.g. possible to use :file:`~/bin` as an installation location,
which is on the system :envvar:`PATH` on many operating systems.
.. option:: --system-mp
Forces this script to use the first MacPorts executable found, even when installing with
:option:`install.sh --local`. Use this on OSX, if you already have MacPorts installed and
want DORiE to use it.
.. option:: --serial
Builds MacPorts serially.
.. option:: --parallel <NPROC>
Builds MacPorts in parallel on NPROC processes (default: number of CPUs)
Change standard packages
------------------------
:ref:`install.sh` creates links to some third-party software required to install DORiE
(such as the GNU compilers, or Python) in the :file:`links/` folder, located in the
parent folder of the repository.
If for some reason you would like DORiE to use a different version than the one
:ref:`install.sh` has auto-detected for you, or if the auto-detection has failed,
you can just change the symbolic links there using the :cmd:`ln -s` shell command.
One example: (assuming your current working directory is the repository folder)
.. code-block:: shell
rm links/gcc links/g++ links/gfortran
ln -s /usr/bin/gcc-4.8 links/gcc
ln -s /usr/bin/g++-4.8 links/gcc
ln -s /usr/bin/gfortran-4.8 links/gcc
This makes DORiE use version 4.8 of the GNU compilers instead of version 5.x.
On any other distribution, the procedure of installing dependencies might differ from the step-by-step instructions supplied in :doc:`the ReadMe <README>`.
Installing DORiE into a custom DUNE environment
-----------------------------------------------
Even though the DORiE installation is designed to be as easy as possible, advanced users
might want to install DORiE into a custom DUNE environment (e.g. because they already
have an installation of DUNE on their machine and are comfortable with installing all
dependencies themselves). This way to install DORiE, albeit not officially supported,
is certainly possible. It should be sufficient to copy the folder :file:`dorie/` into
your DUNE environment and install it with ``dunecontrol``.
Windows
-------
Local builds of DUNE and DORiE on Windows are not supported. Please use the Docker installation variant on this system. Docker is available for 64-bit versions of Windows 7 or later. We recommend using Windows 10 Professional or Enterprise. Please refer to the Docker Manual on Windows for further details.
In case you run into errors, you can have a look at the file :file:`doriecontrol.in`,
especially at the creation of the :file:`dune.opts`-file.
If you run another version of Windows than the recommended ones, you have to install the `Docker Toolbox <https://docs.docker.com/toolbox/overview/>`_, to enable the virtualization features necessary for Docker.
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