PXML specification

This article covers the specification for PXML files. To see the specification for PND repository files, please see the PND repository specification.

Attention: at the present time, the PXML file format isn't set in stone, and is therefore subject to change. There is no guarantee that the format or the schema are bug-free or will be changed at any time. In general it is likely that a working PXML file will stay valid, if the schema definition mentioned here is followed.

This is the human-readable specification for the PXML file format. The PXML file format is used in your applications for the OpenPandora® that you package in .pnd-files or distribute otherwise, to make it possible for menus and launchers to use your applications and their properties.

A PXML file should be appended to your .pnd-file, using the tools provided for that purpose, or put in a directory that you want to serve as a redistributable package, to make it possible for launchers and menus to find it. It should have the name PXML.xml (not case sensitive) and there should only be one such file. The contents of the PXML file should also comply to this specification without exception, to guarantee that everyone will be able to read it.

The following specification is based on what the latest version of the PXML_schema.xsd definition accepts as valid data. Files that do not pass the validation might still work as expected, but if the validation is passed you can be (almost) 100% sure that it is supposed to be correct.

XML compatibility

The PXML format is XML-based and fully XML-compliant, which means that it can be read and written by any XML reader or writer. Included with this specification should also be a .xsd-file, which is used by XML tools to validate PXML files. A .xsd-file is also known as a XML schema, and can be called the "computer-readable" version of this document. It is very good practice to validate your PXML-files with that schema before publishing them.

To write a PXML file, you also need to know the basics of writing a XML file. It boils down to the following:

1. If an element contains text or other elements, it needs a start-tag and an end-tag. This looks like (1)
2. If an element does not contain other elements or text, but only attributes, it looks like (2)

<exampleelement someattribute="something">something inside it</exampleelement> <!-- (1) -->
<exampleelement2 someattribute="something"/> <!-- (2) -->

General format

The PXML-file is split up into multiple so-called elements, each of which specify one property of the .pnd-package. All of these elements are surrounded with a <PXML> tag, which tells the readers of the file that the data within that tag belongs to a PXML file. The tag and elements should be defined as follows:

The <PXML> tag

Description

The <PXML> tag serves as the container for all PXML elements. It is the first thing that should occur in your PXML file.

Attributes

xmlns 

The "xmlns" attribute is required by the XML standard, and guarantees that this file will be identified as a PXML file. You must include the xmlns attribute, exactly as shown, in your PXML file, with the URL as specified. Only then can it be guaranteed that the file will be read at all by launchers and menu apps.

Example

<PXML xmlns="http://openpandora.org/namespaces/PXML">
  <!--All of the PXML elements should be put here-->
</PXML>

The <package> element

Since PND files can contain various applications the new <package> element was introduced. It is meant to allow you to describe what the package is about. This will, at least at the moment (firmware 1 pre hotfix6), not be used by the pandora itself for detection, but is meant as tool for package repositories as well as package managers that might eventually be created. Each PND should have one of those at the top (and only one). The information required in the <package> block will be explained below in the respective section below.

The <application> element

The Application-tag permits the PXML.xml container to have multiple applications within it; you should have at least one application tag-pair (for one app), though you may have many. The information required in the <application> blocks will be explained below in the respective section below.

The <package> area

As described above, each PND should start with a package description. For single application packages this can basically be a copy of the respective areas from the <application> element.

Attributes

id

(required) The "id" attribute specifies an identifier common to all versions of a particular PND package. This can be achieved by appending some random number to your package name or by simply generating a completely random, very long identifier. A good ID may consist of the application name, developer name and some key, for example battlejewels.skeezix.001 or quake-1.pickle.001.

The package ID allows repositories to identify different versions of the same package and therefore determine whether that package should be updated. The package ID should therefore not be changed if a package is merely updated.

The package ID must not include characters which would be invalid in directory or file names, such as ?, >, /, etc. Use of such characters will prevent the PND from functioning.

Example

<package id="uniqueID">
  <!--All other elements described in this section (author, version...) should be put here-->
</package>

The <author> element

