PND Cookbook - Revision history

Kingu: content moved to Introduction to PNDs

2013-10-29T00:21:48Z

content moved to Introduction to PNDs

T4b: Corrected tag

2011-04-23T17:13:25Z

Corrected <source> tag

ABC: formating

2011-04-23T06:18:27Z

formating

ABC: /* Checking a file's contents */ cat

2011-04-19T15:14:35Z

‎Checking a file's contents: cat

Vadsamoht at 05:00, 17 April 2011

2011-04-17T05:00:28Z

Maplesugarlover at 17:55, 19 February 2011

2011-02-19T17:55:59Z

Myownlittlworld: Undo revision 3874 by Valera (Talk) Revert vandalism by Valera.

2010-11-12T20:50:38Z

Undo revision 3874 by Valera (Talk) Revert vandalism by Valera.

Valera: /* Checking a file's contents */

2010-10-19T12:43:07Z

‎Checking a file's contents

DawnOfTheRent: /* Providing a default configuration */

2010-09-12T07:22:36Z

‎Providing a default configuration

DawnOfTheRent: /* Providing a default configuration */

2010-09-12T07:22:02Z

‎Providing a default configuration

← Older revision		Revision as of 00:21, 29 October 2013
Line 1:		Line 1:
−	~~=== Using a start-up script ===~~	+	#REDIRECT [[Introduction to PNDs]]
−	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:
−	~~<source lang="bash">~~
−	~~#!/bin/sh~~
−
−	~~# Do stuff here...~~
−
−	~~./my_app~~
−
−	~~# Clean-up~~
−	~~</source>~~
−	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.
−
−	~~=== Avoiding NAND writes by 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.
−	~~<source lang="bash">~~
−	~~export HOME=`pwd`~~
−	~~export HOME=$(pwd)~~
−	~~</source>~~
−
−	~~=== Providing a default configuration ===~~
−	If your application uses a configuration file, you'll usually want to include this in the PND. However, if you simply leave this file in the root of the PND, it will effectively be read-only, preventing the application or user from writing to it. A simple solution is to provide a default configuration file with a different name, and copy this the first time the application is run. The file will then be created under ''appdata'', and can therefore easily be edited.
−	~~<source lang="bash">~~
−	# ~~Method 1: check if file exists, otherwise copy default.~~
−	if [ ~~! -f app.conf ] ; then~~
−	~~cp default.conf app.conf~~
−	fi
−
−	~~# Method 2: Same as above, less typing.~~
−	[ ~~-f app.conf ] \|\| cp default.conf app.conf~~
−
−	~~# Method 3: using a non-destructive copy.~~
−	~~cp --no-clobber default.conf app.conf~~
−	~~</source>~~
−
−	~~==== Nub Configuration ====~~
−	~~This is a little (but not much!) lengthier - see the page on [[PND nub modes]].~~
−
−	~~=== Making writable directories ===~~
−	~~If your application requires that directories be writable for the application, don't put them in the PND, but create them at run-time:~~
−	~~<source lang="bash">~~
−	~~# Bad! This will cause an error after the first run, as the directory will already exist.~~
−	~~mkdir saved_data~~
−
−	~~# Better~~ to ~~use "-p" which won't complain about existing directories.~~
−	~~mkdir -p saved_data~~
−
−	~~# Added bonus: this allows you to create whole trees in one go.~~
−	~~mkdir -p saved_data/foo saved_data/bar/with/deep/sub/dirs~~
−	~~</source>~~
−
−	~~=== 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:
−	~~<source lang="bash">~~
−	~~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.~~
−	~~</source>~~
−
−	~~=== Getting a file/directory from the user ===~~
−	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.
−	~~<source lang="bash">~~
−	~~FILE="`zenity --file-selection --title='Select a File'`"~~
−	~~./my_app "$FILE"~~
−	~~</source>~~
−
−	~~=== Saving a file/directory name ===~~
−	If your application always asks for a file at start-up, it's handy to remember the location for next time. This can be done by writing the name of the directory to a file in appdata, and reading it back next time the application is run.
−	~~<source lang="bash">~~
−	~~SAVEDIR=./dir.saved # Name of the file we'll save the directory name to~~
−
−	~~# Did we save a directory last time? If so, read it into a variable.~~
−	~~DIR=`cat $SAVEDIR 2> /dev/null`~~
−
−	~~# Remember where we are right now, as we'll need to come back later.~~
−	~~PNDDIR=`pwd`~~
−
−	~~# Does the directory still exist?~~
−	~~if [ -d "$DIR" ] ; then~~
−	~~# Yes, go to that directory before Zenity is started.~~
−	~~cd "$DIR"~~
−	~~else~~
−	~~# No, try to go to /media (where the SD cards are mounted)~~
−	~~# or if that fails, go to "/" as a last resort.~~
−	~~cd /media 2> /dev/null \|\| cd /~~
−	fi
−
−	~~# Get a file name form the user. Our current directory is now that which~~
−	~~# was saved, so that's where Zenity will start.~~
−	~~FILE=`zenity --file-selection --title="Select a file"`~~
−
−	~~# If the file selector failed, or the user hit cancel, exit now.~~
−	~~[ $? -eq 0 ] \|\| exit 1;~~
−
−	~~# Go back to the PND's mount point.~~
−	~~cd $PNDDIR~~
−
−	~~# Save the file's directory for next time.~~
−	~~dirname "$FILE" > $SAVEDIR~~
−
−	~~# Run our app with the file as an argument.~~
−	~~./my_app "$FILE"~~
−	~~</source>~~
−
−	~~=== 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:
−	~~<source lang="bash">~~
−	~~$ md5sum bios.img~~
−	~~cfcfd01f1b0dfa97f07cb286b2942dc2 bios.img~~
−	~~</source>~~
−
−	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.
−
−	~~<source lang=bash>~~
−	~~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.~~
−	~~./my_emu "$BIOS"~~
−	~~</source>~~
−
−	~~[[Category:PND]]~~
−	~~[[Category:Development]]~~
−	~~[[Category:Tutorial~~]]

