Libpnd hub - Revision history

PowerGod at 10:08, 23 November 2013

2013-11-23T10:08:57Z

PowerGod at 08:34, 23 November 2013

2013-11-23T08:34:25Z

Kingu at 14:07, 26 October 2013

2013-10-26T14:07:54Z

Kingu: removed dead links

2013-10-26T14:04:23Z

removed dead links

Kingu: removed dead links

2013-10-26T13:47:18Z

removed dead links

Kingu: merged post mortem from development tools

2013-10-26T13:22:49Z

merged post mortem from development tools

Porg: /* Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file */ Update: Changing HOME variable to PND dir was only necessary before Pandora OS 1.6

2012-01-18T01:01:52Z

‎Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file: Update: Changing HOME variable to PND dir was only necessary before Pandora OS 1.6

Porg: /* Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file */ Link to Wikipedia about Zenity GUI. Small typo corrections. Reordering related list items.

2012-01-15T23:21:08Z

‎Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file: Link to Wikipedia about Zenity GUI. Small typo corrections. Reordering related list items.

Porg: /* Creating pnd files */ Corrected erroneous wiki markup of headline

2012-01-15T23:09:06Z

‎Creating pnd files: Corrected erroneous wiki markup of headline

Porg: /* pnd_hup.sh */ Grammar: "whom" as this pronoun addresses an object!

2012-01-15T23:07:37Z

‎pnd_hup.sh: Grammar: "whom" as this pronoun addresses an object!

@@ Line 152: / Line 152: @@
 * device is turned on
-* during init, pndnotifyd is brought up and inhales the config giles
+* during init, pndnotifyd is brought up and inhales the config files
 * pndnotidyd will attempt to auto-discover what PXML.xml directory apps and .pnd-file apps are in the configured searchpaths
 * pndnotifyd will set up filesystem watches on the directories in the notify searchpath; if any of those directories are touched, pndnotifyd will wake up and re-auto-discover .. possibly removing .desktop entries or creating new ones. (i.e.: you drop a new app into the app searchpath, or remove one, or mount an SD card, etc. This is how appications immediately show up or vanish from the window manager desktops.)

@@ Line 551: / Line 551: @@
 ====pnd_run.sh====
-This job does a lot of the heavy lifting for libpnd, including setting up the 'union filesystems', doing .pnd and PXML.xml-app-dir execution and mounting, and so on. Generally you will talk to it via libpnd or .desktop files, but you can invoke it dorectly from your apps if you wish to circumvent libpnd or mount .pnd files within a shellscript/perlscript/etc.
+This job does a lot of the heavy lifting for libpnd, including setting up the 'union filesystems', doing .pnd and PXML.xml-app-dir execution and mounting, and so on. Generally you will talk to it via libpnd or .desktop files, but you can invoke it directly from your apps if you wish to circumvent libpnd or mount .pnd files within a shellscript/perlscript/etc.
 ==Auto-discovery of applications==

@@ Line 120: / Line 120: @@
 ===pndnotifyd===
-Manages the auto-discovery mechanism and integrating PXML.xml dir-apps and [[.pnd]] files into the FreeDesktop standard system (.desktop files). A dedicated libpnd-aware menu could leverage libpnd directly and not need pndnotifyd, though pndnotifyd does offer some handy bits such as HUPping apps to suggest to them that applications may have been added/removed (libpnd includes all the necessary functions for this as well.)
+Manages the auto-discovery mechanism and integrating PXML.xml dir-apps and .pnd files into the FreeDesktop standard system (.desktop files). A dedicated libpnd-aware menu could leverage libpnd directly and not need pndnotifyd, though pndnotifyd does offer some handy bits such as HUPping apps to suggest to them that applications may have been added/removed (libpnd includes all the necessary functions for this as well.)
 ===pndvalidator===
@@ Line 488: / Line 488: @@
 ===Creating pnd files===
-The [[PND quickstart]] page contains this information.
+The [[PND repository specification]] page contains this information.
 ===PXML overrides===

@@ Line 7: / Line 7: @@
 =Overview=
-[[libpnd]] is a basic collection of functions and tools to make working Pandora-specific operations easier; to wit, it is hoped multiple applications will make use of this library rather than re-implement similar functionality and lead to problems down the road. (Instead we can run into problems together and thus clobberize them.)
+libpnd is a basic collection of functions and tools to make working Pandora-specific operations easier; to wit, it is hoped multiple applications will make use of this library rather than re-implement similar functionality and lead to problems down the road. (Instead we can run into problems together and thus clobberize them.)
-[[libpnd]] thus is a collection of:
+A collection of:
 * handy system code that hopefully is reusable - IO functions, CPU clock setting, etc.
