This is the original documentation: see HOWTO.txt for a brief new version

This README contains instructions how to get PhoneGap running on Maemo environment.

Restructured text (reST) format is used for rich-text formatting in this file.

<div class="contents topic" id="contents">
<h3>Contents</h3>

<ul> 
  <li><a href="#introduction" id="id1">Introduction</a></li>
  <li><a href="#html-documentation" id="id2">HTML documentation</a></li>
  <li><a href="#author" id="id3">Author</a><ul>
  <li><a href="#list-of-contributors" id="id4">List of contributors</a></li>
</ul>
</li>
  <li><a href="#features" id="id5">Features</a><ul>
  <li><a href="#phonegap-apis" id="id6">PhoneGap APIs</a></li>
</ul>
</li>
  <li><a href="#prerequisitements" id="id7">Prerequisitements</a></li>
  <li><a href="#build-instructions" id="id8">Build instructions</a></li>
  <li><a href="#run-instructions" id="id9">Run instructions</a></li>
  <li><a href="#updating-phonegap-javascript-application" id="id10">Updating PhoneGap Javascript application</a></li>
  <li><a href="#architecture" id="id11">Architecture</a></li>
  <li><a href="#building-arm-binaries-and-package" id="id12">Building ARM binaries and package</a></li>
  <li><a href="#testing-package" id="id13">Testing package</a></li>
  <li><a href="#building-x86-binaries-and-package" id="id14">Building X86 binaries and package</a></li>
  <li><a href="#distribute-and-install-on-the-device" id="id15">Distribute and install on the device</a></li>
  <li><a href="#building-your-own-application" id="id16">Building your own application</a></li>
  <li><a href="#resources" id="id17">Resources</a></li>
  <li><a href="#html-generation" id="id18">HTML generation</a></li>
  <li><a href="#known-issues" id="id19">Known-issues</a></li>
</ul>
</div>
<h4>Introduction</h4>

PhoneGap is a application development framework which enabled you to build cross-platform mobile applications using Javascript.

Maemo port is a project to bring Maemo (Nokia N900) platform support for PhoneGap.

This insructions cover building and running PhoneGap on Maemo (Fremantle) emulator only. The actual build and deployment for the target device is left as an excercise for the reader.

Maemo uses emulation and build environment called scrachbox. Pay careful attentation whether you should execute commands under your normal Linux user or inside scratchbox environment.

<h4>HTML documentation</h4>

HTML version of this document is available at <a href="http://blog.twinapex.fi/phonegap-on-maemo/">Twinapex blog</a>.

<h4>Author</h4>

PhoneGap Maemo port was initiated by <cite>Twinapex &lt;http://www.twinapex.com&gt;</cite> as proof-of-concept and for client demostrations.

The work (PhoneGap for Maemo) is licensed under MIT license. See LICENSE.txt for more information.

For community support use PhoneGap Google Group. For inquiries regarding development team and technology, contact <cite>Twinapex team &lt;mailto:info&#64;twinapex.com&gt;</cite>.

<h5>List of contributors</h5>

<ul>
  <li>Jussi Toivola (jtoivola)</li>
  <li>Mikko Ohtamaa (miohtama)</li>
</ul>
<h4>Features</h4>

The currently supported features of PhoneGap for Maemo

<ul>
  <li>Support N900 (Fremantle) target</li>
  <li>Build ARM and x86 binaries</li>
  <li>Run in emulator</li>
  <li>Run on the device</li>
  <li>Create distributable Debian files</li>
  <li>Documented developemnt process</li>
</ul>
<h5>PhoneGap APIs</h5>

<ul>
  <li>Device info</li>
  <li>Location</li>
</ul>
<h4>Prerequisitements</h4>

You need one of the following operating systems:

<ul>
  <li>Linux (Debian/Ubuntu flavour preferred)</li>
</ul>
Installation instructions how to come to the light side can be <a href="http://www.ubuntu.com/">found here</a>.

Setup scratchbox environment with

<ul>
  <li><a href="http://maemo.org/development/">Maemo 5</a></li>
  <li><a href="http://wiki.maemo.org/Qt4Hildon#Fremantle">QT libs installed</a></li>
