[04:57] <doctormo> persia: Woo! good luck!
[05:01] <persia> Hi everyone, and welcome to an updated session of Packaging without Compilation.
[05:01] <persia> Heh.
[05:01] <persia> Hi everyone, and welcome to an updated session of Packaging without Compilation.
[05:01] <persia> It's been a couple years since this topic was last covered, and while the old way still works, there are some new ways we can do things.
[05:02] <persia> I prefer to discuss things interactively, so please ask questions (in this channel) as they occur to you.  I'll answer them when I get to them: no worries about interruptions (and the logs can be edited to be in the right order later if someone produces documentation).
[05:02] <persia> So, who's here?
[05:02] <nigelb> o/ (part asleep though)
[05:03] <persia> OK.  One person.  More are welcome (and it's more likely I'll cover things that specifically address your needs if you make your presence (and needs) known).
[05:04] <persia> So, today we're talking about how to package things that don't need to be compiled.
[05:04] <persia> Most packages have a "build" step and an "install" step, where the source code is converted into some binary code that runs on the machine.
[05:05] <persia> But if we're just packaging a couple python scripts (no libraries), some shell scripts, a makefile, some data, some images, a collection of textbooks, music and sprites for a game, etc., we don't really need to build anything: the source code *is* what we want to be installed.
[05:06] <persia> Oh, php webapps also often fall into this category.
[05:06] <amason> persia: here again =)
[05:06] <persia> Take care though: some licenses require that the "source" be the "preferred form for modification", which may not be the end result.  if you are pacakging a bunch of PDF files that are generated from docbook, you'll need to compile the docbook into the PDS files.
[05:06] <persia> Hey amason
[05:07] <persia> s/PDS/PDF/
[05:07] <persia> So, anyway, typically packages are organised into a "source" package, where we put the contents that we get from upstream and our metadata to integrate into Ubuntu, and a "binary" package which is the result the buildds give us (the .deb) which can be installed on a user machine.
[05:08] <persia> Even when we're just installing files, it's nice to have this separation, because we can do things like have a README or NEWS file that is interesting for folks who want to contribute to the content, but not interesting to install on everyone's machine.
[05:10] <persia> So, to create a package, we'll need some source code.  Handily, I wrote a fairly useless utility a couple years ago that makes an acceptable package of this type.
[05:11] <persia> So you might be searching around and find something like http://paste.ubuntu.com/495082/ somewhere.
[05:11] <persia> Assuming this was a utility you really wanted, and wanted to package, it seems like you could just grab it and use it.
[05:12] <persia> Unfortunately, this isn't actually true (with a few minor exceptions for certain geographic regions or professions).
[05:13] <persia> In order to distribute the code we need to have a license to give it to other people, and we probably want to have a license to give others the license to give it to other people (otherwise we couldn't put it on a website or similar, because the hosting provider couldn't distribute it)
[05:13] <persia> So the first step is to make sure upstream gave us a useful license.
[05:13] <persia> I can sometimes convince myself to do things, so I was able to get http://paste.ubuntu.com/495084/
[05:13] <persia> This we can use :)
[05:14] <persia> There are an increasing number of source package formats, but I'm fairly conservative, and find "Format: 1.0" to be the easiest to use.
[05:16] <persia> "Format 1.0" source packages consist of the upstream compressed tarball, a compressed patch including all the metadata, and a description file.
[05:16] <persia> We will want to start with the tarball (unless upstream already created one for us)
[05:16] <persia> Just create a directory named "hello-host-0.1" and put the file therein.
[05:17] <persia> I choose the name of that format because I want to call the package "hello-host" (the name of the script), and I have version "0.1" (upstream didn't version it (bad upstream), so we just pick a number out of the air, after discussion with upstream, and as long as upstream is accepting)
[05:18] <persia> The dpkg-source utility, which is used to pack and unpack source packages, has all sorts of code to make sure that it ends up with a directory of this type: by doing it this way in the beginning, we have a shorter codepath.
[05:20] <persia> Then `tar czf hello-host_0.1.orig.tar.gz hello-host-0.1` to create the tarball.
[05:20] <persia> Again, the name of the package and version are there, this time separated by '_'.  Also note that we have added "orig" to indicate that these contents are from the original author (and if possible, the original tarball the authors distribute, if there is one)
[05:21] <persia> Now, we have (finally) reached the point most folk packaging stuff start from: we have some tarball containing software that we could have downloaded from somewhere.
[05:21] <persia> Well, we're one step ahead: it's already unpacked :)
[05:22] <persia> So, `cd hello-host-0.1` to get into the working area and start packaging.
[05:23] <persia> The package metadata is split into 4 main files: "control" which gives the name of the source and binary packages, package relationships, descriptions, etc., "copyright" which details all the copyright owners and licenses for the package, "changelog" which explains who did what when in the packaging (upstream changes do not belong here except in very special circumstances), and "rules" which explain how to convert the source package into a
[05:23] <persia> binary package.
[05:24] <persia> I find copyright hardest, so I tend to do it first (it's also the one that is most likely to result in one realising the software cannot be packaged, so better to get it out of the way before engaging in technical effort)
[05:24] <persia> There's a few acceptable formats to copyright, but these days I tend to follow the DEP-5 guidelines.
[05:25] <persia> This is documented at http://dep.debian.net/deps/dep5/
[05:26] <persia> So, looking at the license of the upstream code, and after some thought deciding how I wanted to license the packaging, I've constructed http://paste.ubuntu.com/495087/
[05:26] <persia> Can anyone spot the difference between the copyright holders there?
[05:27] <persia> Odd, I would have expected someone to see it.
[05:28] <persia> Anyway, the point is that for Files: * Copyright is appropriately assigned to some person (who may or may not be affiliated with anything), but is the upstream author, and For Files: debian/* the copyright is assigned to the person who is packaging it for some target (and often represents their affiiliation to that target (Ubuntu in my case))
[05:30] <persia> Next, we'll create debian/control.  This is mostly just an excercise in reviewing  http://www.debian.org/doc/debian-policy/ch-controlfields.html and entering the expected data.
[05:31] <persia> My sample is http://paste.ubuntu.com/495090/
[05:31] <persia> For the first stanza, Source is always required, and it's a good idea to try to match the upstream name of the program, although one must use all lower-case, and avoid some special characters (I forget the list: read policy: it's good for you anyway)
[05:32] <persia> Section can be in either the Source or Package stanzas: if in the Source stanza, it applies to all Package stanzas, which makes things easier if the package ever needs to be split into two binary packages (still one source package).
[05:32] <persia> A list of sections can be found at http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
[05:33] <persia> Priority similarly can be in either, but for new packages should almost always be in the source paragraph, and be "optional".  if you end up with something else, only do so because someone not only tells you to do so, but does so in a way that convinces you that the package needs that sort of special treatment.
[05:34] <persia> Maintainer: is almost certainly whoever packaged the software.  In some cases, such as when one packages something for handoff to some team, etc. one might select a different value.
[05:35] <persia> Build-Depends is the list of software we need to compile the package.  Since we're not compiling anything, we'll just select "debhelper" which, as the name implies, helps make debs.
[05:36] <persia> Standards version should match the version of the debian-policy package on your system.  If it's lower (as in this case), you will want to review the changes in policy and make sure you're up-to-date.
[05:37] <persia> The second stanza is often called the "binary" stanza, because it describes the bianry packages (although it has the "Package" header).
[05:37] <persia> Architecture should always be "all" for uncompiled packages: there's no need for a separate version for each arch, and since there's no compiled code, it doesn't matter which architecture built it.
[05:38] <persia> If you're doing something complicated, you might want to add more to Depends: (e.g. adding "php5" or similar if packaging PHP).  You never need to add anything that is Priority Essential (and you can always check with `apt-cache show ${package}`)
[05:39] <persia> If you use debhelper, you want to add ${misc:Depends}" here.  debhelper will use that to add any dependencies to your package that debhelper needs to add to support how it works.
[05:39] <persia> Description is described at some length in Debian policy: the short form consists of three basic rules:
[05:40] <persia> 1) The text on the same line as "Description: " should complete the cloze "${PACKAGE} is a ${DESCRIPTION}"
[05:41] <persia> 2) The next 3-10 lines of text should be about that long, and provide enough information that someone unfamiliar with the package (and perhaps unable to see the package name) can decide whether it should be installed.
[05:41] <persia> OOps: 2) was length, and 3) was purpose
[05:42] <persia> At this point it gets rapidly easier, as we have more automation to help us (the writing of more automation for the first bit is welcome :) )
[05:43] <persia> Because there's not much to do, we can just grab a hyper-simple debian/rules file.  Install debhelper, which has an example, and `cp /usr/share/doc/debhelper/examples/rules.tiny debian/rules`
[05:43] <persia> To make this work, we have to tell debhelper to use the features of version 7: this is done with `echo 7 > debian/compat`
[05:44] <persia> And the last critical file is changelog.  This can be created by `dch --create`: populate the name of the package, the version, the target (lucid, maverick, unstable, etc.).  make sure your name is right, and leave a comment "Initial Release".
[05:45] <persia> At this point we have a package, but since we don't actually have any scripts to build anything, nor any instructions in debian/rules to do anything specific, we have to describe which files in our source package we want to install to which directories on the user system.
[05:45] <persia> To do this we use a tool "dh_install".  It has a manpage that explains everything, but assumes you already know a lot about it.  Worth a read: ask folks when you get confused.
[05:46] <persia> dh_install looks for one of two configuration files: debian/install or debian/${BINARY_PACKAGE_NAME}.install.
[05:46] <persia> I suggest using the latter, as it is easier to keep track of if your package is every big enough to need to be broken into smaller packages.
[05:47] <persia> For my example program, http://paste.ubuntu.com/495101/ would be debian/hello-host.install
[05:48] <persia> This file can have any number of lines, but each line should have the same syntax: "${SOURCE}${WHITESPACE}${DESTINATION}"
[05:49] <persia> dh_install can't rename files, so it's often easiest to specify the destination as a directory, using the existing file name.
[05:51] <ClassBot> There are are 10 minutes remaining in the current session.
[05:51] <persia> The source can be either a file *or* a directory: if a directory, then every file in that directory (and those below) is installed to the destination.
[05:52] <persia> That's it.  The source package is created with `debuild -S -us -uc`.  If you're uploading it somewhere, you might want to sign with debsign.
[05:52] <persia> if you're looking for stuff to package, http://bashscripts.org/ and http://www.scripts.com/ have a variety of bits of code, some of which are interesting.
[05:52] <persia> (I'm sure you can find more looking elsewhere).
[05:54] <persia> If you end up trying to package a web application, You will want to review http://webapps-common.alioth.debian.org/draft/html/ (and maybe look for a newer version).  this contains a wealth of useful tips and tricks to make web applications work.
[05:54] <persia> Questions?
[05:56] <ClassBot> There are are 5 minutes remaining in the current session.
[05:56] <persia> OK, if there are no questions: I'll close the class early.  Good luck in your efforts with this class of package: probably the easiest to get done quickly, although licensing can b tricky sometimes.
[06:08] <amason_> persia: for non-arch specific applications that aren't intended to go into debian / ubuntu proper is there anything wrong with checkinstall ?
[06:09] <persia> Yes :)
[06:11] <amason_> k. is there anything specifically ? I am still tryiing to find a way for a developer to  be able to package an application, and give it to his /her sysadmin for deployment without having to have an entire copy of the distro since it's just not feasable in many situations.
[06:11] <amason_> i understand why you would want and need this in ubuntu/ debian or if you were distributing it to the wide world.
[06:11] <persia> There's a vast list of reasons why the world would be a better place had checkinstall never been written (and I say this as someone who has patched it), but my pet peeves are 1) requires an separate build system that one has to learn that cannot build in a clean environment because of the checkinstall architecture, 2) it fails to track dependencies in any meaningful sense, often leading to packages that install but fail to be useful in any
[06:11] <persia> way (cannot run, reliably crash, etc.)
[06:14] <persia> I really don't understand what you mean by "have an entire copy of the distro", so don't know how to answer that.  Maybe ask differently in #ubuntu-packaging?
[06:15] <amason_> yeh ok. will move there