@@ Line 22: / Line 22: @@
 ==Design considerations and philosophy==
-While much of [[libpnd]] is obvious, some decisions had to be made and it may help to know the guiding principle behind it; the Pandora device will be a handheld '''computer''', but libpnd is designed to facilitate certain operations with goals towards..
+While much of libpnd is obvious, some decisions had to be made and it may help to know the guiding principle behind it; the Pandora device will be a handheld '''computer''', but libpnd is designed to facilitate certain operations with goals towards..
 * simplicity - just work right, configuration not generally needed
@@ Line 43: / Line 43: @@
 |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
 |-
 |}
@@ Line 120: / Line 120: @@
 ===pndnotifyd===
-Manages the auto-discovery mechanism and integrating PXML.xml dir-apps and [[.pnd]] files into the FreeDesktop standard system (.desktop files). A dedicated libpnd-aware menu could leverage libpnd directly and not need [[pndnotifyd]], though pndnotifyd does offer some handy bits such as HUPping apps to suggest to them that applications may have been added/removed (libpnd includes all the necessary functions for this as well.)
+Manages the auto-discovery mechanism and integrating PXML.xml dir-apps and [[.pnd]] files into the FreeDesktop standard system (.desktop files). A dedicated libpnd-aware menu could leverage libpnd directly and not need pndnotifyd, though pndnotifyd does offer some handy bits such as HUPping apps to suggest to them that applications may have been added/removed (libpnd includes all the necessary functions for this as well.)
 ===pndvalidator===
@@ Line 129: / Line 129: @@
 One of the test tools; it essentially runs an auto-discovery to list off the found apps (be they PXML.xml dir apps or .pnd files), and can dump various data or invoke one or other little tasks; used to test lots of
-bits of [[libpnd]] as it was developed.
+bits of libpnd as it was developed.
 ===rawpxmltest===

@@ Line 353: / Line 353: @@
 ===NAND layout===
-In addition to seeking applications in [[SD cards]], /usr/pandora/apps is included in the default searchpath, so that 'built in' apps can be listed, or users can drop them there.
+In addition to seeking applications in SD cards, /usr/pandora/apps is included in the default searchpath, so that 'built in' apps can be listed, or users can drop them there.
 It might be a cool addition to put a user homedir into the searchpath as well, so [[NAND]] but user-homedir (for on-device browser downloads, say.)

