[maemo-developers] Reviewing beginner packaging docs

[From: Dave Neary]

Hi all,

With Dave, we did a pretty good review of the getting started &
packaging docs a few months ago, which got people to the point where
they could get a hello, world package written & packaged as a .deb.

We didn't go further than that, and so I've spent some time this week
acting as a brand new developer, going from virgin laptop to uploading
my first package to extras-devel - and there are a few gaps in the docs.

This email is just to point some of those out - and to sollicit help in
getting things fixed. Please try to look at these docs with the eyes of
a new developer to see what information you might need to get up &
running in half an hour, which just isn't there.

IRC has been helpful (esp. timeless, Stskeeps, Venemo) but I'm making
only slow progress.

So far, here are a few remarks:
* We point people getting started to the SDK page: from
http://maemo.org/development to
http://wiki.maemo.org/Documentation/Maemo_5_Final_SDK_Installation - but
once you have a Scratchbox SDK up & running, we didn't tell people how
to get started developing. I added a "where to next" section that points
at http://wiki.maemo.org/Packaging - the best reference I'm aware of for
packaging a new "Hello, World" application

* On the Packaging page, we do a pretty good job of explaining the
basics of autotools, and standard Debian packaging. However, if you try
to copy the .deb which you will have at the end of the "Packaging a
.deb" section onto an N900 and install it, it wouldn't work because the
Section: field in debian/control wasn't mentioned up to that point. I
added a section "Testing your package" which goes into some of the
things you need to do to get a package to install.

* At this stage, your package still doesn't have an icon and an entry in
the applications menu - which is what I'm having trouble with now. In
fact, the entire section "Maemo-specific packaging information" has
entirely too many unstated assumptions. Just to give three examples:
  * We talk about sections (and point to the packaging guidelines)
without talking about which file we need to add a section to & where in
the file
  * The Desktop files section points to a [[Desktop file format]] page
which does nothing to explain how to write a .desktop file
  * The paragraph about .install files. There is a line: "You can add
    the desktop file to the .install file for your application so that
    it is installed to the correct place, for example, if you have
    debian/application.install, adding the line:
        application.desktop usr/share/applications/hildon"
    Now - do I need to create a file called "application.install" or is
application to be replaced by my package name? How about
application.desktop? I *think* that I need to s/application/package name
in both... but it's not clear.

So I'm currently stuck trying to figure out how to get an icon file
installed & how to write & install a .desktop file which will load it
up. The advice I've gotten so far is good - but can mostly be summarised
as "download a working package & look to see how they did it". And I
know I'm still missing a bunch of stuff which will be necessary for the
package to go into extras-devel.

What I would like to see us do is better document the installation
process (which files get installed & how, what's Debian specific, what's
Maemo specific, what applies to everyone), and better document the
.desktop format (like, say, explaining which fields have important
values that you must set, which fields go together but are facultative,
and which fields are mostly decorative/informative) and basically make
it trivially easy for someone to create a package, given working source
code, which will pass muster for extras-devel, and understand what each
step is useful for along the way.

Does anyone have some time over the next couple of days to help make
this stuff rock? I'd be very happy to see us split pages off (say: a
.desktop format reference separate from the "here's the 3 required
fields in a .desktop file, here's where you create it, here's how you
make sure it gets installed in the right place" basic docs.

Thanks!
Dave.

-- 
maemo.org docsmaster
Email: dneary at maemo.org
Jabber: bolsh at jabber.org