35 replies to this topic

[mcobit]

Posted this also in the devsection of the other boards, but maybe someone here would find it useful too.

Disclaimer: This is the way I compile software on the Pandora. It may not be the best way, it might not be the simplest solutions, but if you have comments please just post them and I can correct or change parts of this tutorial. You follow this at your own risk. I am not responsible, if you destroy your OS or do anything else to your Pandora!

Porting a simple SDL game to Pandora
The noob way (yes, I am a noob too)

First off, I’d like to state, that I learned all I know about compiling, throwing some lines of code around and packaging, I learned since I have a Pandora.
It all came about, when I, fortunately one of the firsat german pandoraowner, wanted to do something useful for the community.
I worked with creaturexl together on an application for the Pandora and as he wouldn’t get his device anytime soon, he could try his app on my Pandora via ssh. He used screen to let me see, what he did. I learned a lot about symlinks and resolving dependencies.
Later I tried to do something on my own. I packaged up some java-apps with the help of the descriptions on the pandorawiki.
After that I packaged a pythonapp, that worked out of the box on Pandora.

When that was done I thought, that I could try to compile an SDL app. That was Abe’s Amazing Adventure. And this is the app, that this tutorial is about.

Also many thanks to all the people from this community. You really help where you can! Thanks Sebt3, CreatureXL, Paulguy, Skeezix, and everyone else I forgot right now. Thank you very much!

To get started you will need a dev environment. My choice was to use stuckies extends.
In the post he said, that they may be unstable and may cause some bad things, but for me so far it never happend a thing.

So go and download stuckies extend utils. For ease of use you can use the old ones. These are easier, as they only give the option to mount a root or a home extend:

http://www.stuckiegamez.co.uk/apps/pandora/SimpleDev/OldExtendUtils.pnd

Copy it to the pandora/menu folder on a SD card.

Also you need a dev extend. download the one from 18thJune, because as I remember there are some broken packages in the newer one.
Download it here:

http://www.stuckiegamez.co.uk/apps/pandora/SimpleDev/Dev.Extend.18thJune2010.zip

Unzip it to a sd-card. You will get a file named dev.extend.

You will need a home extend too, as the space on the nand is pretty limited:

http://www.stuckiegamez.co.uk/apps/pandora/SimpleDev/1GBExtend.zip

Unzip this one to a sd-card, too. You will get a file named 1gb.extend.

Now it’s time to mount our extends:
Open the menu and select “Extend Root” from the System menu.
You will be asked, which extend you want to mount. Choose the dev.extend file we unzipped earlier. You have to give your root password and then it will tell you, that it will spawn a terminal. When it does so, you can type “gcc” into the terminal window. If it says: “gcc: no input files” The mount was successful.

Now mount your homeextend. Choose “Extend Home” in the system menu and mount your 1gb.extend like you mounted the dev.extend.

FROM NOW ON DON'T REMOVE A SDCARD, THAT CONTAINS THE EXTENDS!!!
BAD THINGS MIGHT HAPPEN IF YOU DO! TO CLEANLY UNMOUNT THEM REBOOT THE PANDORA!

In the terminal, that will pop up at the end you can now cd into your homeextend directory:

cd /tmp/homeExtend

This will be your working directory.

Now the environment is set up. That was easy, wasn’t it?


Now get the source code for the game you want to port. In this example lets download the sources to Abe’s Amazing Advenure. Wget the sources into your /tmp/homeExtend directory with:

wget http://downloads.sourceforge.net/project/abe/abe/abe-1.1/abe-1.1.tar.gz

NOTE: Games, that require OpenGL will not work out of the box! They have to be rewritten or you have to use a wrapper that currently doesn't work on many games!

After the download is finnished, untar the file with

tar xvzf abe-1.1.tar.gz

Now cd into the new directory:

cd abe-1.1

Whe you type ls now you can see all the files, that belong to the game.
To build it we have to create a Makeile first. Fortunately ths is done by the configure script for us.
Run

./autogen.sh

and then

./configure --prefix=/mnt/utmp/abe

Now there will be a couple of checks, that the program does to find all the dependencies for the game and if they are already installed.
"--prefix=/mnt/utmp/abe" means, that the game will be installed into this directory, when it is built.
We have to choose a directory, that will be in /mnt/utmp, as the pnd will mount it there, when it is executed.

The script should finish without errors.
Now type

make

and wait until your game is built for you.

When this finished without errors, we can create the installation dir:

sudo mkdir /mnt/utmp/abe

sudo chmod -R 777 /mnt/utmp/abe

Now we install the game:

make install

As the datafiles are still missing, we need to copy the following directories to the installdirectory:

cp images maps sounds /mnt/utmp/abe

Now go to the directory and run your game:

cd /mnt/utmp/abe

./bin/abe

As you can see it already runs pretty well, but the buttons are not mapped to the pandorabuttons. So let’s go back and change that!

Do

cd /tmp/homeExtend/abe-1.1/src

this is the folder, that contains the sourcecode for the executable.

