From dc2ca27d70ebc1680ce5f2ad710b1f36b7afb47a Mon Sep 17 00:00:00 2001 From: Fabian Castelli Date: Tue, 25 May 2021 20:46:35 +0200 Subject: [PATCH] Update readme --- README.md | 91 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 62 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index e45f03b..6961364 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ The ``candi.sh`` shell script downloads, configures, builds, and installs [deal.II](https://github.com/dealii/dealii) with common dependencies on linux-based systems. + + Quickstart ---- @@ -12,14 +14,15 @@ The following commands download the current stable 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 + git clone https://github.com/dealii/candi.git + cd candi + ./candi.sh ``` 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 26,27,28: @@ -35,29 +38,24 @@ Follow the instructions on the screen #### Install deal.II on macOS (10.11), 10.12, 10.13: ```bash - ./candi.sh + ./candi.sh ``` #### Install deal.II on Windows 10 (1709): Since the Creators Update in fall 2017 (Windows 10 (1709)) the Windows Subsystem for Linux (WSL) is an official part. -Install ubuntu from the Store. -Then enable the WSL feature, -e.g. by opening a PowerShell as Administrator and run: -```bash - Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -``` -You need to reboot your system afterwards. +For an detailed instruction how to install WSL and a recent Ubuntu distribution +on Windows 10 you can follow the Microsoft Documentation. Within the ubuntu terminal application clone this repository and run candi ```bash - sudo apt-get update - sudo apt-get upgrade - git clone https://github.com/dealii/candi - cd candi - ./candi.sh + sudo apt-get update + sudo apt-get upgrade + git clone https://github.com/dealii/candi.git + cd candi + ./candi.sh ``` #### Install deal.II on a generic Linux system or cluster: @@ -72,10 +70,10 @@ the path to ``BLAS`` and ``LAPACK`` in the configuration file #### Install deal.II on a system without pre-installed git: ```bash - wget https://github.com/dealii/candi/archive/master.tar.gz - tar -xzf master.tar.gz - cd candi-master - ./candi.sh + wget https://github.com/dealii/candi/archive/master.tar.gz + tar -xzf master.tar.gz + cd candi-master + ./candi.sh ``` Note that in this case you will need to activate the installation of git by @@ -83,12 +81,13 @@ uncommenting the line `#PACKAGES="${PACKAGES} once:git"` in [candi.cfg](candi.cfg). + Advanced Configuration ---- ### Command line options -#### Help: `[-h]` +#### Help: ``[-h]``, ``[--help]`` You can get a list of all command line options by running ```bash ./candi.sh -h @@ -107,14 +106,27 @@ You can combine the command line options given below. ``` * 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). +* Be careful with this option! You need to have enough system memory (e.g. at + least 8GB for 2 or more processes). + +#### Specific platform: ``[-pf=]``, ``[--platform=]`` +```bash + ./candi.sh -pf=./deal.II-toolchain/platforms/... +``` + +If your platform is not detected automatically you can specify it with this +option manually. As shown above, this option is used to install deal.II via +candi on linux clusters, for example. For a complete list of supported platforms +see [deal.II-toolchain/platforms](deal.II-toolchain/platforms). #### User interaction: ``[-y]``, ``[--yes]``, ``[--assume-yes]`` ```bash ./candi.sh -y ``` -With this option you skip the user interaction. This might be useful if you submit the installation to the queueing system of a cluster. +With this option you skip the user interaction. This might be useful if you +submit the installation to the queueing system of a cluster. + ### Configuration file options @@ -132,17 +144,38 @@ Currently, we provide the packages * hdf5 * opencascade -and others. For a complete list see [deal.II-toolchain/packages](deal.II-toolchain/packages). +and others. For a complete list see +[deal.II-toolchain/packages](deal.II-toolchain/packages). + +There are several options within the configuration file, for example: + +* Remove existing build directories to use always a fresh setup +```bash + CLEAN_BUILD={ON|OFF} +``` -There are several other options within the configuration file, e.g. +* Enable native compiler optimizations like ``-march=native`` +```bash + NATIVE_OPTIMIZATIONS={ON|OFF} +``` -* 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, +* Enable the build of the deal.II examples and documentation +```bash + BUILD_DOCUMENTATION={ON|OFF} + BUILD_EXAMPLES={ON|OFF} +``` and more. +Furthermore you can specify the install directory and other internal +directories, where the source and build files are stored: +* 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 + + ### Single package installation mode If you prefer to install only a single package, you can do so by -- 2.39.5