/usr/share/doc/module-assistant/index.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>module-assistant</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><H1
><A
NAME="AEN1"
></A
>module-assistant</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN15"
></A
><H2
>Name</H2
>module-assistant&nbsp;--&nbsp;manage kernel modules packages</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN18"
></A
><H2
>Synopsis</H2
><P
><B
CLASS="COMMAND"
>module-assistant</B
>  [<CODE
CLASS="OPTION"
>-fihnqstv</CODE
>] [<CODE
CLASS="OPTION"
>-k <TT
CLASS="REPLACEABLE"
><I
>source/headers directory</I
></TT
></CODE
>] [<CODE
CLASS="OPTION"
>-l <TT
CLASS="REPLACEABLE"
><I
>kernel versions</I
></TT
></CODE
>] {update | search | prepare | auto-install | list | list-available | list-installed | auto-unpacked | get | build | install | clean | purge | fakesource} [<TT
CLASS="REPLACEABLE"
><I
>pkg</I
></TT
>...]</P
><P
><B
CLASS="COMMAND"
>m-a ...</B
> </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN48"
></A
><H2
>Description</H2
><P
>   <B
CLASS="COMMAND"
>module-assistant</B
> is the command-line tool for handling
   module-source packages that have been prepared for the Debian
   distribution. It helps users to build and install module package(s)
   easily for one or more custom kernels.

   </P
><P
>   Unless the <CODE
CLASS="OPTION"
>-h</CODE
>, or <CODE
CLASS="OPTION"
>--help</CODE
> option is given, one of
   the commands below should be present to invoke a function
   explicitly. If no (or no valid) command is specified and the
   <TT
CLASS="LITERAL"
>dialog</TT
> tool is available, a simple graphical user
   interface will pop up and guide you trough the available
   functionality.

   </P
><P
>   NOTE: don't even think about using some random linux-source-x.y.z
   package contents (or linux-x.y.z tarball from the Internet) to
   specify the kernel source for your currently running
   kernel. <B
CLASS="COMMAND"
>Don't!</B
> 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 <B
CLASS="COMMAND"
>module-assistant prepare</B
> command once before
   you do anything else.

   </P
><P
>   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 <B
CLASS="COMMAND"
>fakesource</B
> function may be useful, see
   below.

   </P
><P
>   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 (<B
CLASS="COMMAND"
>make menuconfig</B
> etc.)  and
   run <B
CLASS="COMMAND"
>make dep</B
> (for kernel 2.4.x) or <B
CLASS="COMMAND"
>make
   prepare</B
> (for newer ones).
 </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN65"
></A
><H2
>Commands</H2
><P
>   Most commands require a specification of the package names that
   they should be applied on.  <B
CLASS="COMMAND"
>pkg</B
> can be a single word
   (package name) or multiple names. The word <B
CLASS="COMMAND"
>all</B
> will be
   expanded to the list of all available packages, the word
   <B
CLASS="COMMAND"
>alli</B
> to the list of currently installed (source) packages
   and the word <B
CLASS="COMMAND"
>allu</B
> 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, <B
CLASS="COMMAND"
>module-assistant</B
> (abbreviated: <B
CLASS="COMMAND"
>m-a</B
>)
   will extend the package name with the popular suffixes like
   -kernel, -driver, -module, -source and combinations of them.

   </P
><P
>   Multiple commands can be specified in one invocation,
   eg. "<B
CLASS="COMMAND"
>m-a clean,get,build arla cdfs</B
>" 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).

   </P
><P
>   If you do not like the dialog/whiptail GUI, feel free to use the
   <CODE
CLASS="OPTION"
>-t</CODE
> switch to disable it.

   </P
><P
>   <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>update</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>update</TT
> is used to resynchronize the version index files
     from their sources. This happens with helper scripts provided by
     the packages. <B
CLASS="COMMAND"
>module-assistant</B
> has a default built-in
     list of the packages that it should look for but other packages
     can be registered by <B
CLASS="COMMAND"
>module-assistant</B
> if the maintainer
     adds the helper script.
     </P
></DD
><DT
>prepare</DT
><DD
><P
>     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 <TT
CLASS="LITERAL"
>/usr/src/linux</TT
> symlink if
     needed. Also installs the build-essential package to ensure that
     a sane compiler environment is established.
     </P
></DD
><DT
>fakesource</DT
><DD
><P
>     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.
     </P
></DD
><DT
>list | list-available | la</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>list-available</TT
> (abbreviated with <TT
CLASS="LITERAL"
>la</TT
>) 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 <CODE
CLASS="OPTION"
>-v</CODE
>, prints long package paths.
     </P
></DD
><DT
>list-installed | li</DT
><DD
><P
>     Synonym to <TT
CLASS="LITERAL"
>list alli</TT
>. Acts like
     <TT
CLASS="LITERAL"
>list-available</TT
> but limits the list to the installed
     source packages.
     </P
></DD
><DT
>search</DT
><DD
><P
>     Synonym to <TT
CLASS="LITERAL"
>list -s</TT
>. Looks for locally compiled packages
     first and (if none found) searches for alternative installation
     candidates with apt-cache.
     </P
