<!-- -*- mode: sgml; mode: fold -*- -->
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [

<!ENTITY moddir "/usr/share/modass">
<!ENTITY cachedir "/var/cache/modass">

]>

<refentry>
 <docinfo>
   <address><email>module-assistant@packages.debian.org</></address>
   <author><firstname>Eduard</> <surname>Bloch</></>
   <copyright><year>2003</> <holder>Eduard Bloch</></>
   <date>06 September 2003</>
 </docinfo>
 <refmeta>
   <refentrytitle>module-assistant</>
   <manvolnum>8</>
 </refmeta>
 
 <!-- Man page title -->
 <refnamediv>
    <refname>module-assistant</>
    <refpurpose>manage kernel modules packages</>
 </refnamediv>

 <!-- Arguments -->
 <refsynopsisdiv>
   <cmdsynopsis>
      <command>module-assistant</>
      <arg><option>-fihnqstv</></arg>
      <arg><option>-k <replaceable>source/headers directory</></option></arg>
      <arg><option>-l <replaceable>kernel versions</></option></arg>
      <group choice=req>
         <arg>update</>
         <arg>search</>
         <arg>prepare</>
         <arg>auto-install</>
         <arg>list</>
         <arg>list-available</>
         <arg>list-installed</>
         <arg>auto-unpacked</>
         <arg>get</arg>
         <arg>build</arg>
         <arg>install</arg>
         <arg>clean</arg>
         <arg>purge</arg>
         <arg>fakesource</>
      </group>   
      <arg choice="opt" rep="repeat"><replaceable>pkg</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
 
 <RefSect1><Title>Description</>
   <para>
   <command/module-assistant/ 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.
   <para>
   Unless the <option/-h/, or <option/--help/ option is given, one of the
         commands below should be present to invoke a function explicitely. If
         no (or no valid) command is specified and the <literal/dialog/ tool is available, a simple graphical user
               interface will pop up and guide you trough the available functionality.
   <para>
   NOTE: don't even think about using some random kernel-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. 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 kernel-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 kernel-headers-... package.
   Please run the <command>module-assistant prepare</command> command once before you do anything else.
   <para>
      For some packages, kernel-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
      <command/fakesource/ function may be useful, see below.
   <para>
      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 (<command>make menuconfig</command> etc.) and run <command>make dep</command> (for kernel 2.4.x) or <command>make prepare</command> (for newer ones).
     
 </RefSect1>

 <RefSect1><Title>Commands</>
 <para>
    Most commands require a specification of the package names that they should be applied on.
    <command/pkg/ can be a single word (package name) or multiple
   names. The word <command/all/ will be expanded to the list of all available
   packages, the word <command/alli/ to the list of currently installed
      (source) packages and the word <command/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, <command/module-assistant/ (abbreviated: <command/m-a/) will extend the package name with the popular suffixes like -kernel, -driver, -module, -source and combinations of them.
               <para>
         Multiple commands can be specified in one
   invocation, eg. "<command/m-a clean,get,build arla cdfs/" 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-assistan build arla-modules-source cdfs-src" (or similar).
   <para>
      If you do not like the dialog/whiptail GUI, feel free to use the <option/-t/ switch to disable it.
   <para>

   <VariableList>
     <VarListEntry><Term>update</Term>
     <ListItem><Para>
     <literal/update/ is used to resynchronize the version index files from
     their sources. This happens with helper scripts provided by the
     packages. <command/module-assistant/ has a default built-in list of
     the packages that it should look for but other packages can
     be registred by <command/module-assistant/ if the maintainer adds
     the helper script.
     </VarListEntry>

     <VarListEntry><Term>prepare</Term>
     <ListItem><Para>
     Tries to determine the name of the
     required kernel-headers package (either the one matching the currently
     running kernel or for the versions specified with -l), installs it if
     needed and creates the <literal>/usr/src/linux</> symlink if needed.
     </VarListEntry>

     <VarListEntry><Term>fakesource</Term>
     <ListItem><Para>
     Experimental function which tries to determine the name of the
     required/compatible kernel-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.
     </VarListEntry>
     
     <VarListEntry><Term>list | list-available | la</Term>
     <ListItem><Para>   
     <literal/list-available/ (abbreviated with <literal/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 <option/-v/, prints long package paths.
     </VarListEntry>

     <VarListEntry><Term>list-installed | li</Term>
     <ListItem><Para>   
     Synonym to <literal/list alli/. Acts like <literal/list-available/
     but limits the list to the installed source packages. 
     </VarListEntry>

     <VarListEntry><Term>search</Term>
     <ListItem><Para>   
     Synonym to <literal/list -s/. Looks for locally compiled packages
     first and (if none found) searches for alternative installation
     candidates with apt-cache.
     </VarListEntry>

     <VarListEntry><Term>get</Term>
     <ListItem><Para>   
     <literal/get/ followed by the package list installs the package
     source, downloading source packages when needed.
     </VarListEntry>

     <VarListEntry><Term>build</Term>
     <ListItem><Para>   
     <literal/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).
     </VarListEntry>

     <VarListEntry><Term>install</Term>
     <ListItem><Para>   
     <literal/install/ is followed by one or more packages desired for 
     installation. The last built package for the current running kernel
     is chosen.
     </VarListEntry>

     <VarListEntry><Term>auto-install | a-i</Term>
     <ListItem><Para>   
     <literal/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 <literal/alli/ or <literal/allu/ shortcuts to select all
           installed modules source packages or only those that have been
           unpacked before (similar to the <literal/make-kpkg/ tool normaly
              does, looking in $MODULE_LOC)
     </VarListEntry>

     <VarListEntry><Term>auto-build | a-b</Term>
     <ListItem><Para>   
           like <literal/auto-install/ but does not install the package immediately
     </VarListEntry>

     <VarListEntry><Term>clean</Term>
     <ListItem><Para>   
     <literal/clean/ clears the build directories of the kernel
     packages.
     </VarListEntry>

     <VarListEntry><Term>purge</Term>
     <ListItem><Para>   
     <literal/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!
     </VarListEntry>

   </VariableList>
 </RefSect1>
 
 <RefSect1><Title>Options</>

   <VariableList>
   
     <VarListEntry><term><option/-t/</><term><option/--text-mode/</>
     <ListItem><Para>
     Show pure build/install/update logs, no progress bars.
     </VarListEntry>

     <VarListEntry><term><option/-k/</><term><option/--kernel-dir/</>
     <ListItem><Para>
     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 
     <command>-k "`echo /usr/src/kernel-headers-*`"</command>
     ).
     The kernel versions detected in this directories are automaticaly added to
     the list of target kernel versions (see <option>--kvers-list</option> for
     details).
     </VarListEntry>

   <VarListEntry><term><option/-l/</><term><option/--kvers-list/</>
   <ListItem><Para>
   List of kernel version strings (as in KVERS) to act on. If omitted,
   the version string of the currently running kernel is inserted. If
   <option>--kernel-dir</option> specifies additional source
   directories, the kernel versions that belong to them will be inserted
   too.
   <para>
      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
      <option>--kernel-dir</option> option.
   </VarListEntry>

     <VarListEntry><term><option/-v/</><term><option/--verbose/</>
     <ListItem><Para>
     Shows a bit more information, like full paths of the binary
     packages.
     </VarListEntry>

     <VarListEntry><term><option/-n/</><term><option/--no-rebuild/</>
     <ListItem><Para>
     If a package that is to be generated does already exist in the
     target directory (maybe in on older version), <option/-n/ prevents
     from building the package again. 
     <para>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).
     </VarListEntry>

     <VarListEntry><term><option/-f/</><term><option/--force/</>
     <ListItem><Para>
     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.
     </VarListEntry>

     <VarListEntry><term><option/-u/</><term><option/--userdir/</>
     <ListItem><Para>
     All relevant environment variables with paths will be redirected to
     new directories under the one specified with this option.
     </VarListEntry>

     <VarListEntry><term><option/-i/</><term><option/--non-inter/</>
     <ListItem><Para>
     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.
     </VarListEntry>

     <VarListEntry><term><option/-s/</><term><option/--apt-search/</>
     <ListItem><Para>
     See <literal/search/ command for details.
     </VarListEntry>

     <VarListEntry><term><option/-h/</><term><option/--help/</>
     <ListItem><Para>
     Prints the usage overview.
     </VarListEntry>
   </VariableList>
     
 </RefSect1>
 <RefSect1><Title>ENVIRONMENT VARIABLES</>
 <para>
 You can export the following environment variables to modify the
 behaviour of the build scripts. Some packages may ignore them or
 interpret them differently.
   <VariableList>
     <VarListEntry><Term>KPKG_DEST_DIR</Term>
     <ListItem><Para>
     <literal/KPKG_DEST_DIR/ 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.
     </VarListEntry>
     <VarListEntry><Term>SIGNCHANGES</Term>
     <ListItem><Para>
     If <literal/SIGNCHANGES/ is set, .changes files will be generated
     (calling <literal/kdist_image/ rule instead of kdist) and debsign (or gpg or
     pgp) will be executed to sign the changes.
     </VarListEntry>
     <VarListEntry><Term>KMAINT | DEBFULLNAME | DEBNAME</Term>
     <ListItem><Para>
     Specifies the realname of the person building the package,
     interesting for .changes file only. In addition, if KMAINT is set
     and <literal/KPKG_DEST_DIR/ is not, <literal/DEB_DESTDIR/ will
     become <literal>$(KSRC)/..</>.
     </VarListEntry>
     <VarListEntry><Term>KEMAIL | DEBEMAIL </Term>
     <ListItem><Para>
     Specifies the realname of the person building the package
     (interesting for .changes file only).
     </VarListEntry>
     <VarListEntry><Term>MODULE_LOC</Term>
     <ListItem><Para>
     A different location for the (already extracted) module source
     directories. Default is <filename>/usr/src/modules</>.
     </VarListEntry>
     <VarListEntry><Term>MA_VARDIR</Term>
     <ListItem><Para>
     A different location for cached data, used by helper scripts from
     <command/module-assistant/. Default is <filename>/var/cache/modass</>.
     </VarListEntry>
     <VarListEntry><Term>MOD_SRCDIR</Term>
     <ListItem><Para>
     A different location for module source tarballs. Default is
     <filename>/usr/src</>.
     </VarListEntry>
     <VarListEntry><Term>ROOT_CMD</Term>
     <ListItem><Para>
     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.
     </VarListEntry>
   </VariableList>
 </RefSect1>

 <RefSect1><Title>Non-Root usage</>
   <para>
   <command/module-assistant/ 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 /var/cache/modass on a normal Debian system. So the
   commands are <command>get</>, <command>install</>,
   <command>auto-install</> and <command>prepare</> 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 <command>list</>
   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.
