PyMaemo/Documentation for pyside-assistant - Revision history

186.215.93.195 at 20:49, 4 July 2011

2011-07-04T20:49:34Z

← Older revision		Revision as of 20:49, 4 July 2011
Line 1:		Line 1:
	== Setting up ==		== Setting up ==

-	==== Installing from Ubuntu PPA ~~(Coming Soon)~~====	+	==== Installing from Ubuntu PPA ====

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

wimoreir: /* Installing from Ubuntu PPA */

2011-07-04T19:05:42Z

Installing from Ubuntu PPA

← Older revision		Revision as of 19:05, 4 July 2011
Line 1:		Line 1:
	== Setting up ==		== Setting up ==

-	==== Installing from Ubuntu PPA ====	+	==== Installing from Ubuntu PPA (Coming Soon)====

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

186.215.93.195: /* Building and installing from source */

2011-07-01T17:51:19Z

Building and installing from source

← Older revision		Revision as of 17:51, 1 July 2011
Line 13:		Line 13:
	==== Building and installing from source ====		==== Building and installing from source ====

-	To build and install ''pyside-assistant'' you will need a Debian-based Linux distribution. First, install ''python2.5'' ''sharutils'' and ''python-stdeb'' packages, that are runtime dependencies of ''pyside-assistant''. Get the source from the Github [https://github.com/PySide/PySideAssistant page], then in the directory which pyside-assistant was downloaded, run:	+	To build and install ''pyside-assistant'' you will need a Debian-based Linux distribution. First, install ''python2.5'', ''sharutils'' and ''python-stdeb'' packages, that are runtime dependencies of ''pyside-assistant''. Get the source from the Github [https://github.com/PySide/PySideAssistant page], then in the directory which pyside-assistant was downloaded, run:

	<nowiki>		<nowiki>

wimoreir: /* build-deb command */

2011-07-01T17:42:21Z

build-deb command

← Older revision		Revision as of 17:42, 1 July 2011
Line 129:		Line 129:

	The binary package will be found under the ''./deb_dist'' directory.		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 [http://library.developer.nokia.com/topic/MeeGo_1.2_Harmattan_API/html/guide/html/Developer_Library_Developing_for_Harmattan_Harmattan_security_6cbe.html here]

	==== update command ====		==== update command ====

wimoreir: /* Building and installing from source */

2011-07-01T16:13:37Z

Building and installing from source

← Older revision		Revision as of 16:13, 1 July 2011
Line 13:		Line 13:
	==== Building and installing from source ====		==== Building and installing from source ====

-	To build and install ''pyside-assistant'' you will need a Debian-based Linux distribution. First, install ''sharutils'' and ''python-stdeb'' packages, that are runtime dependencies of ''pyside-assistant''. Get the source from the Github [https://github.com/PySide/PySideAssistant page], then in the directory which pyside-assistant was downloaded, run:	+	To build and install ''pyside-assistant'' you will need a Debian-based Linux distribution. First, install ''python2.5'' ''sharutils'' and ''python-stdeb'' packages, that are runtime dependencies of ''pyside-assistant''. Get the source from the Github [https://github.com/PySide/PySideAssistant page], then in the directory which pyside-assistant was downloaded, run:

	<nowiki>		<nowiki>
	$ dpkg-buildpackage -D -rfakeroot -us -uc		$ dpkg-buildpackage -D -rfakeroot -us -uc
		+	</nowiki>
		+
		+	'''NOTE:''' If you don't have python2.5 available in your repository, like Ubuntu Natty users, you can install it from [https://launchpad.net/~fkrull/+archive/deadsnakes this] ppa.
		+
		+	<nowiki>
		+	$ sudo add-apt-repository ppa:fkrull/deadsnakes
		+	$ sudo apt-get update
		+	$ sudo apt-get install python2.5
	</nowiki>		</nowiki>

wimoreir: New page: == 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 pp...

2011-07-01T15:57:35Z

New page: == Setting up == ==== Installing from Ubuntu PPA ==== If you are using Ubuntu then you can add PySide's ppa and get ''pyside-assistant'' from there: <nowiki> sudo add-apt-repository pp...

New page

== Setting up ==

==== Installing from Ubuntu PPA ====

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

<nowiki>
sudo add-apt-repository ppa:pyside
sudo apt-get update
sudo apt-get install pyside-assistant
</nowiki>

==== Building and installing from source ====

To build and install ''pyside-assistant'' you will need a Debian-based Linux distribution. First, install ''sharutils'' and ''python-stdeb'' packages, that are runtime dependencies of ''pyside-assistant''. Get the source from the Github [https://github.com/PySide/PySideAssistant page], then in the directory which pyside-assistant was downloaded, run:

<nowiki>
$ dpkg-buildpackage -D -rfakeroot -us -uc
</nowiki>

'''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:

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

== Usage Instructions ==

The main script for using pyside-assistant is <code>psa</code>.

==== init command ====

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

<nowiki>
$ psa init sampleproject fremantle
</nowiki>

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 <code>psa init</code> to set various fields from the start; these parameters are shown below:

<nowiki>
-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
</nowiki>

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

<nowiki>
=========================================
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

* 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.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.

* sampleproject.qml: The QML file for the application. By default
just displays the words "Hello QML!" in the center of the window.

* sampleproject: Main program. Initializes the application and provide
support for displaying the QML file 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.

</nowiki>

==== 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:

<nowiki>
$ psa build-deb
</nowiki>

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 [http://library.developer.nokia.com/topic/MeeGo_1.2_Harmattan_API/html/guide/html/Developer_Library_Developing_for_Harmattan_Harmattan_security_6cbe.html 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:

<nowiki>
-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
</nowiki>

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

<nowiki>
$ psa update -d "Sample project" -s games
</nowiki>

== Example workflow ==
<nowiki>
$ psa init sampleproject fremantle
$ cd sampleproject
(... hack ...)
$ psa build-deb
(... copy binary package to destination and install it ...)
(... hack some more ...)
$ psa update -c AudioVideo -s graphics
$ psa build-deb

(and so on.)
</nowiki>

== 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 [http://docs.python.org/distutils/index.html Python Distutils].

For that purpose, follow these steps:

* Run <code>psa init</code> 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 [http://docs.python.org/distutils/index.html 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 <code>psa build-deb</code>, update fields with <code>psa update</code>, and so on.