Pandora Packaging a game into a PND

[mcobit]

Packaging up an app.


This is a followup to the „Porting a simple SDL game“ tutorial. Make sure you have your home and root extends mounted and have a compiled version of Abe’s Amazing Adventure in your /mnt/utmp/abe folder.


Disclaimer: This is how I package pnds. There might be better solutions, but this works for me.


I am not responsible, if you mess up your system or do anything else to your Pandora!


When I wanted to package up some apps, I followed the packaging tutorial in the pandorawiki.


This is a little confusig, as it is written for different OSses and the link to the example PXML.xml file is broken.


So here is a step-by step tutorial, that only uses the Pandora itself.


This is a followup to the „Porting a simple SDL game“ tutorial. Make sure you have your home and root extends mounted and have a compiled version of Abe’s Amazing Adventure in your /mnt/utmp/abe folder.


Now, that we have the game compiled, cd into the /tmp homeExtend folder:

cd /tmp/homeExtend

Make a new dir, to hold your pnd:

mkdir /tmp/homeExtend/abe-pnd

Now cd into the new dir and copy the /mnt/utmp/abe folder over:

cd abe-pnd

cp -R /mnt/utmp/abe .

Now we will create an PXML –file. For this type:

touch PXML.xml

nano PXML.xml

Now that you have opened in the editor, you can just copy and paste the example below into the empty file:

<?xml version="1.0" encoding="UTF-8" ?> 

  <PXML xmlns="http://openpandora.org/namespaces/PXML">

  <application id="abe" appdata="abe">

  <title lang="en_US">Abe's Amazing Adventure</title> 

  <description lang="en_US">A scrolling, platform-jumping, key-collecting, ancient pyramid exploring game, vaguely in the style of similar games for the Commodore+4. The game is intended to show young people all the cool games they missed.</description> 

  <version major="1" minor="1" release="0" build="0" /> 

  <exec command="./abe.sh" background="true" standalone="true" /> 

  <author name="Gabor Torok, Pedro Izecksohn, Alex Clarck" website="http://abe.sourceforge.net/" email="cctorok@yahoo.com" /> 

  <icon src="icon.png" /> 

  <categories>

  <category name="Game">

  <subcategory name="ActionGame" /> 

  </category>

  </categories>

  </application>

  </PXML>

You can modify this file for every app you want to package, but for our little project this is just what we want.

Save the file and exit the editor.



There is something else we need right now and that is an icon for our game. As there is no default icon for Abe’s Amazing Adventure, I took a png from Google:

wget http://ubuntu.allmyapps.com/data/a/b/abe-abes-amazing-adventure/icon_48x48__usr_share_pixmaps_abe.png

Let’s rename it to fit the name we specified in the PXML.xml:

mv icon_48x48__usr_share_pixmaps_abe.png icon.png

Now put a copy of both files into the abe folder:

cp PXML.xml icon.png abe/

Cd into the folder,

cd abe

As you might know, some programs need additional libs, that are not included in the original firmware. This program doesn’t, but we will nontheless package all the libs needed with it. Fort he learning experience ;-)



So create a new folder called lib and cd into the folder:

mkdir lib

cd lib

But how do we know, what libraries are needed by the program? This can be found out with the nice little program called ldd.

This is not in the dev.extend by default, so we need to install it:

sudo opkg install ldd

When this finished we can check for the libraries with ldd:

ldd ../bin/abe

This will print out a list with all the needed libraries. So now we know which ones we need, copy them all to our lib folder:

cp /lib/libdl.so.2 /lib/libm.so.6 /usr/liblibSDL-1.2.so.0 /lib/libthread.so.0 /usr/lib/libSDL_mixer-1.2.so.0 /lib/libc.so.6 /lib/ld-linux.so.3 /usr/lib/libts-1.0.so.0 /lib/libgcc_s.so.1 /usr/lib/libmad.so.0 .

Go out oft he folder:

cd ..

Now we can create our startupscript, as seen in the PXML file:

touch abe.sh

We also need to make it executable:

chmod +x abe.sh

Now we open the file and edit it:

nano  abe.sh

Here you can see the contents of an abe.sh file, I made:

#!/bin/sh

# We don’t want to let the program write its configuration, savestates etc. to the NAND.

#So we need to export our HOME environment variable first.

export HOME=/mnt/utmp/abe


# There may be libs, that the program needs and that are not on the NAND by default.

#So we need to export the LD_LIBRARY_PATH environment variable to point to the libs we will package into our pnd.

export LD_LIBRARY_PATH=LD_LIBRARY_PATH:/mnt/utmp/abe/lib

#Now we need to launch our program.

./bin/abe

#You can attach any commandlinearguments to the above line, if a program needs them.

Save and close the editor.

Then go to the abe-pnd folder again:

cd ..

Now we should have everything, that will be packaged into the pnd.

The only thing we don’t have is the script to make the pnd. You can make a copy in this folder by typing:

cp /usr/pandora/scripts/pnd_make.sh .

Now we are ready!

The usage of pnd_make.sh is as follows:

./pnd_make.sh –d yourfolder –p yourpnd.pnd –x yourpxmlfile.xml –i youricon.png –c

The –c ist to tell the script that it should create a compressed sqashfs filesystem instead fo iso in the pnd. This saves some space.

So in our case the command should be:

./pnd_make.sh  -d abe –p abe.pnd –x PXML.xml –i icon.png -c