@@ Line 113: / Line 113: @@
 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.
-<source>
+<source lang=bash>
 BIOS=bios.img       # The name of our BIOS file

@@ Line 1: / Line 1: @@
 === 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:
+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:
-<pre>
+<source lang="bash">
 #!/bin/sh
@@ Line 9: / Line 9: @@
 # Clean-up
-</pre>
+</source>
 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.
 === Avoiding NAND writes by 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.
+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.
-<pre>
+<source lang="bash">
 export HOME=`pwd`
 export HOME=$(pwd)
-</pre>
+</source>
 === Providing a default configuration ===
 If your application uses a configuration file, you'll usually want to include this in the PND. However, if you simply leave this file in the root of the PND, it will effectively be read-only, preventing the application or user from writing to it. A simple solution is to provide a default configuration file with a different name, and copy this the first time the application is run. The file will then be created under ''appdata'', and can therefore easily be edited.
-<pre>
+<source lang="bash">
 # Method 1: check if file exists, otherwise copy default.
 if [ ! -f app.conf ] ; then
@@ Line 32: / Line 32: @@
 # Method 3: using a non-destructive copy.
 cp --no-clobber default.conf app.conf
-</pre>
+</source>
 ==== Nub Configuration ====
@@ Line 39: / Line 39: @@
 === Making writable directories ===
 If your application requires that directories be writable for the application, don't put them in the PND, but create them at run-time:
-<pre>
+<source lang="bash">
 # Bad! This will cause an error after the first run, as the directory will already exist.
 mkdir saved_data
@@ Line 48: / Line 48: @@
 # Added bonus: this allows you to create whole trees in one go.
 mkdir -p saved_data/foo saved_data/bar/with/deep/sub/dirs
-</pre>
+</source>
 === 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:
-<pre>
+<source lang="bash">
 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.
-</pre>
+</source>
 === Getting a file/directory from the user ===
 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.
-<pre>
+<source lang="bash">
 FILE="`zenity --file-selection --title='Select a File'`"
 ./my_app "$FILE"
-</pre>
+</source>
 === Saving a file/directory name ===
 If your application always asks for a file at start-up, it's handy to remember the location for next time. This can be done by writing the name of the directory to a file in appdata, and reading it back next time the application is run.
-<pre>
+<source lang="bash">
 SAVEDIR=./dir.saved    # Name of the file we'll save the directory name to
@@ Line 100: / Line 100: @@
 # Run our app with the file as an argument.
 ./my_app "$FILE"
-</pre>
+</source>
 === Checking a file's contents ===
@@ Line 106: / Line 106: @@
 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>
+<source lang="bash">
 $ md5sum bios.img
 cfcfd01f1b0dfa97f07cb286b2942dc2  bios.img
-</pre>
+</source>
 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>
+<source>
 BIOS=bios.img       # The name of our BIOS file
@@ Line 141: / Line 141: @@
 # Run our emulator with the BIOS file as an argument.
 ./my_emu "$BIOS"
-</pre>
+</source>
 [[Category:PND]]
 [[Category:Tutorial]]

@@ Line 142: / Line 142: @@
 ./my_emu "$BIOS"
 </pre>
 [[Category:PND]]
-[[Category:Documentation]]
+[[Category:Tutorial]]

@@ Line 33: / Line 33: @@
 cp --no-clobber default.conf app.conf
 </pre>
 === Making writable directories ===

← Older revision		Revision as of 17:55, 19 February 2011
Line 139:		Line 139:
	./my_emu "$BIOS"		./my_emu "$BIOS"
	</pre>		</pre>
		+	[[Category:PND]]
		+	[[Category:Documentation]]

@@ Line 20: / Line 20: @@
 === Providing a default configuration ===
-If your application uses a configuration file, you'll usually want to include this in the PND. However, if you simply leave this file int he root of the PND, it will effectively be read-only, preventing the application or user from writing to it. A simple solution is to provide a default configuration file with a different name, and copy this the first time the application is run. The file will then be created under ''appdata'', and can therefore easily be edited.
+If your application uses a configuration file,  you'll usually want to include this in the PND. However, if you simply leave this file int he root of the PND, it will effectively be read-only, preventing the application or user from writing to it. A simple solution is to provide a default configuration file with a different name, and copy this the first time the application is run. The file will then be created under ''appdata'', and can therefore easily be edited.
 <pre>
 # Method 1: check if file exists, otherwise copy default.