</ul>
Also install following extra packages under scratchbox environment:

<pre>
fakeroot apt-get install libqt4-phonon libqt4-opengl libqt4-opengl-dev libqt4-sql-sqlite
</pre>

Install git:

<pre>
sudo apt-get install git-core
</pre>

Checkout phonegap, Maemo branch:

<pre>
cd /scratchbox/users/&lt;you&gt;/home/&lt;you&gt;/phonegap/maemo

git clone git://github.com/jtoivola/phonegap.git
</pre>

<h4>Build instructions</h4>

Assuming you have checked out the project to your Scratchbox home dir:

<pre>
/scratchbox/users/&lt;you&gt;/home/&lt;you&gt;/phonegap/maemo
</pre>

Scratchbox shell can be started:

<pre>
/scratchbox/login
</pre>

To build your <em>phonegap</em> application binary, run the following commands under scratchbox:

<pre>
qmake
make
</pre>

<h4>Run instructions</h4>

Setup Xephyr X server for the emulator before running. For installation instructions and details consult Maemo documentation.

Under non-scratchbox shell:

<pre>
Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -kb
</pre>

Set up X display under scratchbox shell:

<pre>
export DISPLAY=:2
</pre>

Start PhoneGap under scratchbox using Maemo emulator bootstrap script:

<pre>
run-standalone.sh ./phonegap
</pre>

You can stop application by sending CTRL+C keystroke to scratchbox shell.

<h4>Updating PhoneGap Javascript application</h4>

The project uses advanced software construction tool <a href="http://www.scons.org/">Scons</a> to manage PhoneGap application packaging. Scons is Python based framework to create complex build recipes.

Application packaging has the following features

<ul>
  <li>Compressing Javascript files</li>
  <li>Merging Javascript files</li>
</ul>
Please verify your Javascripts are syntatically correct before merging them. Use tool like <a href="http://www.jslint.com/">jslint</a>.

The phonegap javascript libraries are packaged with an SCons script. Install scons outside Scratchbox:

<pre>
sudo apt-get install scons
</pre>

Enter phonegap application directory in non-scratchbox shell (example user moo)

<pre>
cd /scratchbox/users/moo/home/moo/phonegap/maemo
</pre>

Run:

<pre>
scons
</pre>

This will create compressed app.js which contains all the application Javascript code packaged in one file.

Now deploy application to the run-time target path:

<pre>
cp app.js www
</pre>

<h4>Architecture</h4>

QWebView (WebKit) Qt widget is used as the primary web rendering interface. Note that this differs from Maemo Nokia Browser which is Gecko based. Other PhoneGap platfoms use WebKit also, so this should ensure maximum compatibility.

Maemo Qt libraries are rich in functionality, including QWebView, so direct Javascript-to-C++ API calls and other goodies are possible.

index.html is bootstrapped by main.cpp in QWebView.

<h4>Building ARM binaries and package</h4>

Additional resources

<ul>
  <li>help <a href="http://wiki.forum.nokia.com/index.php/Maemo_5_SDK_installation_for_beginners#Nokia_binaries_for_ARM_.28ARMEL.29">http://wiki.forum.nokia.com/index.php/Maemo_5_SDK_installation_for_beginners#Nokia_binaries_for_ARM_.28ARMEL.29</a></li>
  <li><a href="http://wiki.maemo.org/Packaging_a_Qt_application">http://wiki.maemo.org/Packaging_a_Qt_application</a></li>
  <li><a href="http://tldp.org/HOWTO/Debian-Binary-Package-Building-HOWTO/x60.html">http://tldp.org/HOWTO/Debian-Binary-Package-Building-HOWTO/x60.html</a></li>
</ul>
Brief instructions

<ul>
  <li>Download and install Nokia Maemo 5 SDK (<strong>not</strong> Maemo SDK+)</li>
  <li>Enable Nokia binaries and add Nokia binary blob deb line from <a href="http://tablets-dev.nokia.com/eula/index.php">here</a>:</li>
  <li>Enter Scratchbox (ARMEL):<pre>
/scratchbox/login
sb-conf se FREMANTLE_ARMEL
</pre>

