From 0e81ca24374a1820e42161d90ee5ba7287f548f6 Mon Sep 17 00:00:00 2001 From: Giovanni Harting <539@idlegandalf.com> Date: Sat, 10 Aug 2024 23:38:12 +0200 Subject: [PATCH] better readme --- README.md | 78 +++++++++++++++++++++++++------------------------------ 1 file changed, 36 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 6a75f98..3432086 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,23 @@ # ALHP -[![](https://img.shields.io/badge/license-GPL-blue?style=flat-square)](https://somegit.dev/anonfunc/ALHP.GO/src/branch/master/LICENSE) [![](https://img.shields.io/badge/package-status-informational?style=flat-square)](https://status.alhp.dev) [![](https://goreportcard.com/badge/somegit.dev/ALHP/ALHP.GO?style=flat-square)](https://goreportcard.com/report/somegit.dev/ALHP/ALHP.GO) [![](https://pkg.go.dev/badge/somegit.dev/ALHP/ALHP.GO)](https://pkg.go.dev/somegit.dev/ALHP/ALHP.GO) +[![](https://img.shields.io/badge/license-GPL-blue?style=flat-square)](https://somegit.dev/anonfunc/ALHP.GO/src/branch/master/LICENSE) [![](https://img.shields.io/liberapay/patrons/anonfunc.svg?logo=liberapay&style=flat-square)](https://liberapay.com/anonfunc/) -Buildbot for Archlinux-based repos build with different +Buildbot for Archlinux based repos with different [x86-64 feature levels](https://www.phoronix.com/scan.php?page=news_item&px=GCC-11-x86-64-Feature-Levels), `-O3` and [LTO](https://en.wikipedia.org/wiki/Interprocedural_optimization). > [!WARNING] -> NVIDIA graphic users using the **proprietary driver** is highly recommended reading the -> [FAQ about Linux kernel modules](#directly-linked-kernel-modules) +> NVIDIA graphics users using the **proprietary driver** are strongly encouraged to read the +> [FAQ about Linux kernel modules](#directly-linked-kernel-modules) before enabling any repos. --- -* [ALHP](#alhp) - * [Quickstart](#quickstart) +* [Quick Start](#quick-start) * [FAQ](#faq) * [Matrix](#matrix) * [Donations](#donations) @@ -27,25 +26,22 @@ Buildbot for Archlinux-based repos build with different --- -## Quickstart +## Quick Start ### 1. Check your system for support > [!CAUTION] -> Before you enable any of these repos, check if your system supports the feature level you want to -> enable -(e.g. `x86-64-v3`). -> **If you don't check beforehand, you might be unable to boot your system anymore and need to downgrade any package -that you may have upgraded.** - -Check which feature-levels your CPU supports with +> Before enabling any of these repos, make sure that your system supports the level of functionality you want to +> enable (e.g. `x86-64-v3`). +> **If you don't check first, you may not be able to boot your system and will have to downgrade any packages you may +have upgraded.** +Check which feature levels your CPU supports with ```bash /lib/ld-linux-x86-64.so.2 --help ``` Example output snippet for a system supporting up to `x86-64-v3`: - ``` Subdirectories of glibc-hwcaps directories, in priority order: x86-64-v4 @@ -54,14 +50,13 @@ Subdirectories of glibc-hwcaps directories, in priority order: ``` > [!NOTE] -> ALHP builds for `x86-64-v2`, `x86-64-v3` and `x86-64-v4` at the moment. You can see all available -> repositories -> [here](https://alhp.dev/). +> ALHP repos for `x86-64-v2`, `x86-64-v3` and `x86-64-v4` are currently available. You can see all available +> repositories [here](https://alhp.dev/). ### 2. Install keyring & mirrorlist Install [alhp-keyring](https://aur.archlinux.org/packages/alhp-keyring/) -and [alhp-mirrorlist](https://aur.archlinux.org/packages/alhp-mirrorlist/) from **AUR**. +and [alhp-mirrorlist](https://aur.archlinux.org/packages/alhp-mirrorlist/) from the **AUR**. Example with `yay`: @@ -73,16 +68,16 @@ yay -S alhp-keyring alhp-mirrorlist ### 3. Choose a mirror (optional) -Edit `/etc/pacman.d/alhp-mirrorlist` and comment out/in mirrors you want to have enabled/disabled. Per default selected -is a cloudflare-based mirror which -[*should* provide decent speed worldwide](https://somegit.dev/ALHP/ALHP.GO/issues/38#issuecomment-891). +Edit `/etc/pacman.d/alhp-mirrorlist` and comment in/out the mirrors you want to enable/disable. +By default, a CDN mirror provided by ALHP is selected. > [!NOTE] -> `cdn.alhp.dev` and `alhp.dev` are provided by ALHP directly. If you have problems with a mirror, +> `cdn.alhp.dev` and `alhp.dev` are provided directly by ALHP. If you have problems with a mirror, > open an issue at [the mirrorlist repo](https://somegit.dev/ALHP/alhp-mirrorlist). -### 4. Modify /etc/pacman.conf +### 4. Modify pacman.conf -Add the appropriate repos **above** your regular Archlinux repos. +Add the ALHP repos to your `/etc/pacman.conf`. Make sure the appropriate ALHP repository is **above** the Archlinux +repo. Example for `x86-64-v3`: @@ -110,9 +105,9 @@ Include = /etc/pacman.d/mirrorlist Replace `x86-64-v3` with the x86-64 feature level you want to enable. > [!TIP] -> Stacking multiple levels is possible, as described in https://somegit.dev/ALHP/ALHP.GO/issues/255#issuecomment-3335. +> Multiple layers can be stacked as described in https://somegit.dev/ALHP/ALHP.GO/issues/255#issuecomment-3335. -### 5. Update package database and upgrade: +### 5. Update package database and upgrade ``` pacman -Suy @@ -122,9 +117,9 @@ pacman -Suy ### Remove ALHP packages -To disable ALHP remove all *x86-64-vX* entries in `/etc/pacman.conf` and remove `alhp-keyring` and `alhp-mirrorlist`. +To disable ALHP, remove all *x86-64-vX* entries in `/etc/pacman.conf` and remove `alhp-keyring` and `alhp-mirrorlist`. -After that you can refresh pacmans databases and downgrade all packages like: +After that, you can update pacman's databases and downgrade all packages, like ``` pacman -Suuy @@ -132,7 +127,7 @@ pacman -Suuy ### LTO -Enabled for all packages build after 04 Nov 2021 12:07:00 +Enabled for all packages built after 04 Nov 2021 12:07:00 UTC. [More details.](https://somegit.dev/ALHP/ALHP.GO/issues/52) LTO status is visible per package on the package status page. @@ -142,7 +137,7 @@ LTO status is visible per package on the package status page. ### Directly linked kernel modules -Due to our increase in pkgrel, building the kernel packages **breaks all directly linked modules** like `nvidia` +Due to our increase in pkgrel, building the kernel packages **will break any directly linked modules** such as `nvidia` (not `nvidia-dkms`) or `virtualbox-host-modules-arch` (not `virtualbox-host-dkms`). **Their respective `dkms`-variant is not affected**. This issue is being tracked in #68, a solution is being worked on. @@ -154,19 +149,18 @@ so, [see alhp-mirrorlist for how to become one](https://somegit.dev/ALHP/alhp-mi ### What packages are built Packages [excluded](https://www.reddit.com/r/archlinux/comments/oflged/alhp_archlinux_recompiled_for_x8664v3_experimental/h4fkinu?utm_source=share&utm_medium=web2x&context=3) -from building (besides all 'any' architecture packages) are being listed in issue #16. -Also [package status page](https://status.alhp.dev) (search for `blacklisted`). +from building (besides all `any` architecture packages) are being listed in issue #16. +See also [package status page](https://status.alhp.dev) (search for `blacklisted`). ### Why is package X not up-to-date Also relevant for: **I can't find package X / Application X fails to start because it links to an old/newer lib** -ALHP build packages **after** they are released in the official Archlinux Repos (not including `[*-testing]`). -This leads to packages being delayed if the current batch contains many packages or packages which take a while to +ALHP builds packages **after** they are released in the official Archlinux repos (excluding `[*-testing]`). +This will cause packages to be delayed if the current batch contains many packages, or packages that take a while to build (e.g. `chromium`). -You can always check on the progress of the current build-cycle on -the [package status page](https://status.alhp.dev). +You can always check on the progress of the current build cycle on the [package status page](https://status.alhp.dev). Please refrain from opening issues caused by packages currently in queue/not yet build/not yet moved to the repo. Please keep in mind that large rebuilds such as `openssl` or `python` can take days to complete on our current build hardware. @@ -184,16 +178,16 @@ echo "https://debuginfod.alhp.dev" > /etc/debuginfod/alhp.urls ### Switch between levels If you want to switch between levels, e.g. from `x86-64-v3` to `x86-64-v4`, you need to revert to official packages -first, then enable your desired repos again. +first, and then enable your desired repos again. -1. Comment or remove ALHP repo entries in `/etc/pacman.conf`. +1. Comment out or remove the ALHP repo entries in `/etc/pacman.conf`. 2. Downgrade packages with `pacman -Suuy`. 3. Clear pacman's package cache with `pacman -Scc`. 4. Uncomment/add your desired repos to `/etc/pacman.conf` and update with `pacman -Suy`. ## Matrix -For any non-issue questions or if you just want to chat, ALHP has a matrix +For any non-issue questions, or if you just want to chat, ALHP has a Matrix room [here](https://matrix.to/#/#alhp:ofsg.eu) (`#alhp@ofsg.eu`). You can also find me (@idlegandalf) in `#archlinux:archlinux.org`. @@ -207,5 +201,5 @@ work ALHP would not be possible. ## License and Legal -This project including all of its source files is released under the terms of the GNU General Public License version 2 -(or any later version). See [LICENSE](https://somegit.dev/ALHP/ALHP.GO/src/branch/master/LICENSE) for details. +This project and all of its source code is released under the terms of the GNU General Public License, version 2 +or any later version. See [LICENSE](https://somegit.dev/ALHP/ALHP.GO/src/branch/master/LICENSE) for details.