Python/pyside-assistant

Latest revision as of 23:45, 27 February 2012

Setting up

Installing from Ubuntu PPA

If you are using Ubuntu then you can add PySide's ppa and get pyside-assistant from there:

sudo add-apt-repository ppa:pyside

If you're using Ubuntu Oneiric you have to add this to /etc/apt/sources.list.d/pyside-ppa-oneiric.list

deb http://ppa.launchpad.net/pyside/ppa/ubuntu natty main

Then run

 
sudo apt-get update
sudo apt-get install pyside-assistant

Building and installing from source

To build and install pyside-assistant you will need a Debian-based Linux distribution. First, install python2.6, sharutils and python-stdeb packages, that are runtime dependencies of pyside-assistant. Get the source from the Github page, then in the directory which pyside-assistant was downloaded, run:

    $ dpkg-buildpackage -D -rfakeroot -us -uc

Warning: Do not install python-stdeb from the git sources, or pyside-assistant will not work properly! The version from Debian and Ubuntu (0.6.0+20100620-1) works as expected.

Now go back a directory level and install the binary package:

    $ sudo dpkg -i pyside-assistant_<version>_all.deb

Usage Instructions

The main script for using pyside-assistant is psa.

list command

The list command lists all templates available.

    $ psa list

Currently available templates are:

fremantle

For N900 devices.

harmattan

For N9/N950 devices.

ubuntu-qml

Ubuntu project using QML for user interface.

ubuntu-qtgui

Ubuntu project using QtGui for user interface.

init command

The init command creates a project from the templates. It receives two mandatory arguments: a string that identifies the entire project, called project slug, and the target template (e.g. harmattan). The following call will create a project in the current directory with the project slug sampleproject:

    $ psa init sampleproject harmattan

All project files will be contained in a directory named after the project slug, which in this case is sampleproject. Additional parameters can be passed to psa init to set various fields from the start; these parameters are shown below:

    -a APPNAME, --app-name=APPNAME
                        Human-readable application name, refers to the Name field of sampleproject.desktop
    -s SECTION, --section=SECTION
                        Application section, refers to the section field of stdeb.cfg
    -d DESC, --description=DESC
                        Application short description, refers to the description field of setup.py
    -c CATEGORY, --category=CATEGORY
                        Application category, refers to the appname field of sampleproject.desktop

The created projects come with a file called README.assistant, which lists what each file does. The contents of this file is listed below:

=========================================
README - pyside-assistant generated files
=========================================

All files generated by psa init are described below. The sampleproject
slug used for them was 'sampleproject', with the following psa call:

    $ psa init sampleproject <fremantle|harmattan|...>

To list all available templates, use:

    $ psa list

* MANIFEST.in: Distutils considers a list of files by default for
installation, listed at [1].  Additional files to be distributed
must be supplied in the MANIFEST.in file. The generated file includes
the .desktop file and any QML files found.

[1] http://docs.python.org/distutils/sourcedist.html#specifying-the-files-to-distribute.

* setup.py: The main file for using Distutils, contains most of the
information needed to build the package. Information about setup.py
can be found at http://docs.python.org/distutils/introduction.html.
Two fields of this file can be modified by psa update parameters:
 - description: -d or --description
 - long_description: the contents of sampleproject.longdesc are used

* stdeb.cfg: Configuration file for stdeb, specifying additional
parameters for the binary package. The specification for this
file can be found at https://github.com/astraw/stdeb, in the section
stdeb.cfg configuration file. One field of this file can be modified by
psa update parameters:
 - Section: -s or --section

Note that the section should be a valid one,
as specified in http://wiki.maemo.org/Task:Package_categories#New_list_for_Diablo.

* sampleproject.aegis: Sample credentials file, which initially is empty. Information
of how to populate it can be found at [2].
NOTE: this file is used only in harmattan projects.

