UMEGuide/ApplicationDevelopment/AnatomyOfUMEPythonApplication

Purpose

This wiki page describes the files and directories you need to know about to add a Python application to the UME Hildon Desktop (Applications) > Extras menu.

The first section lists the files an application needs to be discovered, presented, and launched by the Desktop.
The next section explains the "application directory" that contains source code and other application-specific files.
The complete set of files that makeup a sample Python application is detailed.
A sample make file is provided.

Application files

Each Python application requires the following files:

Desktop file -- Describes the application to the UME Desktop. The presence of this file in the right location informs the Desktop that the application exists and provides information necessary to display it in a menu and launch it.
Executable file -- The file the Desktop runs to execute the application. For Python applications, this is a shell script that launches the Python interpreter and is passed the application's main Python file.
Main Python code file -- The main python file for the application

Additional optional files may include the following:

Additional Python or other application-specific files
Glade user interface file(s) -- The XML file(s) produced with Glade and imported into Python that describes the application's user interface objects
Icon -- The icon displayed in menus to represent the application before it is launched.

Before taking a closer look at these files, let's take note of an application's dedicated "application directory."

ApplicationDirectory

"Core" application-specific files (those that are not related to registering the application with the Desktop or displaying it in the user interface prior to launching) reside in a dedicated "application directory."

The application directory contains:

The main Python file
Any other application-specific files your code may need, such as other Python files or your Glade user interface description file(s)

The application directory is a subdirectory of:

/usr/share

In the example explained here, the application's directory is named pyglade, as follows;

/usr/share/pyglade

For the sample application considered in this wiki page, this directory contains the following:

main.py -- the main Python file
pygladeui.glade -- the Glade user interface description file

Now, let's take a tour of the actual files, starting with the critical .desktop file.

Application auto-discovery via the .desktop file

The Desktop automatically discovers applications that have a .desktop file in the /usr/share/applications directory. This file always starts with "[Desktop Entry]" and continues with a number of key value pairs that define the application to the Desktop, including:

the file name of the application's executable -- the Exec key
the name of the the application to display in the applications menu -- the Name key
the file name (without the file extension) of the icon to display along with the name in the applications menu, if any -- the Icon key

Here's a sample .desktop file:

[Desktop Entry]
Version=1.0.0
Encoding=UTF-8
Name=PyGlade
Type=Application
Exec=/usr/bin/pyglade
Terminal=false
Icon=pyglade_26
Categories=Applications

Currently, applications with a valid .desktop file are presented to the user in the (Applications) > Extras menu.

The executable and icon files are described below.

Executable file

The Desktop doesn't launch Python files directly. Instead, the Desktop launches the executable specified with the Exec key in the .desktop file. This executable is usually a simple shell script that does two things:

it switches to the application's directory
it launches Python and passes it the application's main Python file (which resides in the application's directory).

Here are details:

Run time location: /usr/bin

File name extension: Can be anything

Example: /usr/bin/pyglade

Type: For Python applications, this is generally an executable shell script.

Sample:

cd /usr/share/pyglade
python main.py

Key points:

/usr/share/pyglade is the application directory that contains the application's Python code
- Note: as with all other run-time paths, this path is relative to the UME's root (or the chroot when working in an Image-Creator target).
python main.py launches the Python interpreter and passes it the application's Python file, namely main.py

Main Python file

This is the application's main Python file.

Run time location: The ApplicationDirectory

File name extension: Can be anything, typically is .py

Example: /usr/share/pyglade/main.py

Type: Python file

Glade user interface file

This optional file defines the application's GTK user interface objects. Such files are created using Glade and imported into your Python code, after which its GTK objects can be accessed and used in Python.

Run time location: The ApplicationDirectory

File name extension: .glade

Example: /usr/share/pyglade/pygladeui.glade

Type: Glade definition file

Icon file

This is the optional icon that is displayed in the UME applications menu next to the application name.

Run time location: /usr/share/icons/hicolor/22x22/

File name extension: .png

Example: /usr/share/icons/hicolor/22x22/pyglade_26.png

Type: PNG, SVG

Sample make file

Here's the make file I used to install the sample application referred to in this page. (Setting up a build environment with an external source directory mounted to the target is beyond the scope of this page.)

BINDIR = ${DESTDIR}/usr/bin/
APPDIR = ${DESTDIR}/usr/share/pyglade
all: 
install:
        @mkdir -p ${BINDIR}
        @mkdir -p ${APPDIR}
        @install -m 755 -D main.py ${APPDIR}/main.py
        @install -m 755 -D pygladeui.glade ${APPDIR}/pygladeui.glade
        @install -m 755 -D executable.txt ${BINDIR}/pyglade
        @install -m 755 -D desktop.txt ${DESTDIR}/usr/share/applications/pyglade.desktop
        @install -m 755 -D pyglade_26.png ${DESTDIR}/usr/share/icons/hicolor/22x22/apps/pyglade_26.png

clean:
        @rm -f ${APPDIR}/main.py
        @rm -f ${APPDIR}/ui.glade
        @rm -f ${BINDIR}/pyglade
        @rm -f ${DESTDIR}/usr/share/applications/pyglade.desktop
        @rm -f ${DESTDIR}/usr/share/icons/${THEME}/22x22/apps/pyglade_26.png

Ubuntu Documentation