Pandora How To Write A Well-Behaved Pnd Program?


multiplex

Member
Joined
Aug 20, 2008
Messages
189
So I'm currently looking at http://pandorawiki.org/Libpnd_hub and trying to find out how to write a program that will behave nicely when packaged as a PND.
The system itself is decently specified, but what exactly is required from the application programmer is left kind of implicit, so I thought I'd confirm some things.

- As I gather, all files should be read relative to the location of the executable. Specifically, resource files should be read from the program folder, and configuration and save data should be written to the program folder. Is that right, or should some things go to the user's home directory?
I've mentioned this before as well, but it would be nice if the launcher could set up some environment variables so programs that follow the XDG Base Directory spec would just work when packaged up correctly. If my understanding is correct, you'd need to specify the mounted directory in XDG_DATA_HOME and XDG_CONFIG_HOME, and append it to XDG_DATA_DIRS and XDG_CONFIG_DIRS.

- Programs that require user supplied data files, like id game engines, should use the <mkdir> tag to create a directory in the root of the SD card for the user to put their stuff in. They should then search (both?) inserted SD cards for their files, and display an message explaining what the user needs to do if it doesn't find them.

- File associations are specified with MIME types. There isn't currently any way for a PND to add new MIME types to the system.
If this is the case, I do hope the system will come with a fairly complete set of file types. In particular, it would be nice if it covered all the common ROM formats. I see some fuzz about front-ends and specifying ROM directories and such, but I personally just want to browse to my ROM and tap it.
 
Apps should simply read/write to CWD (current working dir) or its subdirs. ie: refer to ./mydata for instance.

We've been using a simple trick for some apps that refer directly to $HOME (for .rc files, for example); in those, I just have the pnd run a 'runme.sh' type sh-script, which just does "set HOME=.; ./actualprogram" to work, which usually does the trick ;)

