From 267fd23faf642a0c5a8365b1fc0198acd3d3e832 Mon Sep 17 00:00:00 2001 From: Timo Wilken Date: Tue, 20 Feb 2024 13:57:25 +0100 Subject: [PATCH 1/2] De-emphasise manual installation of aliBuild The manual installation instructions seems to trip people up. Make it clearer that the per-OS instructions are the recommended ones, and link to the "advanced" installation instructions on a separate page. --- building/custom.md | 68 +++++--------------------------------- building/manual-install.md | 66 ++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 60 deletions(-) create mode 100644 building/manual-install.md diff --git a/building/custom.md b/building/custom.md index 4ce815cc..289d5ea3 100644 --- a/building/custom.md +++ b/building/custom.md @@ -48,7 +48,7 @@ packages to install and configurations to perform. **Platforms supported on a best-effort basis:** -* [macOS Ventura (13.0)](prereq-macos.md) +* [macOS Ventura and Sonoma (13.0, 14.0)](prereq-macos.md) * [Ubuntu (20.04 LTS, 22.04 LTS)](prereq-ubuntu.md) * [Fedora](prereq-fedora.md) * Linux Mint @@ -60,15 +60,18 @@ packages to install and configurations to perform. If your operating system is _not_ in any list, it does not mean our software won't work on it; it will be just more difficult for you to get support for it. +Only in case you cannot install aliBuild in the way described above, you can [install aliBuild manually](manual-install.md). +This procedure should only be used as a fall-back, in case you cannot follow the instructions for your operating system linked above. + ## Configure aliBuild -After you are done installing alibuild you need to configure it by adding two -following lines to your `~/.bashrc` or `~/.bash_profile` (depending on your -configuration): +After you are done installing alibuild you need to configure it by adding the two +following lines to your `~/.bashrc`, `~/.bash_profile`, `~/.zshrc` or `~/.zprofile` +(depending on your operating system and configuration): ```bash export ALIBUILD_WORK_DIR="$HOME/alice/sw" -eval "`alienv shell-helper`" +eval "$(alienv shell-helper)" ``` The first line tells what directory is used as "build cache", the second line installs a "shell @@ -81,61 +84,6 @@ You need to close and reopen your terminal for the change to be effective. The d > case of cleanups. -### I don't have root permissions - -In case you don't have root permissions, one of the possibilities is installing aliBuild under a -user-owned directory. Start with opening your `~/.bashrc` or `~/.bash_profile` (this depends on your -system), and add the following lines: - -```bash -export PYTHONUSERBASE="$HOME/user_python" -export PATH="$PYTHONUSERBASE/bin:$PATH" -``` - -Now close all your terminals and reopen them to load the new configuration. Check if it works by -printing the variable: - -```bash -echo $PYTHONUSERBASE -``` - -The operations above need to be performed only once. Now, to install or upgrade aliBuild, just do: - -```bash -pip install alibuild --upgrade --user -``` - -> This time we did not specify `sudo` and we have added the `--user` option. The Python variable -> `PYTHONUSERBASE` tells `pip` where to install the package. - -Verify you have `aliBuild` in your path: - -```bash -type aliBuild -``` - -### I need a special version of aliBuild - -In some cases you might want to install a "release candidate" version, or you want to get the code -directly from GitHub. By default, the last stable version is installed. **Do not install a special -version of aliBuild if you were not instructed to do so or if you don't know what you are doing, we -provide no support for unstable releases!** - -To install a release candidate (for instance, `v1.5.1rc3`): - -```bash -sudo pip install alibuild=v1.5.1rc3 --upgrade -``` - -To install from GitHub (you can specify a tag or a hash, or another branch, instead of `master`): - -```bash -sudo pip install git+https://github.com/alisw/alibuild@master --upgrade -``` - -> Do not forget to drop `sudo` and add `--user` in case you do not have root permissions! - - ## Build the packages When aliBuild is installed on your computer and your prerequisites are satisfied, you can move to diff --git a/building/manual-install.md b/building/manual-install.md new file mode 100644 index 00000000..f34441aa --- /dev/null +++ b/building/manual-install.md @@ -0,0 +1,66 @@ +# Fall-back manual installation method + +In the first instance, you should always follow the instructions for your operating system [linked under "Prerequisites" here](custom.md#prerequisites). +This ensures that you only have a single installation of aliBuild, and that it is updated automatically with the rest of your system. + +If you cannot follow the instructions linked above for any reason (such as if you are using a shared machine and you do not have administrative access), see below for alternative ways to install aliBuild. + +If you follow these instructions, you are responsible for keeping aliBuild up to date manually. +Please remember to update aliBuild before asking for support, as any issues you encounter may already be solved in the latest version. + +### I don't have root permissions + +In case you don't have root permissions, one of the possibilities is installing aliBuild under a +user-owned directory. Start with opening your `~/.bashrc`, `~/.bash_profile`, `~/.zshrc` or `~/.zprofile` +(this depends on your system), and add the following line at the end: + +```bash +export PATH="$HOME/.local/bin:$PATH" +``` + +Now close all your terminals and reopen them to load the new configuration. +The operations above need to be performed only once. Now, to install or upgrade aliBuild, just do: + +```bash +python3 -m pip install alibuild --upgrade --user +``` + +> This time we did not specify `sudo` and we have added the `--user` option. + +Verify you have `aliBuild` in your path: + +```bash +type aliBuild +``` + +You are responsible for keeping aliBuild up to date manually. +You can update by running the following command: + +```bash +python3 -m pip install alibuild --upgrade --user +``` + +Now continue by [configuring aliBuild](custom.md#configure-alibuild). + +### I need a special version of aliBuild + +In some cases you might want to install a "release candidate" version, or you want to get the code +directly from GitHub. By default, the last stable version is installed. **Do not install a special +version of aliBuild if you were not instructed to do so or if you don't know what you are doing, we +provide no support for unstable releases!** + +First, remove any other copy of aliBuild installed on your system in any other way, to avoid conflicts. + +To install a release candidate (for instance, `v1.5.1rc3`): + +```bash +python3 -m pip install --user --upgrade alibuild==v1.5.1rc3 +``` + +To install from GitHub (you can specify a tag or a hash, or another branch, instead of `master`): + +```bash +python3 -m pip install --user --upgrade 'git+https://github.com/alisw/alibuild@master' +``` + +Now continue by [configuring aliBuild](custom.md#configure-alibuild). From 0c4daf1bb5e2ee7716c4973cb0e1b21c65acadb5 Mon Sep 17 00:00:00 2001 From: Timo Wilken Date: Tue, 20 Feb 2024 14:01:25 +0100 Subject: [PATCH 2/2] Add new page to sitemap --- SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/SUMMARY.md b/SUMMARY.md index 44d99daa..71b75ddf 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -9,6 +9,7 @@ * [Prerequisites for macOS](building/prereq-macos.md) * [Prerequisites for Ubuntu](building/prereq-ubuntu.md) * [Prerequisites for Fedora](building/prereq-fedora.md) + * [Fall-back manual installation method](building/manual-install.md) * [🛠 Build the packages](building/build.md) * [📦 Use the precompiled binaries](building/precomp.md) * [💪 Develop a single package (Experimental)](building/devel.md)