></DD
><DT
>get</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>get</TT
> followed by the package list installs the package
     source, downloading source packages when needed.
     </P
></DD
><DT
>build</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>build</TT
> 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).
     </P
></DD
><DT
>install</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>install</TT
> is followed by one or more packages desired for
     installation. The last built package for the current running
     kernel is chosen.
     </P
></DD
><DT
>auto-install | a-i</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>auto-install</TT
> 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
     <TT
CLASS="LITERAL"
>alli</TT
> or <TT
CLASS="LITERAL"
>allu</TT
> shortcuts to select all
     installed modules source packages or only those that have been
     unpacked before (similar to the <TT
CLASS="LITERAL"
>make-kpkg</TT
> tool normally
     does, looking in $MODULE_LOC)
     </P
></DD
><DT
>auto-build | a-b</DT
><DD
><P
>     like <TT
CLASS="LITERAL"
>auto-install</TT
> but does not install the package
     immediately
     </P
></DD
><DT
>clean</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>clean</TT
> clears the build directories of the kernel
     packages.
     </P
></DD
><DT
>purge</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>purge</TT
> 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!
     </P
></DD
></DL
></DIV
>
 </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN152"
></A
><H2
>Options</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="OPTION"
>-t</CODE
>, <CODE
CLASS="OPTION"
>--text-mode</CODE
></DT
><DD
><P
>   Show pure build/install/update logs, no progress bars.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-k</CODE
>, <CODE
CLASS="OPTION"
>--kernel-dir</CODE
></DT
><DD
><P
>   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 using
   <B
CLASS="COMMAND"
>-k "`echo /usr/src/linux-headers-*`"</B
>
   ).
   The kernel versions detected in this directories are automatically
   added to the list of target kernel versions
   (see <CODE
CLASS="OPTION"
>--kvers-list</CODE
> for details).
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-l</CODE
>, <CODE
CLASS="OPTION"
>--kvers-list</CODE
></DT
><DD
><P
>   List of kernel version strings (as in KVERS) to act on. If omitted,
   the version string of the currently running kernel is inserted. If
   <CODE
CLASS="OPTION"
>--kernel-dir</CODE
> specifies additional source
   directories, the kernel versions that belong to them will be
   inserted too.
   </P
><P
>   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
   <CODE
CLASS="OPTION"
>--kernel-dir</CODE
> option.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-v</CODE
>, <CODE
CLASS="OPTION"
>--verbose</CODE
></DT
><DD
><P
>   Shows a bit more information, like full paths of the binary
   packages.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-n</CODE
>, <CODE
CLASS="OPTION"
>--no-rebuild</CODE
></DT
><DD
><P
>   If a package that is to be generated does already exist in the
   target directory (maybe in on older version), <CODE
CLASS="OPTION"
>-n</CODE
> prevents
   from building the package again.
   </P
><P
>   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).
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-f</CODE
>, <CODE
CLASS="OPTION"
>--force</CODE
></DT
><DD
><P
>   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.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-u</CODE
>, <CODE
CLASS="OPTION"
>--userdir</CODE
></DT
><DD
><P
>   All relevant environment variables with paths will be redirected to
   new directories under the one specified with this option.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-i</CODE
>, <CODE
CLASS="OPTION"
>--non-inter</CODE
></DT
><DD
><P
>   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.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-o</CODE
>, <CODE
CLASS="OPTION"
>--unpack-once</CODE
></DT
><DD
><P
>   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.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-O</CODE
>, <CODE
CLASS="OPTION"
>--not-unpack</CODE
></DT
><DD
><P
>   Never unpack the source tarball. Usefull after manual manipulation
   of module source.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-q</CODE
>, <CODE
CLASS="OPTION"
>--quiet</CODE
></DT
><DD
><P
>   Suppress some of the noisy messages during the processing.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-S</CODE
>, <CODE
CLASS="OPTION"
>--sudo-cmd</CODE
></DT
><DD
><P
>   A replacement command for superuser commands to be used instead of
   <TT
CLASS="LITERAL"
>sudo</TT
>.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-s</CODE
>, <CODE
CLASS="OPTION"
>--apt-search</CODE
></DT
><DD
><P
>   See <TT
CLASS="LITERAL"
>search</TT
> command for details.
   </P
></DD
><DT
><CODE
CLASS="OPTION"
>-h</CODE
>, <CODE
CLASS="OPTION"
>--help</CODE
></DT
><DD
><P
>   Prints the usage overview.
   </P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN262"
></A
><H2
>ENVIRONMENT VARIABLES</H2
><P
>   You can export the following environment variables to modify the
   behaviour of the build scripts. Some packages may ignore them or
   interpret them differently.

   <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>KPKG_DEST_DIR</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>KPKG_DEST_DIR</TT
> specify the target directory where the
     resulting Debian package should be installed into. However, many
     packages ignore this variable and install the file into the
     directory above the kernel source directory or above the current
     directory.
     </P
></DD
><DT
>KERNELDIRS</DT
><DD
><P
>     <TT
CLASS="LITERAL"
>KERNELDIRS</TT
> specifies or extends the list of kernel
     source/header directory which m-a should build modules for. See
     /-k/-Option for details.
     </P
