From: Uwe Köcher <koecher@hsu-hamburg.de>
Date: Tue, 14 Feb 2017 08:56:44 +0000 (+0100)
Subject: updates and enhances README.md
X-Git-Tag: v0.8.5~29^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=45b66cbbe93e00014fa7945b852531e8b91367df;p=candi.git

updates and enhances README.md
---

diff --git a/README.md b/README.md
index 9d9b1c7..b82efb7 100644
--- a/README.md
+++ b/README.md
@@ -1,78 +1,124 @@
 candi (Compile &amp; Install)
 =====
 
-This shell script downloads, configures, builds, and installs deal.II with common dependencies on linux-based systems.
+The ``candi.sh`` shell script downloads, configures, builds, and installs deal.II
+with common dependencies on linux-based systems.
 
 Quickstart
 ----
 
-The following commands download the current version of the installer and then installs
-the latest deal.II release and common dependencies:
+The following commands download the current version of the installer and
+then install the latest deal.II release and common dependencies:
 
 ```bash
  git clone https://github.com/dealii/candi
  cd candi
- ./candi.sh -j2
+ ./candi.sh
 ```
 
-Follow the instructions on the screen (you can abort the process by pressing < CTRL > + C)
+Follow the instructions on the screen
+(you can abort the process by pressing < CTRL > + C)
 
 ### Examples
 
-#### Install deal.II on RHEL 7, CentOS 7 or Fedora 21/22:
+#### Install deal.II on RHEL 7, CentOS 7 or Fedora 23,24,25:
 ```bash
   module load mpi/openmpi-`uname -i`
   export CC=mpicc; export CXX=mpicxx; export FC=mpif90; export FF=mpif77
   ./candi.sh
 ```
 
-#### Install deal.II on ubuntu 12.04, 14.xx, 15.xx:
+#### Install deal.II on ubuntu 12.04, 14.xx, 15.xx, 16.xx:
 ```bash
   export CC=mpicc; export CXX=mpicxx; export FC=mpif90; export FF=mpif77
   ./candi.sh
 ```
 
-#### Install deal.II on a generic Linux cluster:
+#### Install deal.II on a generic Linux system or cluster:
 ```bash
   export CC=mpicc, export CXX=mpicxx; export FC=mpif90; export FF=mpif77
   ./candi.sh --platform=./deal.II-toolchain/platforms/supported/linux_cluster.platform
 ```
-Note that you probably also want to change the prefix path (see below) and 
-the path to BLAS and LAPACK in the configuration file (see below).
 
-Adapting candi to your needs
+Note that you probably also want to change the prefix path, or 
+the path to ``BLAS`` and ``LAPACK`` in the configuration file
+(see documentation below).
+
+Advanced Configuration
 ----
 
 ### Command line options
 
-You can get a list of all options by running ``./candi.sh -h``
+#### Help: `[-h]`
+You can get a list of all command line options by running
+```bash
+  ./candi.sh -h
+```
 
 You can combine the command line options given below.
 
-#### Prefix path: `[-p=<PATH>]`, `[--prefix=<PATH>]`
+#### Prefix path: ``[-p=<PATH>]``, ``[--prefix=<PATH>]``
 ```bash
   ./candi.sh --prefix=Your/Prefix/Path
 ```
 
-#### Multiple build processes: `[-j <N>]`, `[-j<N>]`, `[--PROCS=<N>]`
+#### Multiple build processes: ``[-j <N>]``, ``[--PROCS=<N>]``
 ```bash
   ./candi.sh -j <N>
 ```
 
-* Example: to use 2 build processes type `./candi.sh -j2`.
+* Example: to use 2 build processes type ``./candi.sh -j 2``.
 * Be careful with this option! You need to have enough system memory (e.g. at least 8GB for 2 or more processes).
 
 ### Configuration file options
 
-Edit the configuration file behind the file "candi.cfg", e.g.
+If you want to change the set of packages to be installed,
+you can enable or disable a package in the configuration file
+``candi.cfg``.
+This file is a simple text file and can be changed with any text editor.
+
+Currently, we provide the packages
+
+* trilinos
+* petsc, slepc
+* superlu_dist (to be used with trilinos)
+* p4est
+* hdf5
+* opencascade
+
+for instance.
+
+There are several other options within the configuration file, e.g.
+
+* the ``DOWNLOAD_PATH`` folder (can be safely removed after installation),
+* the ``UNPACK_PATH`` folder of the downloaded packages (can be safely removed after installation),
+* the ``BUILD_PATH`` folder (can be safely removed after installation),
+* the ``INSTALL_PATH`` destination folder,
+
+and more.
+
+### Single package installation mode
+
+If you prefer to install only a single package, you can do so by
 ```bash
-  gedit candi.cfg
+  ./candi.sh --packages="dealii"
 ```
+for instance, or a set of packages by
+```bash
+  ./candi.sh --packages="opencascade petsc"
+```
+
+### Developer mode
+
+Our installer provides a software developer mode by setting
+``DEVELOPER_MODE=ON``
+within ``candi.cfg``.
 
-You can adapt several things to your personal needs here
-* the `DOWNLOAD_PATH` folder (can be safely removed after installation),
-* the `UNPACK_PATH` folder of the downloaded packages (can be safely removed after installation),
-* the `BUILD_PATH` folder (can be safely removed after installation),
-* the `INSTALL_PATH` destination folder,
+More precisely, the developer mode skips the package ``fetch`` and ``unpack``,
+everything else (package configuration, building and installation) is done
+as before.
 
-and more options.
+Note that you need to have a previous run of candi and
+you must not remove the ``UNPACK_PATH`` directory.
+Then you can modify source files in ``UNPACK_PATH`` of a package and
+run candi again.