Maemo Wiki Mirror - User contributions [en]

PyMaemo/Scratchboxless packaging guide

2011-03-02T13:46:23Z

189.2.128.130: Fix some typos

== Introduction ==

The usual way of developing Maemo applications is using either Scratchbox or [[MADDE]], which are quite heavy for Python development. An alternative is using [http://github.com/astraw/stdeb stdeb], a set of extensions to distutils that allows generating Debian packages, both binary and source, that can be installed on the device or sent to the [[extras-devel]] repository.

This tutorial will show how to integrate it into your project, build the packages and upload them to extras-devel.

== Prerequisites ==

This tutorial is aimed at Debian-based systems, as some stdeb commands requires the dpkg tools installed. If you're using another distro, please refer to the section

Also, you should get the [http://github.com/astraw/stdeb git] version of stdeb to use the debianize command, as it is a new addition and not yet available in the repositories. Run the following commands to install it:

# Clone the git repository
git clone http://github.com/astraw/stdeb.git

# Enter source package
cd stdeb

# Build .deb (making use of stdeb package directory in sys.path).
python setup.py --command-packages=stdeb.command bdist_deb

# Install it
sudo dpkg -i deb_dist/python-stdeb_0.5.1+git-1_all.deb

As only python2.5 is supported in pymaemo, it should be installed if you want to create binary packages. On Ubuntu Lucid (10.04), you can install it from [https://launchpad.net/~fkrull/+archive/deadsnakes this ppa], following the instructions [http://www.codigomanso.com/en/2010/05/google-app-engine-en--10-4-lucid-lynx/ here].

== Preparing the package ==

As stdeb extends distutils, it is necessary that you have a working setup.py script. For our example application, which consists of a [http://pymaemo.garage.maemo.org/stdeb_example/myscript-app/myscript single script] named "myscript" and support files like [http://pymaemo.garage.maemo.org/stdeb_example/myscript-app/myscript.desktop .desktop]<ref name="desktop">[[Desktop file format]]</ref> and an [http://pymaemo.garage.maemo.org/stdeb_example/myscript-app/myscript.png icon]<ref name="icon">[[Packaging#Displaying an icon in the Application Manager next to your package]]</ref>, the [http://pymaemo.garage.maemo.org/stdeb_example/myscript-app/setup.py setup.py] will look like this:
<source lang="python">
from distutils.core import setup

setup(
name='myscript',
version='0.1',
author='Lauro Moura',
author_email='lauro.neto@donotspamme.com',
scripts=['myscript'],
data_files=[('share/applications/hildon', ['myscript.desktop']),
('share/pixmaps', ['myscript.png'])],
)
</source>
A file named [http://pymaemo.garage.maemo.org/stdeb_example/myscript-app/stdeb.cfg stdeb.cfg] in the same directory as setup.py is required, with stdeb Maemo-specific options. A detailed list of options can be found in the [http://github.com/astraw/stdeb stdeb website].

[DEFAULT]
XS-Python-Version: 2.5 # Only version currently supported by PyMaemo.
Package:my-script # Binary package name. stdeb adds the prefix "python-" by default
Section: user/development # Section should start with user/ to appear in the menu.
Depends: python-gtk2 # extra dependencies go here

Warning 1: Make sure to use [[Maemo_packaging#Sections|an allowed section]].

Warning 2: The <code>Depends</code> field in stdeb.cfg will be used on your debian/control file, so fill it correctly with all the dependencies of your application - otherwise it will break when you try to install it. For instance, [http://gitorious.org/twcano/twcano twcano] depends on the following packages: <code>python-simplejson, pyside-qt4-maemo5, pyside-qt4-webkit and python-twitter</code>, so the <code>Depends</code> field should be filled this way:

Depends: python-simplejson, pyside-qt4-maemo5, pyside-qt4-webkit, python-twitter

== Building the packages ==

The basic command is

python setup.py --command-packages=stdeb.command bdist_deb

It'll create a folder called deb_dist with the source and binary packages. Alternatively, the "sdist_dsc" command will create only the source package.

After generating, you can copy the package to your device and install it (requires an [[SSH]] server):

$ scp myscript_0.1-1_all.deb root@<n900 ip>:/root
$ ssh root@<n900 ip>
# dpkg -i myscript_0.1-1_all.deb

== Building a basic debian directory ==

Another useful command is ''debianize''. It will read the configuration file and write a directory named debian in the same directory. This can be used for manually creating the packages using dpkg tools directly. For a detailed usage example see the [http://github.com/astraw/stdeb#debianize-distutils-command stdeb website].

Note: sdist_dsc and bdist_deb do '''not''' use this directory, generating a new one in the source dir under deb_dist/.

== Uploading to extras ==

To upload to extras, use the debianize command and then call dpkg-buildpackage:

$ dpkg-buildpackage -rfakeroot -uc -us -S

This command will create the .dsc, .tar.gz and .changes files that can be used to [[uploading to Extras-devel|upload the application to extras-devel]].

== Support for non-Debian systems ==

{{ambox
| type = notice
| image=
| text = Keep in mind that the support for non-Debian systems is '''experimental''': it is not as funcional as the stdeb approach shown above and may not work for your package. Also, these instructions may change without notice. }}

If you're using a distro not based on Debian, you can still create source packages for uploading to extras-devel, but won't be able to create binary packages (.deb).

For doing this, you will need the sdist_deb module available [http://gitorious.org/pymaemo/sboxless here]; just clone it in some directory and point the PYTHONPATH environment variable there.

Now create a file called sboxless.cfg, which will contain additional information for generating the package. For now, you can add additional runtime dependencies for your package. If you want to add python-twitter as dependency, just write

[control]
depends=python-twitter

The file is mandatory, so if you don't want to add any dependency, just leave the field empty ('depends=').

Now, run the sdist_deb command:

PYTHONPATH=/path/to/sboxless python setup.py --command-packages=sboxless sdist_deb

The source files will be generated on the ./dist directory.

== References ==

<references />

[[Category:Python]]
[[Category:Packaging]]

PyMaemo/Quick start guide

2010-02-19T18:57:20Z

189.2.128.130: Undo revision 29864 by 189.2.128.130 (Talk)

= Getting Started: Setting Up Python Development Environment for N900 =

A basic development environment for Python development for Maemo consists of:

* A source code editor
* Some way to transfer application files to the tablet
* Easily run the application (without installing it)

Alternatively, you can try other more complex development environments, briefly described at the end of this article.

This article will cover:

* Installation of necessary packages and USB connectivity setup
* Some suggestions for Python code editors
* How to transfer the application files to the N900
* How to run the application

Application packaging and final deployment will be discussed separately at a later date.

Finally, there is a [http://www.youtube.com/watch?v=onAkb_7U5pk screencast] demonstrating the instructions from this guide, which should help clarifying some of the steps in a real setup session.

== Requirements ==

Before continuing, make sure you have:

Tablet requirements:

* Some kind of connectivity to the tablet (e.g. WLAN or GPRS), so that you can install required packages.
* The N900 USB cable, which will be used to transfer files to the tablet.

Host requirements:

* A SSH client. For Linux, OpenSSH (through the "ssh" command) is enough. For Windows, [http://en.sourceforge.jp/projects/ttssh2/releases/ Tera Term] can be used. For Mac you can use "ssh" command in the Terminal.
* A SCP/SFTP client. For Linux, OpenSSH (through the "scp" command) is enough. The KDE/GNOME environments also have built-in support for these protocols. For Windows, you can try [http://winscp.net/eng/index.php WinSCP] or [http://filezilla-project.org/ FileZilla].

For the purposes of this tutorial, you will '''not''' need Scratchbox installed. Scratchbox would only be necessary if you are unable to test your applications on the actual tablet.

== Installing required packages on N900 ==

You will need to install two applications on the tablet:

* OpenSSH Server
* rootsh

OpenSSH is needed to run commands remotely on your N900. This will make testing on the device a lot easier.

rootsh is needed to allow to run commands as root on the X Terminal (using "sudo gainroot"). See http://wiki.maemo.org/Root_access for other options to enable root access.

To install these applications, follow these steps:

# Enable extras repository. See http://wiki.maemo.org/Extras#Using_Extras for how to do it.
# Install the packages listed above.
# The installation will ask for a new root password for SSH access. Choose a good one.
# Wait for installation to complete.

== Enabling USB networking ==

USB networking allows to easily and quickly transfer files to the device and connect to it using SSH. To enable it, follow these steps (you need to repeat them every time you reboot the device):

# If the USB cable is plugged and in "Mass storage mode", unplug the cable and plug it again, now selecting "PC Suite Mode".
# On N900, open "X Terminal" and run:
rootsh ifup usb0
# Now you need to configure the host. This is dependent on which OS (or Linux distro) you use, see http://wiki.maemo.org/USB_networking#Host_USB_Network_Configuration for detailed instructions for various OSes and Linux distros.

From now on you can connect to the N900 using any SSH client and the following information:
Host: 192.168.2.15
Port: 22
User: root
Password: the password setup earlier

For instance, from a Linux terminal, you can connect to the tablet using this command:

ssh root@192.168.2.15

== Preparing the N900 for Python Development ==

To enable the full power for Python development for Maemo, you must enable the "extras-devel" repository on your device. ''Be advised that this might be a risky operation'' because extras-devel contains many untested and possibly broken packages. But it also contains the latest versions of all available Python bindings for Maemo, which we are interested on.

Note that the requirement to enable the "extras-devel" repository might be removed later.

To enable extras-devel add a new catalogue to the Application Manager, as instructed in [[Extras-devel]] (did you see the big warning on that page?)

After extras-devel is enabled, you will see on Application Manager a package called "maemo-python-device-env". Installing it will also install the basic environment necessary to run most Python applications on Maemo.

== Writing your code ==

Any good programmer oriented editor will be enough for development. If you have some development experience, you most probably already have chosen your favorite code editor and you can simply use it.

Here we list some options, both for Linux and Windows:

* [http://projects.gnome.org/gedit/ gedit]: the GNOME Editor has syntax highlight support for Python (Linux only)
* [http://www.vim.org/ VIM] and [http://www.gnu.org/software/emacs/ Emacs]: the most popular editors, with many advanced features and versions for both Linux and Windows
* [http://wiki.netbeans.org/Python NetBeans + Python plugin]: NetBeans is a multi-platform IDE, which with help of a plugin, supports development for Python
* [http://maemo.org/downloads/product/Maemo5/pygtkeditor/ PyGTKEditor]: a syntax highlighting Python editor which runs natively on Maemo devices

Note that none of these editors will support code completion for PyMaemo modules out of box.

For testing purposes, you can try the following code (the classic "hello world" example):

import gtk
from gtk import Window, Button, Widget
if __name__ == "__main__":
window = Window(gtk.WINDOW_TOPLEVEL)
window.connect("destroy", gtk.main_quit)
button = Button("Hello World")
button.connect_object("clicked", Widget.destroy, window)
window.add(button)
window.show_all()
gtk.main()

Once you have your code written, you can proceed to copying application files to the device.

== Running the Python application on the device ==

Now that you have the N900 properly setup and the code to run, you just need to copy the application files to the device and run it.

The simplest way to copy files it to use a SFTP or SCP client. There are many free clients available for most OSes (we listed some examples on the "Requirements" section). On the Linux command line, you can use:

scp -pr my_application/ root@192.168.2.15:/root/my_application/

Replace "my_application/" with the path to the directory which contains your application files.

Finally, to run the application on the tablet, use (from a SSH terminal):

cd /root/my_application
python my_application.py

== Alternative development environments ==

Besides the environment described on this article, there are two alternative development environments that might or might not be more appropriate for your purposes:

; PluThon (Eclipse based)
: [http://pluthon.garage.maemo.org/ PluThon] is a full Python IDE for Maemo, based on Eclipse. While PluThon is easy to use and provides a complete solution, it is not necessary for basic Python development for Maemo. If you already use Eclipse for your development, PluThon might be your best option.
; Official Maemo SDK (Scratchbox based)
: [http://www.scratchbox.org/ Scratchbox] is a cross-compilation toolkit used for native Maemo development. Although it can be used in Python development as well (and comes very handy if you do not have access to a real device), it has a non-trivial learning curve and is not needed for pure Python development. However, if you plan to write new Python extensions (for instance, using [http://www.cython.org/ Cython] or [http://docs.python.org/c-api/index.html Python/C API] directly), Scratchbox is needed to cross-compile the C code. See the [http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Development_Environment/Maemo_SDK Maemo SDK section] on Maemo 5 developer guide for more details on it.

Note that PluThon has built-in support for transferring and running code on the device. On the other hand, the Maemo SDK has no such support (unless you use some IDE like [http://esbox.garage.maemo.org/ ESbox]), so you need to follow steps similar to the ones described on this guide to copy and run your code on the tablet, if you choose to use the Maemo SDK.

== Advanced tips ==

If you want to activate USB networking automatically upon connecting the device to the computer, just create a file called /etc/event.d/usbnet on the device with the following contents:

start on G_NOKIA_READY

console output
exec ifconfig usb0 192.168.2.15 up

This way you just have to select "PC Suite mode" when plugging the device in.

[[Category:N900]]
[[Category:Python]]

PyMaemo/Quick start guide

2010-02-19T18:32:12Z

189.2.128.130: /* Advanced tips */

PyMaemo/How to build

2010-01-18T18:36:34Z

189.2.128.130: /* Modifying PyMaemo packages */

DRAFT

= How to build PyMaemo packages=

== Introduction ==

To build PyMaemo packages from the source, you'll need:

* Maemo 5 SDK
* Rootstraps for X86 and ARMEL targets
* grep-dctrl
* pymaemo-tools

The scripts from pymaemo-tools are used to download packages' sources and build them using sbdmock, one at a time. sbdmock, in turn, uses the SDK and the rootstraps to create a clean environment for building every package. More information about sbdmock can be obtained [[Building_packages_with_sbdmock|here]], although pymaemo-tools uses a slightly modified of sbdmock - see pymaemo-tools README if you want to know which modifications were made.

The build scripts from pymaemo-tools can be used to build the entire set of packages or only some of them, for X86 or ARMEL targets. It is advised to first build and (if possible) test in the X86 target and use ARMEL target only for cross-compiling for the device.

== Overview of the build process ==

The build process is composed of three phases: download, preparation and the proper build. A high-level description of the process follows:

* Download phase:
** If the package is originally from Debian or Ubuntu:
*** The original source is taken from upstream;
*** The Debian packaging for Maemo is taken from the respective repository in PyMaemo project.
** If the package is Maemo-specific:
*** The source package is taken from the respective repository in PyMaemo project
* Preparation phase:
** If the package is taken from upstream, assemble package
** Verify if dependencies are satisfied
* Build phase:
** Call sbdmock with proper parameters

== Configuration ==

The base directory for these instructions, refered as $BASE, is /scratchbox/users/<user>/home/<user>/pymaemo,
where <user> is your username in Scratchbox. All operations are made '''outside''' Scratchbox.

First, download the rootstraps for X86 and ARMEL targets and put them in $BASE/rootstraps:

* http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz
* http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz

Clone the pymaemo-tools project inside $BASE:

$ git clone [git repo]

This will create the directory pymaemo-tools under $BASE.

Edit the fremantle_i386.cfg and fremantle_armel.cfg under $BASE/pymaemo-tools/sbdmock,
putting the rootstrap path correspondent to each in the following key:
* i386: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_i386.tgz"
* armel: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_armel.tgz"

== Building ==

For building all the packages for the X86 target, enter $BASE/pymaemo-tools and run:

$ ./build_packages.sh sbdmock:fremantle_i386 packages_fremantle.ini

The same can be done to ARMEL target, just replacing "i386" with "armel". The file packages_fremantle.ini contains all data necessary for obtaining the sources.

You can build individual packages too, specifying them as parameters. If you want to build only, let's say, pyopenssl and pycurl for the ARMEL target, run:

$ ./build_packages.sh sbdmock:fremantle_armel packages_fremantle.ini pyopenssl,pycurl

Be advised that any PyMaemo dependency for these packages must be built first, as build_packages.sh will attempt to build only the packages provided at the command line.

There are other options for the build; for more information, run build_packages.sh
with no parameters or refer to the README file inside pymaemo-tools.

When the build finishes the resultant Debian packages will be placed at
$BASE/pymaemo-tools/workdir/fremantle_<target>/repo, where <target> is i386 or armel,and the build logs placed in $BASE/pymaemo-tools/workdir/fremantle_<target>/logs.
From that point on, they can be installed on the targets and the ARMEL ones
can be copied to the device to be installed there.

=== Directories created ===

* $BASE/pymaemo-tools/download_cache: all downloaded files are placed here, one directory by package, so you don't have to download everything again in every build. If the sources are updated, though, you will have to erase the corresponding entries on download_cache for allow them to be downloaded again.
* $BASE/pymaemo-tools/workdir: the generated files (prepared sources, logs, built packages) are placed under this directory, grouped by the name of the sbdmock config file used to build them. Inside each group, the logs and repo directories will contain, respectively, the build logs and the built packages.

== Customization ==

If you want to roll out your own packages or modify the existing ones, the sections below will provide some directions.

=== Adding your own packages to the build ===

If you want to add your own package to the build process, you just have to edit one simple file, packages-fremantle.ini. Just add an entry at the end of the file depending on how your package is organized.

* If all the contents of your package are contained in a single SVN or GIT repository, you have a "native" package. If you're using SVN, the lines below are enough:

[new-package]
svn_url=https://svnrepository.com/new-package/trunk
native=yes

If you're using git, just change "svn_url" to "git_url" and use the appropriate repository address (git://...). Note also that the flag "native=yes" must be present. Just change "new-package" to a string identifying your package and you're set.

* If your package has Debian or Ubuntu as upstream and only the packaging is specific for Maemo, you'll have to specify the location of all the files needed in addition to the repository where the packaging is located. See below an example for pyclutter:

[pyclutter]
source_url=http://ftp.de.debian.org/debian/pool/main/p/pyclutter/pyclutter_0.8.0.orig.tar.gz
diff_url=http://ftp.de.debian.org/debian/pool/main/p/pyclutter/pyclutter_0.8.0-1.diff.gz
dsc_url=http://ftp.de.debian.org/debian/pool/main/p/pyclutter/pyclutter_0.8.0-1.dsc
svn_url=https://garage.maemo.org/svn/pymaemo/packages/pyclutter/trunk/debian

In this example the source, .diff.gz and .dsc files are taken from Debian, and the Maemo-specific packaging is taken from the (former) PyMaemo repository. pymaemo-tools will assemble the package prior to build, as explained in the Overview section.

=== Modifying PyMaemo packages ===

The PyMaemo packages are in Gitorious now, allowing the submission of modifications for any of them via merge requests. An overview of the entire process is listed below:

# Create a clone of the repository at Gitorious for the package you want to modify, and git-clone it;
# Modify the packages-fremantle.ini entry of the package to point to the full path of the repository directory;
# Erase your package files from $BASE/download_cache, $BASE/workdir and $BASE/workdir/fremantle_<target>/repo before the build;
# Modify the package and run build_packages.sh to build it;
# Install on Scratchbox and on the device, if possible, and run all available unit tests for the package - needless to say, your modifications should not introduce regressions of any type;
# Add unit tests to assert the funcionality of the new features added, whenever possible;
# When you are satisfied with the results, push your local changes to your Gitorious clone and file a merge request.

As said before, there are two types of packages: native and taken from upstream. If you want to modify a native package, you can do anything you want, as the entire package is contained in the repository. However, if the package is taken from upstream, the only changes you can make will be located in the packaging - you'll have to use patches to actually modify any upstream file in build time.

== Tips ==

=== Create Debian repository with one line ===

If you want to quickly make a Debian repository for easy installation,
run the following command at $BASE/pymaemo-tools/workdir/fremantle_<target>/repo:

$ apt-ftparchive packages . | gzip -9c > Packages.gz

Now you have to expose the packages' path to the Web server and add the repository
in the target machine accordingly.

=== Tracking build in real time ===

If you want to accompany the build log of any package in real time, you can just use the tail command in the following log files:

* Prep and setup:
$ tail -F $BASE/workdir/fremantle_<target>/repo/root.log
* Build:
$ tail -F $BASE/workdir/fremantle_<target>/repo/build.log

PyMaemo/How to build

2010-01-18T16:05:26Z

189.2.128.130: /* Adding your own packages to the build */

DRAFT

= How to build PyMaemo packages=

== Introduction ==

To build PyMaemo packages from the source, you'll need:

* Maemo 5 SDK
* Rootstraps for X86 and ARMEL targets
* grep-dctrl
* pymaemo-tools

The scripts from pymaemo-tools are used to download packages' sources and build them using sbdmock, one at a time. sbdmock, in turn, uses the SDK and the rootstraps to create a clean environment for building every package. More information about sbdmock can be obtained [[Building_packages_with_sbdmock|here]], although pymaemo-tools uses a slightly modified of sbdmock - see pymaemo-tools README if you want to know which modifications were made.

The build scripts from pymaemo-tools can be used to build the entire set of packages or only some of them, for X86 or ARMEL targets. It is advised to first build and (if possible) test in the X86 target and use ARMEL target only for cross-compiling for the device.

== Overview of the build process ==

The build process is composed of three phases: download, preparation and the proper build. A high-level description of the process follows:

* Download phase:
** If the package is originally from Debian or Ubuntu:
*** The original source is taken from upstream;
*** The Debian packaging for Maemo is taken from the respective repository in PyMaemo project.
** If the package is Maemo-specific:
*** The source package is taken from the respective repository in PyMaemo project
* Preparation phase:
** If the package is taken from upstream, assemble package
** Verify if dependencies are satisfied
* Build phase:
** Call sbdmock with proper parameters

== Configuration ==

The base directory for these instructions, refered as $BASE, is /scratchbox/users/<user>/home/<user>/pymaemo,
where <user> is your username in Scratchbox. All operations are made '''outside''' Scratchbox.

First, download the rootstraps for X86 and ARMEL targets and put them in $BASE/rootstraps:

* http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz
* http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz

Clone the pymaemo-tools project inside $BASE:

$ git clone [git repo]

This will create the directory pymaemo-tools under $BASE.

Edit the fremantle_i386.cfg and fremantle_armel.cfg under $BASE/pymaemo-tools/sbdmock,
putting the rootstrap path correspondent to each in the following key:
* i386: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_i386.tgz"
* armel: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_armel.tgz"

== Building ==

For building all the packages for the X86 target, enter $BASE/pymaemo-tools and run:

$ ./build_packages.sh sbdmock:fremantle_i386 packages_fremantle.ini

The same can be done to ARMEL target, just replacing "i386" with "armel". The file packages_fremantle.ini contains all data necessary for obtaining the sources.

You can build individual packages too, specifying them as parameters. If you want to build only, let's say, pyopenssl and pycurl for the ARMEL target, run:

$ ./build_packages.sh sbdmock:fremantle_armel packages_fremantle.ini pyopenssl,pycurl

Be advised that any PyMaemo dependency for these packages must be built first, as build_packages.sh will attempt to build only the packages provided at the command line.

There are other options for the build; for more information, run build_packages.sh
with no parameters or refer to the README file inside pymaemo-tools.

When the build finishes the resultant Debian packages will be placed at
$BASE/pymaemo-tools/workdir/fremantle_<target>/repo, where <target> is i386 or armel,and the build logs placed in $BASE/pymaemo-tools/workdir/fremantle_<target>/logs.
From that point on, they can be installed on the targets and the ARMEL ones
can be copied to the device to be installed there.

=== Directories created ===

* $BASE/pymaemo-tools/download_cache: all downloaded files are placed here, one directory by package, so you don't have to download everything again in every build. If the sources are updated, though, you will have to erase the corresponding entries on download_cache for allow them to be downloaded again.
* $BASE/pymaemo-tools/workdir: the generated files (prepared sources, logs, built packages) are placed under this directory, grouped by the name of the sbdmock config file used to build them. Inside each group, the logs and repo directories will contain, respectively, the build logs and the built packages.

== Customization ==

If you want to roll out your own packages or modify the existing ones, the sections below will provide some directions.

=== Adding your own packages to the build ===

If you want to add your own package to the build process, you just have to edit one simple file, packages-fremantle.ini. Just add an entry at the end of the file depending on how your package is organized.

* If all the contents of your package are contained in a single SVN or GIT repository, you have a "native" package. If you're using SVN, the lines below are enough:

[new-package]
svn_url=https://svnrepository.com/new-package/trunk
native=yes

If you're using git, just change "svn_url" to "git_url" and use the appropriate repository address (git://...). Note also that the flag "native=yes" must be present. Just change "new-package" to a string identifying your package and you're set.

* If your package has Debian or Ubuntu as upstream and only the packaging is specific for Maemo, you'll have to specify the location of all the files needed in addition to the repository where the packaging is located. See below an example for pyclutter:

[pyclutter]
source_url=http://ftp.de.debian.org/debian/pool/main/p/pyclutter/pyclutter_0.8.0.orig.tar.gz
diff_url=http://ftp.de.debian.org/debian/pool/main/p/pyclutter/pyclutter_0.8.0-1.diff.gz
dsc_url=http://ftp.de.debian.org/debian/pool/main/p/pyclutter/pyclutter_0.8.0-1.dsc
svn_url=https://garage.maemo.org/svn/pymaemo/packages/pyclutter/trunk/debian

In this example the source, .diff.gz and .dsc files are taken from Debian, and the Maemo-specific packaging is taken from the (former) PyMaemo repository. pymaemo-tools will assemble the package prior to build, as explained in the Overview section.

=== Modifying PyMaemo packages ===

The PyMaemo packages are all in Gitorious now, allowing easy customization of any package you desire. The high-level steps for the process are listed below.

* Create a clone of the the repository at Gitorious for the package you want to modify, and git-clone it;
* Modify the packages-fremantle.ini repository section of the package to point to the repository you just cloned;
** Use the full path to the directory you cloned in git_url
* Modify the package at will, and then build it using the same command tools - pymaemo-tools will use your local repository for building;
** Erase the prepared files of your package from $BASE/workdir prior to the building proper;
* When you are satisfied with the results, push your local changes to your Gitorious clone, and file a merge request.

As said before, there are two types of packages: native and taken from upstream. If you want to modify a native package, you can do anything you want, as the entire package is contained in the repository. However, if the package is taken from upstream, the only changes you can make will be located in the Maemo packaging - you'll have to use patches to actually modify any upstream file in build time.

== Tips ==

=== Create Debian repository with one line ===

If you want to quickly make a Debian repository for easy installation,
run the following command at $BASE/pymaemo-tools/workdir/fremantle_<target>/repo:

$ apt-ftparchive packages . | gzip -9c > Packages.gz

Now you have to expose the packages' path to the Web server and add the repository
in the target machine accordingly.

=== Tracking build in real time ===

If you want to accompany the build log of any package in real time, you can just use the tail command in the following log files:

* Prep and setup:
$ tail -F $BASE/workdir/fremantle_<target>/repo/root.log
* Build:
$ tail -F $BASE/workdir/fremantle_<target>/repo/build.log

PyMaemo/How to build

2010-01-15T18:31:42Z

189.2.128.130: /* Tips */

= How to build PyMaemo packages=

== Introduction ==

To build PyMaemo packages from the source, you'll need:

* Maemo 5 SDK
* Rootstraps for X86 and ARMEL targets
* grep-dctrl
* pymaemo-builder

The scripts from pymaemo-builder are used to download packages' sources and build them using sbdmock, one at a time. sbdmock, in turn, uses the SDK and the rootstraps to create a clean environment for building every package. More information about sbdmock can be obtained [[Building_packages_with_sbdmock|here]], although pymaemo-builder uses a slightly modified of sbdmock - see pymaemo-builder README if you want to know which modifications were made.

The scripts from pymaemo-builder can be used to build the entire set of packages or only some of them, for X86 or ARMEL targets. It is advised to first build and (if possible) test in the X86 target and use ARMEL target only for cross-compiling for the device.

== Overview of the build process ==

The build process is composed of three phases: download, preparation and the proper build. A high-level description of the process follows:

* Download phase:
** If the package is originally from Debian or Ubuntu:
*** The original source is taken from upstream;
*** The Debian packaging for Maemo is taken from the respective repository in PyMaemo project.
** If the package is Maemo-specific:
*** The source package is taken from the respective repository in PyMaemo project
* Preparation phase:
** If the package is taken from upstream, assemble package
** Verify if dependencies are satisfied
* Build phase:
** Call sbdmock with proper parameters

== Configuration ==

The base directory for these instructions, refered as $BASE, is /scratchbox/users/<user>/home/<user>/pymaemo,
where <user> is your username in Scratchbox. All operations are made '''outside''' Scratchbox.

First, download the rootstraps for X86 and ARMEL targets and put them in $BASE/rootstraps:

* http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz
* http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz

Clone the pymaemo-builder project inside $BASE:

$ git clone [git repo]

This will create the directory pymaemo-builder under $BASE.

Edit the fremantle_i386.cfg and fremantle_armel.cfg under $BASE/pymaemo-builder/sbdmock,
putting the rootstrap path correspondent to each in the following key:
* i386: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_i386.tgz"
* armel: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_armel.tgz"

== Building ==

For building all the packages for the X86 target, enter $BASE/pymaemo-builder and run:

$ ./build_packages.sh sbdmock:fremantle_i386 packages_fremantle.ini

The same can be done to ARMEL target, just replacing "i386" with "armel". The file packages_fremantle.ini contains all data necessary for obtaining the sources.

You can build individual packages too, specifying them as parameters. If you want to build only, let's say, pyopenssl and pycurl for the ARMEL target, run:

$ ./build_packages.sh sbdmock:fremantle_armel packages_fremantle.ini pyopenssl,pycurl

Be advised that any PyMaemo dependency for these packages must be built first, as build_packages.sh will attempt to build only the packages provided at the command line.

There are other options for the build; for more information, run build_packages.sh
with no parameters or refer to the README file inside pymaemo-builder.

When the build finishes the resultant Debian packages will be placed at
$BASE/pymaemo-builder/workdir/fremantle_<target>/repo, where <target> is i386 or armel,and the build logs placed in $BASE/pymaemo-builder/workdir/fremantle_<target>/logs.
From that point on, they can be installed on the targets and the ARMEL ones
can be copied to the device to be installed there.

=== Directories created ===

* $BASE/pymaemo-builder/download_cache: all downloaded files are placed here, one directory by package, so you don't have to download everything again in every build. If the sources are updated, though, you will have to erase the corresponding entries on download_cache for allow them to be downloaded again.
* $BASE/pymaemo-builder/workdir: the generated files (prepared sources, logs, built packages) are placed under this directory, grouped by the name of the sbdmock config file used to build them. Inside each group, the logs and repo directories will contain, respectively, the build logs and the built packages.

== Tips ==

=== Create Debian repository with one line ===

If you want to quickly make a Debian repository for easy installation,
run the following command at $BASE/pymaemo-builder/workdir/fremantle_<target>/repo:

$ apt-ftparchive packages . | gzip -9c > Packages.gz

Now you have to expose the packages' path to the Web server and add the repository
in the target machine accordingly.

=== Tracking build in real time ===

If you want to accompany the build log of any package in real time, you can just use the tail command in the following log files:

* Dependency download:
$ tail -F $BASE/workdir/fremantle_<target>/repo/root.log
* Build:
$ tail -F $BASE/workdir/fremantle_<target>/repo/build.log

PyMaemo/How to build

2010-01-15T16:03:10Z

189.2.128.130: /* Directories created */

= How to build PyMaemo packages=

== Introduction ==

To build PyMaemo packages from the source, you'll need:

* Maemo 5 SDK
* Rootstraps for X86 and ARMEL targets
* grep-dctrl
* pymaemo-builder

The scripts from pymaemo-builder are used to download packages' sources and build them using sbdmock, one at a time. sbdmock, in turn, uses the SDK and the rootstraps to create a clean environment for building every package. More information about sbdmock can be obtained [[Building_packages_with_sbdmock|here]], although pymaemo-builder uses a slightly modified of sbdmock - see pymaemo-builder README if you want to know which modifications were made.

The scripts from pymaemo-builder can be used to build the entire set of packages or only some of them, for X86 or ARMEL targets. It is advised to first build and (if possible) test in the X86 target and use ARMEL target only for cross-compiling for the device.

== Overview of the build process ==

The build process is composed of three phases: download, preparation and the proper build. A high-level description of the process follows:

* Download phase:
** If the package is originally from Debian or Ubuntu:
*** The original source is taken from upstream;
*** The Debian packaging for Maemo is taken from the respective repository in PyMaemo project.
** If the package is Maemo-specific:
*** The source package is taken from the respective repository in PyMaemo project
* Preparation phase:
** If the package is taken from upstream, assemble package
** Verify if dependencies are satisfied
* Build phase:
** Call sbdmock with proper parameters

== Configuration ==

The base directory for these instructions, refered as $BASE, is /scratchbox/users/<user>/home/<user>/pymaemo,
where <user> is your username in Scratchbox. All operations are made '''outside''' Scratchbox.

First, download the rootstraps for X86 and ARMEL targets and put them in $BASE/rootstraps:

* http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz
* http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz

Clone the pymaemo-builder project inside $BASE:

$ git clone [git repo]

This will create the directory pymaemo-builder under $BASE.

Edit the fremantle_i386.cfg and fremantle_armel.cfg under $BASE/pymaemo-builder/sbdmock,
putting the rootstrap path correspondent to each in the following key:
* i386: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_i386.tgz"
* armel: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_armel.tgz"

== Building ==

For building all the packages for the X86 target, enter $BASE/pymaemo-builder and run:

$ ./build_packages.sh sbdmock:fremantle_i386 packages_fremantle.ini

The same can be done to ARMEL target, just replacing "i386" with "armel". The file packages_fremantle.ini contains all data necessary for obtaining the sources.

You can build individual packages too, specifying them as parameters. If you want to build only, let's say, pyopenssl and pycurl for the ARMEL target, run:

$ ./build_packages.sh sbdmock:fremantle_armel packages_fremantle.ini pyopenssl,pycurl

Be advised that any PyMaemo dependency for these packages must be built first, as build_packages.sh will attempt to build only the packages provided at the command line.

There are other options for the build; for more information, run build_packages.sh
with no parameters or refer to the README file inside pymaemo-builder.

When the build finishes the resultant Debian packages will be placed at
$BASE/pymaemo-builder/workdir/fremantle_<target>/repo, where <target> is i386 or armel,and the build logs placed in $BASE/pymaemo-builder/workdir/fremantle_<target>/logs.
From that point on, they can be installed on the targets and the ARMEL ones
can be copied to the device to be installed there.

=== Directories created ===

* $BASE/pymaemo-builder/download_cache: all downloaded files are placed here, one directory by package, so you don't have to download everything again in every build. If the sources are updated, though, you will have to erase the corresponding entries on download_cache for allow them to be downloaded again.
* $BASE/pymaemo-builder/workdir: the generated files (prepared sources, logs, built packages) are placed under this directory, grouped by the name of the sbdmock config file used to build them. Inside each group, the logs and repo directories will contain, respectively, the build logs and the built packages.

== Tips ==

If you want to quickly make a Debian repository for easy installation,
run the following command at $BASE/pymaemo-builder/workdir/fremantle_<target>/repo:

$ apt-ftparchive packages . | gzip -9c > Packages.gz

Now you have to expose the packages' path to the Web server and add the repository
in the target machine accordingly.

PyMaemo/How to build

2010-01-15T16:00:40Z

189.2.128.130: /* Building */

= How to build PyMaemo packages=

== Introduction ==

To build PyMaemo packages from the source, you'll need:

* Maemo 5 SDK
* Rootstraps for X86 and ARMEL targets
* grep-dctrl
* pymaemo-builder

The scripts from pymaemo-builder are used to download packages' sources and build them using sbdmock, one at a time. sbdmock, in turn, uses the SDK and the rootstraps to create a clean environment for building every package. More information about sbdmock can be obtained [[Building_packages_with_sbdmock|here]], although pymaemo-builder uses a slightly modified of sbdmock - see pymaemo-builder README if you want to know which modifications were made.

The scripts from pymaemo-builder can be used to build the entire set of packages or only some of them, for X86 or ARMEL targets. It is advised to first build and (if possible) test in the X86 target and use ARMEL target only for cross-compiling for the device.

== Overview of the build process ==

The build process is composed of three phases: download, preparation and the proper build. A high-level description of the process follows:

* Download phase:
** If the package is originally from Debian or Ubuntu:
*** The original source is taken from upstream;
*** The Debian packaging for Maemo is taken from the respective repository in PyMaemo project.
** If the package is Maemo-specific:
*** The source package is taken from the respective repository in PyMaemo project
* Preparation phase:
** If the package is taken from upstream, assemble package
** Verify if dependencies are satisfied
* Build phase:
** Call sbdmock with proper parameters

== Configuration ==

The base directory for these instructions, refered as $BASE, is /scratchbox/users/<user>/home/<user>/pymaemo,
where <user> is your username in Scratchbox. All operations are made '''outside''' Scratchbox.

First, download the rootstraps for X86 and ARMEL targets and put them in $BASE/rootstraps:

* http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz
* http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz

Clone the pymaemo-builder project inside $BASE:

$ git clone [git repo]

This will create the directory pymaemo-builder under $BASE.

Edit the fremantle_i386.cfg and fremantle_armel.cfg under $BASE/pymaemo-builder/sbdmock,
putting the rootstrap path correspondent to each in the following key:
* i386: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_i386.tgz"
* armel: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_armel.tgz"

== Building ==

For building all the packages for the X86 target, enter $BASE/pymaemo-builder and run:

$ ./build_packages.sh sbdmock:fremantle_i386 packages_fremantle.ini

The same can be done to ARMEL target, just replacing "i386" with "armel". The file packages_fremantle.ini contains all data necessary for obtaining the sources.

You can build individual packages too, specifying them as parameters. If you want to build only, let's say, pyopenssl and pycurl for the ARMEL target, run:

$ ./build_packages.sh sbdmock:fremantle_armel packages_fremantle.ini pyopenssl,pycurl

Be advised that any PyMaemo dependency for these packages must be built first, as build_packages.sh will attempt to build only the packages provided at the command line.

There are other options for the build; for more information, run build_packages.sh
with no parameters or refer to the README file inside pymaemo-builder.

When the build finishes the resultant Debian packages will be placed at
$BASE/pymaemo-builder/workdir/fremantle_<target>/repo, where <target> is i386 or armel,and the build logs placed in $BASE/pymaemo-builder/workdir/fremantle_<target>/logs.
From that point on, they can be installed on the targets and the ARMEL ones
can be copied to the device to be installed there.

=== Directories created ===

* $BASE/pymaemo-builder/download_cache: all downloaded files are placed here, one directory by package, so you don't have to download everything again in every build. If the sources are updated, though, you will have to erase the corresponding entry on download_cache for allow them to be downloaded again.
* $BASE/pymaemo-builder/workdir: the generated files (prepared sources, logs, built packages) are placed under this directory, grouped by the name of the sbdmock config file used to build them. Inside each group, the logs and repo directories will contain, respectively, the build logs and the built packages.

== Tips ==

If you want to quickly make a Debian repository for easy installation,
run the following command at $BASE/pymaemo-builder/workdir/fremantle_<target>/repo:

$ apt-ftparchive packages . | gzip -9c > Packages.gz

Now you have to expose the packages' path to the Web server and add the repository
in the target machine accordingly.

PyMaemo/How to build

2010-01-15T15:57:48Z

189.2.128.130: /* Introduction */

= How to build PyMaemo packages=

== Introduction ==

To build PyMaemo packages from the source, you'll need:

* Maemo 5 SDK
* Rootstraps for X86 and ARMEL targets
* grep-dctrl
* pymaemo-builder

The scripts from pymaemo-builder are used to download packages' sources and build them using sbdmock, one at a time. sbdmock, in turn, uses the SDK and the rootstraps to create a clean environment for building every package. More information about sbdmock can be obtained [[Building_packages_with_sbdmock|here]], although pymaemo-builder uses a slightly modified of sbdmock - see pymaemo-builder README if you want to know which modifications were made.

The scripts from pymaemo-builder can be used to build the entire set of packages or only some of them, for X86 or ARMEL targets. It is advised to first build and (if possible) test in the X86 target and use ARMEL target only for cross-compiling for the device.

== Overview of the build process ==

The build process is composed of three phases: download, preparation and the proper build. A high-level description of the process follows:

* Download phase:
** If the package is originally from Debian or Ubuntu:
*** The original source is taken from upstream;
*** The Debian packaging for Maemo is taken from the respective repository in PyMaemo project.
** If the package is Maemo-specific:
*** The source package is taken from the respective repository in PyMaemo project
* Preparation phase:
** If the package is taken from upstream, assemble package
** Verify if dependencies are satisfied
* Build phase:
** Call sbdmock with proper parameters

== Configuration ==

The base directory for these instructions, refered as $BASE, is /scratchbox/users/<user>/home/<user>/pymaemo,
where <user> is your username in Scratchbox. All operations are made '''outside''' Scratchbox.

First, download the rootstraps for X86 and ARMEL targets and put them in $BASE/rootstraps:

* http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz
* http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz

Clone the pymaemo-builder project inside $BASE:

$ git clone [git repo]

This will create the directory pymaemo-builder under $BASE.

Edit the fremantle_i386.cfg and fremantle_armel.cfg under $BASE/pymaemo-builder/sbdmock,
putting the rootstrap path correspondent to each in the following key:
* i386: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_i386.tgz"
* armel: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_armel.tgz"

== Building ==

For building all the packages for the X86 target, enter $BASE/pymaemo-builder and run:

$ ./build_packages.sh sbdmock:fremantle_i386 packages_fremantle.ini

The same can be done to ARMEL target, just replacing "i386" with "armel". The file packages_fremantle.ini contains all data necessary for obtaining the sources.

You can build individual packages too, specifying them as parameters. If you want to build only, let's say, pyopenssl and pycurl for the ARMEL target, run:

$ ./build_packages.sh sbdmock:fremantle_armel packages_fremantle.ini pyopenssl,pycurl

Be advised that any PyMaemo dependency for these packages must be built first, as build_packages.sh will attempt to build only the packages provided at the command line.

There are other options for the build; for more information, run ./build_packages.sh
with no parameters or refer to the README file inside pymaemo-builder.

When the build finishes the resultant Debian packages will be placed at
$BASE/pymaemo-builder/workdir/fremantle_<target>/repo, where <target> is i386 or armel,and the build logs placed in $BASE/pymaemo-builder/workdir/fremantle_<target>/logs.
From that point on, they can be installed on the targets and the ARMEL ones
can be copied to the device to be installed there.

=== Directories created ===

* $BASE/pymaemo-builder/download_cache: all downloaded files are placed here, one directory by package, so you don't have to download everything again in every build. If the sources are updated, though, you will have to erase the corresponding entry on download_cache for allow them to be downloaded again.
* $BASE/pymaemo-builder/workdir: the generated files (prepared sources, logs, built packages) are placed under this directory, grouped by the name of the sbdmock config file used to build them. Inside each group, the logs and repo directories will contain, respectively, the build logs and the built packages.

== Tips ==

If you want to quickly make a Debian repository for easy installation,
run the following command at $BASE/pymaemo-builder/workdir/fremantle_<target>/repo:

$ apt-ftparchive packages . | gzip -9c > Packages.gz

Now you have to expose the packages' path to the Web server and add the repository
in the target machine accordingly.

PyMaemo/How to build

2010-01-15T15:50:35Z

189.2.128.130: /* Introduction */

= How to build PyMaemo packages=

== Introduction ==

To build PyMaemo packages from the source, you'll need:

* Maemo 5 SDK
* Rootstraps for X86 and ARMEL targets
* grep-dctrl
* pymaemo-builder

The scripts from pymaemo-builder are used to download packages' sources and build them using sbdmock, one at a time. sbdmock, in turn, uses the SDK and the rootstraps to create a clean environment for building every package. More information about sbdmock can be obtained [[Building_packages_with_sbdmock|here]], altough pymaemo-builder uses a slightly modified of sbdmock - see pymaemo-builder README if you want to know which modifications were made.

The scripts from pymaemo-builder can be used to build the entire set of packages or only some of them, for X86 or ARMEL targets. It is advised to first build and (if possible) test in the X86 target and use ARMEL target only for cross-compiling for the device.

== Overview of the build process ==

The build process is composed of three phases: download, preparation and the proper build. A high-level description of the process follows:

* Download phase:
** If the package is originally from Debian or Ubuntu:
*** The original source is taken from upstream;
*** The Debian packaging for Maemo is taken from the respective repository in PyMaemo project.
** If the package is Maemo-specific:
*** The source package is taken from the respective repository in PyMaemo project
* Preparation phase:
** If the package is taken from upstream, assemble package
** Verify if dependencies are satisfied
* Build phase:
** Call sbdmock with proper parameters

== Configuration ==

The base directory for these instructions, refered as $BASE, is /scratchbox/users/<user>/home/<user>/pymaemo,
where <user> is your username in Scratchbox. All operations are made '''outside''' Scratchbox.

First, download the rootstraps for X86 and ARMEL targets and put them in $BASE/rootstraps:

* http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz
* http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz

Clone the pymaemo-builder project inside $BASE:

$ git clone [git repo]

This will create the directory pymaemo-builder under $BASE.

Edit the fremantle_i386.cfg and fremantle_armel.cfg under $BASE/pymaemo-builder/sbdmock,
putting the rootstrap path correspondent to each in the following key:
* i386: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_i386.tgz"
* armel: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_armel.tgz"

== Building ==

For building all the packages for the X86 target, enter $BASE/pymaemo-builder and run:

$ ./build_packages.sh sbdmock:fremantle_i386 packages_fremantle.ini

The same can be done to ARMEL target, just replacing "i386" with "armel". The file packages_fremantle.ini contains all data necessary for obtaining the sources.

You can build individual packages too, specifying them as parameters. If you want to build only, let's say, pyopenssl and pycurl for the ARMEL target, run:

$ ./build_packages.sh sbdmock:fremantle_armel packages_fremantle.ini pyopenssl,pycurl

Be advised that any PyMaemo dependency for these packages must be built first, as build_packages.sh will attempt to build only the packages provided at the command line.

There are other options for the build; for more information, run ./build_packages.sh
with no parameters or refer to the README file inside pymaemo-builder.

When the build finishes the resultant Debian packages will be placed at
$BASE/pymaemo-builder/workdir/fremantle_<target>/repo, where <target> is i386 or armel,and the build logs placed in $BASE/pymaemo-builder/workdir/fremantle_<target>/logs.
From that point on, they can be installed on the targets and the ARMEL ones
can be copied to the device to be installed there.

=== Directories created ===

* $BASE/pymaemo-builder/download_cache: all downloaded files are placed here, one directory by package, so you don't have to download everything again in every build. If the sources are updated, though, you will have to erase the corresponding entry on download_cache for allow them to be downloaded again.
* $BASE/pymaemo-builder/workdir: the generated files (prepared sources, logs, built packages) are placed under this directory, grouped by the name of the sbdmock config file used to build them. Inside each group, the logs and repo directories will contain, respectively, the build logs and the built packages.

== Tips ==

If you want to quickly make a Debian repository for easy installation,
run the following command at $BASE/pymaemo-builder/workdir/fremantle_<target>/repo:

$ apt-ftparchive packages . | gzip -9c > Packages.gz

Now you have to expose the packages' path to the Web server and add the repository
in the target machine accordingly.

PyMaemo/How to build

2010-01-15T15:50:06Z

189.2.128.130: /* Introduction */

= How to build PyMaemo packages=

== Introduction ==

To build PyMaemo packages from the source, you'll need:

* Maemo 5 SDK
* Rootstraps for X86 and ARMEL targets
* grep-dctrl
* pymaemo-builder

The scripts from pymaemo-builder are used to download packages' sources and build them using sbdmock, one at a time. sbdmock, in turn, uses the SDK and the rootstraps to create a clean environment for building every package. More information about sbdmock can be obtained [Building_packages_with_sbdmock|here]], altough pymaemo-builder uses a slightly modified of sbdmock - see pymaemo-builder README if you want to know which modifications were made.

The scripts from pymaemo-builder can be used to build the entire set of packages or only some of them, for X86 or ARMEL targets. It is advised to first build and (if possible) test in the X86 target and use ARMEL target only for cross-compiling for the device.

== Overview of the build process ==

The build process is composed of three phases: download, preparation and the proper build. A high-level description of the process follows:

* Download phase:
** If the package is originally from Debian or Ubuntu:
*** The original source is taken from upstream;
*** The Debian packaging for Maemo is taken from the respective repository in PyMaemo project.
** If the package is Maemo-specific:
*** The source package is taken from the respective repository in PyMaemo project
* Preparation phase:
** If the package is taken from upstream, assemble package
** Verify if dependencies are satisfied
* Build phase:
** Call sbdmock with proper parameters

== Configuration ==

The base directory for these instructions, refered as $BASE, is /scratchbox/users/<user>/home/<user>/pymaemo,
where <user> is your username in Scratchbox. All operations are made '''outside''' Scratchbox.

First, download the rootstraps for X86 and ARMEL targets and put them in $BASE/rootstraps:

* http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz
* http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz

Clone the pymaemo-builder project inside $BASE:

$ git clone [git repo]

This will create the directory pymaemo-builder under $BASE.

Edit the fremantle_i386.cfg and fremantle_armel.cfg under $BASE/pymaemo-builder/sbdmock,
putting the rootstrap path correspondent to each in the following key:
* i386: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_i386.tgz"
* armel: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_armel.tgz"

== Building ==

For building all the packages for the X86 target, enter $BASE/pymaemo-builder and run:

$ ./build_packages.sh sbdmock:fremantle_i386 packages_fremantle.ini

The same can be done to ARMEL target, just replacing "i386" with "armel". The file packages_fremantle.ini contains all data necessary for obtaining the sources.

You can build individual packages too, specifying them as parameters. If you want to build only, let's say, pyopenssl and pycurl for the ARMEL target, run:

$ ./build_packages.sh sbdmock:fremantle_armel packages_fremantle.ini pyopenssl,pycurl

Be advised that any PyMaemo dependency for these packages must be built first, as build_packages.sh will attempt to build only the packages provided at the command line.

There are other options for the build; for more information, run ./build_packages.sh
with no parameters or refer to the README file inside pymaemo-builder.

When the build finishes the resultant Debian packages will be placed at
$BASE/pymaemo-builder/workdir/fremantle_<target>/repo, where <target> is i386 or armel,and the build logs placed in $BASE/pymaemo-builder/workdir/fremantle_<target>/logs.
From that point on, they can be installed on the targets and the ARMEL ones
can be copied to the device to be installed there.

=== Directories created ===

* $BASE/pymaemo-builder/download_cache: all downloaded files are placed here, one directory by package, so you don't have to download everything again in every build. If the sources are updated, though, you will have to erase the corresponding entry on download_cache for allow them to be downloaded again.
* $BASE/pymaemo-builder/workdir: the generated files (prepared sources, logs, built packages) are placed under this directory, grouped by the name of the sbdmock config file used to build them. Inside each group, the logs and repo directories will contain, respectively, the build logs and the built packages.

== Tips ==

If you want to quickly make a Debian repository for easy installation,
run the following command at $BASE/pymaemo-builder/workdir/fremantle_<target>/repo:

$ apt-ftparchive packages . | gzip -9c > Packages.gz

Now you have to expose the packages' path to the Web server and add the repository
in the target machine accordingly.

PyMaemo/How to build

2010-01-15T13:30:12Z

189.2.128.130: New page: = How to build PyMaemo packages= == Introduction == To build PyMaemo packages from the source, you'll need: * Maemo 5 SDK x86/ARMEL * Rootstraps for X86 and ARMEL targets * sbdmock * g...

= How to build PyMaemo packages=

== Introduction ==

To build PyMaemo packages from the source, you'll need:

* Maemo 5 SDK x86/ARMEL
* Rootstraps for X86 and ARMEL targets
* sbdmock
* grep-dctrl
* pymaemo-builder

The scripts from pymaemo-builder are used to download packages' sources and build them using sbdmock, one at a time. sbdmock, in turn, uses the SDK and the rootstraps to create a clean environment for building every package.

The scripts can be used to build the entire set of packages or only some of them, for x86 or ARMEL targets. It is advised to first build and test in the X86 target and use ARMEL target only for cross-compiling for the device.

== Overview of the build process ==

* Download phase:
** If the package is originally from Debian or Ubuntu:
*** The original source is taken from upstream;
*** The Debian packaging for Maemo is taken from the respective repository in PyMaemo project.
** If the package is Maemo-specific:
*** The source package is taken from the respective repository in PyMaemo project
* Preparation phase:
** If the package is taken from upstream, assemble package
** Verify if dependencies are satisfied
* Build phase:
** Call sbdmock with proper parameters

== Configuration ==

The base directory for these instructions, refered as $BASE, is /scratchbox/users/<user>/home/<user>/pymaemo,
where <user> is your username in Scratchbox. All operations are made '''outside''' Scratchbox.

First, download the rootstraps for X86 and ARMEL targets and put them in $BASE/rootstraps:

* http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz
* http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz

Clone the pymaemo-builder project inside $BASE:

$ git clone [git repo]

This will create the directory pymaemo-builder under $BASE.

Edit the fremantle_i386.cfg and fremantle_armel.cfg under $BASE/pymaemo-builder/sbdmock,
putting the rootstrap path correspondent to each:
* i386: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_i386.tgz"
* armel: config_opts['rootstrap'] = "$BASE/rootstraps/maemo-sdk-rootstrap_5.0_armel.tgz"

== Building ==

For building all the packages for the X86 target, enter $BASE/pymaemo-builder and run:

$ ./build_packages.sh sbdmock:fremantle_i386 packages_fremantle.ini

The same can be done to ARMEL target, just replacing "i386" with "armel". The
build script does everything automatically: it downloads all the sources and
builds the packages with sbdmock in the proper order. The file packages_fremantle.ini contains all data necessary for obtaining the sources.

You can build individual packages too, specifying them as parameters. If you want to build only, let's say, pyopenssl and pycurl for the ARMEL target, run:

$ ./build_packages.sh sbdmock:fremantle_armel packages_fremantle.ini pyopenssl,pycurl

Be advised that any PyMaemo dependency for these packages must be built first, as build_packages.sh will attempt to build only the packages provided at the command line.

There are other options for the build; for more information, run ./build_packages.sh
with no parameters or refer to the README file inside pymaemo-builder.

When the build finishes the resultant Debian packages will be placed at
$BASE/pymaemo-builder/workdir/fremantle_<target>/repo, where <target> is i386 or armel,and the build logs placed in $BASE/pymaemo-builder/workdir/fremantle_<target>/logs.
From that point on, they can be installed on the targets and the ARMEL ones
can be copied to the device to be installed there.

== Directories created ==

* $BASE/pymaemo-builder/download_cache: all downloaded files are placed here, one directory by package, so you don't have to download everything again in
every build. If the sources are updated, though, you will have to erase the corresponding
entry on download_cache for allow them to be downloaded again.
* $BASE/pymaemo-builder/workdir: the generated files (prepared sources, logs, built packages) are placed under this directory, grouped by the name of the
sbdmock config file used to build them. Inside each group, the logs and repo
directories will contain, respectively, the build logs and the built packages.

== Tips ==

If you want to quickly make a Debian repository for easy installation,
run the following command at $BASE/pymaemo-builder/workdir/fremantle_<target>/repo:

$ apt-ftparchive packages . | gzip -9c > Packages.gz

Now you have to expose the packages' path to the Web server and add the repository
in the target machine accordingly.

PyMaemo/Quick start guide

2010-01-11T19:17:11Z

189.2.128.130: /* Advanced tips */

= Getting Started: Setting Up Python Development Environment for N900 =

A basic development environment for Python development for Maemo consists of:

* A source code editor
* Some way to transfer application files to the tablet
* Easily run the application (without installing it)

Alternatively, you can try other more complex development environments, briefly described at the end of this article.

This article will cover:

* Installation of necessary packages and USB connectivity setup
* Some suggestions for Python code editors
* How to transfer the application files to the N900
* How to run the application

Application packaging and final deployment will be discussed separately at a later date.

Finally, there is a [http://www.youtube.com/watch?v=onAkb_7U5pk screencast] demonstrating the instructions from this guide, which should help clarifying some of the steps in a real setup session.

== Requirements ==

Before continuing, make sure you have:

Tablet requirements:

* Some kind of connectivity to the tablet (e.g. WLAN or GPRS), so that you can install required packages.
* The N900 USB cable, which will be used to transfer files to the tablet.

Host requirements:

* A SSH client. For Linux, OpenSSH (through the "ssh" command) is enough. For Windows, [http://en.sourceforge.jp/projects/ttssh2/releases/ Tera Term] can be used. For Mac you can use "ssh" command in the Terminal.
* A SCP/SFTP client. For Linux, OpenSSH (through the "scp" command) is enough. The KDE/GNOME environments also have built-in support for these protocols. For Windows, you can try [http://winscp.net/eng/index.php WinSCP] or [http://filezilla-project.org/ FileZilla].

For the purposes of this tutorial, you will '''not''' need Scratchbox installed. Scratchbox would only be necessary if you are unable to test your applications on the actual tablet.

== Installing required packages on N900 ==

You will need to install two applications on the tablet:

* OpenSSH Server
* rootsh

OpenSSH is needed to run commands remotely on your N900. This will make testing on the device a lot easier.

rootsh is needed to allow to run commands as root on the X Terminal (using "sudo gainroot"). See http://wiki.maemo.org/Root_access for other options to enable root access.

To install these applications, follow these steps:

# Enable extras repository. See http://wiki.maemo.org/Extras#Using_Extras for how to do it.
# Install the packages listed above.
# The installation will ask for a new root password for SSH access. Choose a good one.
# Wait for installation to complete.

== Enabling USB networking ==

USB networking allows to easily and quickly transfer files to the device and connect to it using SSH. To enable it, follow these steps (you need to repeat them every time you reboot the device):

# If the USB cable is plugged and in "Mass storage mode", unplug the cable and plug it again, now selecting "PC Suite Mode".
# On N900, open "X Terminal" and run:
rootsh ifup usb0
# Now you need to configure the host. This is dependent on which OS (or Linux distro) you use, see http://wiki.maemo.org/USB_networking#Host_USB_Network_Configuration for detailed instructions for various OSes and Linux distros.

From now on you can connect to the N900 using any SSH client and the following information:
Host: 192.168.2.15
Port: 22
User: root
Password: the password setup earlier

For instance, from a Linux terminal, you can connect to the tablet using this command:

ssh root@192.168.2.15

== Preparing the N900 for Python Development ==

To enable the full power for Python development for Maemo, you must enable the "extras-devel" repository on your device. ''Be advised that this might be a risky operation'' because extras-devel contains many untested and possibly broken packages. But it also contains the latest versions of all available Python bindings for Maemo, which we are interested on.

Note that the requirement to enable the "extras-devel" repository might be removed later.

To enable extras-devel add a new catalogue to the Application Manager, as instructed in http://wiki.maemo.org/Extras-devel (did you see the big warning on that page?)

After extras-devel is enabled, you will see on Application Manager a package called "maemo-python-device-env". Installing it will also install the basic environment necessary to run most Python applications on Maemo.

== Writing your code ==

Any good programmer oriented editor will be enough for development. If you have some development experience, you most probably already have chosen your favorite code editor and you can simply use it.

Here we list some options, both for Linux and Windows:

* [http://projects.gnome.org/gedit/ gedit]: the GNOME Editor has syntax highlight support for Python (Linux only)
* [http://www.vim.org/ VIM] and [http://www.gnu.org/software/emacs/ Emacs]: the most popular editors, with many advanced features and versions for both Linux and Windows
* [http://wiki.netbeans.org/Python NetBeans + Python plugin]: NetBeans is a multi-platform IDE, which with help of a plugin, supports development for Python

Note that none of these editors will support code completion for PyMaemo modules out of box.

For testing purposes, you can try the following code (the classic "hello world" example):

import gtk
from gtk import Window, Button, Widget
if __name__ == "__main__":
window = Window(gtk.WINDOW_TOPLEVEL)
window.connect("destroy", gtk.main_quit)
button = Button("Hello World")
button.connect_object("clicked", Widget.destroy, window)
window.add(button)
window.show_all()
gtk.main()

Once you have your code written, you can proceed to copying application files to the device.

== Running the Python application on the device ==

Now that you have the N900 properly setup and the code to run, you just need to copy the application files to the device and run it.

The simplest way to copy files it to use a SFTP or SCP client. There are many free clients available for most OSes (we listed some examples on the "Requirements" section). On the Linux command line, you can use:

scp -pr my_application/ root@192.168.2.15:/root/my_application/

Replace "my_application/" with the path to the directory which contains your application files.

Finally, to run the application on the tablet, use (from a SSH terminal):

cd /root/my_application
python my_application.py

== Alternative development environments ==

Besides the environment described on this article, there are two alternative development environments that might or might not be more appropriate for your purposes:

; PluThon (Eclipse based)
: [http://pluthon.garage.maemo.org/ PluThon] is a full Python IDE for Maemo, based on Eclipse. While PluThon is easy to use and provides a complete solution, it is not necessary for basic Python development for Maemo. If you already use Eclipse for your development, PluThon might be your best option.
; Official Maemo SDK (Scratchbox based)
: [http://www.scratchbox.org/ Scratchbox] is a cross-compilation toolkit used for native Maemo development. Although it can be used in Python development as well (and comes very handy if you do not have access to a real device), it has a non-trivial learning curve and is not needed for pure Python development. However, if you plan to write new Python extensions (for instance, using [http://www.cython.org/ Cython] or [http://docs.python.org/c-api/index.html Python/C API] directly), Scratchbox is needed to cross-compile the C code. See the [http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Development_Environment/Maemo_SDK Maemo SDK section] on Maemo 5 developer guide for more details on it.

Note that PluThon has built-in support for transferring and running code on the device. On the other hand, the Maemo SDK has no such support (unless you use some IDE like [http://esbox.garage.maemo.org/ ESbox]), so you need to follow steps similar to the ones described on this guide to copy and run your code on the tablet, if you choose to use the Maemo SDK.

== Advanced tips ==

If you want to activate USB networking automatically upon connecting the device to the computer, just create a file called /etc/event.d/usbnet on the device with the following contents:

start on G_NOKIA_READY

console output
exec ifconfig usb0 192.168.2.15 up

This way you just have to select "PC Suite mode" when plugging the device in.

[[Category:N900]]
[[Category:Python]]

PyMaemo/Quick start guide

2010-01-11T19:15:57Z

189.2.128.130:

= Getting Started: Setting Up Python Development Environment for N900 =

A basic development environment for Python development for Maemo consists of:

* A source code editor
* Some way to transfer application files to the tablet
* Easily run the application (without installing it)

Alternatively, you can try other more complex development environments, briefly described at the end of this article.

This article will cover:

* Installation of necessary packages and USB connectivity setup
* Some suggestions for Python code editors
* How to transfer the application files to the N900
* How to run the application

Application packaging and final deployment will be discussed separately at a later date.

Finally, there is a [http://www.youtube.com/watch?v=onAkb_7U5pk screencast] demonstrating the instructions from this guide, which should help clarifying some of the steps in a real setup session.

== Requirements ==

Before continuing, make sure you have:

Tablet requirements:

* Some kind of connectivity to the tablet (e.g. WLAN or GPRS), so that you can install required packages.
* The N900 USB cable, which will be used to transfer files to the tablet.

Host requirements:

* A SSH client. For Linux, OpenSSH (through the "ssh" command) is enough. For Windows, [http://en.sourceforge.jp/projects/ttssh2/releases/ Tera Term] can be used. For Mac you can use "ssh" command in the Terminal.
* A SCP/SFTP client. For Linux, OpenSSH (through the "scp" command) is enough. The KDE/GNOME environments also have built-in support for these protocols. For Windows, you can try [http://winscp.net/eng/index.php WinSCP] or [http://filezilla-project.org/ FileZilla].

For the purposes of this tutorial, you will '''not''' need Scratchbox installed. Scratchbox would only be necessary if you are unable to test your applications on the actual tablet.

== Installing required packages on N900 ==

You will need to install two applications on the tablet:

* OpenSSH Server
* rootsh

OpenSSH is needed to run commands remotely on your N900. This will make testing on the device a lot easier.

rootsh is needed to allow to run commands as root on the X Terminal (using "sudo gainroot"). See http://wiki.maemo.org/Root_access for other options to enable root access.

To install these applications, follow these steps:

# Enable extras repository. See http://wiki.maemo.org/Extras#Using_Extras for how to do it.
# Install the packages listed above.
# The installation will ask for a new root password for SSH access. Choose a good one.
# Wait for installation to complete.

== Enabling USB networking ==

USB networking allows to easily and quickly transfer files to the device and connect to it using SSH. To enable it, follow these steps (you need to repeat them every time you reboot the device):

# If the USB cable is plugged and in "Mass storage mode", unplug the cable and plug it again, now selecting "PC Suite Mode".
# On N900, open "X Terminal" and run:
rootsh ifup usb0
# Now you need to configure the host. This is dependent on which OS (or Linux distro) you use, see http://wiki.maemo.org/USB_networking#Host_USB_Network_Configuration for detailed instructions for various OSes and Linux distros.

From now on you can connect to the N900 using any SSH client and the following information:
Host: 192.168.2.15
Port: 22
User: root
Password: the password setup earlier

For instance, from a Linux terminal, you can connect to the tablet using this command:

ssh root@192.168.2.15

== Preparing the N900 for Python Development ==

To enable the full power for Python development for Maemo, you must enable the "extras-devel" repository on your device. ''Be advised that this might be a risky operation'' because extras-devel contains many untested and possibly broken packages. But it also contains the latest versions of all available Python bindings for Maemo, which we are interested on.

Note that the requirement to enable the "extras-devel" repository might be removed later.

To enable extras-devel add a new catalogue to the Application Manager, as instructed in http://wiki.maemo.org/Extras-devel (did you see the big warning on that page?)

After extras-devel is enabled, you will see on Application Manager a package called "maemo-python-device-env". Installing it will also install the basic environment necessary to run most Python applications on Maemo.

== Writing your code ==

Any good programmer oriented editor will be enough for development. If you have some development experience, you most probably already have chosen your favorite code editor and you can simply use it.

Here we list some options, both for Linux and Windows:

* [http://projects.gnome.org/gedit/ gedit]: the GNOME Editor has syntax highlight support for Python (Linux only)
* [http://www.vim.org/ VIM] and [http://www.gnu.org/software/emacs/ Emacs]: the most popular editors, with many advanced features and versions for both Linux and Windows
* [http://wiki.netbeans.org/Python NetBeans + Python plugin]: NetBeans is a multi-platform IDE, which with help of a plugin, supports development for Python

Note that none of these editors will support code completion for PyMaemo modules out of box.

For testing purposes, you can try the following code (the classic "hello world" example):

import gtk
from gtk import Window, Button, Widget
if __name__ == "__main__":
window = Window(gtk.WINDOW_TOPLEVEL)
window.connect("destroy", gtk.main_quit)
button = Button("Hello World")
button.connect_object("clicked", Widget.destroy, window)
window.add(button)
window.show_all()
gtk.main()

Once you have your code written, you can proceed to copying application files to the device.

== Running the Python application on the device ==

Now that you have the N900 properly setup and the code to run, you just need to copy the application files to the device and run it.

The simplest way to copy files it to use a SFTP or SCP client. There are many free clients available for most OSes (we listed some examples on the "Requirements" section). On the Linux command line, you can use:

scp -pr my_application/ root@192.168.2.15:/root/my_application/

Replace "my_application/" with the path to the directory which contains your application files.

Finally, to run the application on the tablet, use (from a SSH terminal):

cd /root/my_application
python my_application.py

== Alternative development environments ==

Besides the environment described on this article, there are two alternative development environments that might or might not be more appropriate for your purposes:

; PluThon (Eclipse based)
: [http://pluthon.garage.maemo.org/ PluThon] is a full Python IDE for Maemo, based on Eclipse. While PluThon is easy to use and provides a complete solution, it is not necessary for basic Python development for Maemo. If you already use Eclipse for your development, PluThon might be your best option.
; Official Maemo SDK (Scratchbox based)
: [http://www.scratchbox.org/ Scratchbox] is a cross-compilation toolkit used for native Maemo development. Although it can be used in Python development as well (and comes very handy if you do not have access to a real device), it has a non-trivial learning curve and is not needed for pure Python development. However, if you plan to write new Python extensions (for instance, using [http://www.cython.org/ Cython] or [http://docs.python.org/c-api/index.html Python/C API] directly), Scratchbox is needed to cross-compile the C code. See the [http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Development_Environment/Maemo_SDK Maemo SDK section] on Maemo 5 developer guide for more details on it.

Note that PluThon has built-in support for transferring and running code on the device. On the other hand, the Maemo SDK has no such support (unless you use some IDE like [http://esbox.garage.maemo.org/ ESbox]), so you need to follow steps similar to the ones described on this guide to copy and run your code on the tablet, if you choose to use the Maemo SDK.

== Advanced tips ==

If you want to activate USB networking automatically upon connecting the device to the computer, just create a file called /etc/event.d/usbnet on the device with the following contents:

start on G_NOKIA_READY

console output
exec ifconfig usb0 192.168.2.15 up

This way you just have to select "PC Suite mode" when connecting the device and you're done.

[[Category:N900]]
[[Category:Python]]

PyMaemo/UI tutorial/Data selection

2009-10-16T16:15:32Z

189.2.128.130: /* Picker dialog and picker buttons */

= Data selection =
Hildon provides a set of widgets for data selection specially designed for touchscreens that allows to build simple and easy-to-use interfaces.

The key widget is a selector widget that allows users to select items from one to many predefined lists. It is similar to a combo box but allows several individual pannable columns.

In addition, Hildon also provides a specialized dialog and a specialized button to be used in combination with a selector.

==Touch selector ==
HildonTouchSelector is the mentioned selector widget. This widget can display several pannable columns. Each column is represented by a GtkTreeModel and single or multiple selection is allowed.

===Text Columns Example===
Let us see the simplest possible example. A selector that shows a single text column.

'''Example 6.1. Example of a single-column selector'''

[[Image:example-single-text-column-selector.png|400px]]

# Based on C code from:
# "Hildon Tutorial" version 2009-04-28
# Example 5.6, "Example of a single-column selector"

import gtk
import hildon

def selection_changed(selector, user_data):
current_selection = selector.get_current_text()
print "Current selection : %s" % (current_selection)

def create_simple_selector():
#Create a HildonTouchSelector with a single text column
# selector = hildon.TouchSelector()
selector = hildon.hildon_touch_selector_new_text()

# Set selection mode to allow multiple selection
selector.set_column_selection_mode(hildon.TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE)

# Set a handler to "changed" signal
selector.connect("changed", selection_changed)

# Populate selector
for i in range(10):
label = "Item %d" % i
# Add item to the column
selector.append_text(label)

return selector

def app_quit(widget, data=None):
gtk.main_quit()

def main():
program = hildon.hildon_program_get_instance()
gtk.set_application_name("hildon-touch-selector example program")

window = hildon.StackableWindow()
program.add_window(window)

# Create touch selector
selector = create_simple_selector()
window.add(selector)

window.connect("destroy", app_quit)

window.show_all()

gtk.main()

if __name__ == "__main__":
main()

A HildonTouchSelector with a single text column is created in this program using the following convenience constructor.

hildon.touch_selector_new_text()

To add text to a selector created by calling the constructor above, use the function.

def append(self, text):

Alternatively, you can use <code>prepend_text()</code> or <code>insert_text()</code> to add text to the selector in different positions.

You can set the desired selection with the function. In the example, the mode was set to allow multiple selection.

def set_column_selection_mode(self, mode):

This example shows a very common use case of this widget. Next section shows how to build a more complex selector with several columns of different types.

Also a simple function was set as a handler for the "changed" signal which is emitted each time the selected items change.

The callback retrieves a text representation of the currently selected items in the selector by calling <code>get_current_text()</code>. By default this function returns a concatenation of the items selected, separated by a comma.

To change how the text representation is generated, set your own function by calling <code>set_print_func()</code> and using the following signature for the function:

def user_function (selector):

===Custom columns===

In the previous section, a selector with a text column was created. That is probably the most common use case of touch selectors. Convenience functions to deal with text columns was used. However, you can also set other type of columns.

Because each column is basically a treeview, you can use the same display to different data and in different ways as you would do with a GtkTreeview. Thus, you can use the GtkCellRenderers available in GTK+ to display the data on each cell.

This section explains how to build a selector within a column displaying stock icons. Firstly, let us take a look on the function which used for appending new columns to a touchable selector.

def append_column(self, model, cell_renderer, ...):

This functions adds a new column to the widget whose data is obtained from the passed model. Pass also a GtkCellRenderer and a list of pairs property/value which is set as attributes of the renderer.

This function basically adds a GtkTreeView to the widget. For more information on how GtkTreeviews work, see [http://library.gnome.org/devel/pygtk/stable/class-gtktreeview.html GTK+ widgets] before.
The following example shows how to set a column to display images in a selector. For clarity, only the function which creates the selector is shown.

'''Example 6.2. Example of a selector with a custom column'''

[[Image:example-single-column-selector.png|400px]]

# Based on C code from:
# "Hildon Tutorial" version 2009-04-28
# Example 6.2 "Example of a selector with a custom column"

import gtk
import hildon
import gobject

def selection_changed(selector, user_data):
current_selection = selector.get_current_text()
print "Current selection : %s" % (current_selection)

def create_customized_selector():
# Create a touch selector
selector = hildon.TouchSelector()

# Stock icons will be used for the example
icon_list = gtk.stock_list_ids()

# Create model to store selector's items
store_icons = gtk.ListStore(gobject.TYPE_STRING);

# Populate model
for item in icon_list:
new_iter = store_icons.append()
store_icons.set(new_iter, 0, item)

# Create and set up a pixbuf renderer to use in the selector
renderer = gtk.CellRendererPixbuf()
renderer.set_fixed_size(-1, 100)

# Add the column to the selector
# FIXME: bug 4646
#column = selector.append_column(store_icons, renderer, "stock-id", 0)

# Set the selection mode
selector.set_column_selection_mode(hildon.TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE)

# Set the property "text-column" that indicates the column
# of the model to get the string from
column.set_property("text-column", 0)

return selector

def app_quit(widget, data=None):
gtk.main_quit()

def main():
program = hildon.hildon_program_get_instance()
gtk.set_application_name("hildon-touch-selector example program")

window = hildon.StackableWindow()
program.add_window(window)

# Create touch selector
selector = create_customized_selector()
window.add(selector)

window.connect("destroy", app_quit)

window.show_all()

gtk.main()

if __name__ == "__main__":
main()

The first step in the example is to create and populate a GtkTreeModel. A GtkListStore is used in the example. In most use cases of the touchable selectors a GtkListStore fits well as selectors were designed to allow users to select from a list of items.

In this case, the model stores a list of GTK+ stock icons identifiers. The following call creates a list store with one column to store strings.

store_icons = gtk.ListStore(G_TYPE_STRING);

The following loop appends all stock identifiers in the newly created model. The identifiers were previously retrieved using

for item in icon_list:
new_iter = store_icons.append()
store_icons.set(new_iter, 0, item)

The next step is to set up the renderer which renders each row of the new column. We need a GtkCellRendererPixbuf to display the stock icons.

renderer = gtk.CellRendererPixbuf()

Finally, we create and append the new column, using the model and renderer previously created.

This call also sets the property "stock-id" of the GtkCellrendererPixbuf. The value is set to 0 which is the number of the column in the GtkTreeModel that stores the stock-id.

column = selector.append_column(store_icons, renderer, "stock-id", 0)

To summarize, setting a new custom column in a touchable selector is quite similar to setting a new column in a normal GtkTreeview. Create a model to store the data and a cell renderer to properly show this data in each row, and finally add the new column.

==Picker dialog and picker buttons ==
Normally, you use HildonTouchSelector together with a HildonPickerDialog activated from a button. For most common cases you use HildonPickerButton.

This is the usual way to present a selector to the user. The picker button opens a dialog which presents the selector and properly manages user interaction.

'''Example'''

Previous sections showed you how to create a touchable selector. In most cases the next step is to attach the selector to a HildonPickerButton.

A HildonPickerButton is a special GtkButton which displays two labels, title and value, and brings up a HildonPickerDialog. The user chooses one or several items. A string representation of the chosen items is displayed in the value label of the picker button.

Below, a modified version of the previous main function is shown, in which you can check how a HildonPickerButton is created and attached to a selector. Also a callback to catch the signal "value-changed" emitted is added.

[[Image:example-picker-button.png|400px]]

'''Example 6.3. Example of a Hildon picker button'''

# Based on C code from:
# "Hildon Tutorial" version 2009-04-28
# Example 6.3, "Example of a Hildon picker button"

import gtk
import hildon
import gobject

def on_picker_value_changed(button, user_data=None):
print "Newly selected value: %s\n" % button.get_value()

def app_quit(widget, data=None):
gtk.main_quit()

def create_customized_selector():
# Create a touch selector
selector = hildon.TouchSelector()

# Stock icons will be used for the example
icon_list = gtk.stock_list_ids()

print icon_list

# Create model to store selector's items
store_icons = gtk.ListStore(gobject.TYPE_STRING)

# Populate model
for item in icon_list:
new_iter = store_icons.append()
store_icons.set_value(new_iter, 0, item)

# Create and set up a text renderer to use in the selector
renderer = gtk.CellRendererPixbuf()
renderer.set_fixed_size(-1, 100)

# Add the column to the selector
column = selector.append_column(store_icons, renderer, stock_id=0)

# Set the selection mode
selector.set_column_selection_mode(hildon.TOUCH_SELECTOR_SELECTION_MODE_MULTIPLE)

# Set the property "text-column" that indicates the column
# of the model to get the string from
column.set_property("text-column", 0)

return selector

def main ():
program = hildon.Program.get_instance()
gtk.set_application_name("hildon-touch-selector example program")

window = hildon.StackableWindow()
program.add_window(window)

# Create touch selector
selector = create_customized_selector()

# Create a picker button
picker_button = hildon.PickerButton(gtk.HILDON_SIZE_AUTO,
hildon.BUTTON_ARRANGEMENT_VERTICAL)

# Set a title to the button
picker_button.set_title("Select an item")

# Attach the touch selector to the picker button
picker_button.set_selector(selector)

# Attach callback to the "value-changed" signal
picker_button.connect("value-changed", on_picker_value_changed)

# Add button to main window
window.add(picker_button)

window.connect("destroy", app_quit)
window.show_all()
gtk.main()

if __name__ == "__main__":
main()

In the above example a picker button is created. The reference to the attached selector is stored in the property "touch-selector" of the picker button. To retrieve the attached selector , use function <code>hildon.PickerButton()</code>. To attach the selector, use the function <code>picker_button.set_selector()</code>.

Note that you do not need to take care of the HildonPickerDialog. The dialog is automatically brought up when users click the picker button and closed when the selection is done.

The dialog shows a button "Done" to allow users finish the selection when the touchable selector allows multiple selection. When the selector allows only single selection, the dialog does not show any button and closes when the user taps on one item.

The label of the button "Done" can be set by using <code>set_done_button_text()</code> and retrieved by using <code>get_done_button_text()</code>.

When users finish their selection, the value label on the button automatically changes to show a textual representation of the item or items selected.

In most cases you want to perform any action when selection is finished. To do that, add a handler to the signal "value-changed" of the picker button. In this example the handler attached to "value-changed" signal retrieves the value label of the button and prints a debug message.

==Touch selector entry ==
The HildonTouchSelectorEntry is a selector widget with a text entry that allows users to select an item from a predefined list or to enter a different one in a HildonEntry. Items can also be searched and selected by typing in the entry.

An additional feature is that the HildonEntry is auto-completed with the list's items as the user types their name.

Example below shows how to build a selector to pick a word in a list of words.

[[Image:Touch_selector_entry.png|400px]]

'''Example 6.4. Example of a Hildon picker button with a selector entry'''

# Based on C code from:
# "Hildon Tutorial" version 2009-04-28
# Example 6.4, "Hildon picker button with a selector entry"

import gtk
import hildon

def app_quit(widget, data=None):
gtk.main_quit()

def main ():
artists = [
"AC/DC",
"Aerosmith",
"Alice in Chains",
"Black Sabbath",
"Carcass",
"Danzig",
"Deep Purple",
"Dream Theater",
"Eric Clapton",
]

program = hildon.hildon_program_get_instance()
gtk.set_application_name("hildon-touch-selector example program")

window = hildon.StackableWindow()
program.add_window(window)

# Create a picker button
picker_button = hildon.PickerButton(gtk.HILDON_SIZE_AUTO,
hildon.BUTTON_ARRANGEMENT_VERTICAL)

# Set a title to the button
picker_button.set_title("Pick a band!")

# Create a touch selector entry */
# FIXME: bug 4647
selector = hildon.hildon_touch_selector_entry_new_text()

# Populate the selector
for artist in artists:
selector.append_text(artist)

# Attach the touch selector to the picker button
picker_button.set_selector(selector)

# Add button to main window
window.add(picker_button)

window.connect("destroy", app_quit)
window.show_all()
gtk.main()

if __name__ == "__main__":
main()

As you can see in the example above, the use of this widget is similar to using a normal touchable selector.

You can also use custom columns in a HildonTouchableEntry but at least one column must be a text column. The text column is indicated by the property "text_column" which you set with <code>set_text_column()</code>.

==Pre-built selectors ==
The widgets HildonDateButton and HildonTimeButton are buttons displaying and allowing the selection of date and time, respectively. Developers can use them directly instead of building their own date or time selectors.

Both widgets are specialized picker buttons with a convenient touchable selector attached that you can use directly in your application.

Here a simple application using a HildonDateButton.

'''Example 6.5. Example of a Hildon date button'''

# Based on C code from:
# "Hildon Tutorial" version 2009-04-28
# Example 6.5, "Example of a Hildon date button"

import gtk
import hildon

def app_quit(widget, data=None):
gtk.main_quit()

def main ():
program = hildon.hildon_program_get_instance()
gtk.set_application_name("hildon-touch-selector example program")

window = hildon.StackableWindow()
program.add_window(window)

# Create a date picker
date_button = hildon.DateButton(gtk.HILDON_SIZE_AUTO,
hildon.BUTTON_ARRANGEMENT_VERTICAL)

# Set a title to the button
date_button.set_title("Select an item")

# Add button to main window
window.add(date_button)

window.connect("destroy", app_quit)
window.show_all()
gtk.main()

if __name__ == "__main__":
main()

PyMaemo/UI tutorial/Getting started

2009-10-16T12:28:41Z

189.2.128.130: /* Getting started */

=Getting started=
Before starting to develop your Hildon applications you need to get, install and properly configure the Maemo SDK. You can download and learn how to use the latest SDK in [http://maemo.org/development/sdks/ Maemo SDK Releases].

To begin our introduction to Hildon, we start with the simplest program possible - base.py. This program creates a window and has no way of exiting except to be killed by using the shell.

'''Example 1.1. Simple Hildon program'''

# Based on C code from:
# "Hildon Tutorial" version 2009-04-28
# Example 1.1, "Simple Hildon program"

import gtk
import hildon

def main():
gtk.set_application_name("Simplest example")

window = hildon.Window()
window.show()

gtk.main()

if __name__ == "__main__":
main()

To run the program you can use:

run-standalone.sh python2.5 base.py

All programs will import hildon which declares the variables, functions, structures, etc. that will be used in your Hildon application.

The next two lines of code create and display a window.

window = hildon.Window()
window.show()

The hildon.Window used in this example represents a top-level window in the Hildon framework. It is derived from gtk.Window and provides additional commodities specific to the Hildon framework.

In very simple applications, hildon.Window could be enough. However, in most of the applications a hildon.StackableWindow should be used. Next chapters will clarify this.

The show() shows the widget (makes it visible) that would not be otherwise displayed.

The last line enters the GTK+ main processing loop.

gtk.main();

This call can be found in every GTK+ application and therefore, in every Hildon application. When control reaches this point, GTK+ will sleep waiting for X events (such as button or key presses), timeouts, or file IO notifications to occur. In our simple example, however, events are ignored.

==Hello World in Hildon ==

To begin our introduction to Hildon, we introduce the classic Hello World, Hildon style. This program will create a window with a widget (a button).

'''Example 1.2. Hildon Hello World program'''

# Based on C code from:
# "Hildon Tutorial" version 2009-04-28
# Example 1.2, "Hildon Hello World program"

import gtk
import hildon

# This is a callback function. The data arguments are ignored in this example.
def hello(widget, data):
print "Hello World!"

def main():
# Get an instance of HildonProgram. It is an object used to represent an
# application running in the Hildon framework.
program = hildon.Program.get_instance()

# create a new hildon window
window = hildon.Window()

# Registers a window as belonging to the program
program.add_window(window)

# When the window is given the "delete_event" signal (this is given by the
# window manager, usually by the "close" option, or on the titlebar), we
# ask it to call the delete_event () function as defined above. The data
# passed to the callback function is None and is ignored in the callback
# function.
window.connect("delete_event", gtk.main_quit, None)

button = hildon.Button(gtk.HILDON_SIZE_AUTO, hildon.BUTTON_ARRANGEMENT_VERTICAL, "Hello world!")

# When the button is given the "clicked" signal, we ask it to call the
# hello () function as defined above. The data passed to the callback
# function is None and is ignored in the callback function.
button.connect("clicked", hello, None)

# This packs the button into the window (a GTK+ container).
window.add(button)

# The final step is to display this newly created widget and all widgets it
# contains.
window.show_all()

# All GTK+ applications must have a gtk_main(). Control ends here and waits
# for an event to occur (like a key press or mouse event).
gtk.main()

if __name__ == "__main__":
main()

As you can see in this simple example, writing Hildon applications is slightly different from writing standard GTK+ applications. We are going to review these differences through the next chapters.

==Running Hello World ==

To run use:

run-standalone.sh python2.5 hello-world.py

==Stepping through Hello World ==

This section explains the Hello World example above step-by-step.

The following lines define the callback function that is called when the button is clicked. We ignore both the widget and the data in this example, but usually developers would need to handle events from them.

def hello(widget, data):
print "Hello World!"

Here starts the definition of the main function like it is usually done in programs written in Python.

if __name__ == "__main__":
main()

Before using Hildon, it is needed to import it. This import connects to the window system display.

import hildon

Only one HildonProgram can be created per process. Use <code>hildon.Program.get_instance()</code> to access it.

program = hildon.Program.get_instance()

In this simple example, a new HildonWindow is created. In cases with nested views, use a HildonStackableWindow.

window = hildon.Window()

This call registers a window as belonging to the program. This allows applying program-wide settings to all the registered windows, such as assigning a common menu to all the registered windows by setting it to the program.

program.add_window(window)

The following code is an example of connecting a signal handler to an object, in this case, the window. The function gtk.main_quit() is set as a handler to the “delete_event” signal. This function tells GTK+ that it must exit from gtk.main() when control is returned to it, making the program terminate.

window.connect("delete_event", gtk.main_quit)

This call creates a new HildonButton. This button allows to set two labels, one main label and another secondary one. You can also set the size of the button and the order of the labels. Notice that you can use GtkButton's in Hildon applications in case you do not need the additional features that Hildon provides.

button = hildon.Button(gtk.HILDON_SIZE_AUTO, hildon.BUTTON_ARRANGEMENT_VERTICAL, "Hello world!")

Here, a signal handler is attached to the newly created button so that when it emits the "clicked" signal, our <code>hello()</code> function is called. The data is ignored, so we simply pass in NULL to the <code>hello()</code> callback function. Obviously, the "clicked" signal is emitted when the button is pressed.

button.connect("clicked", hello, None)

This packing call tells GTK+ to place the button in the window. For more information, see the Packing Widgets section of the [http://library.gnome.org/devel/pygtk/stable/] Tutorial.

window.add(button)

When everything is set up with all signal handlers in place and the button placed in the window, we ask GTK to "show" the widgets on the screen.

window.show_all()

And of course, we call gtk_main() which waits for events to come from the X server and will call on the widgets to emit signals when these events come.

gtk.main()

PyMaemo

2009-10-15T19:51:49Z

189.2.128.130: /* Ye Olde Documentation */

== What is PyMaemo? ==

The [http://pymaemo.garage.maemo.org/ PyMaemo] (Python for Maemo) project maintains a set of packages necessary to run and develop Python applications on the Maemo platform.

== Supported Software ==

We currently maintain support for the python interpreter, bindings and a few applications in the Maemo platform. A detailed list can be found in [[PyMaemo/Components]].

=== In progress documentation ===

This section contains links to documentation that is still being written.

* [[PyMaemo/Python26PortingGuide|Python 2.6 porting guide]]
* [[PyMaemo/PythonOssoExamples|Python OSSO Examples]]

== Using it ==

[[PyMaemo/Installation]]

[[PyMaemo/ManualInstallation]]

[[PyMaemo/SDKInstallation]]

[[PyMaemo/FAQ]]

== Screenshots ==

[[PyMaemo/Screenshots]]

== Documentation ==

* [[PyMaemo/UITutorial|Graphical UI Tutorial]]

== Ye Olde Documentation ==

This section contains documentation that is quite old (770, Chinook, etc).

* [[PyMaemo/UsingPythonInMaemo|Using Python in Maemo]]
* [http://maemo.org/development/documentation/apis/3-x/python-maemo-3.x/ API Documentation (Maemo 3.x Bora)]
* [http://www.teemuharju.net/2006/01/26/coding-for-nokia-770-using-python-part-1/ Coding for Nokia 770 using Python part 1]
* [http://www.teemuharju.net/2006/02/08/coding-for-nokia-770-using-python-part-2/ Coding for Nokia 770 using Python part 2]
* [http://my.opera.com/monroe/blog/pymaemo-tips Jason's useful tips for PyMaemo development]
* [http://pycage.blogspot.com/2007/12/tablet-python-1-relocatable-software.html Martin's useful tips for PyMaemo development]
* [[PyMaemo/Python-GPSbt|python-gpsbt introduction and example (only applicable to Maemo 4.x)]]

PyMaemo/HildonDesktop

2009-09-28T14:48:57Z

189.2.128.130: /* Testing the example */

== Python bindings for libhildondesktop ==

These bindings allow to create the so called Hildon Home and Status Menu applets (or widgets, in Maemo 5). It consists of two binary packages:

* python-hildondesktop: the actual Python bindings. Can be used to write standalone widgets, or ones that can be added by the user using the "Add widget" option in Maemo 5.
* hildon-desktop-python-loader: this is a Hildon Desktop loader for Python plugins.

=== API changes for Fremantle ===

The libhildondesktop version in Fremantle contains some API changes that also reflect on the Python bindings. Namely, you should pay attention to the following differences when migrating Home Widgets from older Maemo releases to Fremantle:

* The base class for Home Widgets is now called "HomePluginItem", instead of the older "HomeItem" name.
* The base class for Status menu widgets is now called "StatusMenuItem", instead of the older "StatusBarItem".
* The callback function that is called by the load is now called "hd_plugin_get_object", instead of the older "hd_plugin_get_objects". This is so because in fremantle the plugin is can create only one plugin object.
* Also note that the "hd_plugin_get_object" function should return a single object, instead of a list.
* The returned object must be instantiated using the gobject.new() function (see the example below). This is necessary because the plugin-id property needs to be set, otherwise the hildon-home process will crash.

NOTE: this last requirement might change in future, to avoid the mentioned crash.

=== Example - Home widgets (Fremantle only) ===

The code below was based on the C example that can be found on the maemo-examples package sources [https://garage.maemo.org/svn/maemoexamples/branches/fremantle-sdk-testing/maemo-examples/hello-world-home.c].

<pre>
import gobject
import gtk
import hildondesktop

class HelloWorldButton(gtk.Button):
def __init__(self, padding):
gtk.Button.__init__(self)
icon_theme = gtk.icon_theme_get_default()
icon = icon_theme.load_icon("hello", 40, 0)
if icon is None:
icon = icon_theme.load_icon("qgn_list_gene_default_app", 40, 0)
icon_image = gtk.Image()
icon_image.set_from_pixbuf(icon)
icon_image.set_padding(padding, padding)
self.add(icon_image)
self.show_all()

class HelloWorldDialog(gtk.Dialog):
def __init__(self):
gtk.Dialog.__init__(self, "Hello World", None,
gtk.DIALOG_DESTROY_WITH_PARENT | gtk.DIALOG_NO_SEPARATOR,
("Close", gtk.RESPONSE_OK))
self.vbox.add(gtk.Label("Hello World!"))
self.show_all()

def hello_world_dialog_show(button):
dialog = HelloWorldDialog()
dialog.run()
dialog.destroy()

class HelloHomePlugin(hildondesktop.HomePluginItem):
__gtype_name__ = 'HelloHomePlugin'

def __init__(self):
hildondesktop.HomePluginItem.__init__(self)
button = HelloWorldButton(10)
button.connect("clicked", hello_world_dialog_show)
button.show_all()
self.add(button)

def hd_plugin_get_object():
return gobject.new(HelloHomePlugin, plugin_id="hello_world_home")

if __name__ == "__main__":
obj = hd_plugin_get_object()
obj.show_all()
gtk.main()
</pre>

=== Testing the example ===

First, add Fremantle extras-devel to the /etc/apt/sources.list in your scratchbox target and install the required packages:

<pre>
[sbox]> fakeroot apt-get install python-hildondesktop hildon-desktop-python-loader
</pre>

Save the example code shown above as /usr/lib/hildon-desktop/hello_world_home.py inside your FREMANTLE_X86 target. Next, save the following text as /usr/share/applications/hildon-home/hello_world_home.desktop:

<pre>
[Desktop Entry]
Name=Hello, World! (Python)
Comment=Example Home Python plugin
Type=python
X-Path=hello_world_home.py
</pre>

Make sure the hildon desktop and hildon-home are running. For that, you can use the following commands:

<pre>
[sbox]> export DISPLAY=:2 # if you are using scratchbox + Xephyr
[sbox]> af-sb-init.sh start
[sbox]> run-standalone.sh maemo-summoner /usr/bin/hildon-home.launch &
</pre>

Now you need to add the newly installed home widget to the desktop. For that you can either manually add it to the ~/.config/hildon-desktop/home.plugins file, or follow these instructions to add it using the Hildon Desktop interface:

# Click anywhere on the Maemo desktop background.
# You should see a "engine" icon on the top right. Click on it.
# It will be shown a menu bar containing "Desktop menu" and "Done". Click on "Desktop menu".
# You should now see a menu with 4 buttons. Click on the "Add widget" button.
# A menu containing the list of installed widgets will appear. Select the one we installed, called "Hello, World! (Python)".
# Finally, click on "Done".

You should then see the following (the images look distorted because they were taken on Xephyr):

[[Image:Hello_world_home_python1.png]]

After clicking on the widget button, you should see:

[[Image:Hello_world_home_python2.png]]

=== Example - Status menu widgets (Fremantle only) ===

The code below was based on the C example that can be found on the Maemo 5 Developer Guide [http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Application_Development/Writing_Desktop_Widgets#Status_Menu_widgets].
<pre>
import gobject
import gtk
import hildondesktop

class ExampleStatusPlugin(hildondesktop.StatusMenuItem):
__gtype_name__ = 'ExampleStatusPlugin'

def __init__(self):
hildondesktop.StatusMenuItem.__init__(self)

STATUS_AREA_EXAMPLE_ICON_SIZE = 22
icon_theme = gtk.icon_theme_get_default()
pixbuf = icon_theme.load_icon("general_email", STATUS_AREA_EXAMPLE_ICON_SIZE, gtk.ICON_LOOKUP_NO_SVG)
self.set_status_area_icon(pixbuf)

label = gtk.Label("Example message")
self.add(label)
self.show_all()

def hd_plugin_get_object():
return gobject.new(ExampleStatusPlugin, plugin_id="example_status_plugin")

if __name__ == "__main__":
obj = hd_plugin_get_object()
obj.show_all()
gtk.main()
</pre>

=== Testing the example ===

First, install the same packages needed for Home widgets, then save the example above as as /usr/lib/hildon-desktop/hello_world_status_menu.py inside your FREMANTLE_X86 target. Next, save the following text as /usr/share/applications/hildon-status-menu/hello_world_status_menu.desktop:

<pre>
[Desktop Entry]
Name=Hello, World! (Python)
Comment=Example Status Menu Python plugin
Type=python
X-Path=hello_world_status_menu.py
</pre>

Make sure the hildon desktop and hildon-status-menu are running. For that, you can use the following commands:

<pre>
[sbox]> export DISPLAY=:2 # if you are using scratchbox + Xephyr
[sbox]> af-sb-init.sh start
[sbox]> run-standalone.sh maemo-summoner /usr/bin/hildon-status-menu.launch &
</pre>

The example status menu widget should appear as soon as hildon-status-menu process is started, as the plugin used in this example is of the permanent category. See [http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Application_Development/Writing_Desktop_Widgets#Status_Menu_widgets] for more information of status menu widgets categories.

This is a screenshot taken on Xephyr showing how the widget will look like:

[[Image:Status-menu-1.png]]

When clicked, it will show the specified message, enclosed in a gtk.Label:

[[Image:Status-menu-2.png]]