MODULE-ASSISTANT(8)

📦
version 0.11.14build1 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

so the page you're reading is MODULE-ASSISTANT(8), and the star of the show is module-assistant — it manages kernel modules packages ✨ bestie this tool is everything if you've ever needed to build a kernel module, no cap.

🎀 SYNOPSIS 🎀

module-assistant [ -fihnqstv ] [ -k source/headers directory ] [ -l kernel versions ] { update | search | prepare | auto-install | list | list-available | list-installed | auto-unpacked | get | unpack | build | install | clean | purge | fakesource } [ pkg ... ]

m-a ...

💖 DESCRIPTION 💖

module-assistant is THE command-line tool for handling module-source packages that have been prepared for the Debian distribution. it literally helps users build and install module package(s) easily for one or more custom kernels 🫶

unless the -h or --help option is given, one of the commands below should be present to invoke a function explicitly. and if no (or no valid) command is specified, and the dialog tool is available, a simple graphical user interface will pop up and guide you through the available functionality. cute, right? 💅

⚠️ NOTE: don't even think about using some random linux-source-x.y.z package contents (or a linux-x.y.z tarball from the Internet) to specify the kernel source for your currently running kernel. Don't! 🛑 those source is not exactly what have been used to build the running kernel and its configuration most likely does not match yours. you need the configured kernel source directory or at least the derived linux-headers-... package containing the kernel configuration for the exact kernel version (complete version string). if you do not understand anything of the above, run "m-a prepare" and/or look at the description and contents of some linux-headers-... package. please run the module-assistant prepare command once before you do anything else. periodt. ✨

for some packages, linux-headers (reduced source) is not enough. you will have the choice to run a completely customized kernel, or to recreate the source that have been used to build the current one. the fakesource function may be useful, see below 👀

in order to configure a kernel source properly, you need to make sure that the file version.h is generated. to get it, configure the options as usual (make menuconfig etc.) and run make dep (for kernel 2.4.x) or make prepare (for newer ones). iykyk 💜

🦋 COMMANDS 🦋

most commands require a specification of the package names that they should be applied on. pkg can be a single word (package name) or multiple names. the word all will be expanded to the list of all available packages, the word alli to the list of currently installed (source) packages, and the word allu will be expanded to the list of packages that seem to be installed and unpacked in the base source directory 🌈 if a source package with the given name is not available, module-assistant (abbreviated: m-a) will extend the package name with the popular suffixes like -kernel, -driver, -module, -source and combinations of them 👑

multiple commands can be specified in one invocation, e.g.:

m-a clean,get,build arla cdfs

which is the short way to write:

module-assistant clean arla-modules-source ; module-assistant clean cdfs-src ; module-assistant get arla-modules-source cdfs-src ; module-assistant build arla-modules-source cdfs-src

(or similar) 🎀

if you do not like the dialog/whiptail GUI, feel free to use the -t switch to disable it 💅

update

update is used to resynchronize the version index files from their sources. this happens with helper scripts provided by the packages. module-assistant has a default built-in list of the packages that it should look for, but other packages can be registered by module-assistant if the maintainer adds the helper script ✨

prepare

tries to determine the name of the required linux-headers package (either the one matching the currently running kernel or for the versions specified with -l), installs it if needed and creates the /usr/src/linux symlink if needed. also installs the build-essential package to ensure that a sane compiler environment is established 🔥

fakesource

experimental function which tries to determine the name of the required/compatible linux-source package, installs it, modifies the Makefile to look like the original source and runs configuration routines as needed.

💀 Warning: DO NOT RELY ON THE RESULTING SOURCE. it may be very different from the original version.

list | list-available | la

list-available (abbreviated with la) presents a list of details about specified packages, including installed version, installable versions and recently built binary packages. if the package names are omitted, shows all known packages. with -v, prints long package paths 👑

list-installed | li

synonym to list alli. acts like list-available but limits the list to the installed source packages 🎀

synonym to list -s. looks for locally compiled packages first and (if none found) searches for alternative installation candidates with apt-cache 🔍

get

get followed by the package list installs the package source, downloading source packages when needed 📥

unpack

unpack is followed by one or more previously-installed source packages that should be extracted from their source tarballs into build directories 🧚

build

build is followed by one or more source packages that should be built. it chooses the kernel source appropriate for the currently running kernel unless different directories have been specified. if the build fails, look for the most recent log file in /var/cache/modass (or the user-specified location) 😭

install

install is followed by one or more packages desired for installation. the last built package for the current running kernel is chosen ✨

auto-install | a-i

auto-install is followed by one or more packages desired for installation. it will run prepare to configure your system to build packages, get the package source, try to build it for the current kernel and install it. you can use alli or allu shortcuts to select all installed modules source packages or only those that have been unpacked before (similar to the make-kpkg tool normally does, looking in $MODULE_LOC) 💅

auto-build | a-b

like auto-install but does not install the package immediately 👀

clean

clean clears the build directories of the kernel packages 🧹

purge

purge clears the information cache of a source package and removes all binary packages locally built from it (that module-assistant knows about).

🚨 USE WITH CARE!

✨ OPTIONS ✨

  • -t, --text-mode — show pure build/install/update logs, no progress bars 📝
  • -k, --kernel-dir — the kernel source directories to be used for builds. you can specify multiple directories with multiple options or separated by commas or line separators, e.g.:
-k "`echo /usr/src/linux-headers-*`"

the kernel versions detected in these directories are automatically added to the list of target kernel versions (see --kvers-list for details) 💜

  • -l, --kvers-list — list of kernel version strings (as in KVERS) to act on. if omitted, the version string of the currently running kernel is inserted. if --kernel-dir specifies additional source directories, the kernel versions that belong to them will be inserted too.

