[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Introduction to Debian Packaging Paper



Hello

I'm resending this to debian-doc since I didn't get any comments on Debian
user.

JD
---------------------- Forwarded by John F Davis/Raleigh/IBM on 03/18/2002
01:14 PM ---------------------------

John F Davis/Raleigh/IBM@ibmus on 03/18/2002 10:39:02 AM

To:    debian-user@lists.debian.org
cc:
Subject:    Introduction to Debian Packaging Paper



Hello

I wrote a Introduction to Debian Packaging Paper (html) for my local
linux users group.  Nothing fancy, but its a quick intro to the packaging
on debian.  How to use apt, dpkg, dselect, and even how to build
a package - quick summary of new maintainers guide.

I would like comments on correctness and general readability.  If
at all possible, I would also like to release the document to
the debian document database and IBM's developer works
web page.  Any help would be appreciated.

See attached document.

John F. Davis
(See attached file: debian-package-talk.html)
(See attached file: debian-package-talk.html)
Title: Debian Concepts

Debian Concepts

last mod: 3/14/02

Author: John F. Davis

Forward

This document is written for a talk at TriLug's March 2002 meeting. It is intended to introduce Debian Packaging to Linux users.

Assumptions

This document assumes the reader understands how to install computer programs on a Windows computer and/or a RedHat Linux system.

Introduction

Debian Linux is popular because of its sophisticated packaging system. This system allows users to add and remove software applications from the Linux file-system with ease. Users of RedHat are most probably familiar with its packaging method which uses RPM's. Debian's RPM equivalent is a DEB.

This document explains the Debian packaging system in four steps. The first step is to introduce Debian's concept of a software package. Second, I explain which files and directories are used by the Debian packaging system. Third, I explain how to install and maintain packages. Fourth, I give a quick method intro to building a package.

Debian Package Files

This section introduces the Debian package concept. After reading this section, you will know the answers to the following questions:

Does Debian use RPM's?

The quick answer is no. Debian does not use RPM's. RPM's are clumsy and not as powerful nor safe as a Debian Package file. The longer answer is that Debian can use RPM's but it is not its preferred packaging method. Debian uses files similar to RPM's called DEB's.

What is a deb file?

Deb files (or packages) are single files which end in ".deb". They contain a collection of files, directories and scripts which are performed during installation and removal. Different scripts can be set to execute at various points in the installation of a deb. Deb files contain a wealth of information besides files, directories, and scripts. For instance, every deb file contains the following information:

How does a deb file compare to a RPM?

Users of RedHat should see a close similarity between a deb file and a RedHat RPM. Both ".deb"s and ".RPM"s are single files which contain multiple files and scripts. They also contain version information, prerequisite packages,

Debian Packaging Files and Directories

This section covers the files and directories used by the Debian packaging system. While reading this section, you will learn answers to the following questions?

/etc/apt/apt.conf

The /etc/apt/apt.conf doesn't exist any more. In its place is a Debian conf tool.

/var/cache/apt/archives

storage area for retrieved package files.

/etc/apt/sources.list

servers to use for apt. Note, you use this file to determine if you are using stable, testing or unstable. Apt will install the latest version it finds. So, its not uncommon to have stable and unstable entries in this file. By default, apt will install the latest version, but you can specifically install a different version. ie. install wine from stable even though the rest of your system in unstable.

Sources for packages

Debian can install packages from the file-system (ie. a file on your Linux file-system), mounted cdroms, or via the net.

Debian Packaging Tools

This section tells how to use the packaging tools to manipulate debs. Some of the questions it attempts to answer are:

Common Tools

Debian has many tools for packaging and I don't know them all. I've tried to document the tools which are more commonly used in this section. In other words, these are the tools which I use on a daily basis.

apt-get

APT package handling utility -- command-line interface" The basic command line tool to get and install packages. Also used to upgrade and update a system. Also allows complete system upgrades to new releases. Its considered a front-end to dpkg. It gets files and hands them to dpkg for installation or removal.

apt-get update

This updates the list of available packages and their locations.

apt-get upgrade

This gets the latest versions of all your installed packages.

apt-get dist-upgrade

I think this is similar to upgrade but its used when you are upgrading from one release to the next. ie. you are currently running stable and you just added testing to your sources list. Adds new dependencies if the new package has them.

apt-get install

Use this to install a package and all its dependencies. You can also use it to install a particular release of a package. ie., apt-get install foo=stable

When apt installs a package that has config files, it will prompt you if you want to use the new config files or keep your old ones. If you choose to replace the file, it will backup the old copy to foo.dpkg-old. If you choose not to replace the file, it will copy the new file to foo.dpkg-dist.

apt-get remove

apt-get check

apt-get clean

apt-get dselect-upgrade

This will update your dselect sources and apt sources at the same time. Otherwise, you need to perform step 1 of deselect which is upgrade sources list before you install packages.

apt-get source

apt-get autoclean

clean will delete all packages in the archive. auto-clean will erase only packages which are not the latest.

Options for Apt

  • --fix-broken
  • --fix-missing
  • --assume-yes

    dpkg

    dpkg maintains information about installed packages.

    dpkg --search or -S

    search for packages which contain files with a file name that somehow matches the search string. In other words, it lists the packages which contain files matching the search pattern in the file name. The file names are listed also.

    -s = status

    prints a boatload of information about a package. I think its a dump of all the entries in the dpkg database for a particular package.

    dpkg -i

    install package.

    -c or --contents

    This shows the contents of a DEB file.

    dpkg --help

    display help on dpkg.

    dpkg -r

    remove files owned by package. Will not remove config files. You need to run --purge.

    dpkg -l

    list packages given by pattern name. If you don't specify a pattern, it will list all installed packages. Here's a neat trick to see how many packages are installed on your system.

    dpkg -l | grep ^ii | wc -l
    

    dpkg -L

    lists the files in a given package.

    --configure = configure

    This will configure a package. Most of the times you use this if your package partially installed and now you are trying to configure it after fixing the error.

    -C | --audit

    Check for paritially installed packages. Use with the --configure mechanism.

    -b build

    This is supposed to build a package however, you won't use it directory if you are using the debhelper tools.

    -I info

    Use this on a package to get description, md5sum, version number, etc.

    root@tadpole:~/docs/trilug-imagetesty# dpkg -I imagetesty_0.6-1_i386.deb 
     new debian package, version 2.0.
     size 575544 bytes: control archive= 990 bytes.
         259 bytes,     9 lines      control              
        1024 bytes,    14 lines      md5sums              
         269 bytes,     9 lines   *  postinst             #!/bin/sh
         202 bytes,     7 lines   *  prerm                #!/bin/sh
     Package: imagetesty
     Version: 0.6-1
     Section: devel
     Priority: optional
     Architecture: i386
     Installed-Size: 680
    

    -x | --extract

    Used to extract files from a package without installing them. Think of it as tar -x ...

    root@tadpole:~/docs/trilug-imagetesty/foo# dpkg -x imagetesty_0.6-1_i386.deb .
    root@tadpole:~/docs/trilug-imagetesty/foo# ls
    imagetesty_0.6-1_i386.deb opt/ usr/
    

    -X | --vextract

    Works the same as above but it displays the filenames as it extracts them. Think of it as tar -xv ...

    --root = install diff dir

    I have tried to use this to install a package into a directory other than the one it was meant to install into. eg. like a relocatable package in redhat. However, it didn't work. It complained about not having access to a status file. I've been told that I was using it wrong and that it is for working with mounted filesystems. In other words, lets say you are building a filesystem for a second computer on this computer and you want to install a package on its filesystem. You could use this option to install a program on its mounted filesystem so that when the second computer is booted and used it could manage the package installed by the first computer.

    --admindir = var diff dir

    Same thing as above.

    Dselect

    Dselect is a front end for the dpkg tool. When I first started out with Debian, I used this tool exclusively. It is also used during the install to setup your initial list of packages. It steps the user through the package installation procedure. First, you update the list dselect uses for packages and their locations. Second, you use dselect to select the packages you want to install. It will flag dependencies and conflicts automatically. During this time, the user can get package information such as the files in the package, version information, and dependencies/conflicts. Third, the user does the install. If its using the net to install the packages, it can take some time especially if a lot of packages are to be installed over a slow network connection. Fourth, the packages which are installed are configured. This step is when debconf comes into play. It allows the user to answer questions about the package installation configuration, how /etc files are used. Lastly, deselect removes unused packages. Note, apt-get update doesn't update dselect's sources list. You must use the first menu item to update dselect's source's, or use the update parameter to dselect. ie. dselect update. I believe this will update apt as well.

    Apt-Cache

    Used this for finding packages, package dependencies, and descriptions. Some people use this and never use dselect. I mostly use it for searching for unknown names packages which perform a known action.

    Using apt-cache to search for packages

    apt-cache search mp3 will give you a list of all packages which plays mp3's

    Using apt-cache to show package dependencies and provides.

    suit:~# apt-cache showpkg xmms
    Package: xmms
    Versions:
    1.2.6-1(/var/lib/apt/lists/http.us.debian.org_debian_dists_sid_main_binary-i386_Packages)(/var/lib/dpkg/status)
    
    Reverse Depends:
      xmms-liveice,xmms
      xmmsarts,xmms
      xmms-wmdiscotux,xmms
      xmms-volnorm,xmms
    
    Dependencies:
    1.2.6-1 - libc6 (2 2.2.4-4) libglib1.2 (2 1.2.0) libgtk1.2 (2 1.2.10-4) xlibs (4 4.1.0) unzip (0 (null)) gdk-imlib1 (0 (null)) libart2 (2 1.2.13-5) libdb3 (2 3.2.9-1) libgnome32 (2 1.2.13-5) libgnomesupport0 (2 1.2.13-5) libgnomeui32 (2 1.2.13-5) libgnorba27 (2 1.2.13-5) liborbit0 (2 0.5.12) libpanel-applet0 (2 1.4.0.2-3) libwrap0 (0 (null)) libaudiofile0 (0 (null)) libesd0 (18 0.2.23-1) libesd-alsa0 (2 0.2.23-1) libgl1 (0 (null)) libmikmod2 (2 3.1.9) libogg0 (2 1.0rc3-1) libvorbis0 (2 1.0rc3-1) libxml1 (2 1:1.8.14-3) zlib1g (2 1:1.1.3) x11ampg (0 (null)) x11amp (0 (null)) xmms-vorbis (0 (null)) x11ampg (0 (null)) x11amp (0 (null))
    xmms-vorbis (0 (null))
    Provides:
    1.2.6-1 - xmms-vorbis x11amp x11ampg mp3-decoder
    Reverse Provides:
    

    Using apt-cache depends

    It shows depends, conflicts and suggests.

    Uncommon Tools

    The last section covered the more common tools. This section covers the tools which I am somewhat familiar with and I don't use or I don't use very often.

    Debconf and debconf-tiny

    You can't run debconf but it is a configuration management system which packages can ask for questions during installation. This is something packagers/maintainers use. As a normal user, you will not need to use it. Until I wrote this paper I have never really cared about it nor have I needed to. About the only thing I know about this package is it has two versions. A "lite" version and a regular version. I haven't done a fresh install in a long time, but from what I remember the lite version is installed on a net or floppy install. Once the network is up, you can apt-get install debconf.

    debconf-show

    Shows the items in the debconf database owned by a package. examples:

    suit:~# debconf-show locales
    x locales/default_environment_locale: C
    x locales/locales_to_be_generated: en_US ISO-8859-1
    suit:~# debconf-show debconf
    x debconf/priority: medium
    x debconf/frontend: Dialog
      debconf/showold: false
    suit:~# debconf-show xserver-xfree86
      xserver-xfree86/config/inputdevice/keyboard/variant:
    x xserver-xfree86/config/inputdevice/keyboard/rules: xfree86
    x xserver-xfree86/config/inputdevice/keyboard/layout: us
      shared/clobber_x-server_symlink: false
      xserver-xfree86/config/device/identifier: Generic Video Card
      xserver-xfree86/config/inputdevice/keyboard/options:
    x xserver-xfree86/config/inputdevice/keyboard/model: pc101
    x shared/default-x-server: xserver-xfree86
    x xserver-xfree86/config/display/default_depth: 24
    stuff cut for brevity.
    

    dpkg-reconfigure

    Reconfigure a package already installed.

    deity

    Its a curses based app which is similar to dselect except it displays packages in a tree format based up priority and package type.

    aptitude

    Its another curses based app which looks like a cross between dselect and deity. It also supports a curses based menu.

    make-kpkg

    Its the debian way to make kernel packages. I've only used it for a brief time and I didn't see the benefit of using it. I realize it would be usefull, if you had a slew of machines with identical hardware and you wanted to update the kernels on all of them with just one kernel build. All of my machines are different so I build/install all my packages individually. If you know of a way to document make-kpkg, please let me know.

    With that said, I recall that I also used make-kpkg when building a openafs client module. In that case I just followed the directions in the openafs source directory and did as it suggested.

    alien

    Used to conver rpm's debian packages.

    Building a Debian Package

    This is a quick intoduction to building a debian package. It is no substitute for reading the new maintainers guide. In fact, its really just a quick and dirty synopsis of that document.

    Preparing the Package Source

    For this demo, I created a simple java app to view jpeg/gif images. I also included some sample images.

    Place the application source and images in a directory of the form: package_name-version_string. ie. imagetesty-0.1. The debian tool used to build a package doesn't like underscores in the package name, so keep this in mind when naming your package.

    "Debianize" the Makefile

    Edit the makefile so that the install target doesn't install into the root directory, but instead uses the $(DESTDIR) directory. You must include a blank define for DESTDIR in the makefile.

    Below is the contents of my sample makefile. Note, I "Debianized this makefile below by adding the DESTDIR varialbles.

    root@tadpole:~/docs/trilug/imagetesty-0.1# cat Makefile
    
    DESTDIR =
    
    all:
        javac ImageTesty3/ImageTesty3.java
    
    install: all
        install -d $(DESTDIR)/opt/imagetesty/
        install -d $(DESTDIR)/opt/imagetesty/ImagePanel
        install -d $(DESTDIR)/opt/imagetesty/ImageTesty3
        install -d $(DESTDIR)/usr/share/man/man1
        install -m644 SkinkNet.gif $(DESTDIR)/opt/imagetesty/
        install -m644 corn.jpg $(DESTDIR)/opt/imagetesty/
        install -m644 shiny.jpg $(DESTDIR)/opt/imagetesty/
        install -m644 ImagePanel/*.class $(DESTDIR)/opt/imagetesty/ImagePanel
        install -m644 ImageTesty3/*.class $(DESTDIR)/opt/imagetesty/ImageTesty3
        install imagetesty.1 $(DESTDIR)/usr/share/man/man1
        echo "done"
    
    
    
    clean:
        find . -name "*.class" -print | xargs -t rm
    
    .PHONY : all
    

    "Debianize" the source tree

    From the tree use dh_make to "Debianize" the source tree. Since this package contains multiple graphic images, specify the package type to be multiple binary.

    root@tadpole:~/docs/trilug/imagetesty-0.1# dh_make -e davis@skink.net 
     
    Type of package: single binary, multiple binary, or library? [s/m/l] s
    
    Maintainer name : root
    Email-Address   : davis@skink.net 
    Date            : Thu, 14 Mar 2002 13:13:20 -0500
    Package Name    : imagetesty
    Version         : 0.1
    Type of Package : single
    Hit  to confirm: 
    Done. Please edit the files in the debian/ subdirectory now. You should also
    check that the imagetesty Makefiles install into $DESTDIR and not in / .
    

    This will create a imagetesty-0.1.orig directory which is as its name implies a copy of the original source tree. In the existing source tree, it will create a debian directory with template files in it. In my case, I edited the debian/README.Debian, debain/control, rules and copyright. If you read the files, you will see how they should be changed since they are document templates with the exception of the rules file.

    The most important file here is the control file. It works with dpkg and apt-get to determine dependencies. In this case, since this is just a test file, I didn't specify any dependencies. If it were not a test file, I would specify a java compiler and a JVM as package dependencies.

    The rules file determines what types of entries are in the deb. I edited the file so it only built the copyright, readme, and manpages. I skipped info files and cron scripts, etc. More of this is covered in the next section.

    Building the package

    The final step is to configure the debian/rules file so that it will build the package and include in the package the various document templates such as man pages, document directories, etc.

    This is the interesting portion of my rules file:

    # Build architecture-dependent files here.
    binary-arch: build install
        dh_testdir
        dh_testroot
    #   dh_installdebconf   
        dh_installdocs
    #   dh_installexamples
    #   dh_installmenu
    #   dh_installlogrotate
    #   dh_installemacsen
    #   dh_installpam
    #   dh_installmime
    #   dh_installinit
    #   dh_installcron
        dh_installman
    #   dh_installinfo
    #   dh_undocumented
        dh_installchangelogs
    #   dh_link
    #   dh_strip
    #   dh_compress
    #   dh_fixperms
    #   dh_makeshlibs
        dh_installdeb
    #   dh_perl
        dh_shlibdeps
        dh_gencontrol
        dh_md5sums
        dh_builddeb
    
    

    To make your life easier, delete all the .ex files in the debian directory so that you can rid your life of clutter.

    Then issue the following command in the imagetesty-0.1 directory.

    root@tadpole:~/docs/trilug-imagetesty/imagetesty-0.4# dpkg-buildpackage
    

    It will build the package and place it in the parent directory.

    APPENDIX

    Web pages cited

    Documents cited


    Reply to: