Anatomy of an application

This section explains the structure of a MeeGo 1.2 Harmattan application on the host workstation and on the Harmattan device. When you start developing an application from scratch, as in the example in Creating and running a Hello World application with Qt SDK, Qt Creator creates the project file structure on the host workstation and adds the files to the project by default. You can edit the project or add new files, such as icons. Some of the files do not require any attention or editing. Such files are, for example, the QmlApplicationViewer wrapper files.

When you build the application, Qt Creator adds a new directory which includes build files such as the Debian package (.deb) to be installed on the device.

When you install the application on the device either with the Qt SDK or as a Debian package, all of the project files are not installed.

Application files on the host workstation

The following figure illustrates the file structure inside the project main directory:

Project file

• <project name>.pro: a project file needed to create the Makefile with qmake

  The .pro file ties the source code and the resulting application binary together. The file describes how the application is built by creating the Makefile into the appropriate build directory, which is then executed to actually build the application. For more information, see the qmake Manual.

Source code files

• main.cpp: executes the code to set up the QML environment
• qml\<project name>\main.qml: the top level application container code

  This file is used to create the application logic and the user interface.

• qml\<project name>\MainPage.qml: a sample page that is instantiated in main.qml

  This file is used to create the application logic and the user interface.

Icon files

• <project name>64.png: the icon shown in the Package Manager

  Choose the file for your application yourself. The default file is the Qt logo.

• <project name>80.png: the icon shown in the Applications view of the device home screen where applications are launched

  Choose the file for your application yourself. The default file is the Qt logo.

• <project name>.svg: a vector representation of the application icon created by the Qt SDK, which is not directly used by the project

Configuration files

• <project name>.desktop: a desktop configuration file for the Fremantle target which describes, for example, the link to the icon that launches the application

  The file is not needed in Harmattan applications.

• <project name>_harmattan.desktop: a desktop configuration file for the Harmattan target which describes, for example, the link to the icon that launches the application

Wrapper files

Under normal circumstances, you do not need to edit any of the following wrapper files:

• qmlapplicationviewer\qmlapplicationviewer.pri: a Qt Project Include file, it is similar to a .pro file
• qmlapplicationviewer\qmlapplicationviewer.cpp: an infrastructural class file, included in main.cpp
• qmlapplicationviewer\qmlapplicationviewer.h: an infrastructural header file, included in main.cpp

User settings

• <project name>.pro.user: contains project-specific SDK settings.

Debian packaging files

The Debian packaging files can be added when you create a new project, or they can be added later. The following figure illustrates the packaging files on the host workstation:

The packaging files are:

• changelog: includes the package name, version, distribution, urgency, and changes made in the package revision

  The Qt SDK updates this file, but you can edit the file manually.

• compat: contains the debhelper compatibility level

  Do not edit this file.

• control: includes the packaging metadata for your application

  Edit the file to update the long and short descriptions and the name shown on package manager.

• copyright: contains the information about copyright and license information

  Edit the file according to the license of your application.

• manifest.aegis: defines the credentials that your application needs to access protected Harmattan resources. For more information, see Harmattan security.

  The Qt SDK generates the file automatically, but it can be created and edited manually.

• README: can be used to document any extra details or discrepancies between the original package and your Debian version

  Edit the file if needed.

• rules: contains the exact rules for different targets specifying how to the create the packages

  Usually you do not have to edit this file.

For more information on packaging, see Packaging your application.

Build files

When you build an application, Qt Creator creates a build directory to a designated place, for example, the same directory where the project main directory is. The following figure illustrates the contents:

All of the files in the build directory are created in the build process. The directory is created every time you build the application. You can delete the build directory if you wish. Deleting the build directory has no effect on the application or project, but note that build directory includes the .deb Debian package that you can install on the device or send to Nokia Store. There can be multiple build directories since different targets, such as simulators and debuggers can create them.

Application files on the device

When you install your application's Debian package on the device, all of the project files are not installed. For example <project name>.pro, manifest.aegis, C, and C++ source code files are left out.

To see the application file system on the device, enter the following command on the terminal, either on the device or through SSH connection on the host workstation:

dpkg --contents <Debian package name>.deb

Note: You can also use the command dpkg-query --listfiles <package_name> to see the contents of any package. Use this command if the .deb file is not available, for example, when you have installed the application on the device with the Qt SDK.

The following figure illustrates the example application's file system on the device:

The following files are created on the device:

• /opt/<project name>/bin/<project name>: the actual application executable binary
• /opt/<project name>/qml/main.qml: a QML source code file
• /opt/<project name>/qml/MainPage.qml: a QML source code file
• /usr/share/applications/<project name>_harmattan.desktop: a desktop configuration file for the Harmattan target which describes, for example, how the application is launched and how it appears in menus
• /usr/share/doc/<project name>/changelog.gz: includes the package name, version, distribution, urgency, and changes made in the package revision
• /usr/share/doc/<project name>/copyright: contains the information about copyright and license information
• /usr/share/icons/hicolor/80x80/apps/<project name>80.png: the icon file shown in the Applications view