The external data files (ie: so 3 different implementations of Quake1 can all refer to the same base data files) it gets a little goofy; you could do it a few ways..
i) Specify an 'appdata path' by name (not implicit based on unique-id), and assume others can re-use it; thats risky in the Quake1 type case, due to different conf-files/etc; ie: the named appdata-path is mostly for user convenience of appdata, not for merging multiple apps.
ii) Use a 'canonical path'; ie: /quake1. And as you say, might be wise to search both SD cards for '/quake1' (or other media, since could be USB drives etc mounted into /media). In fact, you could use pnd_locate function, or use the goofy but hihly useful libpnd searchpath hack that all libpnd uses. (A couple macros that essentially cause your code to iterate across all matches of searchpaths.) Or look into the searchpath code and crib the bits you like.
iii) Or assume the user will drop the data files into the app appdata; ie: duplicate for each quake implementation, but SD cards are huge now! (don't get out of control for CD .iso's, they're big ;) (ie: Consider .. GemRB, where dat files for one Bioware game could be several GB in size; you reall want a canonicle location for that if you expect an alternate parser.)

The 'mkdir' option in PXML.xml is a convenience -- ie: probably best avoided, but could be useful as a user hint. "hmm, where do I put files... oh look, I see /quake1 on my SD!'; however, I prefer to avoid its use since 1) it doesn't notify the user of its actions, or ask for authorization; 2) it doesn't really know which SD the user woudl want data files, on, etc.. So it works, but may be 'unkind'; was added as an option, and I think Imade it so that behaviour could be disabled in another conf file, so that you cannot depend on it.

Note that I think a well behaved pnd should supply a documentation hint; ie: include some readme.html in your pnd and code the PXML.xml so that it shows up in the Documentation menus (note that minimenu also will make it available, in addition to all your Freedesktop compliant systems.) (Also note that the doc html is free to be as complex as it wants - could link to other files or whatever. I really have high hopes for the documentation links to be useful, or to even link to utility scripts that unpack documentation to a user defined location, etc.)

File associations were something I kept meaning to implement, but it needed more fleshing out so I kept on hesitating rather than commit the code I'd worked on; we'll have to sort it out and expand on it together, once we have more usage data.

An example: Kronos, my IF (interactive fiction/text adventure) interpreter set, I'm just allowing a file select for the user to define the default path, and remembering it; thats a pretty good way much of the time. Sensible default, with easy override.
Another example: Hatari, my port of Hatari Atari ST emu; default to a sensible, with file selector again.
I forget what Pickle is doing for dosbox, but I think he's going to assume something like /dosbox/drive_C or whatever, on the same-SD as the pnd-is.

Make good defaults, and document right up front in your doc-link, and I think we'll be okay.

jeff
 
If you agree with any of the above, let me know if you think I should write it up into the libpnd hub. You are right, the 'developer guidelines' perhaps need fleshing out.

(ie: I hope I fleshed out the pnd-recommended-layout, for instance, but I'll have to go check. ie: Include your icon-foo.png and PXML.xml in the root of the pnd, even though they're also appended to the end of the .iso to turn it into a .pnd-file. This way, when users unpack the pnd and then repack it after hacking it up (it'll happen :), they don't lose the files :)

jeff
 
Thanks for your answers, that does help. I think we'll require a dedicated page with instructions on "how to write/port a program for the Pandora" that targets application programmers.

I'm not sure if CWD can be relied on in absolutely all cases, as according to the PXML specification, the "startdir" attribute of the <exec> element can be used to specify the working directory.

The sh script trick would leave a resident shell process until the program exits, though I suppose that's a pretty minor issue.

It's fair not wanting to rush the associations, hope we'll manage something for the next version.
 
Instead of leaving the sh running, you could 'exec' your app as the new shell, after setting the env. ie: Lots of the usual tricks.

CWD can be relied on; remember, you're writing your own PXML.xml, its not thrust upon you, so if you're using startdir or specying a path in your bin in the exec line, etc.. thats your business :)

The behaviuour is _predictable_ and _dev controlled_ which is the key, so yeah, should be fine.

I expect most apps to run from the root of the pnd.

jeff

re: file assoc's; I've always maintained that I'm not the only check-in for libpnd, epecially post-launch; I do worry that if we open it up widely than random people will deposit all sorts of junk in the lib, but at the same time its not my place to audit what goes in per se; I'm not sure what the best approach is, but a single or group of people who audit submissions seems a decent thing (works for Linux, right?) but whatever. Anyway, if 'we' (community) can settle on useful additions to libpnd that don't break things, I figure it can go in. Some vetting process? I figured we could figure this sort of policy out post-release.. so, soon I guess :)

So yeah, file assoc code cna go in, but I thought it best to see how things go first. (likewise for pnds that can extend the lib-paths, or alter the OS etc .. best to see how things go before laying something down first. *shrug*)

(But boy, I've been holding off on a lot of changes to libpnd; don't want to break anything and delay release, so a lot of good ideas, useful things, or significant changes have been held off :)

--

btw, libpnd will build and run on an x86 Linux box as well; its not hard to make use of it for testing on a regular distro; I regularly built an app for x86 and pnd'd it up, so I could test things easily.
 
Just wrote this up quick; feel free to add to it or refine it, just hurried it in :)

http://pandorawiki.org/Libpnd_hub#Recommended_layout_of_a_pnd_directory_structure.2C_ie:_how_to_make_a_well_behaved_pnd_file

jeff
 
Ok, so I'm trying to get my application to write to it's appdata directory but no matter what I try it seem to ignore what I set in my runme.sh script.
I don't think that set HOME=. works the way you think it does. I tried this on my desktop and it doesn't seem to do anything.
using export HOME=. does something, but not what you'd hope, either. What happens is, it makes whatever directory you are currently in "home" even if you change directory, you're "home" is that directory... say:

I cd Desktop from my home folder and export HOME=. Then change directory to what would be /home/mindlord/Music and then cd ~, I stay right in /home/mindlord/Music, and don't go back to /home/mindlord/Desktop.

What you should be doing is export HOME=`pwd`. Those are grave marks around pwd, that causes bash to expand whatever is between them, just once.
 
Back
Top