projectmoon-overlay/README.md

149 lines
5.3 KiB
Markdown
Raw Normal View History

2021-08-06 10:02:18 +00:00
Personal Gentoo overlay, focusing mostly on needed tools and
2022-11-10 13:48:17 +00:00
compatibility for a libre version of Gentoo on the Librem 14 computer.
2021-08-05 22:28:50 +00:00
2021-08-06 10:02:18 +00:00
Available packages:
- **dev-python/ecp**: Python implementation of Emacs RPC stack. Depends
2023-02-24 12:20:05 +00:00
on `orjson` or `orjson-bin` from the GURU (or another) overlay.
2022-11-08 16:16:00 +00:00
- **sys-kernel/libre-kernel**: A dist-kernel built from the [Linux-libre
sources][linux-libre].
2022-11-10 13:48:17 +00:00
- **media-fonts/fonts-meta**: Modified version to remove non-Free
fonts from the dependencies.
2023-03-01 06:31:22 +00:00
- **sys-kernel/librem-ec-acpi**: An ebuild packaging the [Librem 14
2022-11-08 16:16:00 +00:00
EC ACPI kernel module][ec-acpi], necessary for proper functioning
of the laptop's battery charging and function keys.
2022-11-15 21:54:14 +00:00
* **sys-power/librem-control**: A GTK application to control
parameters of the Librem EC (battery charge levels, etc).
2023-02-28 13:19:23 +00:00
* **sys-apps/purism_ectool**: Tool for querying and flashing
2022-11-15 21:54:14 +00:00
Purism EC firmware images on certain Librem laptops.
2021-08-05 22:28:50 +00:00
2021-08-06 10:02:18 +00:00
## How to Add This Repository
2021-08-05 22:28:50 +00:00
2021-08-06 10:02:18 +00:00
Using eselect-repository:
```
# eselect repository add projectmoon git https://git.agnos.is/projectmoon/projectmoon-overlay
```
It usually a best practice to mask packages from overlays, except the ones you want:
In `/etc/portage/package.mask`:
```
*/*::projectmoon
```
Individual packages can be unmasked (and added to
`package.accept_keywords` if necessary). In `/etc/portage/package.unmask`:
```
sys-kernel/libre-kernel::projectmoon
virtual/dist-kernel::projectmoon
sec-keys/openpgp-keys-linux-libre::projectmoon
```
2022-11-08 16:16:00 +00:00
## The Linux-libre dist-kernel
This overlay provides a dist-kernel (based on
`sys-kernel/vanilla-kernel`) using the Linux-libre kernel sources, and
an accompanying updated version of `virtual/dist-kernel`. It is
maintained and tested for my personal use on amd64. The Linux-libre
kernel removes the ability for the Linux kernel to load firmware that
2022-11-15 21:54:14 +00:00
is not [Free Software][free-software]. The ebuild roughly follows the
current stable gentoo-kernel for amd64.
2022-11-08 16:16:00 +00:00
The libre kernel can be installed alongside other dist-kernels, and
works with the `dist-kernel` and `initramfs` USE flags. The ebuild
does NOT fail if non-free firmware (i.e. `sys-kernel/linux-firmware`
with `redistributable` USE flag set) is installed, but it will warn
you if this is the case. It will also warn you if the `linux-firmware`
package is not found at all, like normal dist-kernel ebuilds.
The kernel installed by this ebuild has the version suffix
`-gnu-dist`, making it easy to determine which kernel it is.
### Signature Verification
It is recommended to enable GPG signature verification of
`sys-kenrel/libre-kernel` by adding the USE flag to
`/etc/portage/package.use`:
```
sys-kernel/libre-kernel verify-sig
```
### Keeping the Linux-libre Kernel Installed
Portage will sometimes try to install `sys-kernel/gentoo-kernel` or
another dist-kernel if there is a newer stable version than
`sys-kernel/libre-kernel`. This happens because of a version bump to
`virtual/dist-kernel` before this overlay has updated its own copy of
`virtual/dist-kernel`.
To prevent portage from attempting to install another dist-kernel
instead of the Linux-libre kernel, you should mask other dist-kernels in
`/etc/portage/package.mask`:
```
# stay on libre kernel
sys-kernel/gentoo-kernel
sys-kernel/gentoo-kernel-bin
sys-kernel/vanilla-kernel
```
### Linux Firmware
*Note: If you are running the Linux-libre kernel, it is unlikely (though
not impossible) that you need to install `sys-kernel/linux-firmware`.*
2022-11-08 16:16:00 +00:00
To install only the Linux firmware that meets the [Free Software
2022-11-15 21:54:14 +00:00
Definition][free-software], configure `/etc/portage/package.use`
accordingly:
2022-11-08 16:16:00 +00:00
```
# Install only libre firmware
sys-kernel/linux-firmware -redistributable -unknown-license
```
You can also edit `/etc/portage/profile/package.use.mask` to prevent
the linux-firmware package from ever installing the closed-source
firmware by adding this line:
```
# forcibly stop non-free firmware installation
sys-kernel/linux-firmware redistributable unknown-license
```
2021-08-05 22:28:50 +00:00
## Using the Librem EC ACPI kernel module
2021-08-06 10:02:18 +00:00
The Librem EC ACPI kernel module should install and be automatically
available (via modprobe) after installation, using `emerge
2023-03-01 06:31:22 +00:00
sys-kernel/librem-ec-acpi`. The module is currently installed to
2021-08-06 10:02:18 +00:00
`/lib/modules/<kernel>/librem/`.
2021-08-05 22:28:50 +00:00
2022-11-08 16:16:00 +00:00
This ebuild supports the `dist-kernel` USE flag, and the module will
automatically be rebuilt when installing a new dist-kernel if that
flag is enabled.
If you are not using a dist-kernel, you will need to do `emerge
@modules-rebuild` to install the module after you upgrade or install a
new kernel,
2021-08-05 22:28:50 +00:00
2022-11-15 21:54:14 +00:00
### Librem Control and the Purism EC Tool
These two appliations can be used to manipulate device-specific
features of the Librem 14, including the flashing of firmware images.
2022-11-15 22:01:16 +00:00
It is not recommended to use the EC tool from this overlay for
2022-11-15 21:54:14 +00:00
flashing a firmware image. Instead, follow the official [firmware
flashing instrutions][ec-instructions].
2022-11-10 13:48:17 +00:00
# Disclaimer
The ebuilds in this overlay are really only tested for my specific
use-case. I do not test every combination of USE flags, for example.
So there may be issues with non-Free dependencies etc in some cases.
2022-11-08 16:16:00 +00:00
[linux-libre]: https://www.fsfla.org/ikiwiki/selibre/linux-libre/
[free-software]: https://www.gnu.org/philosophy/free-sw.en.html#fs-definition
2021-08-05 22:28:50 +00:00
[ec-acpi]: https://source.puri.sm/nicole.faerber/librem-ec-acpi-dkms
2022-11-15 21:54:14 +00:00
[ec-instructions]: https://puri.sm/projects/librem-ec/