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