From 6cfc4c8a0f40b516b9807ece3a35849d8cf438ca Mon Sep 17 00:00:00 2001 From: projectmoon Date: Thu, 16 Mar 2023 22:13:13 +0100 Subject: [PATCH] Update and split readme --- README.md | 119 ++++++++---------------------------- docs/Libre-Kernel.md | 140 +++++++++++++++++++++++++++++++++++++++++++ docs/Librem.md | 58 ++++++++++++++++++ 3 files changed, 223 insertions(+), 94 deletions(-) create mode 100644 docs/Libre-Kernel.md create mode 100644 docs/Librem.md diff --git a/README.md b/README.md index 0dadc3a..16a7d98 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,8 @@ Personal Gentoo overlay, focusing mostly on needed tools and -compatibility for a libre version of Gentoo on the Librem 14 computer. +compatibility for a libre version of Gentoo on the Librem 14 computer. A +handful of other pacakages are also provided. -Available packages: - - **dev-python/ecp**: Python implementation of Emacs RPC stack. Depends - on `orjson` or `orjson-bin` from the GURU (or another) overlay. +Linux-libre and Librem-related packages: - **sys-kernel/libre-kernel**: A dist-kernel built from the [Linux-libre sources][linux-libre]. - **media-fonts/fonts-meta**: Modified version to remove non-Free @@ -14,7 +13,13 @@ Available packages: * **sys-power/librem-control**: A GTK application to control parameters of the Librem EC (battery charge levels, etc). * **sys-apps/purism_ectool**: Tool for querying and flashing - Purism EC firmware images on certain Librem laptops. + Purism EC firmware images on certain Librem laptops.v + +Other Packages: + - **dev-python/ecp**: Python implementation of Emacs RPC stack. Depends + on `orjson` or `orjson-bin` from the GURU (or another) overlay. + - **www-plugins/firefox-pwa-connector**: The native host connector for + the [PWAs for Firefox][ff-pwas] project. ## How to Add This Repository @@ -32,109 +37,34 @@ In `/etc/portage/package.mask`: ``` 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 -``` +`package.accept_keywords` if necessary). For instructions on unmasking +individual packages, see the relevant documentation below. ## The Linux-libre dist-kernel +*See [docs/Libre-Kernel.md](docs/Libre-Kernel.md). + 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 -is not [Free Software][free-software]. The ebuild roughly follows the +kernel removes the ability for the Linux kernel to load firmware that is +not [Free Software][free-software]. The ebuild roughly follows the current stable gentoo-kernel for amd64. -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. +## Purism Librem Computer Packages -The kernel installed by this ebuild has the version suffix -`-gnu-dist`, making it easy to determine which kernel it is. +*See [docs/Librem.md](docs/Librem.md).* +This overlay contains packages for Purism's Librem computers, focusing +mostly on the Librem 14. -### Signature Verification +## Other Packages -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`.* - -To install only the Linux firmware that meets the [Free Software -Definition][free-software], configure `/etc/portage/package.use` -accordingly: - -``` -# 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 -``` - -## Using the Librem EC ACPI kernel module - -The Librem EC ACPI kernel module should install and be automatically -available (via modprobe) after installation, using `emerge -sys-kernel/librem-ec-acpi`. The module is currently installed to -`/lib/modules//librem/`. - -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, - -### 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. -It is not recommended to use the EC tool from this overlay for -flashing a firmware image. Instead, follow the official [firmware -flashing instrutions][ec-instructions]. +*More documentation coming soon.* +Packages must be unmasked and added to `package.accept_keywords` as +necessary. # Disclaimer @@ -146,3 +76,4 @@ So there may be issues with non-Free dependencies etc in some cases. [free-software]: https://www.gnu.org/philosophy/free-sw.en.html#fs-definition [ec-acpi]: https://source.puri.sm/nicole.faerber/librem-ec-acpi-dkms [ec-instructions]: https://puri.sm/projects/librem-ec/ +[ff-pwas]: https://github.com/filips123/PWAsForFirefox diff --git a/docs/Libre-Kernel.md b/docs/Libre-Kernel.md new file mode 100644 index 0000000..3469375 --- /dev/null +++ b/docs/Libre-Kernel.md @@ -0,0 +1,140 @@ +# 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 +is not [Free Software][free-software]. The ebuild roughly follows the +current stable gentoo-kernel for amd64. + +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. + +## Quick Setup + +This is a quick guide for setting up the system to properly install the +Linux-libre Kernel. It assumes you have set up the overlay as described +in the README. + +In `/etc/portage/package.use`: + +``` +# Install only libre firmware +sys-kernel/linux-firmware -redistributable -unknown-license + +# libre kernel with gentoo kernel patches applied +sys-kernel/libre-kernel verify-sig + +# or, if you do not want gentoo patches applied +sys-kernel/libre-kernel verify-sig -gentoo +``` + +In `/etc/portage/package.unmask`: + +``` +sys-kernel/libre-kernel::projectmoon +virtual/dist-kernel::projectmoon +sec-keys/openpgp-keys-linux-libre::projectmoon +``` + +In `/etc/portage/package.accept_keywords`: + +``` +sys-kernel/librem-ec-acpi::projectmoon +sys-kernel/libre-kernel::projectmoon ~amd64 +virtual/dist-kernel::projectmoon +``` + +In `/etc/portage/package.mask`: + +``` +# stay on libre kernel +sys-kernel/gentoo-kernel +sys-kernel/gentoo-kernel-bin +sys-kernel/vanilla-kernel +``` + +## Detailed Instructions + +The rest of this documentation covers the quick steps above in detail, +and extra information about the Linux firmware package, the Librem EC +ACPI module, etc. + +### Signature Verification + +It is recommended to enable GPG signature verification of +`sys-kenrel/libre-kernel` by adding the USE flag to +o`/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`.* + +To install only the Linux firmware that meets the [Free Software +Definition][free-software], configure `/etc/portage/package.use` +accordingly: + +``` +# 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 +``` + +### Using the Librem EC ACPI kernel module + +The Librem EC ACPI kernel module should install and be automatically +available (via modprobe) after installation, using `emerge +sys-kernel/librem-ec-acpi`. The module is currently installed to +`/lib/modules//librem/`. + +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. + +[free-software]: https://www.gnu.org/philosophy/free-sw.en.html#fs-definition +[linux-libre]: https://www.fsfla.org/ikiwiki/selibre/linux-libre/ +[free-software]: https://www.gnu.org/philosophy/free-sw.en.html#fs-definition diff --git a/docs/Librem.md b/docs/Librem.md new file mode 100644 index 0000000..6609621 --- /dev/null +++ b/docs/Librem.md @@ -0,0 +1,58 @@ +# Packages for Purism Librem Computers + +This overlay provides a handful of ebuilds for Purism Librem computers (particularly, the Librem 14): + - **sys-kernel/librem-ec-acpi**: An ebuild packaging the [Librem 14 + EC ACPI kernel module][ec-acpi], necessary for proper functioning + of the laptop's battery charging and function keys. + * **sys-power/librem-control**: A GTK application to control + parameters of the Librem EC (battery charge levels, etc). + * **sys-apps/purism_ectool**: Tool for querying and flashing + Purism EC firmware images on certain Librem laptops. + +## Quick Setup + +This is a quick guide for setting up the system to properly install +Librem-related packages. It assumes you have set up the overlay as +described in the README. + +In `/etc/portage/package.unmask`: + +``` +sys-kernel/librem-ec-acpi::projectmoone +sys-firmware/purism_ectool::projectmoon +sys-power/librem-control::projectmoon +``` + +In `/etc/portage/package.accept_keywords`: + +``` +sys-kernel/librem-ec-acpi::projectmoon +sys-firmware/purism_ectool::projectmoon +sys-power/librem-control::projectmoon ** +``` + +## The Librem EC ACPI kernel module + +The Librem EC ACPI kernel module should install and be automatically +available (via modprobe) after installation, using `emerge +sys-kernel/librem-ec-acpi`. The module is currently installed to +`/lib/modules//librem/`. + +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. + +### 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. +It is not recommended to use the EC tool from this overlay for +flashing a firmware image. Instead, follow the official [firmware +flashing instrutions][ec-instructions]. + +[ec-acpi]: https://source.puri.sm/nicole.faerber/librem-ec-acpi-dkms +[ec-instructions]: https://puri.sm/projects/librem-ec/