Here edit the files, that contain the keymappings. Let’s begin with the main game:

nano Game.c

(I use Nano, but you can of course use any texteditor you want)

In nano you can press ctrl+w and search for SDLK.
This will set your cursor to the first buttonmapping. Scroll down to find the Line with case SDLK_SPACE. This would trigger the guy to jump in the game.

Before we edit:
The Pandoracontrols are just like keys on a keyboard.
Here are the SDL-keymappings for the Buttons and D-Pad:

A = SDLK_HOME
B = SDLK_END
Y = SDLK_PAGEUP
X = SDLK_PAGEDOWN
L-Shoulder = SDLK_RSHIFT
R-Shoulder = SDLK_RCTRL
START = SDLK_LALT
SELECT = SDLK_LCTRL

D-PAD-Left = SDLK_LEFT
D-PAD-Right = SDLK_RIGHT
D-PAD-Up = SDLK_UP
D-PAD-Down = SDLK_DOWN

This is enough for us to work with.

Now substitute the SDLK_SPACE with SDLK_HOME to make the guy jump, when we press the actionbutton A.

Then there is the balloonfunction, that is currently mapped to SDLK_RETURN.
Change it to SDLK_PAGEUP, as you did for the jumpbutton.

Now press ctrl+x to quit the editor and type y when it asks you to save.

Now we can go through all the sourcefiles and edit the Keys to our liking:
Edit the SDLK_SPACE in Menu.c to SDLK_HOME.
And while we are at it: Search for “space to toggle” and change it into “A to toggle”
Also you can change “arrows to navigate” into “d-pad to navigate”
Do the same for the SDLK_SPACE in the Splash.c file.

Now everything is good for a second compile!
Go to /tmp/homeExtend and type make. The changes you did to the sourcecode will now be incorporated into the binary.
When this finished without errors, you should do make install again to copy the new binary into the installdirectory.
Should there be an error while compiling, maybe you messed up something in one of the sourcefiles. You can always start over by reextracting the tar.gz archive.

Go to /mnt/utmp/abe and type

./bin/abe

to test, if all controls are fine.

Congratulations! You ported a SDL game to the Pandora!

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!

Edited by mcobit, 25 January 2011 - 05:10 PM.

[MonkeyChops]

thanks for this, I've been wanting to try porting something for myself. Perhaps this will get me going.

[skeezix]

Maybe post a link to this in the wiki; or perhaps a mod may want to move this to a dev section?

Very good tutorial I think; no need to copy the pnd_make.sh into the working dir, could just refer to it fully by path, but such a minor thing

jeff

[Farox]

This is very good.
And as skeezix suggested this must be on the Wiki.

[EvilDragon]

Awesome
Will definately try to also use my Pandora to compile

[Esn]

This looks like a very good tutorial that even I might be able to follow. Maybe I'll try, one of these days.

I've put a link to it in the wiki.
http://pandorawiki.org/Tutorials_and_documentation#Topics_for_application_developers

[meandu229]

I tried to compile a game last night but it complained that sqlite3 was not there (on ./configure), so I installed via sudo opkg install --force-depends sqlite3 but still the same error even though sqlite3 installed.
Any ideas?

[mcobit]

You need to install the dev packages.
sudo opkg install sqlite3-dev

And don't use --force-depends else it will not install everything to work properly.

[meandu229]

You need to install the dev packages.
sudo opkg install sqlite3-dev

And don't use --force-depends else it will not install everything to work properly.

ohhh thanks will try it later,

[Gruso]

This is fantastic stuff mcobit.

[Chaser]

Really great guide and clearly written. I will definitely give this a go myself when I've time, even if its just to get an idea of how this all works. Many thanks

[Esn]

I tried this with Homebank and followed the instructions up until "./autogen.sh", at which point I got this:

[sebt3]

I tried this with Homebank and followed the instructions up until "./autogen.sh", at which point I got this:

The autogen.sh script is used to generate the "configure" one. If autogen.sh isnt there but the configure one is there, just go to next step

[Esn]

Thanks. I did that, and got this:


(it wants me to install intltool)

Edited by Esn, 29 January 2011 - 06:14 AM.

[mcobit]

Just do that.

sudo opkg update
sudo opkg install intltool

Remember: As long, as you have the dev.extend mounted, the packages you downloaded won't end up in the nand, but in the dev.extend file.

And do it for every other package it complains about. If you have to install libraries, install the *-dev packages.
You can search for available packages at http://www.angstrom-...ution.org/repo/

Good luck!

Edit: Should have covered downloading dependencies in the tutorial, but normaly sdl games doesn't need anything that is not in the dev.extend

Could be that you have to download some more packages to get a desktop application working, like the gtk+-dev package...

Sometimes while downloading it will complain about, that a package is already installed by another package.
First try to download it again, if that doesn't work you can sudo opkg remove packagethatisalreadyinstalled --nodeps
And try again to download the package you wanted to download in the first place.

Edited by mcobit, 29 January 2011 - 11:08 AM.