1. Introduction
---------------

Penguin Oil is a set of program tools designed to make Linux kernel
configuration, deployment and maintenance smoother, currently only compatible
with Gentoo Linux.

kernel-gen
   Builds a kernel source directory, generating a Portage binary package
   containing the resulting kernel binary and any in-tree modules, optionally
   including an initramfs from a compatible initramfs-building system such as
   Tinytium. See also § 2.1. Using kernel-gen.

kernel-lsoot
   Lists out-of-tree firmware and/or modules for Linux along with the packages
   that installed them.


2. Usage
--------

2.1. Using kernel-gen
---------------------

Prior to running kernel-gen, a kernel source code folder must be obtained
(e.g. emerge sys-kernel/gentoo-sources) and configured (e.g. make nconfig).
Once that’s done, kernel-gen can be directed to the correct folder by either
creating a symlink to it at /usr/src/linux (as managed by USE=symlink), or by
passing a --source argument, or by invoking kernel-gen directly from the
desired folder.


2.1.1. Building the kernel
--------------------------

kernel-gen will build the selected kernel using as much of the Portage’s
configuration as possible (e.g. distcc settings, make flags).

Before running make, kernel-gen will inspect the kernel configuration
(.config) to make sure that no settings will result in the kernel being unable
to use the initramfs, if one is to be built (see § 2.1.2. Building an
initramfs).

After the kernel image has been generated, kernel-gen will rebuild all
external modules to make them compatible with the just-built image, unless
--no-oot-modules is specified.


2.1.2. Building an initramfs
----------------------------

Perhaps the most useful feature of kernel-gen is its ability to rebuild an
initramfs to include the in-tree and out-of-tree kernel modules that have been
just built.

kernel-gen supports using for an initramfs either a folder with the initramfs
contents, or a folder containing at least an executable named “build”, which
will be invoked from within the temporary working directory which kernel-gen
will create the initramfs archive from. Additionally, these environment
variables are passed to the build program:

   ARCH
      Target architecture, using the Linux kernel’s naming convention.
   CROSS_COMPILE
      Cross-compiling toolchain prefix.
   PORTAGE_ARCH
      Target architecture, using Portage’s naming convention.
   ROOT
      Root directory, as seen by Portage.

The build program will be responsible for adding any additional files to the
working directory, which will then be taken as-is to generate the initramfs
archive.

For kernel-gen to pick an initramfs and enable the generation of the initramfs
archive, a symlink to it must be created at /usr/src/initramfs, or the path to
it must be passed using the --initramfs-source argument to kernel-gen.

When debugging the initramfs’s build program, passing the argument
--initramfs-debug will generate a dump of the contents of the initramfs just
before it is packaged.


2.1.3. Generated kernel binary package
--------------------------------------

After building the kernel and its optional initramfs, kernel-gen will create a
Portage binary package containing:

•  Kernel (compressed) image (e.g. /boot/linux-3.10.2)
•  initramfs (compressed) archive (e.g. /boot/initramfs-3.10.2.cpio.lzo)
•  Kernel configuration (e.g. /boot/config-3.10.2)
•  Kernel symbol table (e.g. /boot/System.map-3.10.2)
•  Kernel in-tree and external modules (e.g. /lib/modules/3.10.2)

The package name will be similar to the original source package name, but it
will have the local version added to it.
For example, running kernel-gen on /usr/src/linux-3.10.2-gentoo (from
sys-kernel/gentoo-sources), configured with “-my-laptop” as the local version,
will yield a binary package named sys-kernel/gentoo-my-laptop-bin-3.10.2 .

The binary package is installed immediately after being built; to avoid this,
invoke kernel-gen with the --no-install option; this will leave the binary
package available for manual installation, for example using emerge:

   emerge --usepkgonly=y sys-kernel/gentoo-my-laptop-bin




------------------------------------------------------------------------------
Copyright 2012-2015, 2017, 2024 Raffaello D. Di Napoli <rafdev@dinapo.li>
Distributed under the terms of the GNU General Public License v3