Difference between revisions of "Libpnd hub"

From Pandora Wiki
Jump to: navigation, search
Line 4: Line 4:
  
 
The library is of course broken into parts:
 
The library is of course broken into parts:
<nowiki>
+
 
 +
<pre>
 
include    - include these files to make use of the lib
 
include    - include these files to make use of the lib
 
lib        - the code that produces the lib
 
lib        - the code that produces the lib
Line 11: Line 12:
 
testdata/  - for testing /etc/pandora; will contain 'conf' dir, for example
 
testdata/  - for testing /etc/pandora; will contain 'conf' dir, for example
 
apps/      - actual applications people may use, such as pndnotifyd
 
apps/      - actual applications people may use, such as pndnotifyd
</nowiki>
+
</pre>
 +
 
 +
For now though, here are a couple notes about the design.
  
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). I have gone out of my way to limit external references so that bindings are easier to make.  
  
- it is straight C code, to be maximumly re-usable (perhaps C++ and other language bindings will tie back to it)
+
- contrary to the previous comment, we've used a bit of C++ for the tinyxml parser .. hopefully this is not an issue.
  
- we do pretend to follow some OO principles; data hiding, encapsulation...
+
- 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.
  
- 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
+
- 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 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
Line 25: Line 28:
 
- 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.)
 
- 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==
 
==Opportunities for improvement==
Line 38: Line 42:
 
Without going into how to set up a GIT, the summary that I (as a registered dev in the repo) used was:
 
Without going into how to set up a GIT, the summary that I (as a registered dev in the repo) used was:
  
<code>
+
<pre>
 
mkdir libpnd
 
mkdir libpnd
 
cd libpnd
 
cd libpnd
Line 44: Line 48:
 
git remote add libpnd ssh://skeezixgit@git.openpandora.org/srv/git/pandora-libraries.git
 
git remote add libpnd ssh://skeezixgit@git.openpandora.org/srv/git/pandora-libraries.git
 
git pull libpnd master
 
git pull libpnd master
</code>
+
</pre>
  
 
==Building the library==
 
==Building the library==
Line 51: Line 55:
  
 
Note that the make defalut target is 'everything', which will emit:
 
Note that the make defalut target is 'everything', which will emit:
<code>
+
<pre>
 
libpnd.a - the static linked verison of the lib
 
libpnd.a - the static linked verison of the lib
 
libpnd.so.1.0.1 - the dynlinked version
 
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
 
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
 
bin/* - the 'test' dir and the 'apps' dir builds will end up in bin
</code>
+
</pre>
  
 
There are a few additional make targets, however.
 
There are a few additional make targets, however.
  
<code>
+
<pre>
 
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 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 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
 
make pnd - create a few sample pnd files for testing the lib on an x86 machine
</code>
+
</pre>
  
 
==Command line tools and testing==
 
==Command line tools and testing==

Revision as of 16:44, 30 October 2009

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]

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.

PXML.xml and .pnd files

What are PXML.xml and .pnd files?

File format - PXML.xml

File format - .pnd files

Included shellscripts to generate files

Auto-discovery of applications

Integration with FreeDesktop .desktop systems

dotdesktop (.desktop) files

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.


APIs