This version of the manual is written for deb-install 0.6. Older versions of deb-install do not have all of the functionality described here.

Contents

  1. Introduction to deb-install
  2. Parameters of deb-install
  3. Tasks
  4. Adjusting the behaviour of deb-install
  5. Technical informations
  6. Complementary topics
  7. Contact and Feedback

Introduction to deb-install

The program "deb-install" is intended to simplify installation and removal of programs on debian based systems. It is a command line tool which can understand many different packaging formats, both binary and source.
deb-install uses the complete tool-chain for package management that comes with every debian distribution (apt-get, dpkg, apt-cache, ...). It prints out which tool it uses in which situation, to give the user a clue how to do things manually, if he so desires.
deb-install -h will give a short summary of how to achieve what with this program. The more eleborate explainations can be found in this document.

Parameters of deb-install

Check mode

deb-install -c or deb-install --check will start deb-install in check mode.
It checks the following:
  • whether all the base tools are installed (if one is missing, deb-install proposes to install it)
  • whether the files /dev/zero and /dev/null are ok (if not, they are recreated)
  • whether there are remnants of a crashed deb-install (if found, they are removed)
  • whether your $PATH variable has all the nessecary entries (if one is missing, a line is added to /etc/bash.rc to fix it)
  • whether apt-get thinks that your package system is clean (if it doesn't, deb-install tries to fix it [this attempt is not always successful])

  • After the crash check deb-install will update it's database (more precisely the databases of apt-get and apt-file, depending on how UPDATEWHAT is set [standard is UPDATEWHAT=apt-get])

    -s / --search / --show : Search mode

    deb-install -s or deb-install --search or deb-install --show will start deb-install in search mode.
    deb-install tries to give you as much information as it can about the string you hand over to it. (see also: regular expressions)
  • First it will look whether there is a file/folder of that name. If there is, it will print informations about a .rpm or about about a .deb file (otherwise the file is skipped). In case of a folder it will tell whether it seems to be automatically buildable (see also: --archive-only).
  • Then deb-install looks whether there is a package of that name. If there is, informations about that package will be displayed.
  • Then deb-install will look for packages that contain the search pattern in their name. If it can't find any that do, it will look for packages containing the search pattern in their description.
  • Then deb-install will look for a file of the same name as your search string.
  • If nothing of the above was successfull, deb-install will search for a file that contains the search pattern as a part of its name.

  • In the last three cases the results will be displayed one file/package per line. At the end of each line one out of three things is written:
  • (not installed) - the package is not installed
  • <version> - the package is installed in version <version>. There is no upgrade available.
  • <version1> --> <version2> - the package is installed in version <version1>, and there is an upgrade to version <version2> available.

  • -u / --update : Update mode

    Updates the package, if it is already installed. And updates all the dependencies+recommendations+suggestions of the package (again, if they are already installed). (see also: regular expressions)
    If such a dependency (/recommendation/suggestion) is a metapackage, the process recurses.

    Example:

    deb-install -u kde updates the package kde, if it is installed (it probably isn't). It also updates the metapackages kde depends on: kdemultimedia, kdenonbeta, kdegames, ... (If you use kde, a few of them will be installed.) Since they are metapackages, update recurses into them, and updates their dependencies as well: juk, kgolf, ...
    Since those aren't metapackages, the process stops here. So, in effect, this command has updated all your kde packages :-)

    -i / --install : Install mode

    Installs a file or a package. (see also: regular expressions)
    First deb-install checks whether there is a file of that name.
    If there is: See Installing a file.
    If there isn't: It checks whether apt-get knows a package of that name.
    If apt-get knows the package, deb-install hands over to apt-get (See Installing a new package for a checklist before entering such a command.)

    -h / --help : Concise help

    Prints out a concise help for deb-install.

    -v / --version

    Prints out the version number, license, and contact address for deb-install.

    -ao / --archive-only: Do not look for matching local file names

    This option keeps deb-install from trying to match your string/regular expression against local file names. Instead it goes straight to the package archive and looks for matches there.
    This can be useful if you are working with regular expressions, or if you just happen to have a file in your current directory, that has the same name as the package you are interested in.
    Furthermore it keeps autocompletion from matching local files against what you already typed in when you hit TAB.

    -lf / --list-files: Search mode with file listing

    This option puts deb-install into search mode, but with a twist: Normally deb-install only lists executable files contained within an archive. With this option, every contained file is listed instead.

    -fo / --force-overwrite

    This option can damage your system!
    It should only be used by people who are willing to risk that, or have investigated enough to be sure it won't do any harm in their particular case.
    Installing a package results in new files being added into your system. Normally deb-install will refuse to install a package that wants to replace files. The option "force-overwrite" changes this behaviour, and allows replacing.
    Why is this dangerous? The overwriten file could be from a completely different program, that was just unlucky enough to have an identically named file. Or it could be a different version of the same library, breaking any program relying on that different version (known in the windows world as "DLL hell").
    By the way: Replacing an older version of the same program should always be possible without this option, as the package management removes the old version before it installs the new one.
    This option doesn't have any effect on packages that are installed through apt-get, since apt-get does not know such an option.

    -- : No more options

    This option is supported by most Unix tools. Its meaning is: This is the last option, only filenames/packagenames follow.
    This is useful if you want to call deb-install with a file that starts with a dash.
    Example: If you want to install a file named -file.rpm, then deb-install -i -file.rpm won't work (aborts with "unknown option").
    But deb-install -i -- -file.rpm does work!

    Without arguments

    deb-install alone, without an option or file-/packagename appended, will get deb-install to retry, if it aborted on the last attempt. This works only on local files.
    Example: If the compilation of a package failed because of a missing file, you can provide that file, and then run deb-install to let the compilation continue.

    However, if your original command specified a regular expression as filename, retrying won't continue with other matches of the regular expression. Once the current input file is successfully processed, deb-install finishes.
    So, if you issued the command deb-install -i (emacs|konqueror).tar.gz, and compilation of emacs.tar.gz failed, you then run deb-install without arguments, and this time the compilation succeded, deb-install won't try to process konqueror.tar.gz afterwards.

    --abort-on

    Use this option if you don't want deb-install to install the package, but stop earlier (works only with local files). You have to specify, upon reaching which state deb-install should stop.
    Possible values:
  • --abort-on debianBinary - aborts as soon as the .deb package has been generated
  • --abort-on analysing - aborts as soon as the package has been unpacked into the temp directory
  • --abort-on debianSourceDirectory - for installations of source archives: aborts as soon as the directory has been debianized (compilation into .deb would be next)
  • There are more states, but those should be the ones useful for manual interruption (Tip: you can use tab completion to type out the states for you).
    Whenever deb-install aborts, either because it was told to, or because it encountered an error, it leaves behind its temp directory. Take a look at the file /tmp/deb-install_<username>/deb-install.mode: It contains the state deb-install will reassume if started without arguments.

    --make / --configure

    The word following one of these options is passed through to make or configure. Use single quotes (') to keep the bash from interpreting it.
    Example: deb-install --make 'CFLAGS="-O3"' ./wesnoth.tar.gz
    Important: These two options are only applied when building from a source archive, not when compiling from a debian source package!
    These options are not the only ones passed to make and configure, they are added behind the other ones.

    --dpkg-buildpackage

    The word following this option is passed through to dpkg-buildpackage. Use single quotes (') to keep the bash from interpreting it.
    Example: deb-install --dpkg-buildpackage '-d' ./wesnoth.tar.gz

    Tasks

    Installing a new package

    To install a new package:
    1. Make sure the file /etc/apt/sources.list looks the way you want it to.
    2. Make sure you are online. (if you aren't installing from cdroms)
    3. Especially before you start a bigger install session (e.g. kde) it can't hurt to run deb-install -c, which makes sure your environment is sane and which updates the database of apt-get (if you haven't configured UPDATEWHAT=none) (see Check mode)
    4. Use deb-install -s <packagename> to make sure the program you want to install hides behind the package name you think it does, and to make sure you will install the version you want. (see also: Bash autocompletion)
      If you don't know the packagename, look into the section Finding a program.
    5. Install the package using deb-install -i <packagename> If additional packages have to be installed/updated to achieve that, you will be asked.

    Installing a file

    To install a file, type deb-install -i <filename> just like you would specify it for any other command line tool. If you install a file using deb-install, it becomes integrated into the debian package management system, and thus easily removable (see: removing a package)
    Example: You have downloaded the file "audacity.tgz" into your home directory. Type deb-install -i ~/audacity.tgz to compile and install it.
    The currently supported filetypes are:
  • .deb - a debian archive
  • .rpm - a red hat package management archive
  • .dsc - a debian source package (the corresponding .tar.gz file has to be in the same directory)
  • .tgz - a slackware package (may contain a source archive instead)
  • .tar / .zip - a source archive (deb-install will try to figure out how to build it, but sometimes that is an impossible task (e.g. nethack). I have set up a wiki page that lists programs and whether they build automatically with deb-install.)
  • a directory - either a generic source directory or a debian source directory

  • All of the above can be compressed. deb-install simply uncompresses them first. Supported compressions:
  • gzip compressed: .gz, .z, .Z, .tgz, .tz, .tZ (everything that on "file <filename>" returns "gzip compressed")
  • bzip2 compressed: .bz, .bz2, .tbz, .tbz2 (everything that on "file <filename>" returns "bzip2 compressed")

  • A few more words to the installing of source archives (as opposed to debian source packages): They don't contain dependencies!
    That means that you will have to take a look at the compilation instructions on the website to find out what you need to have installed for the compile to succeed. And look at the optional stuff before you ignore it: It is often neccessary for features you don't want to do without (e.g. music in games).
    In most cases it isn't enough to install the binary version of the auxiliary program/library: If the source archive you want to compile links against it, you will need either the header files or the dev version installed as well. (the dev versions are named like the binary versions with a -dev appended, and they have the binary version as a dependency)
    A Tip: Use the package management system (see: Installing a new package) to install these auxiliary programs/libraries. You save yourself lots of headaches if you don't try to compile everything from source archives...

    deb-install never touches the file you specified, but copies it into the /tmp directory and works with it from there.

    Removing a package

    To remove a package, use the command apt-get remove <packagename>.
    Alternatively you can use the command apt-get --purge remove <packagename>. That command additionally deletes the configuration files of the package, and possibly user saved data as well. A game for example would almost certainly delete game saves as well, if removed with this command.

    Finding a program

    Ok, you want to install a program to edit sound files. Now what?
    Take a look at the web-page http://linuxshop.ru/linuxbegin/win-lin-soft-en/table.shtml (or google for linux windows, and follow the first hit) There you will find a category "Multimedia: Audio/CD". Following this link one of the boxes in the table is labeled "Audio editors", where you find links to the homepages of the projects, and thus can inform yourself about the available alternatives. Lets say you find that the program "audacity" sounds promising: Take note which version is offered on the website, and decide whether you want to install the stable version or maybe the newer development snapshot (not all projects offer development snapshots).
    Use deb-install -s audacity to find out which version is known to the apt-tools, and whether the package is named exactly this way. (see also: Bash autocompletion)
  • If you now know the packagename and want to install the version reported: Install the package
  • If the package system doesn't know the program or if you want to have the newer version from the website: Download and install the file offered on the website.

  • Adjusting the behaviour of deb-install

    Standard behaviour

    This is the default behaviour of deb-install as long as you don't modify it's configuration files:
  • If you just type deb-install <filename/packagename> it will display informations about that file/package.
    (DEBINSTALLMODE=search)
  • deb-install will update the database of apt-get for you.
    (UPDATEWHAT=apt-get)
  • deb-install will update the database if it is started as root and at least a day has passed since it last updated the database.
    (UPDATEWHEN=1440) [1440 Minutes are a day]
  • deb-install will delete cached package files that are neither downloadable nor installed [used command: "apt-get autoclean"]
    (AUTOCLEAN=yes)

  • Editing the configuration files

    The configuration file /etc/deb-install.conf is valid for all users.
    The preferences specified there can be overwritten on a per-user base by the configuration-file ~/.deb-install/deb-install.conf.

    To adjust the behaviour of deb-install to your needs, simply set the variable in the configuration file to one of the possible values, which are listed in the global configuration file.

    Should you ever break /etc/deb-install.conf, you can simply delete it. Then start deb-install as root, and it will be recreated with the standard values.

    In the file deb-install (wich is, after all, only a shell script) you can find a long list of constants following the line "#Constants", many of them file locations.
    All of those variables can be overriden via the configuration file as well.
    Example: If you add a line DEBUG=true into ~/.deb-install/deb-install.conf, you will get debug output.

    Technical informations

    Known limitations of deb-install

  • deb-install uses the debian package management chain as backend - that means it is only really useful on debian based systems
  • deb-install doesn't take more than one filename/packagename. If you want to execute deb-install konqueror emacs, you could write either deb-install konqueror; deb-install emacs or deb-install 'konqueror|emacs'
  • If you use a regular expression to specify with which files to work, your command has to look like this: deb-install [<options> ][<path>]<regexp>
    Or in other words: You can't work with files from more than one directory using regular expressions.
  • Every deb-install process started by the same user uses the same temp directory. This is bound to lead to problems, so please don't start more than one deb-install in parallel as the same user. (doing so as different users should be perfectly save)

  • Problems and their solutions (FAQ)

    Index of Questions

    1. Have I found a bug?
    2. There appears a line "waiting for lock..." / "Waiting for database update to end, before continuing...", then nothing happens. What do I do?
    3. I am trying to compile a program from a source archive, but it fails. What do I do?
    4. My slackware package is not recognized as such. What do I do?

    Questions and Answers

    1. Q: Have I found a bug?
      A: Quite possibly. As this program isn't widely in use yet, you might just have tried something I didn't think of, your system might be configured differently,... There are lots of possibilities. And if in doubt, I would like to hear about the problem. Even if it ISN'T a bug, hearing about the problem can only improve deb-install, e.g. by providing better error messages. I can tell you a few instances when you have DEFINITELY found a bug:

    2. Q: There appears a line "waiting for lock..." / "Waiting for database update to end, before continuing...", then nothing happens. What do I do?
      A: Another instance of deb-install set files indicating this state (state:"sth. is updating, please wait"). Either this is real, then just wait until the other instance releases its lock. Or it isn't - which means another deb-install crashed and left the files behind. Since you have a problem, the automatic crash recovery obviously either couldn't fix it, or didn't discover the crash in the first place.
      Try (as root): killall deb-install; deb-install -c
      If THAT doesn't help, send me a mail, or report it on the forum.

    3. Q: I am trying to compile a program from a source archive, but it fails. What do I do?
      A: Here's a checklist of what you can try:

    4. Q: My slackware package is not recognized as such. What do I do?
      A: Unless an archive contains the file "/install/slack-desc" there is no way for deb-install to tell whether the archive is indeed a slackware package, or just a normal archive file. Unfortunately, not all slackware packages contain that file.
      You can fix the problem by manually creating the file.

    Complementary topics

    The file /etc/apt/sources.list

    This file is used by apt-get to find out where it should get its debian packages from (that aren't already cached on your computer). The apt tools know nothing about the existance of a package that isn't hosted at one of the places specified in this file. You can get an explanation of how this file works with the command man soures.list
    You should outcomment all but one version of debian: Use either stable or testing or unstable. apt-get sometimes runs into weird conflicts otherwise (and this has nothing to do with deb-install).
    A good place to get packages that aren't officially supported by debian (e.g. to watch encrypted DVDs) is ftp://ftp.nerim.net/debian-marillat.
    To use it, add the line "deb ftp://ftp.nerim.net/debian-marillat/ unstable main" to your "sources.list" file. Replace unstable with stable, if you run stable. Replace it with testing, if you run testing.

    Regular expressions

    Everywhere you can specify the name of a package or a file, you can give a regular expression instead (look at Known limitations of deb-install though).
    If you use a regular expression, single quote it to keep the bash from trying to interpret it.
    Special characters in regular expressions:
    ?
    Matches one arbitrary character. (In standard regular expressions '.' is used for this.)
    would match 'a' or '0' , but not 'a0'

    |
    Matches, if either the left or the right side of it matches.
    'a|bc' would match 'a' or 'bc' , but neither 'abc' nor 'c'

    []
    Matches, if one of the characters inside the brackets matches.
    '[abc]' would match 'a' or 'b' or 'c' , but not 'ab'

    *
    What's before it, matches zero or more times.
    'a*lib' would match 'lib' , 'alib' or 'aalib' , but not 'blib'

    &
    What's before it, matches one or more times. (In standard regular expressions '+' is used for this.)
    'a&lib' would match 'alib' or 'aalib' , but neither 'lib' nor 'blib'

    Examples:

    deb-install -s 'konqueror?*' would return all packages whose name starts with konqueror. (konqueror and konqueror-nsplugins)

    Shell autocompletion

    In general

    Whenever you use the bash shell (the standard shell under linux), you have a feature available called "autocompletion", which is invoked by hitting the TAB key. Once you have figured out how this works, you will most likely find it incredibly useful.

    To try it out: Change into a directory that has subdirectories in it (how about your homedirectory? [cd ~]).
    Now type "cd " (the space is important!), then hit the TAB key. If the directory has exactly one subdirectory in it, its name will magically appear behind the "cd ".
    If (more likely) more than one subdirectory exists, nothing happens. Hit the TAB key a second time. Now a listing of all subdirectories will be printed on screen. If you type in enough letters of it to make it unambiguous, then hit TAB again, the bash shell will complete the directory name for you.
    Many shell programs have clever autocompletions. For example "apt-get remove "<TAB><TAB> (see: Removing a package) will give you a listing of all currently installed packages!

    In deb-install

    "deb-install -"<TAB><TAB> will list all available options of deb-install.
    "deb-install <string>"<TAB><TAB> will list all local files (=files in this directory) and all packages starting with <string>.
    "deb-install -ao <string>"<TAB><TAB> will list packages starting with <string>, but not local files. (see: -ao / --archive-only)
    "deb-install --abort-on "<TAB><TAB> will list all states known to deb-install (see: --abort-on)

    Custom autocompletion for deb-install is only included in the .deb file, not in the .tar.gz file.

    Contact and Feedback

    If you want to report a bug, give encouragement or constructive critic, then visit the program homepage at http://deb-install.sourceforge.net.
    Alternatively you can write a mail to: icekiss@users.sourceforge.net
    You can find out this mail adress by typing deb-install -v as well.