Execute the script and you should have a fresh abe.pnd file in the same folder you are in now. Test it by copying it to one of your sdcards.



Now we should remove the folder in /mnt/utmp:

sudo rm -r /mnt/utmp/abe

Congratulations! You packaged your first selfported game!

 

[sebt3]

This will print out a list with all the needed libraries. So now we know which ones we need, copy them all to our lib folder:

cp /lib/libdl.so.2 /lib/libm.so.6 /usr/liblibSDL-1.2.so.0 /lib/libthread.so.0 /usr/lib/libSDL_mixer-1.2.so.0 /lib/libc.so.6 /lib/ld-linux.so.3 /usr/lib/libts-1.0.so.0 /lib/libgcc_s.so.1 /usr/lib/libmad.so.0 .

The libraries already part of the OS dont need to be packaged, only those that are not.

 

[mcobit]

This will print out a list with all the needed libraries. So now we know which ones we need, copy them all to our lib folder:

cp /lib/libdl.so.2 /lib/libm.so.6 /usr/liblibSDL-1.2.so.0 /lib/libthread.so.0 /usr/lib/libSDL_mixer-1.2.so.0 /lib/libc.so.6 /lib/ld-linux.so.3 /usr/lib/libts-1.0.so.0 /lib/libgcc_s.so.1 /usr/lib/libmad.so.0 .

The libraries already part of the OS dont need to be packaged, only those that are not.

As you might know, some programs need additional libs, that are not included in the original firmware. This program doesn’t, but we will nontheless package all the libs needed with it. Fort he learning experience ;-)

As it doesn't harm anybody and the libs are really small I thought we should just do it. When a new OS version uses a new sdl, that breaks backwardscompatibility, this app will still run ;-)

 

[darfgarf]

best way to ensure compatability would be to statically link the executable, so all the needed libraries are included in it, completely independant of the os, means a bigger executable, but you'll never have to go back and fix it because some obscure library got removed in an update

 

[Geca]

And for unpack a pnd file to extract the content ?

 

[milkshake]

depends how it was packages but usually

unsqushfs yourapp.pnd

will do there trick, baring in mind you have to be in the same directory as the pnd for this command to work unless you specify the dir aswell, the files will be unpacked into the dir where the terminal is pointing.

 

[DoubleDash]

Thanks mcobit, a really useful tutorial.


I'm still tweaking my dev setup atm but when I'm done I intend to post a newbie guide to what I did. I might PM you for comment before I do, if you don't mind?


I've got a game I wrote at quite a leisurely pace whilst waiting for the pandora to move states from vapour>prototype>trickle to in my hands! I just need to check out the copyright on some images I pulled. After that it would be a good candidate for trying out your pnd tutorial

More good tutorials = more developers (that start and don't give up!) = more software

 

[Geca]

depends how it was packages but usually

unsqushfs yourapp.pnd

will do there trick, baring in mind you have to be in the same directory as the pnd for this command to work unless you specify the dir aswell, the files will be unpacked into the dir where the terminal is pointing.

I got this message:


"filesysten on 'my_game.pnd' is <4.0> which is a later filesystem that i support!"


Where i can find the lastest version of unsqushfs ?


Thanks.


EDIT: I find it, and i have descompress sucessfull the pnd, thanks

 

[mcobit]

I think there is a link in the wiki to the newest squashfstools. You can of course PM me if you have questions.


Edit: Found it: ftp://ftp.slax.org/useful-binaries/win32/

 

[Geca]

I think there is a link in the wiki to the newest squashfstools. You can of course PM me if you have questions.


Edit: Found it: ftp://ftp.slax.org/useful-binaries/win32/

I made it on my Linux PC, thanks a lot!

 

[mcobit]

Thats easier anyways.

 

[WaveHack]

Doesn't GPL disallow packaging SDL shared object files into distributable packages?

 

[Letalis Sonus]

If you distribute something that's using GPL-licensed code (e.g. in form of a precompiled library), it has to grant the same rights, i.e. it has to be released under the GPL as well or another compatible license. If this is the case there is no problem with packaging it up to distribute it.


But SDL isn't licensed under the GPL, it's licensed under the LGPL and may therefore even be used by and distributed with closed source software. Example: The Linux client of Neverwinter Nights is using SDL and ships an own SDL library to prevent possible incompatibilities.

 

[klapse]

I dont see a squashfs or unsquashfs on the Pandora itself. I would like to be able to unsquash (like unzip) a .pnd file. Could someone write a script that does this, or must I mount the .pnd as a squashfs, make changes, then unmount it?

 

[sebt3]

unsquashfs is indeed not available, but you can use the pnd_run.sh script to mount the PND (or just mount it manually)


mksquashfs is available

 

[_wb_]

It's better not to put in libs that are already in the default OS, unless that version is too old for what you need. It's unlikely that firmware upgrades will break backwards compatibility (typically when a lib becomes backwards compatible it gets a new major version number and the old version is kept around for a while), but it is possible that they will include improved versions of the libs (e.g. notaz' SDL is still improving). By not putting those libs in your PNDs the PND will be smaller and it will benefit from future improvements to those libs.


Other than that: nice tutorial, mcobit!

 

[klapse]

Packaging up an app.

So in our case the command should be:

./pnd_make.sh -d abe –p abe.pnd –x PXML.xml –i icon.png -c

I needed to add the directory name in front of the xml and png,

e.g: -x abe/PXML.xml -i abe/icon.png

Again thanks for the howto mcobit!