Simple Debian package hacking tutorial.

[wiki.git] / doc / debian-hacking.mdwn

diff --git a/doc/debian-hacking.mdwn b/doc/debian-hacking.mdwn
new file mode 100644 (file)
index 0000000..70c84d5
--- /dev/null
+++ b/doc/debian-hacking.mdwn
@@ -0,0 +1,36 @@
+Debian and Ubuntu packages make it easy to hack on software that's
+packaged and try out your changes. These instructions assume that you
+have an understanding of how Debian packaging works, although all you
+really need to know is that each file in the distribution comes from a
+<i>package</i>, which contains the compiled form of a <i>source
+package</i>.
+
+1. Figure out what package the software is from. Usually it's named
+approximately the same as the software itself, e.g., `barnowl` or `gdb`
+or `libwww-mechanize-ruby`. You can use the command `dpkg -S` to figure
+out where a file comes from, or search on
+[packages.debian.org](http://packages.debian.org/) or
+[packages.ubuntu.com](http://packages.ubuntu.com/).
+
+2. Type `apt-get source` followed by the package name. This will
+download the source package.
+
+3. cd into the directory that was just created and make whatever changes
+you want.
+
+4. Run the command `dch -i`, which edits the debian/changelog file. Add
+something like "~edited1" to the end of the verson; a version with a
+tilde in it comes before a version without. This means Debian will let
+you install your edited version over the current version, but also
+permit the next offical release to supersede your hacked version.
+
+5. Run the command `debuild` to compile the software and build a
+package.
+
+6. `cd ..` and then find the package that was just built. As root, run
+`dpkg -i` followed by this package name.
+
+You can find more information about writing Debian or Ubuntu packages in
+[Ubuntu's packaging guide](https://wiki.ubuntu.com/PackagingGuide) or
+SIPB's [packaging tutorial](http://debathena.mit.edu/packaging/) on the
+Debathena website.