Description

The author element is an element that is used by the author to introduce him/herself. An author element is mandatory. It accepts the following attributes:

Attributes

name 

(required) The name attribute specifies the name of the author.

website 

(optional) The website attribute specifies the website of the author.

email 

(optional) The email attribute specifies the e-mail of the author.

Example

<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>

The <version> element

Description

The version element specifies the application version. A version element is required. It is recommended to keep the entries as simple as possible, where possible just numbers. It accepts the following attributes:

Attributes

major 

(required) The major attribute specifies the major version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.

minor 

(required) The minor attribute specifies the minor version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.

release 

(required) The release attribute specifies the release number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.

build 

(required) The build attribute specifies what build the application is at. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.

type 

(optional You can specify a type attribute that is either set to "release", "beta" or "alpha". This will (at the moment) not be read by libpnd but package repositories might use it in some way (to eg mark "beta" versions explicitly or something like this). If this is not specified, "release" will be assumed.

Example

<version major="1" minor="1" release="1" build="2" type="release"/>

The <titles> element

Description

The titles element is an element that contains multiple other elements.

The titles element specifies the text that is shown to the users of your PND file as the package title. Inside the <titles> block should be one entry for each language you want to support. The first language listed should always be en_US. The language is indicated by the lang attribute. The <titles> element with at least one "title"-element is required, in the en_US American English language. Additional tags are optional.

At least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.

Example

<titles>
  <title lang="en_US">Your application name</title>
  <title lang="de_DE">Dein Programmname</title>
</titles>

The <descriptions> element

Description

The descriptions element is an element that contains multiple other elements.

The descriptions element specifies the text that is shown to the users of your PND file as the package description. Inside the <descriptions> block should be one entry for each language you want to support. The first language listed should always be en_US. The language is indicated by the lang attribute. Additional tags are optional. The "descriptions"-element is optional, though it is highly recommended to specify it. If specified, at least one entry for "en_US" ( American English language) is required. Several of those elements are allowed, one for each lang that you want to display.

Example

<descriptions>
  <description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description>
  <description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und seine wichtigsten Features beschreiben sollte.</description>
</descriptions>

The <icon> element

Description

The icon element should specify a nice icon for your application. An icon element is optional, but if one is specified you have to include the src attribute. Only up to one icon element is allowed. It accepts the following attributes:

src 

(required) The src attribute specifies the path to the image file used as the icon.

NOTE: Current implementation will use the PND file's appended icon; for a PXML-app-directory, it will try to use the icon mentioned in the PXML. So, for a PND file, all subapps will show the appended-icon regardless of the <icon> tag within the PXML.xml.

Example

<icon src="images/icon.png"/>

The <application> area

The Application-tag permits the PXML.xml container to have multiple applications within it; you should have at least one application tag-pair (for one app), though you may have many.

<application id="uniqueID" appdata="dirname">
  <!--All other elements described in this section (exec, author...) should be put here-->
</application>

The sections which follow describe the allowed elements inside <application> blocks. You can have as many applications listed in a single PXML file as you want to (though there is/was a limit in libpnd that was set to about 50 once upon the time, which might eventually be completely be removed).

Attributes

id

(required) The "id" attribute specifies an identifier for your current application, and should be something globally unique so that no two PND packages have the same id. This can be achieved by appending some random number to your application name, and to use that as your id; or to simply generate a completely random, very long id. If this id already is used in another PND file, those two PND files will conflict with each other, and unforseeable errors will occur. Please put effort into generating a unique id for your PXML-file.

appdata

(optional) The "appdata" permits a directory name (NOT PATH) to be specified as preferred; if not present, the unique id provided in the ID attribute will be used. For example, we may want a unique id of Battlejewels.skeezix.3216836217382163.v001, but an appdata path of battlejewels to make it easier on the user, or to have multiple different battlejewels sharing one appdata.

Notice: appdata names with dashes in (e.g. quake-2 rather than quake2) will cause the PND file to function improperly.

Suggestions for Generating A Unique ID

A unique ID must not include directory or filename invalid characters, such as ?, >, /, etc. Any of those will cause the PND file to not function.

The unique-id should be unique against other PND files, but may be re-used by other 'application' tags within the PND; for example, you may have multiple subapps that want to share the same appdata path (which is formed based on unique-id!), so use the same unique-id. You might then have a utility application in that same PND, which needs its own appdata, and so gets its own unique-id.

A good unique id is the application name, developer name, and some key you may wish to update on occasion (should state-data become incompatible between updates, say.) Consider:

• battlejewels.skeezix.001
• quake-1.pickle.001

The <exec> element

Description

The exec element should specify all the information needed to execute your application. An exec element must be included in every PXML file. Only exactly one exec element is allowed. It accepts the following attributes:

Attributes

command 

(required) The command attribute specifies the path to the executable file. This should be a relative path to a file within the PND package. Must contain no arguments! One strategy you may need is to point to a shell script in your PND file, which in turn sets up LD_LIBRARY_PATH, determines arguments to pass, uses zenity to pop up a pre-run menu, or other trickery.

arguments 

(optional) The arguments attribute may be not present, or present with 1 or more arguments to the executable.

startdir 

(optional) The startdir attribute specifies the starting directory (Also known as the working directory) that the application should start in. This should be a relative path to a directory within the PND package, or to a well-known directory in the Pandora file system.

standalone 

(optional) The standalone attribute specifies whether or not this application can run on its own, or if it needs parameters to run. A value of "true" or "1" means that the application can be run without parameters. A value of "false" or "0" means that the application must be run with parameters (Meaning that no icon will appear for it in a launcher; it will only be run via file associations or via the terminal).

background 

(optional) The background attribute specifies whether or not this application should run in the background, and it should be possible to switch to other apps while it is running, or if it is the only application that should be running. A value of "true" or "1" means that the application can run in the background. A value of "false" or "0" means that the application must be run as the only application.

x11 

(optional) The x11 attribute may be missing; values are one of "req", "stop", and "ignore". If "req" is set, it means the application requires X11 (and possibly could be filtered out of users display in a menu if X is not running, or perhaps such a menu would have to start X.) If "stop" is set, it means X must be not running, or temporarily shut down, for the app. If "ignore" is set, the app doesn't care if X is running or not (such as an SDL app, or a sh-script, etc.)

extraarguments

(optional) The extraarguments attribute may be missing; values here are appended to the Exec= .desktop line after everything else, and after adding a --

pnd_run.sh, when executing this, will let the dashdash arguments be handled first by the shell then fed into the PND application. Regular arguments above are quoted and shielded by pnd_run.sh so not handled/expanded by the shell or desktop environment. Example: For file associations, %f (or others) may be a desirable argument.. however, placing %f into the arguments element above will result in a literal %f being passed into the PND application; adding %f into extraarguments will result in a file associated invocation with %f expanded to the desired string, instead.

Specifically, arguments above will insert -a "foo" into the Exec= line, while extraarguments will append -- foo.

Example

A minimal (and typical) exec:

<exec command="myprogram.sh"/>

A fully loaded one:

<exec background="true" startdir="/usr/share/icons/" standalone="true" command="myprogram" arguments="arg1 arg2" x11="option" extraarguments="%f"/>

The <author> element

Description

The author element is an element that is used by the author to introduce him/herself. An author element is mandatory. It accepts the following attributes:

Attributes

name 

(required) The name attribute specifies the name of the author.

website 

(optional) The website attribute specifies the website of the author.

email 

(optional) The email attribute specifies the e-mail of the author.

Example

<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>

The <version> element

Description

The version element specifies the application version. A version element is required. It is recommended to keep the entries as simple as possible, where possible just numbers. It accepts the following attributes:

Attributes

major 

(required) The major attribute specifies the major version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.

minor 

(required) The minor attribute specifies the minor version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.

release 

(required) The release attribute specifies the release number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.

build 

(required) The build attribute specifies what build the application is at. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.

type 

(optional) You can specify a type attribute that is either set to "release", "beta" or "alpha". This will (at the moment) not be read by libpnd but package repositories might use it in some way (to eg mark "beta" versions explicitly or something like this). If this is not specified, "release" will be assumed.

Example

<version major="1" minor="1" release="1" build="2" type="release"/>

The <osversion> element

Description

The osversion element specifies the minimal OS version that supports the PND file. The PND file will not be loaded by an OS that has an older version than the one specified here. If unsure, just use a '0' in the respective field.

Attributes

major 

(required) The major attribute specifies the major version number. Valid entries: non negative integers.

minor 

(required) The minor attribute specifies the minor version number. Valid entries: non negative integers.

release 

(required) The release attribute specifies the release number. Valid entries: non negative integers.

build 

(required) The build attribute specifies what build the application is at. Valid entries: non negative integers.

Example

<osversion major="1" minor="1" release="1" build="2"/>

The <titles> element

Description

The titles element is an element that contains multiple other elements.

The titles element specifies the text that is shown to the users of your PND file as the application title. Inside the <titles> block should be one entry for each language you want to support. The first language listed should always be en_US. The language is indicated by the lang attribute. The <titles> element with at least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.

Note: This is new in HF6. For backwards compatibilty please include the <title lang="en_US"> once outside the <titles> block, too!

At least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.

Example

<titles>
  <title lang="en_US">Your application name</title>
  <title lang="de_DE">Dein Programmname</title>
</titles>
<title lang="en_US">Your application name</title><!--pre HF6 compatibility-->

The <descriptions> element

Description

The descriptions element is an element that contains multiple other elements.

The descriptions element specifies the text that is shown to the users of your PND file as the package description. Inside the <descriptions> block should be one entry for each language you want to support. The first language listed should always be en_US. The language is indicated by the lang attribute. The "descriptions"-element is optional, though it is highly recommended to specify it. If specified, at least one entry for "en_US" ( American English language) is required. Several of those elements are allowed, one for each lang that you want to display.

Note: This is new in HF6. For backwards compatibilty please include the <description lang="en_US"> once outside the <titles> block, too!

Example

<descriptions>
  <description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description>
  <description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und seine wichtigsten Features beschreiben sollte.</description>
</descriptions>
<description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description><!--pre HF6 compatibility-->

The <icon> element

Description

The icon element should specify a nice icon for your application. An icon element is optional, but if one is specified you have to include the src attribute. Only up to one icon element is allowed. It accepts the following attributes:

Attributes

src 

(required) The src attribute specifies the path to the image file used as the icon.

NOTE: Current implementation will use the PND file's appended icon; for a PXML-app-directory, it will try to use the icon mentioned in the PXML. So, for a PND file, all subapps will show the appended-icon regardless of the <icon> tag within the PXML.xml.

Example

<icon src="images/icon.png"/>

The <licenses> element

Description

The licenses element is an element that contains multiple other elements.

It contains multiple license elements. Every element represents one license (so you *can* also multilicense something). You have to provide at least one license for your application. You can basically enter anything you want, though if you are using an existing license, it is best to just enter the name and provide a link to the full version. This tag also allows you to provide links to websites with the sourcecode.

Attributes

name 

(required) The name attribute specifies what the license is called. If you don't have a real license you can also enter some short text here (please keep it short!) or just enter "other" and doN't care no more.

url 

(optional) The url attribute can be used to specify a url to the full license text.

sourcecodeurl 

(optional) The sourcecodeurl attribute can be used to specify a url to the sources.

Example

<licenses>
  <license name="GPLv2+" url="http://www.gnu.org/licenses/gpl-2.0.html" sourcecodeurl="http://pandora.org/sources/package.tar.bz2"/>
  <license name="other"/>
</licenses>

The <previewpics> element

Description

The previewpics element is an element that contains multiple other elements. A previewpics element is optional.

It contains multiple pic-elements. Every pic-element represents one preview picture. If the previewpics element is specified, it must contain at least one pic element. Use the native 800x480 LCD screen resolution, minimenu and others will scale it down as needed.

Attributes

src 

(required) The src attribute on a pic element specifies the path to the image file used as the preview picture.

Recommendation

If you define multiple <previewpic> elements, then set the most illustrative picture as the primary <previewpic>!
Why? Because many context use only that picture at all or at that picture at first sight and more only on demand. Examples:

• Minimenu's preview function (toggled via "A") shows only the first picture,
• Repo RSS feed shows only the first picture,
• PNDManager's app info shows 1 picture at first sight, more on demand.

Currently there is no technical definition of the "primary" <previewpic>, therefore ensure that your intended primary <previewpic>

• occurs first in the source code order,
• has a filename that lists it first in a typical lexicographical sorting order.

What is an illustrative picture?
It should quickly give an impression of the look & feel of an application.
I.e. for video games this would mean and in-game screenshot rather than a main menu screenshot, except if the menu is just a small overlay, and the important parts of the game can still be seen.

Discussion in the developer forum

Example

<previewpics>
  <pic src="preview/pic1.jpg"/>
  <pic src="preview/pic2.jpg"/>
</previewpics>

The <info> element

Description

The "info" element allows the PXML.xml to suggest to the desktop environment or menu a file that may be shown to the user when they want to know more - be it an About, a Install Guide, a User Guide, or all of the above. Per application only up to one of those entries is allowed. If you need more, the best approach is to create an html file and link the other files.

The file can be a txt-file or an html-file, and as the PXML-app-dir or .pnd-application will be mounted, the file may in turn branch to other files should it wish to.

Developers do not need to have this element, if their app is nice and simple and just runs. If the application requires additional set up (such as Quake requiring separate pak files that cannot be included in the PND), or if you wish to include sample config files or config guidelines for something complex like DosBox, or include Pandora-specific notes.. those are all good things. But the developer is encouraged to be tasteful and not go hog-wild!

Attributes

name 

(required) the name to be shown in the menu; should be obvious that it belongs to the PND .. Quake's game PND could have "Quake 1 Setup".

type 

(required) the mime type for the file; in the event the consuming application can map mimetypes to an appropriate executable, this would be a good way of letting the user's preferred reader come up. Should be one of text/html (for an html file) or text/plain (for a .txt file). Those two are the only types allowed if the validation against the scheme is meant to be successful.

src 

(required) A file (including path relative to the PND; ie: ./index.html would be the root of the PND) in the PND to open up; by default, the web browser will likely be used to open it.

Example

<info name="AwesomeGame Setup" type="text/html" src="index.html"/>

The <categories> element

Description

The categories element is an element that contains multiple other elements. A categories element is required, and must contain at least one category.

Menus that use your PXML in any shape or form will use the category information to sort your application entry into the tree or sub menus. Depending on the menu system, this will be done differently every time. It is therefore advisable to specify as many categories and subcategories as possible (and as suitable; don't specify that your application belongs in a category if it doesn't).

The "categories" element contains multiple category-elements. Every category-element represents one category that this app can be sorted into. Valid top-level categories are (among others):

1. AudioVideo
2. Audio
3. Video
4. Development
5. Education
6. Game
7. Graphics
8. Network
9. Office
10. Settings
11. System
12. Utility

Please see the FreeDesktop specification for more information. In it, you will also find valid subcategories for your top-level categories.

The category-element takes one attribute: The name-attribute. This attribute represents the category name, which preferrably should be one of the above.

A category-element can contain further child-elements: subcategory-elements. These represent the subcategories of a category that the app will be sorted into.

The subcategory-element also takes a name-attribute; this attibute can contain a name for your subcategory.

For passing validation any category/subcategory entries have to confirm to the FDO specs linked above.

Example

<categories>
  <!-- This app belongs in the "Game/StrategyGame" category -->
  <category name="Game">
    <subcategory name="StrategyGame"/>
  </category>
  <!-- This app also belongs in the "Graphics/ImageProcessing" category -->
  <category name="Graphics">
    <subcategory name="ImageProcessing"/>
  </category>
</categories>

The <associations> element

Description

The associations element is an element that contains multiple other elements. An associations element is optional, except if exec.standalone is false (this is not checked via the schema!).

It contains one or multiple association-elements. Every association-element represents one file action association (though it is possible to put multiple mimetypes into a single association it muddies the waters so is best avoided.) The association is a request that this application may open a specified mimetype(s). Many applications may associate the same mimetype, and the desktop may offer a menu to allow one to be selected.

Note: This element is a 'recent' addition to the firmware (Super Zaxxon) - users will have to ensure they are in a late edition firmware

Attributes

name 

(required) The name attribute on an association element specifies the user-friendly action name for the association. ex: "Open PNG". It will be shown in menus, so include your app name ideally.

filetype 

(required) The filetype attribute on an association element specifies what file types (in MIME format) that this association should apply to. ex: image/png

command 

(no longer used) The command attribute is not used; most linux distributions do not allow for alternative execution methods for file associations versus standalone execution, so we have dropped this idea

arguments 

(no longer used) The arguments attribution is no longer used; see 'command' for why.

You will likely want to add an extraarguments element into the <exec> line, to contain %f or other hint; in this way the desktop environment will know to insert the filename(s), url(s), etc:

• %f → a single file
• %F → multiple files
• %u → a single url
• %U → multiple urls
• and so on (see the freedesktop specification in the Exec tag)

The result in the .desktop file is a Exec= line looking approximately like:

Exec=/usr/pandora/scripts/pnd_run.sh -p "/media/mysdcard/pandora/menu//ristrun.pnd" -e "run.sh" -b "ristrun" -- %f

Example

...
<exec command="myprogram.sh" extraarguments="%f"/>
...
<associations>
  <association name="Open a BMP Image" filetype="image/bmp" />
  <association name="Open a stylesheet" filetype="text/css" />
</associations>
...

The <clockspeed> element

Description

The clockspeed element specifies what clockspeed this app should run at. Please do only specify this element if your application *needs* to run at the specified clock speed. A clockspeed element is optional. It accepts the following attributes:

Attributes

frequency 

(required) The frequency attribute specifies the wanted frequency, in megahertz (MHz).

Example

<clockspeed frequency="600"/>

Example files

There are several example files available in the git repository. They do match the current specification and (unless mentioned differently) validate. Below the direct links and a short description what they are meant to show:

• PXML.xml: This is a sample PXML.xml file making use of many different things.
• average-case_PXML.xml: This is an example how a "common" pnd with just one application could look. Most of the information for the <package> block can in this case directly be copied over from the respective parts in the <application> block.
• full-sample_PXML.xml: This is a complex example defining a "real" package collection. It offers several applications, all using different features of PXML.
• minimum-schema_PXML.xml: This is a minimum example that will validate with the schema but basically offer nothing beside what really is required. This application should work nicely with any pnd repositories based upon the PXML specs. NOTE: This application will not work with pre HF6, for support for OS versions up to HF6 an additional <title> block outside of <titles> is required!
• minimum-libpnd_PXML.xml: This is a minimum example that will work on the pandora, but is not following the schema and lots of information that will be required for repositories based on the PXML specs is not available.

Validation

To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it. The schema is also available in a plaintext file described in words that are by far more compact than this page but still understandable for coders: plaintext description of the schema

The current-most XSD is in 'libpnd' (in the git repository). Here is the file history: PXML_schema.xsd file history Once on the history page, just click on the filename (right click -> save as) to download the latest version.

The easiest way to run validation is using this command:

 xmllint --noout --schema PATH/TO/PXML_schema.xsd PATH/TO/PXML.xml

To run it you have to have xmllint installed and the (latest) PXML_schema.xsd definition downloaded. Using this command you can now simply evaluate if the PXML.xml file is valid. xmllint can be installed via the angstrom repository (it is part of libxml2-utils).

Attention: It is possible to validate PXML files that won't work with pre HotFix6. If you want to have the pnd work with basically all versions of the OS (you most likely want this!) please have a look above searching for ' and include those blocks in your pxml file.