[2] http://library.developer.nokia.com/topic/MeeGo_1.2_Harmattan_API/html/guide/html/Developer_Library_Developing_for_Harmattan_Harmattan_security_6cbe.html

* sampleproject.desktop: This file specifies how to run the application
from the application grid, with various fields. Information about
.desktop files can be found at http://wiki.maemo.org/Desktop_file_format.
Two fields of this file can be modified by psa update parameters:
 - Name: -a or --app-name
 - Category: -c or --category

Note that the category should be a valid one, as specified in
http://standards.freedesktop.org/menu-spec/latest/apa.html.

* sampleproject.png: The application icon, which is displayed in the
application grid.

* qml/*.qml: The QML files for the application. Their contents depend
on the platform.

* sampleproject: Main program. Initializes the application and provide
support for displaying the QML files contents.

* sampleproject.longdesc: Holds the contents of the long_description field of
setup.py, which as the name implies is a more detailed description of what the project is.

build-deb command

The build-deb command does all necessary steps for generating a binary package. It essentially calls stdeb to build the proper Debian package and then places the application icons inside it. For using this command, you just have to enter the project directory and run:

    $ psa build-deb

The binary package will be found under the ./deb_dist directory.

If you want to add credentials to your project, you have to edit the .aegis file, which initially is empty and thus ignored. After you write all the necessary credentials to the file it will be injected into the binary package the next time the build-deb command is called. More information about credentials can be found here

update command

The update command can change certain values inside the project files, minimizing the need to open and edit them directly. This command accepts the following parameters:

    -a APPNAME, --app-name=APPNAME
                        Human-readable application name, resides in sampleproject.desktop
    -s SECTION, --section=SECTION
                        Application section, resides in stdeb.cfg
    -d DESC, --description=DESC
                        Application short description, resides in setup.py
    -c CATEGORY, --category=CATEGORY
                        Application category, resides in sampleproject.desktop

These parameters can be used in any order. As an example, to change the description and section of the project, run:

    $ psa update -d "Sample project" -s games

Example workflow

$ psa init sampleproject harmattan
$ cd sampleproject
(... hack ...for example, edit your .py files AND edit setup.py, see below)
$ psa build-deb
(... copy binary package to destination and install it, see below...)
(... hack some more ...)
$ psa update -c AudioVideo -s graphics
$ psa build-deb

(and so on.)

Pyside-assistant provides a starting point, for a project having a single Python module (the same name as your project slug.) If your project grows to include your own Python packages (directories with an __init__.py file), you will need to edit setup.py to specify those packages, including every nested package.

Assuming you are creating a debian package on a Ubuntu platform, to install the created pkg:

    (... assuming you are still in the sampleproject directory...)
    $ dpkg -i deb_dist/*.deb

Packaging generic Python applications

pyside-assistant was initially conceived for creating PySide applications, but in fact it can be used to build binary packages for any pure Python application that uses Python Distutils.

For that purpose, follow these steps:

• Run psa init as usual, to create the initial project layout;
• Erase the qml directory, as its files are specific to Qt programs;
• Create or add all files of your Python application;
• Edit stdeb.cfg and replace the contents of the Depends field with the correct runtime dependencies for your application, if any.
• If you don't have a setup.py file for your project, edit the provided one removing the .qml file reference and adding any other project files you need. See the Python Distutils documentation to know how the setup.py file works and how to edit it.

From now on, the same workflow applies: modify files, build binary package with psa build-deb, update fields with psa update, and so on.

If packaging fails

Pyside-assistant is a Python script that you can read to understand error messages.

Look for errors in log files that pyside-assistant creates in various directories.

Install and use the Debian program lintian to check a package.

Debian requires package names to be lower case; don't use uppercase letters in your project slug.

See also

Pyside-assistant is a tool for building binary packages for PySide projects, but only Debian packages for those platforms which use them.

For packaging PySide projects on other platforms:

Windows

MacOSX