Libpnd hub

libpnd - the Pandora Library

Design considerations

The library is of course broken into parts:

include     - include these files to make use of the lib
lib         - the code that produces the lib
test        - mini tools to test various pieces of the lib in isolation
bin         - test tools - tools for testing the lib as it is developed, not anticipated to be used by many
testdata/   - for testing /etc/pandora; will contain 'conf' dir, for example
apps/       - actual applications people may use, such as pndnotifyd

For now though, here are a couple notes about the design.

- it is straight C code, to be maximumly re-usable (perhaps C++ and other language bindings will tie back to it). I have gone out of my way to limit external references so that bindings are easier to make.

- contrary to the previous comment, we've used a bit of C++ for the tinyxml parser .. hopefully this is not an issue.

- I have tried to keep the API relatively simple and am faking some OO like data hiding to try to keep dev noses out of structures that are subject to change. ie: functions for list management and node access are provided, don't dig into the void* cast structs, or you could get burnt.

- the API should be pretty stable; so far very few user-code changes have ever been needed.. lib internal changes should be binary compatible.

- As a result of that decision, 'handles' are used; a handle is a 'black box' type, something you cannot just use 'handle h; h -> foo = 5' type code for. Instead, internally the library will cast the handle to the actual useful type (which may involve pointer arith etc). This way the user can be returned a handle, and pass the handle to various access functions to get useful data/operations.. but the user is not encouraged to look inside the data objects himself

- As another implication, access functions are available aplenty; it is a little unwieldy perhaps, but its all about keeping the API good without the user peeking inside and risking being broken down the road. (By example, consider.. you use ftell() on a FILE object; you don't go looking in FILE for the 'position' member, since it might be platform specific, etc.)

- The lib works pretty well, but there is room for improvement internally; it won't hurt my feelings for you to suggest improvements, and I'm sure we would all be grateful for any patches you provide. We've _started_ this library, but by no means wish to carry it alone!

Opportunities for improvement

Certainly nothing is perfect, especially when chasing moving targets. Some aspects of the library are less efficient, or missing, or buggy, and a few things are noted here should someone have time. The API was designed to be pretty stable so the internal code could be altered without breaking the API interface.

- better iso lang handling .. due to shift from original PXML spec to new PXML spec with better lang support I've not updated some of the internal code, API uses etc to handle it. (even .desktop files could include all iso-lang titles, and let the WM pick through as the spec suggests.)

Obtaining the library

libpnd is in the Official Pandora GIT repo: [1]

To obtain yourself a copy, use something like:

git clone git://git.openpandora.org/pandora-libraries.git

Thats all you normally need. For copy-paste from the private wiki sake, heres what I had before:

Without going into how to set up a GIT, the summary that I (as a registered dev in the repo) used was:

mkdir libpnd
cd libpnd
git init
git remote add libpnd ssh://skeezixgit@git.openpandora.org/srv/git/pandora-libraries.git
git pull libpnd master

Building the library

Standard 'make' should be sufficient here; pull down the directory from the GIT, cd into it, and run make. Thats it.

Note that the make defalut target is 'everything', which will emit:

libpnd.a - the static linked verison of the lib
libpnd.so.1.0.1 - the dynlinked version
libpnd.so.1 - the stub for the shared lib; ie: apps should link against libpnd.so.1 and not the 1.0.1 over-specific version
bin/* - the 'test' dir and the 'apps' dir builds will end up in bin

There are a few additional make targets, however.

make clean - wipes out the object files, the bin files, and *~* (emacs backup files), empties some of the deploy stuff, etc. Do this before commiting to GIT or we will beat you with sticks.
make deploy - populates the deploy/ directory, which is what is used inthe shipping images; ie: testdata/conf includes test configs, while deploy/etc/pandora/conf includes the configs we ship with. This make will copy over some of the libs and binaries and such.
make pnd - create a few sample pnd files for testing the lib on an x86 machine

Assumptions about the filesystem

Note that for libpnd to work, it makes certain assumptions about the filesystem and config files. Since libpnd was developed with the images it should work for the Pandora .. but just dropping libpnd onto another Linux distribution and it won't likely 'work out of the box'. Certain config files will need to be set, and certain conventions followed.

Command line tools and testing

A number of scripts and tools are included or built with libpnd, to facilitate testing of the lib as its being developed and to assist in making .pnd files and PXML.xml files.

PXML.xml and .pnd files

On most platforms, applications are distributed as an executable and optional datafiles and likely an installer. The installers job is to integrate the application into the filesystem, as the transport mechanism itself is not executable and is considered temporary. In Windows an application might be installed into Program Files, while in Unix an application might be dropped into /usr/local/bin .. data files in various other places.

For the Pandora platform we wanted a very easy to use workflow -- download and run -- and also have a very different operating environment. With multiple SD cards available for expansion (and that space being highly desirable due to a smaller internal store) it is desirable to install applications to SD, and yet SD cards are by definition something users will wish to carry multiple of. With two slots, it could be quite a chore to install an application to SD1, its data to SD2, and then saqy have only one of them plugged in at a time, or switch which slot they're in, or any number of scenarios.

The PXML.xml and .pnd-file approach we came up with attempts to address these issues.

The goals:

- for the user, an application can be a single file download

- furthermore, there is no installation whatsoever, beyond dropping that single file into the right place on the SD card

- using the application should be easy -- stick in the SD card, and tap/launch on the icon.

- for uninstallation, delete the single file. Thats it, no fuss.

- for the developer, creating that single file should be easy to do

- for the system, performance should be high

File format - PXML.xml

See the PXML specification

Alternatively the spec is included in the docs/ directory of the libpnd distribution, though the wiki version linked above should be considered cannon.

A note on history; the PXML spec was originally created by EvilDragon, and went through a number of revisions as suggestions came in; as these things are wont to do, the target was ever moving and the scope and meaning of PXML changed so at some point a more strategic approach was needed. dflemstr took it upon himself to help recode some of the parse and re-evaluate many of the PXML decisions and hence was born the PXML-version-2 spec.

File format - .pnd files

The pnd file format is pretty straight forward.

Basically its just an ISO file with an PXML and an PNG icon appended. (cat appfolder.iso app.pxml icon.png > app.pnd)

This simple format makes it possible to easily create .pnd files with the default utility's of most operating systems.

Manually creating a .pnd (or even a PXML) is a pain thou so there will be a few helper scripts or maybe even a gui app out when we launch.

Integration with FreeDesktop .desktop systems

Icons

There are some rules for Icons in PXML.xml and pnd/directory bundles

- An Icon should be in the root of the directory or .pnd bundle

- An Icon must be specified in the PXML.xml if you expect it to work

- As the PXML.xml is parsed, the icon is sought; if the icon is specified, but not found, it is assumed to be a system default icon and the filename will be placed into the .desktop Icon= line verbatim (ex: Icon=foo.png), and the window manager presumably will know how to locate it. If the icon is specified, and is found, then it will be copied into the configured IconPath, and the full path to it will be used for the Icon= line in the .desktop file ex: Icon=/tmp/myicon.png). If no icon is specified in the PXML file, then no Icon= line will be entered into the .desktop and the WM will presumably apply a default icon based on category or whatever.