Skip to content

Commit 4826ee2

Browse files
TimoWilkenTimoWilken
authored
De-emphasise manual installation of aliBuild (#165)
* 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. * Add new page to sitemap
1 parent 0be1003 commit 4826ee2

File tree

3 files changed

+75
-60
lines changed

3 files changed

+75
-60
lines changed

‎SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
* [Prerequisites for macOS](building/prereq-macos.md)
1010
* [Prerequisites for Ubuntu](building/prereq-ubuntu.md)
1111
* [Prerequisites for Fedora](building/prereq-fedora.md)
12+
* [Fall-back manual installation method](building/manual-install.md)
1213
* [🛠 Build the packages](building/build.md)
1314
* [📦 Use the precompiled binaries](building/precomp.md)
1415
* [💪 Develop a single package (Experimental)](building/devel.md)

‎building/custom.md‎

Lines changed: 8 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ packages to install and configurations to perform.
4848

4949
**Platforms supported on a best-effort basis:**
5050

51-
* [macOS Ventura (13.0)](prereq-macos.md)
51+
* [macOS Ventura and Sonoma (13.0, 14.0)](prereq-macos.md)
5252
* [Ubuntu (20.04 LTS, 22.04 LTS)](prereq-ubuntu.md)
5353
* [Fedora](prereq-fedora.md)
5454
* Linux Mint
@@ -60,15 +60,18 @@ packages to install and configurations to perform.
6060
If your operating system is _not_ in any list, it does not mean our software won't work on it;
6161
it will be just more difficult for you to get support for it.
6262

63+
Only in case you cannot install aliBuild in the way described above, you can [install aliBuild manually](manual-install.md).
64+
This procedure should only be used as a fall-back, in case you cannot follow the instructions for your operating system linked above.
65+
6366
## Configure aliBuild
6467

65-
After you are done installing alibuild you need to configure it by adding two
66-
following lines to your `~/.bashrc` or `~/.bash_profile` (depending on your
67-
configuration):
68+
After you are done installing alibuild you need to configure it by adding the two
69+
following lines to your `~/.bashrc`, `~/.bash_profile`, `~/.zshrc` or `~/.zprofile`
70+
(depending on your operating system and configuration):
6871

6972
```bash
7073
export ALIBUILD_WORK_DIR="$HOME/alice/sw"
71-
eval "`alienv shell-helper`"
74+
eval "$(alienv shell-helper)"
7275
```
7376

7477
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
8184
> case of cleanups.
8285
8386

84-
### I don't have root permissions
85-
86-
In case you don't have root permissions, one of the possibilities is installing aliBuild under a
87-
user-owned directory. Start with opening your `~/.bashrc` or `~/.bash_profile` (this depends on your
88-
system), and add the following lines:
89-
90-
```bash
91-
export PYTHONUSERBASE="$HOME/user_python"
92-
export PATH="$PYTHONUSERBASE/bin:$PATH"
93-
```
94-
95-
Now close all your terminals and reopen them to load the new configuration. Check if it works by
96-
printing the variable:
97-
98-
```bash
99-
echo $PYTHONUSERBASE
100-
```
101-
102-
The operations above need to be performed only once. Now, to install or upgrade aliBuild, just do:
103-
104-
```bash
105-
pip install alibuild --upgrade --user
106-
```
107-
108-
> This time we did not specify `sudo` and we have added the `--user` option. The Python variable
109-
> `PYTHONUSERBASE` tells `pip` where to install the package.
110-
111-
Verify you have `aliBuild` in your path:
112-
113-
```bash
114-
type aliBuild
115-
```
116-
117-
### I need a special version of aliBuild
118-
119-
In some cases you might want to install a "release candidate" version, or you want to get the code
120-
directly from GitHub. By default, the last stable version is installed. **Do not install a special
121-
version of aliBuild if you were not instructed to do so or if you don't know what you are doing, we
122-
provide no support for unstable releases!**
123-
124-
To install a release candidate (for instance, `v1.5.1rc3`):
125-
126-
```bash
127-
sudo pip install alibuild=v1.5.1rc3 --upgrade
128-
```
129-
130-
To install from GitHub (you can specify a tag or a hash, or another branch, instead of `master`):
131-
132-
```bash
133-
sudo pip install git+https://github.com/alisw/alibuild@master --upgrade
134-
```
135-
136-
> Do not forget to drop `sudo` and add `--user` in case you do not have root permissions!
137-
138-
13987
## Build the packages
14088

14189
When aliBuild is installed on your computer and your prerequisites are satisfied, you can move to

‎building/manual-install.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Fall-back manual installation method
2+
3+
In the first instance, you should always follow the instructions for your operating system [linked under "Prerequisites" here](custom.md#prerequisites).
4+
This ensures that you only have a single installation of aliBuild, and that it is updated automatically with the rest of your system.
5+
6+
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.
7+
8+
If you follow these instructions, you are responsible for keeping aliBuild up to date manually.
9+
Please remember to update aliBuild before asking for support, as any issues you encounter may already be solved in the latest version.
10+
11+
### I don't have root permissions
12+
13+
In case you don't have root permissions, one of the possibilities is installing aliBuild under a
14+
user-owned directory. Start with opening your `~/.bashrc`, `~/.bash_profile`, `~/.zshrc` or `~/.zprofile`
15+
(this depends on your system), and add the following line at the end:
16+
17+
```bash
18+
export PATH="$HOME/.local/bin:$PATH"
19+
```
20+
21+
Now close all your terminals and reopen them to load the new configuration.
22+
The operations above need to be performed only once. Now, to install or upgrade aliBuild, just do:
23+
24+
```bash
25+
python3 -m pip install alibuild --upgrade --user
26+
```
27+
28+
> This time we did not specify `sudo` and we have added the `--user` option.
29+
30+
Verify you have `aliBuild` in your path:
31+
32+
```bash
33+
type aliBuild
34+
```
35+
36+
You are responsible for keeping aliBuild up to date manually.
37+
You can update by running the following command:
38+
39+
```bash
40+
python3 -m pip install alibuild --upgrade --user
41+
```
42+
43+
Now continue by [configuring aliBuild](custom.md#configure-alibuild).
44+
45+
### I need a special version of aliBuild
46+
47+
In some cases you might want to install a "release candidate" version, or you want to get the code
48+
directly from GitHub. By default, the last stable version is installed. **Do not install a special
49+
version of aliBuild if you were not instructed to do so or if you don't know what you are doing, we
50+
provide no support for unstable releases!**
51+
52+
First, remove any other copy of aliBuild installed on your system in any other way, to avoid conflicts.
53+
54+
To install a release candidate (for instance, `v1.5.1rc3`):
55+
56+
```bash
57+
python3 -m pip install --user --upgrade alibuild==v1.5.1rc3
58+
```
59+
60+
To install from GitHub (you can specify a tag or a hash, or another branch, instead of `master`):
61+
62+
```bash
63+
python3 -m pip install --user --upgrade 'git+https://github.com/alisw/alibuild@master'
64+
```
65+
66+
Now continue by [configuring aliBuild](custom.md#configure-alibuild).

0 commit comments

Comments
 (0)