</RefSect1>
     
 <RefSect1><Title>Files</>
   <variablelist>
     <VarListEntry><term><filename>/usr/share/modass/packages/*</></term>
     <ListItem><Para>
     List of helper scripts shipped with the module-assistant package.
     </VarListEntry>

     <VarListEntry><term><filename>/usr/share/modass/overrides/*</></term>
     <ListItem><Para>
     Helper scripts installed by other packages.
     </VarListEntry>
    </variablelist>
 </RefSect1>

 <RefSect1><Title>See Also</>
   <para>
   <CiteRefEntry>
     <RefEntryTitle>
       <command/make-kpkg/
     </RefEntryTitle>
       <ManVolNum/1/
   </CiteRefEntry>
   ,
   <CiteRefEntry>
        <RefEntryTitle>
                <filename>/usr/share/doc/module-assistant/RATIONALE</>
        </RefEntryTitle>
   </CiteRefEntry>
   
 </RefSect1>

 <RefSect1><Title>Bugs</>
   <para>
   See the <ulink url='http://bugs.debian.org/src:module-assistant'>module-assistant bug page</>.  
   If you wish to report a bug in module-assistant, please use 
   the <CiteRefEntry><RefEntryTitle><command/reportbug/
   </RefEntryTitle>
        <ManVolNum/1/
   </CiteRefEntry>
    command.
 </RefSect1>


 <RefSect1><Title>Return codes</>
   <VariableList>
     <VarListEntry><Term>0</Term>
     <ListItem><Para>
           Success
     </VarListEntry>
     <VarListEntry><Term>1..249</Term>
     <ListItem><Para>
           various errors during the build process
     </VarListEntry>
     <VarListEntry><Term>254</Term>
     <ListItem><Para>
          problem with permissions 
     </VarListEntry>
     <VarListEntry><Term>255</Term>
     <ListItem><Para>
          fixable error after user intervention 
     </VarListEntry>
  </VariableList>
 </RefSect1>

<RefSect1><Title>TODO</>
   <para>
      Quicklist (fast output without details)
   <para>
      Integration into APT and/or into the init system
   <para>
      "Aggressive" debianisation using the templates set (to generate a package
      with guessed name from any source that looks like beeing compatible with
      kernel 2.6 build system)
   <para>
      automatic transformation of kernel sources to generate .udeb packages
 </RefSect1>

<RefSect1><Title>Author</>
   <para>
   Module-Assistant was written by Eduard Bloch <email>blade@debian.org</> for the
   Debian distribution.
 </RefSect1>
 
</refentry>