Introduction to PNDs

For developers: PND quickstart, or Libpnd hub

A .pnd ("pandora") file is an application (game, word processor, emulator, whatever.) More accurately, it is a full application bundled up into a single file; think of it like a zip, with a relatively well defined internal structure.

The pnd-file system was designed so you could use an application without the hassle of installation or uninstallation, or even having to organize it yourself if you don't want to. You just download or obtain the pnd-file, and use it.

If you remember classic computers such as the Amiga - where you inserted a disk and then launched the applications read by Workbench (the Amiga's operating system) - then this is similar:
When you insert an SD card into one of the two slots, the (Linux-based) Pandora OS will scan it for your PND program files. Any program it finds will either turn up on the desktop or the application menu (just like in Windows).

How do I run a PND-application?

Put your pnd-files in your SD A pnd-file is usually invoked in one of the following ways

• in MiniMenu, the applications will be shown by name; you can just select and run them from the menu

• browse to the file using the directory browser, and click to run it. (.pnd files are file-associated to another program, pnd_run which knows how to run them.) This lets you organize pnd-files in directories of your choice on the device NAND or SD.

• for pnd-files placed into /pandora/menu on SD, the application will be shown in the Start menu on the device; use your stylus or buttons to invoke it

• for pnd-files placed into /pandora/desktop or /pandora/apps on SD, they will show up automatically on your desktop; invoke them with the stylus, your finger, or controls as you see fit

Where do .PNDs Go?

This is what the folder structure on your SD card should look like. The drive letter and card name will vary; they're not important.

Put .pnd-files into specific directories if you want them to show up in the Start menu or on your Pandora desktop, or in Minimenu.

You can put them anywhere you like in internal NAND or SD, if you wish to organize them yourself and launch them with taps.

Folder	Note
/pandora/desktop	pnd files show up on the desktop
/pandora/menu	show up in the Applications menu (by the developers suggested categories.)
/pandora/apps	show up in the desktop, and in Minimenu
/pandora/mmenu	show up only in minimenu, ignored by the rest of the system

These locations are not written in stone. The libpnd config files are in /etc/pandora/conf in the NAND. Generally you will never need to alter these files, but you certainly can if you wish. In theory, obliterating the files will still leave the system working, and they are easily restored. One file, /etc/pandora/conf/desktop defines the "search paths" to look for .pnd files, and where to put ".desktop" files when they are found. The searchpaths says where to find them (such as /pandora/desktop), and where to put the application link - /usr/share/applications is where the menu items are pulled from. IF you wish to put pnd files somewhere not in the searchpath, just add the directory to the search-path and you're good to go.

NOTE: You can actually put subdirectories into those locations above, should you wish to organize your pnd-files somehow within those larger categories.

Where DON'T .PND files go?

• .pnd files are looked for in the directories mentioned above; that list can be tailored if you wish to edit config files.
• .pnd files are not looked for in the / (root) of the SD cards.. this is _on purpose_; consider, if your SD card is 32GB, or if you're using a 2TB USB drive even -- it could have tens of thousands of files on it; having the Pandora scan the entire device for pnd files would take forever. Instead, we made a well defined set of directories the system will use - /pandora for everything, with 'appdata' and 'menu' and 'desktop' and other special purpose directories.

We could perhaps add / (root) of SD, without checking subdirectories, but thought it may run into confusion; we may add that later. But currently, the system will scan all subdirectories of the directories named above, so you can organize pnd files within those directories if you like.

Where does my data go? How do I make files visible to the applications?

An application normally will see what is contained within the pnd-file, or your personal data created with the tool; it can of course look anywhere on the SD or device internal memory. For example a Quake port might expect to see extra level files in /quake, or give you a way of selecting a path to put files in.. or it might just expect it to be in your personal data folders, or in the pnd-file itself. Its up to the application, with suggestions in the pnd-guidelines for developers.

The first time a pnd-application is run, an "app data" directory is created for it; anything that app data folder contains will be visible to the application as if it was in the pnd-file (and in fact, this lets you override files in the pnd-file without modifying the .pnd itself, which could be handy.) If your app creates a file "foo", it'll show up in /pandora/appdata/appname-id as "foo". The actual appdata folder name depends on the name used by the developer, but should generally look like application-name and some funny number afterwards. It should be easy to spot.

example: Quake 1 will probably put score or save data in /pandora/appdata/quake1-123/ or somesuch.

It will always be helpful to read the description or readme file included.

Example: Hatari

Hatari (Atari ST emulator) by default is set to look in "./disks" for the disk images (ROMs) to use. What this means is within the pnd-file (where no disks are supplied), and in the appdata directory. With Hatari, you can browse anywhere from the UI and pick a disk anywhere on your SD cards, but by default it'll look into the ./disks directory.

So you might put Hatari into the menu (/pandora/menu/Hatari131.pnd), or into the desktop (/pandora/desktop/Hatari131.pnd), or somewhere else. Regardless, the appdata will be (with the version I'm building now), /pandora/appdata/hatari.skeezix and thus you would put your .ST or .MSA disk images into /pandora/appdata/hatari.skeezix/disks to make them visible to the emulator. However, given it features its own UI, you can put them into /roms/atarist or /disks or whatever, and use them from there.

Advanced topics

I want to override the .PND icon, name, or other settings, how is this done?

The easiest way right now is via the "override" (or "overlay") system -- .ovr files.

An .ovr is just a text file you create, with the same name as the pnd-file and in the same location, but with a different file extension. Piece of cake.

If your pnd-file is Hatari.pnd, and you're putting it into /pandora/desktop, then you might create an ovr file for it as: /pandora/desktop/Hatari.ovr If you wish to provide your own icon, create it with the same location and filename, but as a .png file: /pandora/desktop/Hatari.png

.ovr files are automatically supported by the system so should work across all pnd-application aware applications and desktops. .png icon overrides have to be handled by the menus, but are already handled by minimenu and anything using the .desktop system (such as xfce full desktop or other standard desktop environments.)

An ovr-file simply looks like this:

• The ovr file may (at this time) override the icon title, the CPU clock speed to set on launch, the main category, and the first subcategory for the main category. Additional fields will become overridable.
• The category list uses the existing desktop standard. See here for a list of categories and subcategories supported.
• Minimenu honors up to 3 lines of 'notes', pulled from the .ovr file. (Make sure they are in the right subapp group). note-1, note-2, note-3, see example below. The notes in minimenu are shown at the bottom of the detail text panel.

[Application-0]
title                   HatariHack0
maincategory            Audio
maincategorysub1        Emulator
[Application-1]
title                   HatariHack1
clockspeed              200
note-1                  My text for note line 1

Notice the Application-0 and Application-1 -- any given .pnd file may include multiple applications, so you need to assign your overrides to the correct "sub application". It can be tricky to figure out which subapp you wish to override, but there are some tricks. minimenu, for example, shows the subapp-number in the detail panel. When looking at a .desktop filename, you'll notice #0.desktop .. some number after the # is the subapp-number.

How Do I Make .PNDs?

PND quickstart has more information.

How Do I Look Inside a .PND?

To open a PND, the easiest way is probably to use the PNDTools or PNDManager programs, which can browse and create PNDs. They're Windows-only, currently.

You could also install 7zip on your home PC, change the .pnd's file extension to .sfs, and 7zip should be able to open it. (This is a simple way to look into a .pnd on Ubuntu: unsquashfs FILE.pnd needs squashfs-tools installed) [1] On the Pandora, you can run a PND and look at what's inside /mnt/tmp. To do this in a terminal (on PC or Pandora), see this tutorial.

{{IntroNote | The following is a work in progress, the instructions in here may or may not work for you. It was taken from PND quickstart.

This page is a quickstart to packaging an existing directory tree as a PND for distribution.

PND generation overview

• create a directory to represent the application on SD card; i.e.: ./mame-app

• create a PXML.xml file and drop it into the dir (./mame-app/PXML.xml); genpxml script can be used, or do it by hand

• drop the executable and data files into this dir (say, ./mame-app/mame.bin, and ./mame-app/artwork/foo, etc.) <- note, with a PXML.xml and executable, it can now be discovered and run without even bundling into .pnd!

• invoke pnd-make.sh (or on Windows, various commands in the command-line) to produce mame4all-pandora-1.0-arm.pnd or whatever you want to call it (foobearspanky.pnd, we don't care.)

• you're done, distribute it as you see fit

Preparations

When GUI tools get released, they may simplify these steps. However, until then you must do the following:

1. Make a PXML.xml file (through whatever means; copy a template, or get a PXML.xml tool when they come available.) Ensure that you've got a reasonably unique-id in that field (ie: say, app-name, your name, and date/time all catenated together.) Check out the PXML specification, as well as this example file.
2. Put your application and all needed files into a single directory .. say "myapp"; it doesn't matter what you call it.
3. In your app-dir, put the PXML.xml file in the root
4. Put the icon in the root of that dir as well (make it a .png file)
5. Make sure the PXML.xml names the icon (just its filename.png), and specifies the executable (foo.bin or whatever.)

Making PND files

Windows / DOS

Command-line

There should be a basic GUI along very soon, and more advanced friendlier GUIs in due time. But for now, we thought it prudent to include some basic instructions on the command line for day-zero.

For this command-line tutorial, I will assume you have already created a PXML.xml file; copy one of the templates and then edit it, using notepad or whatever _TEXT_ editor you see fit.

Windows specific preparations

Get yourself mkisofs tools; for example, grab from here: http://www.student.tugraz.at/thomas.plank/ -- get cdrtools-2.01-win32-bin.zip and DLL version 1.5.25, and extract to somewhere. That lets you run 'mkisofs' to spit out .iso files

If you want to make a compressed image, use squashfs tools here: ftp://ftp.slax.org/useful-binaries/win32/squashfs-tools/

Generate the actual PND-file

Make yourself the iso; this step produces the iso, but to turn the iso into a pnd you need a couple last steps. You could also use some fancy iso-building tool.

mkisofs -o foo.iso -R /path/to/folder/myapp

Append PXML.xml to the .iso (yes, the PXML.xml is included in the iso, but we also want to append it for performance reasons.)

copy foo.iso+PXML.xml foo.step2

Append the icon PNG file to the .iso (if you have an icon; if not, you can leave this step out.)

copy foo.step2+myicon.png foo.pnd

Clean up:

del foo.step2 foo.iso

Profit!

GUI

You have a few choices here:

• PNDTools by foxblock. Discussion: OP, GP32X. Can browse and create PNDs. Two (simple and advanced) editors for PXML creation.
• PNDBuilder by StreaK. Discussion (old). Can create PNDs and edit PXML files.
• PNDManager by Speaker Ender. Discussion.
• PNDbuilder by freedomdown. Discussion.

Linux/BSD/Unix (including on Pandora)

Command-line

Tools are included in the libpnd distribution; see below for discussion, but suffice to say they are included in the GIT. Look in testdata/scripts for:

• genpxml - spits out a template PXML.xml for you, and even includes a reasonably unique-id
• pnd_make.sh - given a directory and some arguments, will spit out a .pnd file; great for use in Makefiles

We're working on others as well, so it should be a piece of cake under Unix and Unix-like OSes.

Command-line (alternate instructions)

For these instructions, you will first need to grab the example file, here.

• Edit ./pnds.sh. I use that script to handle multiple apps at once. Each line represents a command line for an app / game to turn the directory into a PND. If I change the app / game, I simply uncomment the line in pnds.sh so that I can easily create or update multiple PNDs by simply running one single script.
• Run ./pnds.sh
• Upload

Don't forget to check the license conditions for anything you re-distribute.

GUI

• PNDbuilder by freedomdown. Discussion. Download v1.1 for Pandora.

Mac OSX

TBD

Example PNDs

You can look at an example PND file to help you out if you're struggling with the above steps. Download one or several PNDs (preferably from the Repo, as it forces strict PXML standards), and use PNDTools to open them and see how they're organised inside, what the PXML file looks like, and so on.

The PND Cookbook contains recipes for common PND tasks, like setting up your application's environment and configuration, locating and copying files, etc.

More Info About .PNDs

Visit libpnd hub for more information, but be warned that that page is targeted more towards developers.