diff --git a/building/prereq-centos7.md b/building/prereq-centos7.md index ddf517d0..62b6ed47 100644 --- a/building/prereq-centos7.md +++ b/building/prereq-centos7.md @@ -1,100 +1,56 @@ -aliBuild prerequisites for CentOS 7 +aliBuild Prerequisites for CentOS 7 =================================== -For ALICE O2, our policy is [to support CERN CentOS 7 as our official deployment -platform](https://indico.cern.ch/event/642232/#3-wp3-common-tools-and-softwar). CERN CentOS 7 is -essentially a CentOS 7 with some more CERN-specific packages, so these instructions apply to the -pristine CentOS 7 as well. +For ALICE O2, CERN CentOS 7 (CC7)is the [officialy supported target platform](https://indico.cern.ch/event/642232/#3-wp3-common-tools-and-softwar). Since CC7 is CentOS 7 with additional CERN packages, instructions apply to vanilla CentOS 7 as well. -As the primary supported platform, our [alidock](https://github.com/alidock/alidock/wiki) -installation method is based on it. If you use alidock, you don't need to follow those -prerequisites. The environment we provide is ready to use. +## Install or Upgrade the Required Packages - -## Install or upgrade the required packages - -Install packages (one long line, just copy and paste it), as **root user**: +With root permissions, i.e. `sudo` or as `root` install the prerequisites using: ```bash -yum install -y python git mysql-devel curl curl-devel python python-devel python-pip bzip2 bzip2-devel unzip autoconf automake texinfo gettext gettext-devel libtool freetype freetype-devel libpng libpng-devel sqlite sqlite-devel ncurses-devel mesa-libGLU-devel libX11-devel libXpm-devel libXext-devel libXft-devel libxml2 libxml2-devel motif motif-devel kernel-devel pciutils-devel kmod-devel bison flex perl-ExtUtils-Embed environment-modules tk-devel +yum install -y git mysql-devel curl curl-devel bzip2 bzip2-devel unzip autoconf automake texinfo gettext gettext-devel libtool freetype freetype-devel libpng libpng-devel sqlite sqlite-devel ncurses-devel mesa-libGLU-devel libX11-devel libXpm-devel libXext-devel libXft-devel libxml2 libxml2-devel motif motif-devel kernel-devel pciutils-devel kmod-devel bison flex perl-ExtUtils-Embed environment-modules tk-devel ``` -Now get a recent version of `pip` (the Python package manager): this is required for installing aliBuild and other Python dependencies. Do, always as **root user**: - - -``` -curl -o /tmp/get-pip.py https://bootstrap.pypa.io/get-pip.py -python /tmp/get-pip.py -``` - -Now get some Python dependencies (again **as root user**): - +## Python and pip +AliBuild, our build tool, is installed via the python Package manager `pip`. +In case +```bash +pip3 show pip +``` +returns `command not found` or similar, install `pip` with root permissions, i.e. `sudo` or as `root`: ```bash -pip install matplotlib==2.0.2 numpy certifi ipython==5.1.0 ipywidgets ipykernel notebook metakernel pyyaml +yum install -y python3-pip +pip3 install --upgrade pip ``` +## Get or Update Developer Toolset 7 -## Get or update the compiler from Devtoolset +We require a more recent set of compilers than shipped by the OS. They can be obtained via [Softawre +Collections](https://www.softwarecollections.org/). -The default compiler on CentOS 7 is quite old. Luckily, [Softawre -Collections](https://www.softwarecollections.org/) has RPMs for recent versions of GCC. - -{% callout "Developer Toolset version" %} -CC7 with the Developer Toolset is the default OS for ALICE O2 operations, therefore we take -particular care about compatibility and upgrading our recommendations. Our policy is to never -upgrade O2 to a newer compiler unless the corresponding Developer Toolset package is out and tested. - -Every recommendation change concerning the Develpoer Toolset versions is reviewed, discussed and -voted. The **current situation (July 2018)** is: - -* [devtoolset-7](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-7/) (GCC v7.3.1) is - the currently **approved and working** version for O2. - -**Please make sure your `devtoolset-7` is up-to-date!** Due to -[a bug](https://bugzilla.redhat.com/show_bug.cgi?id=1519073), versions of `devtoolset-7` with GCC -v7.2.1 do not work. - -All versions other than the very latest `devtoolset-7` are to be considered unsupported. -{% endcallout %} - -First off, enable Software Collections: +The only supported Developer Toolset for ALICE software is `devtoolset-7`. +With root permissions, i.e. `sudo` or as `root` enable software collections: ```bash yum install -y centos-release-scl yum-config-manager --enable rhel-server-rhscl-7-rpms ``` - -Get the compiler with: - +Then, still with `root` permissions install compilers and developer tools via: ```bash yum install -y devtoolset-7 ``` - -Note that by default if you type now `gcc` at the prompt you will not see the new GCC! You need to -enable it explicitly: - - - - - - - - +By design these tools do not replace the standard tools shipped by the system and have to be enabled explicitly for every new shell session you open: ```bash source scl_source enable devtoolset-7 ``` - -You can either do it in every shell manually, or add it to your `~/.bashrc` or `~/.bash_profile`. If -you do so, the new GCC will always be enabled in every shell. This might not be desirable in some -cases, so beware. Also, if you add this line to the shell configuration, this will be enabled in all -new terminals (not the current one). +If desired so, the above line can be added to your `~/.bashrc` or `~/.bash_profile`, so that tools shipped via devtoolset are automatically available in every shell. However beware that in some special cases that this might have undesired side effects. You can check if you are running the correct version of GCC with: @@ -102,7 +58,15 @@ You can check if you are running the correct version of GCC with: gcc --version ``` -It should report **GCC v7.3.1**. +It should report `GCC v7.3.1`. You are now ready for [installing aliBuild and start building ALICE software](README.md#get-or-upgrade-alibuild) + + + + + + + + diff --git a/building/prereq-fedora.md b/building/prereq-fedora.md index e3d03901..fc7a6b6d 100644 --- a/building/prereq-fedora.md +++ b/building/prereq-fedora.md @@ -1,51 +1,37 @@ -aliBuild prerequisites for Fedora 27 -==================================== +aliBuild prerequisites for Fedora +================================= -We support on a best-effort basis recent versions of Fedora as development platform. Currently -supported version is Fedora 27. Other versions (older or newer) are to be considered not supported. + + +ALICE software on Fedora is supported on a best effort basis. There is no guarantee that software builds or runs correctly. Support requests might have low priority. -{% callout "Fedora is bleeding-edge" %} -Note that in general it is not so easy to support a distribution like Fedora due to its "bleeding -edge" nature. Every new version tends to adopt new standards and packages very easily, requiring -adjustments in our software chain. Such adjustments are, as per our -[policy](https://indico.cern.ch/event/642232/#3-wp3-common-tools-and-softwar), are performed on a -best-effort basis. +## Install required system packages -If you are a Fedora user, let us remind you once again that any version different than Fedora 27 is -not supported at the moment. You might want to wait until we update our software chain and -documentation before upgrading to a newer Fedora version. If you are impatient, you might want to -use Docker with a supported OS (such as CentOS 7) as your development environment. -{% endcallout %} - - -## Corresponding Fedora container - -You can use Docker to run a Fedora environment even if your OS is different. Check out the official -[Fedora images](https://hub.docker.com/_/fedora/). The image corresponding to a base Fedora 27 -installation is `fedora:27`. - - -## Install or upgrade required packages - -Install packages (one long line, just copy and paste it), as **root user**: +With root permissions, i.e. `sudo` or as `root` install the prerequisites using: + ```bash -dnf install -y git python mysql-devel curl curl-devel python python-devel python-pip bzip2 bzip2-devel unzip autoconf automake texinfo gettext gettext-devel libtool freetype freetype-devel libpng libpng-devel sqlite sqlite-devel ncurses-devel mesa-libGLU-devel libX11-devel libXpm-devel libXext-devel libXft-devel libxml2 libxml2-devel motif motif-devel kernel-devel pciutils-devel kmod-devel bison flex perl-ExtUtils-Embed environment-modules which gcc-gfortran gcc-c++ swig rsync +dnf install -y git python mysql-devel curl curl-devel bzip2 bzip2-devel unzip autoconf automake texinfo gettext gettext-devel libtool freetype freetype-devel libpng libpng-devel sqlite sqlite-devel ncurses-devel mesa-libGLU-devel libX11-devel libXpm-devel libXext-devel libXft-devel libxml2 libxml2-devel motif motif-devel kernel-devel pciutils-devel kmod-devel bison flex perl-ExtUtils-Embed environment-modules which gcc-gfortran gcc-c++ swig rsync make ``` -**Note:** at the time of writing (February 2018), our current software does not support OpenSSL 1.1, -therefore it is necessary to install the following two compatibility packages with the -`--allowerasing` option: - +## Python and pip +AliBuild, our build tool, is installed via the python Package manager `pip`. +In case ```bash -dnf install compat-openssl10-devel compat-openssl10 --allowerasing -``` - -Now get some Python dependencies (again **as root user**): - +pip3 show pip +``` +returns `command not found` or similar, install `pip` with root permissions, i.e. `sudo` or as `root`: + ```bash -pip install matplotlib numpy certifi ipython==5.1.0 ipywidgets ipykernel notebook metakernel pyyaml +dnf install -y python3-pip +pip3 install --upgrade pip ``` You are now ready for [installing aliBuild and start building ALICE software](README.md#get-or-upgrade-alibuild) + + + + + + diff --git a/building/prereq-macos.md b/building/prereq-macos.md index 0b16be26..3827e7a4 100644 --- a/building/prereq-macos.md +++ b/building/prereq-macos.md @@ -1,269 +1,77 @@ aliBuild prerequisites for macOS ================================ -ALICE software compiles just fine on macOS using Apple-provided build tools. We support exclusively -the following two versions of macOS: +ALICE software on macOS is supported on a best effort basis. Even though we systematically check macOS builds there is no guarantee that software builds or runs correctly. Support requests might have low priority. We were able to successfully build on: -* High Sierra (10.13) * Mojave (10.14) +* Catalina (10.15) -**Any other version of macOS has to be considered not supported.** If you are in doubt about -upgrading your operating system and you still don't see the new version here, then please refrain -from upgrading. +With very short update cycles of macOS, refrain from updating until we list the latest version of macOS as verified for your own good. -**Please follow these instructions every time you install a new macOS version and every time you get -a newer Xcode! This is non-optional!** - -{% callout "Upgrade your macOS/Xcode with care" %} -The instructions you see on this page have been validated **on October 1, 2018** using: - -* macOS 10.14 -* Xcode 10.0 (10A255) - -Even minor version updates on macOS/Xcode may break our build chain, and it might take us days -before fixing it. Keep an eye on this page to see if we have tested the latest versions first. -{% endcallout %} - - -## Get or upgrade Xcode - -Xcode is the Apple-provided toolkit for developing software on Apple devices. Xcode is required as -it contains the necessary compilers and build tools used by ALICE. - -Get it from the App Store [by clicking here](https://itunes.apple.com/gh/app/xcode/id497799835?mt=12): -if the link does not work, just open the App Store and search for Xcode. The installation is free of -charge, but it takes quite some space on your Mac. - -When installed, open it: if it asks you to install additional required components, please approve -the action. - -Installation's not over yet. Additional components (the "command-line tools") are required. Open a -terminal and run: +## Get Xcode +Xcode provides the necessary tools to build software in the apple ecosystem +* Download it from the [App Store](https://itunes.apple.com/gh/app/xcode/id497799835?mt=12) +* Open once installed. It will ask to install additional components - approve the action. +* Open a terminal (`Applicaions>Utilities>Terminal`) and install the command line tools using: ```bash -xcode-select --install -``` - -In case they are already installed, you'll see the following message: - -``` -xcode-select: error: command line tools are already installed, use "Software Update" to install updates +sudo xcode-select --install ``` - -**This is important:** once Xcode and the command-line tools are installed, every update will occur -graphically via the App Store. - -Now, at your first installation, you need to accept the Xcode license. If the above command did not -ask you anything, just open a terminal and write: - +* approve the license conditions by ```bash -git +sudo xcodebuild -license ``` -without any further option. You will be prompted in case there is a license to accept. In case the -license has been accepted already, you'll just see the list of options for the `git` command. - - -## Get or upgrade Homebrew - -[Homebrew](https://brew.sh) is a command-line package manager for macOS. It is the most popular now, -and it is the only one we support. +## Get Homebrew -> If you have other package managers installed, such as MacPorts or Fink, you must get rid of them -> before proceeding. They will conflict with Homebrew and ALICE software in a bad way. - -Note that Homebrew does not run as root. Do not prepend `sudo` to **any** of the following commands! - -Installation instructions are [ridiculously simple on the website](https://brew.sh/). Once Homebrew -is installed, run (as suggested): +[Homebrew](https://brew.sh) is the most poppular command-line package manager for macOS, and the only one we support. +* Install Homebrew using the [instructions on their webpage](https://brew.sh/). +* Once installed detect any problems regarding Homebrew and your system using ```bash brew doctor ``` -and fix any potential error highlighted by the tool. **Errors and warnings should not be -overlooked!** Pay close attention to warnings concerning outdated Xcode/compiler versions: you must upgrade Xcode to the latest available version before proceeding any further! - -{% callout "Clean up your Homebrew installation" %} -Due to a [problem with the automake 1.16 package](http://gnu-automake.7480.n7.nabble.com/automake-1-16-aclocal-is-unable-to-process-AM-PATH-PYTHON-with-variable-as-value-td22860.html), -subsequently fixed in version 1.16.1, a Homebrew workaround has been suggested on this page. +## Install the required packages -If you have applied the suggested workaround, the `brew doctor` command from above complains with -the following message: - -``` -Warning: Homebrew/homebrew-core is not on the master branch - -Check out the master branch by running: - git -C "$(brew --repo homebrew/core)" checkout master -``` - -To clean it up, it is better if you run the following commands (and not just the one suggested by -`brew doctor`): - -```bash -cd "$(brew --repo homebrew/core)" -git checkout master -git fetch origin master -git reset --hard origin/master -``` -{% endcallout %} - -When you are done fixing the warnings, upgrade all the currently installed Homebrew packages: - -```bash -brew upgrade -``` - -It is now time to install a bunch of required packages: +Note that Homebrew does not run as root. Do not prepend `sudo` to **any** of the following commands. +* Install the prerequisites via: ```bash brew install alisw/system-deps/o2-full-deps ``` +* If you have just upgraded your Xcode or macOS, you should run `brew reinstall` instead, in order to force the reinstallation of already installed packages. You also might want to run `brew cleanup` at the end to free up some space. -If you have just upgraded your Xcode or macOS, you should run `brew reinstall` instead, in order to -force the reinstallation of already installed packages. You also might want to run `brew cleanup` at -the end to free up some space. - -Now, open your `~/.bash_profile` (you should have a default one; create one if it does not exist, -and bear in mind that `~` represents your home directory) and add the following content: - +* Edit or create `~/.bash_profile` (Mojave) or `~/.zprofile` (Catalina) and add ```bash export PATH="/usr/local/opt/gettext/bin:/usr/local/bin:$PATH" ``` +* Close Terminal and reopen it to apply changes. -The line above tells your shell (assuming it's Bash) where to find Homebrew programs. To check if it -works, close the terminal, open a new one, and type: - -```bash -type autopoint -``` - -You should get as an answer: - -``` -autopoint is /usr/local/opt/gettext/bin/autopoint -``` - - -## Get or upgrade gfortran - -Your Xcode installation is missing a Fortran compiler, unfortunately. We need it for some parts of -our code, therefore you must install it. - -The GCC project has a [downloads page for macOS](https://gcc.gnu.org/wiki/GFortranBinaries#MacOS): get the version that corresponds to your operating -system the most. This means that if gfortran for your operating system version is not out yet, you -can safely download the one for the previous version. - -Downloads are dmg files: just double-click on them with Finder and follow the graphical installation -procedure. - -When done, open a terminal and check if you can find it: - -```bash -type gfortran -``` - -You should obtain: - -``` -gfortran is /usr/local/bin/gfortran -``` - -## Disable System Integrity Protection - -Starting from El Capitan (10.11), Apple has introduced a security feature called [System Integrity -Protection](https://www.macworld.com/article/2986118/security/how-to-modify-system-integrity-protection-in-el-capitan.html), or SIP. - -At the moment, unfortunately, ALICE software requires this feature to be turned off. - -To turn SIP off: - -* Reboot your Mac in _Recovery Mode_. That is, before macOS starts up, hold down `Command-R` and - keep both keys pressed until the Apple logo appears. -* From the **Utilities** menu open a **Terminal**. -* Type: `csrutil disable`: a message will notify the success of your operation. -* Select **Restart** from the  menu. - -**Note:** you can always re-enable it using `csrutil enable` instead. - - -## Get or upgrade pip - -`pip` is the Python package manager. Our build tool -[aliBuild](https://pypi.python.org/pypi/alibuild/) and other Python dependencies are installed -through it. - +## Python In case you are using [Python from Anaconda](https://www.anaconda.com/) or Python from Homebrew then you have `pip` already. Check it by typing: - -```bash -type pip -``` - -at your shell prompt. In case you don't use Anaconda, please install `pip` with this command: - -```bash -sudo easy_install pip -``` - -Note that you need admin permissions for running the above command. Once done, check that `pip` got -installed under `/usr/local/bin`: - -```bash -type pip -``` - -It should yield: - -``` -pip is /usr/local/bin/pip -``` - -Note that the Python version installed by means of `easy_install` might be too old. Check it with: - -```bash -pip --version -``` - -You must have at least pip 9.0.1. If this is not the case, please run: - ```bash -pip install --upgrade pip==9.0.1 +type pip3 ``` - - -## Get or upgrade required Python packages - -Some Python packages are required for building our software. They are mostly related to ROOT 6. Just -run: - +If not present install with ```bash -sudo pip install --upgrade --force-reinstall matplotlib numpy certifi ipython==5.1.0 ipywidgets ipykernel notebook metakernel pyyaml +sudo easy_install3.7 pip +sudo pip3 install --upgrade pip ``` -> It is important to specify `ipython`'s version explicitly. - - -## Exclude your work directory from Spotlight - -Mac users have two nice features, Time Machine for backups and Spotlight for searches, that might -have a detrimental effect on your Mac's performances. - -Spotlight, in particular, indexes _every_ created file, and since during our build and installation -processes we create _a lot_ of files we don't really want to index, it's better to tell Spotlight -not to index our working directory. - -We are assuming our working directory is `~/alice`. Before telling Spotlight to exclude it, we need -to create an empty one, so in a Terminal do: +## (Optional) Python modules +Optinally you can install the required python modules. If we cannot find them, our build system will do it for you. +With the **system python**: ```bash -mkdir ~/alice +sudo pip3 install --upgrade --force-reinstall matplotlib numpy certifi ipython==5.1.0 ipywidgets ipykernel notebook metakernel pyyaml ``` +For **Homebrew python**, leave out the `sudo`. -(you can also use the Finder for that.) Then, go to the ** (Apple) menu → System preferences → -Spotlight**. Click on the **Privacy** tab, then hit the **+** sign at the bottom of the window. Now -select the `~/alice` directory and confirm. +## (Optinal) Exclude your work directory from Spotlight +The mac search engine (Spotlight) will be indexing the build directory which can have severe effects on your system performance. To avoid that, you can exclude your working directory (we are assuming `~/alice` - create if not yet existing). +Go to `(Apple) menu>System preferences>Spotlight`. In the `Privacy` tab, hit the `+` button. Now select the `~/alice` directory and confirm. You are now ready for [installing aliBuild and start building ALICE software](README.md#get-or-upgrade-alibuild) diff --git a/building/prereq-ubuntu.md b/building/prereq-ubuntu.md index 23b2f213..d0b009c4 100644 --- a/building/prereq-ubuntu.md +++ b/building/prereq-ubuntu.md @@ -9,62 +9,46 @@ aliBuild prerequisites for Ubuntu -At ALICE we do our best to support two versions of Ubuntu: the latest and greatest, and the latest -LTS (Long Term Support) release. What we currently support is: +ALICE software on Ubuntu is supported on a best effort basis. There is no guarantee that software builds or runs correctly. Support requests might have low priority. We were able to successfully build on: * Ubuntu 18.04 LTS -* Ubuntu 17.10 _(not a LTS)_ * Ubuntu 16.04 LTS -**We do not support Ubuntu pre-releases** (_i.e._ if something breaks there, you are on your own). +## Install required system packages -Ubuntu has a [comprehensive page with its support policy](https://www.ubuntu.com/info/release-end-of-life). +With root permissions, _i.e._ `sudo` update your package sources: -**If your release is not mentioned (yet) in the list above, it means we cannot guarantee support for -it.** It does not mean it does not work, however, and [we will be happy to review your -contribution](../README.md) if you have more information! - - -## Corresponding Docker containers - -Not an Ubuntu user, but you want to build on Ubuntu still? You can use one of the official [Ubuntu -Docker images](https://hub.docker.com/_/ubuntu/). The images corresponding to the supported Ubuntu -versions are: - -* `ubuntu:16.04` -* `ubuntu:17.10` -* `ubuntu:18.04` - -You can try following those instructions in one of the containers above. - - -## Install or upgrade required packages - -Refresh the list of packages first (you need root, _i.e._ `sudo`, permissions): ```bash sudo apt update -y ``` - -**On Ubuntu 16.04 and 17.10**, install packages with the following long line: - +### Ubuntu 16.04: +With root permissions, _i.e._ `sudo` install the following packages: ```bash -sudo apt install -y curl libcurl4-openssl-dev build-essential gfortran cmake libmysqlclient-dev xorg-dev libglu1-mesa-dev libfftw3-dev libssl-dev libxml2-dev git unzip python-pip autoconf automake autopoint texinfo gettext libtool libtool-bin pkg-config bison flex libperl-dev libbz2-dev libboost-all-dev swig liblzma-dev libnanomsg-dev libyaml-cpp-dev rsync lsb-release unzip environment-modules +sudo apt install -y curl libcurl4-openssl-dev build-essential gfortran cmake libmysqlclient-dev xorg-dev libglu1-mesa-dev libfftw3-dev libxml2-dev git unzip autoconf automake autopoint texinfo gettext libtool libtool-bin pkg-config bison flex libperl-dev libbz2-dev swig liblzma-dev libnanomsg-dev libyaml-cpp-dev rsync lsb-release unzip environment-modules ``` -**On Ubuntu 18.04**, install the following list instead: +### Ubuntu 18.04: +With root permissions, _i.e._ `sudo` install the following packages: ```bash -sudo apt install -y curl libcurl4-gnutls-dev build-essential gfortran cmake libmysqlclient-dev xorg-dev libglu1-mesa-dev libfftw3-dev libssl1.0 libssl1.0-dev libxml2-dev git unzip python-pip autoconf automake autopoint texinfo gettext libtool libtool-bin pkg-config bison flex libperl-dev libbz2-dev libboost-all-dev swig liblzma-dev libnanomsg-dev libyaml-cpp-dev rsync lsb-release unzip environment-modules +sudo apt install -y curl libcurl4-gnutls-dev build-essential gfortran cmake libmysqlclient-dev xorg-dev libglu1-mesa-dev libfftw3-dev libxml2-dev git unzip autoconf automake autopoint texinfo gettext libtool libtool-bin pkg-config bison flex libperl-dev libbz2-dev swig liblzma-dev libnanomsg-dev libyaml-cpp-dev rsync lsb-release unzip environment-modules ``` -Once this is done, install (as root) the required Python packages: +## Python and pip +AliBuild, our build tool, is installed via the python Package manager `pip`. +In case +```bash +pip show pip +``` +returns `command not found` or similar, install `pip` with `root` permissions, i.e. `sudo` or as `root`: ```bash -sudo pip install matplotlib numpy certifi ipython==5.1.0 ipywidgets ipykernel notebook metakernel pyyaml +sudo apt -y install python3-pip +sudo pip3 install --upgrade pip ``` You are now ready for [installing aliBuild and start building ALICE