the locations of the kernel source (or headers) that belong to this kernel versions are either detected by a lookup in the "usual" locations on Linux systems, or they must be specified with the --kernel-dir option 🦋

  • -v, --verbose — shows a bit more information, like full paths of the binary packages 👑
  • -n, --no-rebuild — if a package that is to be generated does already exist in the target directory (maybe in on older version), -n prevents from building the package again.

the default behaviour is to skip when exactly the same file (with the same filename) is to be generated as the one that already exists, and the new filename could be detected before starting the build process (depends on the module package) 🎀

  • -f, --force — never look for target file (in another version) and force a build. for the get command, download a newer version of a package even if it is already installed 💪
  • -u, --userdir — all relevant environment variables with paths will be redirected to new directories under the one specified with this option 🌈
  • -i, --non-inter — when the package build was not successful, just continue with other candidates. by default, module-assistant will suggest to examine the build log. this option may also modify the behaviour of dpkg and apt-get to reduce the need for human interaction and install build dependencies as needed 🤖
  • -o, --unpack-once — try to not unpack twice. the option needs to be also specified when the package is being unpacked for the first time.
🧪 experimental option, don't rely on it.
  • -O, --not-unpack — never unpack the source tarball. useful after manual manipulation of module source 🙈
  • -q, --quiet — suppress some of the noisy messages during the processing 🤫
  • -S, --sudo-cmd — a replacement command for superuser commands to be used instead of sudo 🔐
  • -s, --apt-search — see search command for details 🔍
  • -h, --help — prints the usage overview 💖

🌸 ENVIRONMENT VARIABLES 🌸

ok so bestie, you can export these little guys to change how the build scripts act 💖 but lowkey, heads up: some packages are gonna straight-up ignore them or interpret them in their own lil way 🙈 every package is a different girl, yk?

  • KPKG_DEST_DIR — this one tells everyone where the finished Debian package should get installed. BUT ✋ so many packages ignore it and just dump the files into the directory above the kernel source dir, or above the current directory instead. iconic behaviour honestly 💀
  • KERNELDIRS — sets or extends the list of kernel source/header directories that m-a should build modules for 🧚 check the -k option for the deets.
  • SIGNCHANGES — if this is set, .changes files get generated (it calls the kdist_image rule instead of kdist) and then debsign (or gpg, or pgp) runs to sign those changes ✨ very official of you.
  • KMAINT | DEBFULLNAME | DEBNAME — the realname of whoever's building the package 🫶 (only matters for the .changes file, so it's giving main-character credits energy).
  • KEMAIL | DEBEMAIL — the email address of whoever's building the package 💌 (again, only interesting for the .changes file).
  • MODULE_LOC — a whole different location for the already-extracted module source directories 📁 default is /usr/src/modules.
  • MA_VARDIR — a different spot for cached data, used by the helper scripts from module-assistant 🎀 default is /var/cache/modass.
  • MA_APTCMD — the command to download and install packages, used instead of apt-get 👑
  • MOD_SRCDIR — a different location for module source tarballs 🌈 default is /usr/src.
  • ROOT_CMD — a wrapper command to execute stuff as root 🔥 if you're not root, fakeroot gets chosen automatically. this variable has to be interpreted by individual packages, so some of them will just ignore it 🙈 BUT you can still run module-assistant from inside the ROOT_CMD wrapper, so like… slay.

💅 NON-ROOT USAGE 💅

okay so the tea ☕ — module-assistant can work without being root. no cap. BUT:

  • you can't use apt-get or dpkg to install packages 😭
  • you can't write to /var/cache/modass on a normal Debian system

so basically the get, install, auto-install and prepare commands are taboo for regular users 🚫✨

BUT WAIT 🫶 if sudo is installed, it'll get invoked for the apt-get and dpkg operations. problem solved, bestie.

all the remaining commands — except list — need extra environment variables so the target paths move to places the user can actually write to 🧚 and you can trim them all down to one specific location (a writable directory) with the -u switch 💖

🎀 FILES 🎀

  • /usr/share/modass/packages/* — the list of helper scripts shipped right inside the module-assistant package 📦
  • /usr/share/modass/overrides/* — helper scripts that get installed by other packages 👑

👀 SEE ALSO 👀

make-kpkg(1), /usr/share/doc/module-assistant/README

💀 BUGS 💀

go look at the module-assistant bug page — <URL:http://bugs.debian.org/src:module-assistant> 🐛

and if you actually wanna report a bug in module-assistant, pls use the reportbug(1) command, okay? don't just yell into the void 🙏

🔢 RETURN CODES 🔢

  • 0 — success 🎉 we ate.
  • 1..249 — various errors during the build process 😭 it's giving chaos.
  • 254 — problem with permissions 🔒
  • 255 — fixable error after user intervention 🛠️

✨ TODO ✨

the dream list, bestie:

  • Quicklist (fast output without details) ⚡
  • Integration into APT and/or into the init system 🔗
  • "Aggressive" debianisation using the templates set (to generate a package with guessed name from any source that looks like being compatible with kernel 2.6 build system) 👑
  • Automatic transformation of kernel sources to generate .udeb packages 🦋

🌈 AUTHOR 🌈

Module-Assistant was written by Eduard Bloch <blade@debian.org> for the Debian distribution 💜 absolute legend behaviour, fr fr.

and that's the whole page babes 🫶 this gem is from the module-assistant manual, dated 06 September 2003, filed under MODULE-ASSISTANT(8) — yes she's been iconic since 2003 and she's still serving 💅✨ go build some modules, you got this 🎀

📦 where this page comes from