In the "I learn by documenting" vein, I've coded and done development before and have contributed to open-source projects in the past, so I know the ./configure make make install dance and have a rough grasp for how packaging fits into the development cycle - in other words, I started out with tons of advantages over the raw newbie.

And yet this has taken me over a week to do so far (and I haven't even submitted my first package for review yet) Why is this taking me so long? Fear of the unknown, really. I don't know what's involved - how long it will take or how hard it will be - so I budget out time not knowing how close to finished I'll be then, and need repetitive prodding to get started. As Ian Weller said, the first time is always the hardest - so I'm writing down what's helpful and what's confusing while I still have the privilege of considering this to be Mysterious And Hard.

Helpful: I aready had an idea of what packaging meant and what RPMs were. I was told this package needed to be made, and that I could and should do it, rendering me unable to use the "maybe you need some mysterious, undefined experience to be a packager, so I should stop trying to figure it out" excuse and giving me something concrete to deliver: I had a no-excuses target.

Confusing: Where do I find the how-to-make-an-RPM guide? A google search was not particularly helpful. To get from to the RPM howto, I had to take this path, starting at fedoraproject.org

  1. "Packaging is participating, so I can click the little join-fedora sidebar."
  2. "Uh... shoot. Packaging doesn't seem to exactly be OS development, but I'll click OS Developer anyway."
  3. "Ah, that was the right place; Packaging is listed under the skills-you-want-to-learn here. And lo, there is a Packaging link to click on!"
  4. "Now I'm on a page that shows me how to join the packaging crew. The first thing that it tells me to do is read the guidelines, and here's a link to the Creating Packages HOWTO and the Building Packages Guide. Golly, they're both huge. And the Packaging Guidelines. And the...
  5. *** Too Much Information! buffer overflow detected ***: /usr/bin/mel-brain terminated

Helpful: Sebastian Dziallas pointed me towards astronomy-bookmarks, which is nearly identical to the RPM I was trying to make; I downloaded and unpacked it and poked around, noticing what files it contained - and that it did not, in fact, seem to have magic within it. Just files with some settings I didn't yet understand. Presumably, somewhere in the oversupply of RPM-making-howtos, something would teach me how to make something similar.

Confusing: While lurking on another IRC channel, I overheard the RPM Guide being mentioned. It's gorgeous and a helpful reference, but definitely not a walk-through for first-time packagers. Filed in my "good references to have around" section.

Helpful: The Creating Packages HOWTO referred to Christoph Wickert's Building RPM packages tutorial, which was the first thing that really got my rear in gear as far as doing things that would create a package rather than researching how to create a package. It was good to be able to watch Christoph walk newbies through packaging, see what questions they had, and have a conversational stream to follow along.

Using Christoph's chat as a guide, I installed all the necessary tools (rpmbuild and rpmdevtools), ran rpmdev-setuptree to make the appropriate folders in my homedir, put my source (a single bookmarks.html file, following the lead of astronomy-bookmarks) in the SOURCES folder, ran rpmdev-newspec to make a skeletal spec file, and took a first stab at filling it in. This file was my first attempt.

Confusing: According to the instructions, it was now time to run rpmbuild -ba edu-spin-bookmarks.spec. Experienced packagers who've glanced at my first spec might be able to guess the error I ran into. Here it is.


+ install -p -m 644 /home/mchua/rpmbuild/SOURCES /home/mchua/rpmbuild/BUILDROOT/edu-spin-bookmarks-0.0.1-1.fc10.i386/usr/share/bookmarks
install: omitting directory `/home/mchua/rpmbuild/SOURCES'
error: Bad exit status from /var/tmp/rpm-tmp.x3Rq1M (%install)
RPM build errors:
Bad exit status from /var/tmp/rpm-tmp.x3Rq1M (%install)

Two fruitless hours of looking for documentation on %install followed before I realized I'd just spent 1 hour 50 minutes too many and should really just be asking for help.

Helpful: Sebastian, once again, came to the rescue.

<sdziallas> you'll need to specify the bookmarks.html in the source0 part
<sdziallas> mchua: because rpmbuild won't download the file
<sdziallas> mchua: basically, it doesn't know what to do, I guess. you can
 also put just the filename temporarily in the source0 argument.

Lo and behold. changing line 9 from

Source0: http://mchua.fedorapeople.org/edu-spin-bookmarks/

to

Source0: http://mchua.fedorapeople.org/edu-spin-bookmarks/bookmarks.html

did the trick. I had been looking in the wrong place for what turned out to be a trivially obvious answer. (If Sebastian had not been around, where should I have looked for the answer? What's the ideal way for me to have found the fix?) Running rpmbuild now popped out an edu-spin-bookmarks-0.0.1-1.fc10.i386.rpm - and now I was ready for Phase II, making the RPM functional and ready for review... (stay tuned for our next installment!)

Yes, this is a slow and agonizing crawl through something very simple, and I'm sure I'm boring many people here to tears. ;-) Here's the point: to the beginner, it is a slow and agonizing crawl, and we don't see the "very simple" yet. Or at the very least, realizing that it's simple and learning how to navigate the simplicity is not a trivial thing.

I'm actually quite impressed by how simple the process is, and how helpful the resources are - however, my baseline for "easy process!" is "it's better than several weeks of blindly trying to install Linux for the first time via stacks of floppies in 2001!" so just because it's "good enough" doesn't mean it's as good as it could be.

How can we improve this experience?