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

Once we get it near being useful or done, perhaps some documentation will be in order ;) 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)

- we do pretend to follow some OO principles; data hiding, encapsulation...

- Since much is subject to change (especially during development of the lib) I want the internals hidden; this also protects the user down the road.. if we change the internals (likely!), it should not break the users code too much.. API should be changing less frequently than the internals

- 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.)

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]

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

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.

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.