← Older revision		Revision as of 13:22, 26 October 2013
Line 570:		Line 570:

	- 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.		- 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.
		+
		+	===Post Mortem===
		+	All the console output from your application is written to a file (on a per PND basis), and typically users with crashes or other problems will post the contents of this file to help diagnose the problem. So, as a developer, it is sensible to make this file as useful as possible for getting to the bottom of problems. A common issue is the good old fashioned 'crash'; although despite the frequency of this problem typically nothing is logged leaving the developer with very few clues as to what has gone wrong (forcing them to take guesses based on previous data that has been logged). A pretty easy way to improve this situation is to catch crashes and write out the call stack to the console (which gets put in the PND log file). The code to do this is along the lines of:
		+
		+	<syntaxhighlight lang="c">
		+	static const bool kUseExceptionHandler = true;
		+
		+	void handler(int sig)
		+	{
		+	void *array[ 16 ];
		+	size_t size;
		+
		+	// get void*'s for all entries on the stack
		+	size = backtrace(array, PiArraySize( array ) );
		+
		+	// print out all the frames to stderr
		+	fprintf(stderr, "Error: signal %d:\n", sig);
		+	backtrace_symbols_fd( array, size, 2 );
		+	exit( 1 );
		+	}
		+
		+	int main( int argc, char ** argv )
		+	{
		+	if ( kUseExceptionHandler )
		+	{
		+	signal(SIGSEGV, handler);
		+	signal(SIGBUS, handler);
		+	}
		+
		+	// Etc.
		+	}
		+	</syntaxhighlight>
		+
		+	This will dump out a list of addresses on the callstack. You as the developer need to make sure you have access to the binary that caused the crash, and make sure that binary has debug symbols (i.e. is not stripped). Providing you have an unstripped binary, you can use the addr2line utility to convert the callstack addresses into filename, line number and function names, just like you'd see in the debugger. For addr2line, you can use syntax along the lines of:
		+
		+	<syntaxhighlight lang="bash">
		+	addr2line --exe=/path/to/unstripped/executabe -i -f -C
		+	</syntaxhighlight>
		+
		+	The console will then waiting for your input, so you can copy and paste any addresses you wish to look up (or copy and paste entire callstacks to have them decoded).
		+
		+	==Compressing textures==
		+
		+	ImgTec also supplies a tool that allows you to compress your textures to a format the OMAP chip natively supports, such as PVR-TC1, PVR-TC2 (PowerVR tex compression formats) and ETC1 (an Ericsson format)
		+
		+	This toolset comes in a variety of flavors, including a stand-alone GUI, a commandline tool, and plugins for Photoshop, Maya, and 3DS-Max. The tool is already included in the emulator+SDK package, but it is available separately at this page:
		+	* [http://www.imgtec.com/powervr/insider/powervr-pvrtextool.asp PowerVR Texture creation tool] - "PVRTexTool enables conversion of standard bitmap files (e.g. BMP, JPG, PNG, TGA, etc.) to any texture type supported by POWERVR MBX or POWERVR SGX hardware including PVRTC, DXT and ETC compressed formats. Both a GUI and command line version are supplied for Windows and Linux. There are also plug-ins for Autodesk 3ds Max, Maya and Adobe Photoshop." - requires imgtec registration.
		+

@@ Line 463: / Line 463: @@
 * Use an 'application relevant' appdata name; make it as unique as you have to, but consider being less unique; a random example could be .. possibly there may be several quake1 ports; they could all share the same appdata (same config files, same data files), but if you intend on having different config or data files than other quake1's, make your appdata named differently.
-* Always Always Always write your 'state info' to current-working-directory (ie: ./foo, and not ~/foo). The pnd-system will redirect this to the users appdata of course, keeping things clean and predictable. If you're just porting an app, that has ~ all over the darned place, and you don't want to muck up the code.. just have your 'runscript' do something like 'set $HOME=.' and you're good to go!
+* Always Always Always write your 'state info' to current-working-directory (ie: ./foo, and not ~/foo). The pnd-system will redirect this to the users appdata of course, keeping things clean and predictable. If you're just porting an app, that has ~ all over the darned place, and you don't want to muck up the code ... just have your 'runscript' do something like 'export HOME=$(pwd)' and you're good to go! '''Note: At the latest as of Pandora OS release Zaxxon with Hotfix 6, changing the HOME variable to point to the PND working directory is not necessary anymore as the OS takes care of changing the HOME variable of a PND session's variable environment. (Info from Skeezix)'''
 * Try using rudimentary [http://en.wikipedia.org/wiki/Zenity Zenity] scripts to pop up imporant pre-run information to the user via the GUI, if the application can't do so; ie: Hatari itself has a very fine GUI in it, but if the Atari ST TOS image is not present, it just exits and fails to run, so the GUI doesn't have time to do anything useful. In this case, it could be wise to use a 1 line Zenity script that checks before the emu runs for the file in question, then pop up a dialog box saying 'put this file /here', so the user knows what the heck happened

@@ Line 461: / Line 461: @@
 * Use a 'reasonably unique' unique-id of course (to identify your application.) This is used for many internal uses, so uniqueness is pretty wise.
-* Use an 'application relevent' appdata name; make it as unique as you have to, but consider being less unique; a random example could be .. possibly there may be several quake1 ports; they could all share the same appdata (same config files, same data files), but if you intend on having different config or data files than other quake1's, make your appdata named differently.
+* Use an 'application relevant' appdata name; make it as unique as you have to, but consider being less unique; a random example could be .. possibly there may be several quake1 ports; they could all share the same appdata (same config files, same data files), but if you intend on having different config or data files than other quake1's, make your appdata named differently.
-* Always include a documentation 'info' link, if your app has any setup requirements, has popup help screens that the user needs to know a key to pop up, or other essential trivia; feel free to make the doc link as complete as you like, since its all within the pnd file. (ie: Include the full DosBox documentation if you want to, in your DosBox pnd :)
+* Always Always Always write your 'state info' to current-working-directory (ie: ./foo, and not ~/foo). The pnd-system will redirect this to the users appdata of course, keeping things clean and predictable. If you're just porting an app, that has ~ all over the darned place, and you don't want to muck up the code.. just have your 'runscript' do something like 'set $HOME=.' and you're good to go!
-* Try to set up the appdata directory for the user; if you need a 'roms' or 'image' directory in the appdata (such as in the case of an Atari ST emulator needing a location to house the TOS OS image, say), then do a 'mkdir' in your 'runscript', to create it. Thus the user will find a (example) Hatari appdata directory, and within, any directories he needs (possibly empty.) This just makes it obvious for the user where to put stuff.
+* Try using rudimentary [http://en.wikipedia.org/wiki/Zenity Zenity] scripts to pop up imporant pre-run information to the user via the GUI, if the application can't do so; ie: Hatari itself has a very fine GUI in it, but if the Atari ST TOS image is not present, it just exits and fails to run, so the GUI doesn't have time to do anything useful. In this case, it could be wise to use a 1 line Zenity script that checks before the emu runs for the file in question, then pop up a dialog box saying 'put this file /here', so the user knows what the heck happened
-* Try using rudimentary zenity scripts to pop up imporant pre-run information, if the application can't do so; ie: Hatari itself has a very fine GUI in it, but if the Atari ST TOS image is not present, it just exits and fails to run, so the GUI doesn't have time to do anything useful. In this case, it could be wise to use a 1 line zenity script that checks before the emu runs for the file in question, then pop up a dialog box saying 'put this file /here', so the user knows what the heck happened
+* Runscripts; the PXML.xml can specify to run your binary, or you can run a .sh script that in turn runs your binary, say. This lets you do various tests, set up LD_LIBRARY_PATH, or other mischief before your binary gets run. Very handy. I often have PXML.xml run 'runfoo.sh', and runfoo.sh in turn runs ./foo after setting things up, making directories, etc.
-* Always Always Always write your 'state info' to current-working-directory (ie: ./foo, and not ~/foo). The pnd-system will redirect this to the users appdata of course, keeping things clean and predictable. If you're just porting an app, that has ~ all over the darned place, and you don't want to muck up the code.. just have your 'runscript' do something like 'set $HOME=.' and you're good to go!
+* Always include a documentation 'info' link, if your app has any setup requirements, has popup help screens that the user needs to know a key to pop up, or other essential trivia; feel free to make the doc link as complete as you like, since its all within the pnd file. (ie: Include the full DosBox documentation if you want to, in your DosBox pnd :)
-* Runscripts; the PXML.xml can specify to run your binary, or you can run a .sh script that in turn runs your binary, say. This lets you do various tests, set up LD_LIBRARY_PATH, or other mischief before your binary gets run. Very handy. I often have PXML.xml run 'runfoo.sh', and runfoo.sh in turn runs ./foo after setting things up, making directories, etc.
+* Try to set up the appdata directory for the user; if you need a 'roms' or 'image' directory in the appdata (such as in the case of an Atari ST emulator needing a location to house the TOS OS image, say), then do a 'mkdir' in your 'runscript', to create it. Thus the user will find a (example) Hatari appdata directory, and within, any directories he needs (possibly empty.) This just makes it obvious for the user where to put stuff.
 * For data that is not kept in your appdata directory, try to keep it local to the current SD _or_ better still, search both SD. ie: libpnd uses a basic but really handy system for iterating across a list of directories (including glob type expansion); so you can tell it something like /media/*/foo:/tmp and it'll check every mounted device (including both SD slots) in the 'foo' directory, as well as /tmp; you can have it call your code as it looks through, or you can ask libpnd to find a file for you and report where it was found, across all your searchpaths; you don't have to use libpnd's code to do it, you coudl write oyur own (using libpnd as an example if you need the help), as its pretty easy to build (20 lines of code maybe?) Anyway, the trick is to be multi-SD aware, and bonus marks for handling if theres a USB mounted drive etc as well. (Example; I coded minimenu so that when it caches out a preview picture, it checks for free space first, and tries first on the same SD that the pnd is mounting from, and then across a searchpath of alternate locations to cache to; this way the user can customize the caching, and it can be on various devices.)

@@ Line 486: / Line 486: @@
 * squashfs
-====Creating pnd files===
+===Creating pnd files===
 The [[PND quickstart]] page contains this information.

@@ Line 541: / Line 541: @@
 ====pnd_hup.sh====
-pndnotifyd will attempt to locate this script and invoke it after an auto-discovery run, if the pnd_hup entry is present (and uncommented) in the config files. It is expected to be commented out in release images, as xfce watches directories for .desktop files and does not need a HUP; some desktop managers need to be HUPped to rescan for .desktop files in a timely fashion, so the pnd_hup config entry can be uncommented and this script will attempt to figure out who to HUP.
+pndnotifyd will attempt to locate this script and invoke it after an auto-discovery run, if the pnd_hup entry is present (and uncommented) in the config files. It is expected to be commented out in release images, as xfce watches directories for .desktop files and does not need a HUP; some desktop managers need to be HUPped to rescan for .desktop files in a timely fashion, so the pnd_hup config entry can be uncommented and this script will attempt to figure out whom to HUP.
 ====pnd_make.sh====