PyMaemo/Scratchboxless packaging guide

(Fix some typos)
 
(16 intermediate revisions not shown)
Line 1: Line 1:
== Introduction ==
== Introduction ==
-
The usual way of developing Maemo applications is using or 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.
+
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, building the packages and uploading it to extras-devel.
+
This tutorial will show how to integrate it into your project, build the packages and upload them to extras-devel.
== Prerequisites ==
== Prerequisites ==
-
This tutorial is aimed at Debian-based systems, as some stdeb commands requires the dpkg tools installed. In
+
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.
+
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].
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].
Line 15: Line 27:
== Preparing the package ==
== 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] [1] and an [http://pymaemo.garage.maemo.org/stdeb_example/myscript-app/myscript.png icon] [2], the [http://pymaemo.garage.maemo.org/stdeb_example/myscript-app/setup.py setup.py] will look like this:
+
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">
<source lang="python">
from distutils.core import setup
from distutils.core import setup
Line 29: Line 41:
)
)
</source>
</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].
+
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]
  [DEFAULT]
-
  XS-Python-Version: 2.5 # Only version currently supported by pymaemo.
+
  XS-Python-Version: 2.5 # Only version currently supported by PyMaemo.
-
  Package:myscript # Binary package name. stdeb adds the prefix "python-" by default
+
  Package:my-script # Binary package name. stdeb adds the prefix "python-" by default
-
  Section: user/other # Section should start with user/ to appear in the menu.
+
  Section: user/development # Section should start with user/ to appear in the menu.
-
  Depends: python-gtk2 # add extra dependencies here
+
  Depends: python-gtk2 # extra dependencies go here
-
Make sure to use [http://wiki.maemo.org/Maemo_packaging#Sections an allowed section] - otherwise autobuilder will give a warning.
+
<b>Warning 1</b>: Make sure to use [[Maemo_packaging#Sections|an allowed section]].
 +
 
 +
<b>Warning 2</b>: 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 ==
== Building the packages ==
Line 55: Line 71:
== Building a basic debian directory ==
== 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.
+
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/.
Note: sdist_dsc and bdist_deb do '''not''' use this directory, generating a new one in the source dir under deb_dist/.
Line 65: Line 81:
  $ dpkg-buildpackage -rfakeroot -uc -us -S
  $ 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]]
+
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:
-
== Future work ==
+
PYTHONPATH=/path/to/sboxless python setup.py --command-packages=sboxless  sdist_deb
-
Support for non-debian systems.
+
The source files will be generated on the ./dist directory.
== References ==
== References ==
-
[1] http://wiki.maemo.org/Desktop_file_format
 
-
[2] http://wiki.maemo.org/Maemo_packaging#Displaying_an_icon_in_the_Application_Manager_next_to_your_package
+
<references />
[[Category:Python]]
[[Category:Python]]
[[Category:Packaging]]
[[Category:Packaging]]

Latest revision as of 13:46, 2 March 2011

Contents

[edit] 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 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.

[edit] 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 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 this ppa, following the instructions here.

[edit] 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 single script named "myscript" and support files like .desktop[1] and an icon[2], the setup.py will look like this:

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'])],
)

A file named 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 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 an allowed section.

Warning 2: The Depends 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, twcano depends on the following packages: python-simplejson, pyside-qt4-maemo5, pyside-qt4-webkit and python-twitter, so the Depends field should be filled this way:

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

[edit] 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

[edit] 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 stdeb website.

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

[edit] 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 upload the application to extras-devel.


[edit] Support for non-Debian systems

Image:Ambox_notice.png
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 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.

[edit] References

  1. Desktop file format
  2. Packaging#Displaying an icon in the Application Manager next to your package