Announcement
Debian-NYC is proud to announce the continuation of its workshop series with a workshop examaning prototypical packages and looking at all of their components.
This workshop will provide advanced theory useful for people modifying or creating packages. For people modifying packages, you'll learn many typical motifs and about various build systems. For creating packages, you'll be much better prepared to read and understand guides a deep level. However, this is still not a step-by-step guide in "how to build packages", but will get you very close to there.
The Debian-NYC series of workshops as a whole is designed to introduce Debian, Debian tools and techniques, and the Debian community as well as provide skills to attendees. This workshop is targeted towards technically-skilled people who would like knowledge of the Debian packaging system and how to contribute back to the Debian community. Most of the material of these workshops will be applicable to other Debian-derived distributions, such as Ubuntu.
For other Debian-NYC events, including Novice Nights aimed at new users, see http://wiki.debian.org/DebianNYC
Please bring: A Debian (or other Debian-based distribution such as Ubuntu) computer with your preferred development tools on it. Extra computers may be available for you to use if you can't bring one; but please contact us ahead of time if you'd like assistance with machinery, so the folks who can bring extra know how much to bring.
Date/Time/Location: October 27, 2010. Workshop begins at 19:00, please arrive between 18:30 and 19:00. Location: Control Group, located in the Woolworth building (233 Broadway, Manhattan, right next to city hall park, Manhattan). Tell the front desk that you are going to a meeting at Control Group, on the 21st floor. You need some sort of identification to get a visitor pass.
Registration: Free, space is limited, RSVP to (rkd at zgib.net).
Contact: IRC via #debian-nyc on irc.debian.org ; debiannyc@vireo.org ; Richard Darst (rkd at zgib.net)
Web: http://wiki.debian.org/DebianNYC/Workshops/WhatsInAPackage
We would like to thank Control Group, Inc. for providing the space for this workshop. Control Group is a privately held IT consultancy that provides application development, infrastructure, support and training services to clients in the media, entertainment, design, and financial industries. For more information about Control Group and its services, go to http://www.controlgroup.com.
Draft outline
If you want to help here, add as much as you think important to this outline. Then, whoever presents it can narrow it down to what they see as practical in the time we have.
- Introduction
- This workshop goes over all of the major components of binary and source packages
- This does _not_ cover all the little details. All of these utilities have their own semantics, and sometimes we may gloss over things in the name of Getting Through It All. You should read the man pages of these commands when you need to.
- This is NOT a replacement for reading the real debian documentation.
- Packages can change between lenny and squeeze and sid. We have tried to use packages here which are mostly the same across all of these distributions, so that it doesn't matter what you use.
- Getting our build environment uniform
- adjust mirror, and make sure deb-src is there.
- install build-essential and devscripts
- Binary vs source packages
- Binary packages
Unpacking with just ar and tar
- ar xv PACKAGE.deb
- debian-binary
- control.tar.gz
- data.tar.gz
- Better way to unpack: dpkg-deb
- dpkg-deb -e package.deb package-control/
- dpkg-deb -x package.deb package-unpacked/
- Control files/scripts
- control
- conffiles
- md5sums
?Maintainer Scripts:
- preinst
- postinst
- prerm
- postrm
- and possibly others
- Creating a package with dpkg-deb -b
- We don't have examples here,
- Make a filesystem tree with owners, perms, and modes correct: (e.g. package/)
- Make a DEBIAN/ directory at the top of that tree (e.g. package/DEBIAN/) - control data goes here
- Build it, e.g. (dpkg-deb --build package/)
- Roughly speaking, this is a reversible process:
- dpkg-deb -x original.deb dir/
- dpkg-deb -e original.deb dir/DEBIAN/
- dpkg-deb -b dir/ new.deb
- Package files database, no overlaps, dpkg-divert
- Debian source formats
- Up until (and including) lenny, Debian only had version 1.0 packages.
- .orig.tar.gz, .diff.gz, and .dsc
- Source format 3.0 has multiple tarballs:
- .orig.tar.gz, .debian.tar.gz, .extra-stuff.tar.gz
For now, just be aware of this. apt-get source and dpkg-source -x can handle them both for you. We'll talk more about the differences between these formats later.
- Up until (and including) lenny, Debian only had version 1.0 packages.
- Source packages
- Goal here: Make a filesystem root hierarchy with DEBIAN directory, run dpkg-deb --build on it.
Let's look at an example package that uses no helpers: sed
apt-get source sed
package-version/debian/ is the debian directory. It has lots of useful stuff in it.
- debian/control: Meta-info. Notice substvars
- debian/changelog changelog, and version number comes from here.
- debian/copyright
- debian/patches/ - Local source patches (more on this later)
- debian/source/format - Source package version. More on this
- later
- debian/watch - Automatically find updated version (man uscan)
- debian/rules - The real build rules...
- The rules file
sed-4.2.1/debian/rules
- This is a Makefile. Brief introduction to make: there are
- targets (target: dependency1 dependency2), and what is essentially a script following the target.
Let's look at the rules file in the sed package.
- Required targets:
- build
- build-arch and build-indep
- binary - create the binary packages
- binary-arch and binary-indep
- clean - remove any effects of build and binary
- get-orig-source (optional)
- patch (optional)
- The maintainer can have whatever other rules ey would like.
- build
Let's pace through the sed rules file and talk about what the lines do
tmpdir = $(CURDIR)/debian/tmp is where all files will get installed. This is what dpkg-deb --build is called on
- Various variables are set
The build target is relatively simple: $(MAKE) INSTALL_PROGRAM="$(INSTALL_PROGRAM)". It also has a optional make check to run tests. It depends on Makefile being made first.
clean target runs make clean and removes some other files which are automatically made.
We see a rule to generate the Makefile by running ./configure
binary calls binary-arch to generate the actual .deb
make install DESTDIR=$PWD/debian/tmp/ -- installing into our tmp directory
install other files into $PWD/debian/tmp/using install You can see it doing things like copying the docs, changelogs, and copyright files into the right places.
- gzip things that need it
make the DEBIAN/ directory inside of debian/tmp/. This package doesn't have to put anything in there itself.
dpkg-gencontrol puts the control file in debian/tmp/DEBIAN/control
Call dpkg --build .. which places the binary in the parent directory, as it should be.
- Other notes on this process
- debian/rules is a Makefile
- Interface to building: what the autobuilders/policy require:
- debian/rules binary (run with fake or real superuser privileges)
- debian/rules build (run with normal user privileges)
- Other required files
- debian/control
- debian/changelog
- Not build related: debian/{copyright,readme,news,}
- Common packaging tools:
- debhelper - most common packaging helper.
- Tries to automatically install stuff based on common names
A bunch of "smart" dh_* programs.
Example: less, 2vcard, apt-zip
Use debian/package.XXX to add extra stuff to install (Example: apt-zip)
debian/package.{install, docs, xxx}
- debhelper 7
- Next version of debhelper, but radical enough of a change to warrant it's own section:
Example: doxymacs
- cdbs
Example: sqlite3
- Makefile snipets which are included to automatically do things
- Override/extend rules with double-colon rules.
- yada
Example: systune
Replace all the other config files with debian/packages
- What you have to do to not use packaging tools.
See the sed example from above or any packages by Clint Adams.
- debhelper - most common packaging helper.
- Libary packaging
- shlibdeps
- More stuff here
- Package formats
- 1.0: .orig.tar.gz + diff to add debian/ directory
- 3.0: 1 or more .orig.tar.(gz|bz2) + .debian.tar.(gz|bz2)
- Making packages from scratch
dh_make is a good start
Creates a debian directory with lots of templates. You need to extensively edit it. And know or figure out what you are doing. And lots of trial and error.
- Some archive related stuff?
- Other useful tools?
Example packages:
- Ultra-minimal package (no packaging system, no complexity in building)
- Minimal debhelper package (dh and dh7)
- Debhelper package using a few debhelper features
- CDBS package
- yada package
- No helper package
- Really complex packages
Survey
We should take a survey of attendees to figure out why they come and what they would like.
- How long have you been using GNU/Linux?
- What is your general field and interests?
- Which of the following topics would you be interested in? Anything else?