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: dne...@maemo.org Jabber: bo...@jabber.org _______________________________________________ maemo-developers mailing list maemo-developers@maemo.org https://lists.maemo.org/mailman/listinfo/maemo-developers