></DD
><DT
>SIGNCHANGES</DT
><DD
><P
>     If <TT
CLASS="LITERAL"
>SIGNCHANGES</TT
> is set, .changes files will be generated
     (calling <TT
CLASS="LITERAL"
>kdist_image</TT
> rule instead of kdist) and debsign
     (or gpg or pgp) will be executed to sign the changes.
     </P
></DD
><DT
>KMAINT | DEBFULLNAME | DEBNAME</DT
><DD
><P
>     Specifies the realname of the person building the package
     (interesting for .changes file only)
     </P
></DD
><DT
>KEMAIL | DEBEMAIL</DT
><DD
><P
>     Specifies the email address of the person building the package
     (interesting for .changes file only).
     </P
></DD
><DT
>MODULE_LOC</DT
><DD
><P
>     A different location for the (already extracted) module source
     directories. Default is <TT
CLASS="FILENAME"
>/usr/src/modules</TT
>.
     </P
></DD
><DT
>MA_VARDIR</DT
><DD
><P
>     A different location for cached data, used by helper scripts from
     <B
CLASS="COMMAND"
>module-assistant</B
>. Default
     is <TT
CLASS="FILENAME"
>/var/cache/modass</TT
>.
     </P
></DD
><DT
>MA_APTCMD</DT
><DD
><P
>              Command to download install packages, to use instead of the
              <B
CLASS="COMMAND"
>apt-get</B
>.
     </P
></DD
><DT
>MOD_SRCDIR</DT
><DD
><P
>     A different location for module source tarballs. Default is
     <TT
CLASS="FILENAME"
>/usr/src</TT
>.
     </P
></DD
><DT
>ROOT_CMD</DT
><DD
><P
>     Wrapper command to execute command as root. If you are not root,
     fakeroot is chosen automatically. This variable must be
     interpreted by individual packages so some of them may ignore
     it. However, you can still run module-assistant inside of the
     ROOT_CMD wrapper.
     </P
></DD
></DL
></DIV
>
 </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN315"
></A
><H2
>Non-Root usage</H2
><P
>   <B
CLASS="COMMAND"
>module-assistant</B
> can work without being root. However you
   won't be able to use apt-get or dpkg to install the packages, and
   you cannot write to <TT
CLASS="FILENAME"
>/var/cache/modass</TT
> on a
   normal Debian system. So the commands
   are <B
CLASS="COMMAND"
>get</B
>, <B
CLASS="COMMAND"
>install</B
>,
   <B
CLASS="COMMAND"
>auto-install</B
> and <B
CLASS="COMMAND"
>prepare</B
> are taboo for
   regular users. However, if the sudo program is installed, it will be
   invoked for apt-get and dpkg operations.
   All remaining commands except of <B
CLASS="COMMAND"
>list</B
>
   require additional environment variables to move the target paths to
   locations writable for the user. They all can be trimmed to a
   certain location (a writable directory) using the -u switch.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN325"
></A
><H2
>Files</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="FILENAME"
>/usr/share/modass/packages/*</TT
></DT
><DD
><P
>     List of helper scripts shipped with the module-assistant package.
     </P
></DD
><DT
><TT
CLASS="FILENAME"
>/usr/share/modass/overrides/*</TT
></DT
><DD
><P
>     Helper scripts installed by other packages.
     </P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN338"
></A
><H2
>See Also</H2
><P
>   <SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
><B
CLASS="COMMAND"
>make-kpkg</B
></SPAN
>(1)</SPAN
>,
   <SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
><TT
CLASS="FILENAME"
>/usr/share/doc/module-assistant/README</TT
></SPAN
></SPAN
>
 </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN348"
></A
><H2
>Bugs</H2
><P
>   See the <A
HREF="http://bugs.debian.org/src:module-assistant"
TARGET="_top"
>module-assistant bug page</A
>.
   If you wish to report a bug in module-assistant, please use
   the
   <SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
><B
CLASS="COMMAND"
>reportbug</B
></SPAN
>(1)</SPAN
>
   command.
 </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN356"
></A
><H2
>Return codes</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>0</DT
><DD
><P
>     Success
     </P
></DD
><DT
>1..249</DT
><DD
><P
>     various errors during the build process
     </P
></DD
><DT
>254</DT
><DD
><P
>     problem with permissions
     </P
></DD
><DT
>255</DT
><DD
><P
>     fixable error after user intervention
     </P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN375"
></A
><H2
>TODO</H2
><P
>   Quicklist (fast output without details)

   </P
><P
>   Integration into APT and/or into the init system

   </P
><P
>   "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)

   </P
><P
>   Automatic transformation of kernel sources to generate .udeb packages
 </P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN381"
></A
><H2
>Author</H2
><P
>   Module-Assistant was written by Eduard
   Bloch <CODE
CLASS="EMAIL"
>&#60;<A
HREF="mailto:blade@debian.org"
>blade@debian.org</A
>&#62;</CODE
> for the Debian distribution.
 </P
></DIV
></BODY
></HTML
>
module-assistant 0.11.4 / usr / share / doc / module-assistant / index.html
