Difference between revisions of "PND Cookbook"

From Pandora Wiki
Jump to: navigation, search
(Initial version)
 
(Added file content checking using MD5)
Line 31: Line 31:
 
FILE="`zenity --file-selection --title='Select a File'`"
 
FILE="`zenity --file-selection --title='Select a File'`"
 
./my_app $FILE
 
./my_app $FILE
 +
</pre>
 +
 +
=== Checking a file's contents ===
 +
Maybe your application requires some file which cannot be distributed with the PND, either for legal reasons or due to size limitations. A prime example of this is BIOS files used for emulators. Simply copying the file to the current directory will be enough to save it to your program's appdata, but it can also be useful to check the contents of the file are indeed what your application expects.
 +
 +
One way of doing this is to check the file's contents using a hash. A hash is a mathematical formula which can be used to create a "fingerprint" of a file. Two identical files will always generate the same hash value, so knowing this one value is enough to check if two files match. The MD5 hash is a popular choice, and can be easily generated for a given file like so:
 +
<pre>
 +
$ md5sum bios.img
 +
cfcfd01f1b0dfa97f07cb286b2942dc2  bios.img
 +
</pre>
 +
 +
Save this output to a text file named ''bios.md5'' and put it in your PND root directory. The following commands can then be used in your start-up script to copy a file specified by the user, and check it's hash.
 +
 +
<pre>
 +
BIOS=bios.img      # The name of our BIOS file
 +
 +
# Check if the BIOS file already exists.
 +
if [ ! -f ./$BIOS ] ; then
 +
    # Not found, so get a file name from the user.
 +
    cp "`zenity --file-selection --title="Select your $BIOS file"`" $BIOS
 +
    if [ $? != 0 ] ; then
 +
        # User hit cancel, bail out.
 +
        zenity --error --text="Sorry, emulator cannot run without a BIOS file."
 +
        exit 1
 +
    fi
 +
 +
    # Check the MD5 hash of the given file against our known-good value.
 +
    # If the match fails, ask the user if they'd like to try it anyway.
 +
    md5sum -c bios.md5 || zenity --question \
 +
        --text="BIOS does not appear to be the correct version. Use it anyway?"
 +
 +
    if [ $? != 0 ] ; then
 +
        # File did not match hash, and the user opted not to try it anyway,
 +
        # so remove the copied file and bail out.
 +
        rm -f $BIOS
 +
        exit 1
 +
    fi
 +
fi
 +
 +
# Run our emulator with the BIOS file as an argument.
 +
./myemu $BIOS
 
</pre>
 
</pre>

Revision as of 15:15, 26 August 2010

Using a start-up script

In an ideal world, your application will be completely self-contained and can be run directly without any kind of set-up. It is however often necessary to tweak settings or request input from the user before starting your application. This is easily achieved by having the PND specify a shell script as its executable, which then in turn runs the application. The general structure of such a script is:

#!/bin/sh

# Do stuff here...

./my_app

# Clean-up

The first line identifies the file as a shell script, run using "/bin/sh" as the shell. The other lines beginning with a "#" are comments. Before the application is started, parameters can be gathered and/or set. The application itself then gets run by the "./my_app" line, which means "execute the file my_app in the current directory". When the application exits, it may be necessary to restore previous settings, delete temporary files, or perform some other kinds of cleaning up.

Setting $HOME

Many applications write configuration data to the user's home directory by default. This is not desirable on the Pandora as this directory resides on the NAND filesystem. It is however often possible to fool an application into writing to a different directory by setting the $HOME environment variable.

export HOME=`pwd`
export HOME=$(pwd)

Loading shared libraries

If your application requires shared libraries which aren't part of the standard firmware, they can be included in the PND along with the executable. In order for the system to be able to find the libraries, it must be told which directories to search. This can be done by setting the LD_LIBRARY_PATH environment variable. For example:

export LD_LIBRARY_PATH=`pwd`       # Load libraries in the root directory of the PND.
export LD_LIBRARY_PATH=`pwd`/libs  # Load libraries in the "libs" subdirectory of the PND.

Getting a file/directory

Its often necessary to ask the user for the location of a file or directory. This may be because your application requires files which aren't included in the PND itself, or simply because you application doesn't have a built in file picker. The commands below will prompt the user for a file, then run "my_app" with that file as an argument. Note the use of different sorts of quotes which is important for proper operation and handling spaces in file names.

FILE="`zenity --file-selection --title='Select a File'`"
./my_app $FILE

Checking a file's contents

Maybe your application requires some file which cannot be distributed with the PND, either for legal reasons or due to size limitations. A prime example of this is BIOS files used for emulators. Simply copying the file to the current directory will be enough to save it to your program's appdata, but it can also be useful to check the contents of the file are indeed what your application expects.

One way of doing this is to check the file's contents using a hash. A hash is a mathematical formula which can be used to create a "fingerprint" of a file. Two identical files will always generate the same hash value, so knowing this one value is enough to check if two files match. The MD5 hash is a popular choice, and can be easily generated for a given file like so:

$ md5sum bios.img
cfcfd01f1b0dfa97f07cb286b2942dc2  bios.img

Save this output to a text file named bios.md5 and put it in your PND root directory. The following commands can then be used in your start-up script to copy a file specified by the user, and check it's hash.

BIOS=bios.img       # The name of our BIOS file

# Check if the BIOS file already exists.
if [ ! -f ./$BIOS ] ; then
    # Not found, so get a file name from the user.
    cp "`zenity --file-selection --title="Select your $BIOS file"`" $BIOS
    if [ $? != 0 ] ; then
        # User hit cancel, bail out.
        zenity --error --text="Sorry, emulator cannot run without a BIOS file."
        exit 1
    fi

    # Check the MD5 hash of the given file against our known-good value.
    # If the match fails, ask the user if they'd like to try it anyway.
    md5sum -c bios.md5 || zenity --question \
        --text="BIOS does not appear to be the correct version. Use it anyway?"

    if [ $? != 0 ] ; then
        # File did not match hash, and the user opted not to try it anyway,
        # so remove the copied file and bail out.
        rm -f $BIOS
        exit 1
    fi
fi

# Run our emulator with the BIOS file as an argument.
./myemu $BIOS