</li>
  <li><strong>DO NOT RUN sb-menu setup target - this will screw your scratchbox installation</strong></li>
  <li>After you see FREMANTLE_ARMEL prompt install the build dependencies:<pre>
fakeroot apt-get install libqt4-phonon libqt4-opengl libqt4-opengl-dev libqt4-sql-sqlite gawk sharutils
</pre>

</li>
  <li>Compile binary:<pre>
qmake
make
</pre>

</li>
  <li>Run Debian packager:<pre>
make -f Distribution.mk
</pre>

</li>
  <li>Check package contents:<pre>
dpkg-deb -c distribution/phonegapdemo_1.0.0_i386.deb
</pre>

</li>
  <li>You can also put your emulator/device to Red Pill mode: <a href="http://wiki.maemo.org/Red_Pill_mode">http://wiki.maemo.org/Red_Pill_mode</a></li>
</ul>
<h4>Testing package</h4>

You can test your package installation right away.

<ul>
  <li>Install package inside ARMEL scratchbox:<pre>
dpkg -i distribution/phonegap_1.0.0.deb
</pre>

</li>
</ul>
<h4>Building X86 binaries and package</h4>

This is most suitable for testing on the simulator.

<ul>
  <li>Switch scratchbox to FREMANTLE_X86</li>
  <li>Clean up between architectures:<pre>
make clean
</pre>

</li>
  <li>Build again:<pre>
make
</pre>

</li>
  <li>Change ARCH from ARMEL to i386 in Distribution.mk</li>
  <li>Create .deb:<pre>
make -f Distribution.make
</pre>

</li>
  <li>Start Xephyr on host:<pre>
Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -kb
</pre>

</li>
  <li>Run Maemo simulation environment
export DISPLAY=:2 af-sb-init.sh start
</li>
  <li>Install .deb (simulation can run on the background):<pre>
dpkg -i distribution/phonegap_1.0.0.deb
</pre>

</li>
  <li>Run /usr/bin/phonegapdemo:<pre>
cd
phonegapdemo
</pre>

</li>
</ul>
<h4>Distribute and install on the device</h4>

<ul>
  <li>Copy .deb file available to any public network location.</li>
  <li>Download it using the web browser of the device</li>
  <li>Install gainroot from Application Manager on the device</li>
  <li>Start the terminal on the device</li>
  <li>Install dependencies (now manually):<pre>
sudo gainroot
apt-get install libqt4-webkit libqt4-phonon
apt-get install -f # (if needed)
</pre>

</li>
  <li>Then install downloaded file which is usually under the user documents:<pre>
cd MyDocs
cd .documents
dpkg -i phonegapdemo_1.0.0.deb
</pre>

</li>
  <li>Menu icon should appear</li>
  <li>Enjoy!</li>
</ul>
<h4>Building your own application</h4>

<ul>
  <li>Create a copy of Distribution.mk</li>
  <li>Edit headers as you see nessary for your application</li>
  <li>Create copy of phonegapdemo.desktop</li>
  <li>Edit main.cpp - change BINARY_NAME</li>
</ul>
<h4>Resources</h4>

<ul>
  <li>GitHub homepage: <a href="http://github.com/jtoivola/phonegap">http://github.com/jtoivola/phonegap</a></li>
  <li><a href="http://www.twinapex.com">Company homepage</a></li>
  <li><a href="http://blog.twinapex.fi">Twinapex company blog</a> - please follow to get the latest news regarding this project</li>
</ul>
<h4>HTML generation</h4>

This documentcan be converted to HTML using <a href="http://unmaintainable.wordpress.com/2008/03/22/using-rst-with-wordpress/">rst2wp by Matthias Friedrich</a>.

To convert this file to content HTML, these instructions can be run under non-scratchbox:

<pre>
wget http://users.musicbrainz.org/~matt/scripts/rst2wp
sudo apt-get install python-docutils
python rst2wp README.txt &gt; README.html ; gedit README.html &amp;
</pre>

You can copy-paste the resulting HTML code to your favorite HTML WYSIWYG editor.

<h4>Known-issues</h4>

<ul>
  <li>It is not done yet</li>
</ul>