Advanced building and packaging

Using Autotools build

To create a stable build environment, you can use the GNU Autotools. It is a set of tools that assist in creating build scripts for an application. It also makes creating portable source code for POSIX (Unix-like) systems easier.

Follow the below instructions to create a file structure and to add the new files required for this process. For more detailed information about this topic, see the Autoconf manual.

Create a configure.ac file:

[sbox-SDK_ARMEL: ~] > nano configure.ac

and include the following lines:

AC_INIT(helloworld, 0.1)
AC_PREREQ(2.59)

AM_INIT_AUTOMAKE([1.7.9])
AC_CONFIG_HEADERS([config.h])

AC_GNU_SOURCE
AC_CANONICAL_HOST
AM_MAINTAINER_MODE

AC_PROG_INSTALL
AC_PROG_MAKE_SET
AC_PROG_CXX

hildondesktopentrydir=`pkg-config --variable=desktopentrydir osso-af-settings`
AC_SUBST(hildondesktopentrydir)

AC_CONFIG_FILES([Makefile
                 src/Makefile
                 src/helloworld.desktop])

PKG_CHECK_MODULES(LIBHILDONMM, hildonmm >= 0.9.6)
AC_SUBST(LIBHILDONMM_CFLAGS)
AC_SUBST(LIBHILDONMM_LIBS)

AC_OUTPUT

Create a Makefile.am file:

[sbox-SDK_ARMEL: ~] > nano Makefile.am

and include the following lines:

EXTRA_DIST = \
        data/helloworld.png \
        data/helloworld.26.png \
        data/helloworld.40.png \
        data/helloworld.links

# Icon installation
icondir = $(datadir)/icons/hicolor

install-data-local:
        $(mkinstalldirs) $(DESTDIR)$(icondir)/scalable/hildon; \
        $(mkinstalldirs) $(DESTDIR)$(icondir)/26x26/hildon; \
        $(mkinstalldirs) $(DESTDIR)$(icondir)/40x40/hildon; \
        $(INSTALL_DATA) $(srcdir)/data/helloworld.png $(DESTDIR)$(icondir)/scalable/hildon/helloworld.png; \
        $(INSTALL_DATA) $(srcdir)/data/helloworld.26.png $(DESTDIR)$(icondir)/26x26/hildon/helloworld.png; \
        $(INSTALL_DATA) $(srcdir)/data/helloworld.40.png $(DESTDIR)$(icondir)/40x40/hildon/helloworld.png;

uninstall-local:
        rm $(DESTDIR)$(icondir)/scalable/hildon/helloworld.png; \
        rm $(DESTDIR)$(icondir)/26x26/hildon/helloworld.png; \
        rm $(DESTDIR)$(icondir)/40x40/hildon/helloworld.png;

In the helloworld folder, create the following folder and copy the icon in the sizes 26 x 26 pixels, 40 x 40 pixels, and scalable (64 x 54 pixels) to this directory with the names helloworld.26.png, helloworld.40.png, and helloworld.png respectively.
```
[sbox-SDK_ARMEL: ~] > mkdir data
[sbox-SDK_ARMEL: ~] > cp my_icon26x26.png data/helloworld.26.png
[sbox-SDK_ARMEL: ~] > cp my_icon40x40.png data/helloworld.40.png
[sbox-SDK_ARMEL: ~] > cp my_icon64x54.png data/helloworld.png
```
In the helloworld folder, create the following folder:
```
[sbox-SDK_ARMEL: ~] > mkdir src
```
Move the source and header files to the newly created src folder:
```
[sbox-SDK_ARMEL: ~] > mv main.cpp mywindow.cpp mywindow.h src/
```

In the src folder, create the file helloworld.desktop.in with the following content:

[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
Name=helloworld
Comment=helloworld_thumb
Exec=@prefix@/bin/helloworld
Icon=helloworld
X-HildonDesk-ShowInToolbar=true
X-Osso-Type=application/x-executable

Change to the src folder:
```
[sbox-SDK_ARMEL: ~] > cd src/
```

Create a new Makefile.am file:

[sbox-SDK_ARMEL: ~] > nano Makefile.am

and include the following lines:

AUTOMAKE_OPTIONS = foreign

bin_PROGRAMS = helloworld
helloworld_SOURCES = main.cpp \
                     mywindow.cpp \
                     mywindow.h

helloworld_LDADD = $(LIBHILDONMM_LIBS)
helloworld_CXXFLAGS = $(LIBHILDONMM_CFLAGS)

hildondesktopentry_DATA = helloworld.desktop

Now change to the top directory:
```
[sbox-SDK_ARMEL: ~] > cd ..
```
Issue the following commands to test the Autotools configuration and compilation:
```
[sbox-SDK_ARMEL: ~] > autoreconf -i
[sbox-SDK_ARMEL: ~] > ./configure && make
```
The application should check for dependencies. Compile and create an executable which you can once again test with the following command:
```
[sbox-SDK_ARMEL: ~] > run-standalone.sh src/helloworld
```

Packaging the application

Once you have configured Autotools as described above, create a Hello World installable debian file that the Application Manager of the device uses to install the application. (For more information, see Debian Maintainer's Guide).

A debian package includes the name and e-mail of its creator (in this case called maintainer). In order to get your name and e-mail inserted on the package properties you can export these environment variables:
```
[sbox-SDK_ARMEL: ~] > export DEBFULLNAME="John Doe"
[sbox-SDK_ARMEL: ~] > export DEBEMAIL=john.doe@foo.org
```
Optionally, you can have these variables enabled every time you enter the Scratchbox environment (you need to restart Scratchbox after these commands in order to have these variables enabled):
```
[sbox-SDK_ARMEL: ~] > echo "export DEBFULLNAME=\"John Doe\"" >> ~/.bashrc
[sbox-SDK_ARMEL: ~] > echo "export DEBEMAIL=john.doe@foo.org" >> ~/.bashrc
```
Note: This is valid for all Scratchbox targets.
Create a source code distribution using the following command:
```
[sbox-SDK_ARMEL: ~] > make dist
```
This command will create a compressed tar file (.tar.gz) of your software (containing a distributable version of it). Issue the following commands in order to unpack this package:
```
[sbox-SDK_ARMEL: ~] > tar xzf helloworld-0.1.tar.gz
[sbox-SDK_ARMEL: ~] > cd helloworld-0.1
```
Issue the following command to make initial 'debianization':
```
[sbox-SDK_ARMEL: ~] > dh_make -s -f ../helloworld-0.1.tar.gz
```
Note: It is assumed that the examples' root directories are in format <package name>-<version> for education purposes (eases the dh_make command execution). When dealing with applications in real life (inside a repository, for example) it would be better to remove the <version> tag from the directory name because the source code inside it could have a different version than indicated in the directory name.

Next dh_make will print a summary of the package. Then press ENTER to confirm:

Maintainer name : John Doe
Email-Address : john.doe@foo.org
Date : Thu, 13 Sept 2007 21:02:03 +0400
Package Name : helloworld
Version : 0.1
Type of Package : Single
Hit <enter> to confirm:

In order to create a entry on the maemo menu, you must create the file helloworld.links in data directory with the following content:
```
usr/share/applications/hildon/helloworld.desktop etc/others-menu/1400_tana_fi_utilities/0100_helloworld.desktop
```

Now your package is almost ready to be created. We'll see now a little bit about "Application Manager", the maemo's user interface for managing \ application packages.

Packaging for Application Manager

Maemo uses .deb files (Debian packaging system) that are used to install, remove or upgrade packages on the system (similar to .sis files on Symbian). Normally, every user with root priviledges would have access to manage these packages, altough for the normal user the packaging system is managed by "Application Manager", wich is a frontend like synaptic, for example, but with some modifications.

"Application Manager" is aimed at user packages. It wasn't planned to manage all the system packages, but just the ones that the user would know about. It uses the control file (contained in debian/ directory of your application tree) in order to read lots of information about your application package. In order to make your package appear on the " Application Manager", modify the Section: field like this:

Section: user/<SECTION>

Where SECTION is the type of application you are creating. Here is a list of predefined sections:

Accessories:   user/Accessories
Communication: user/Communication
Games:         user/Games
Multimedia:    user/Multimedia
Office:        user/Office
Other:         user/Other
Programming:   user/Programming
Support:       user/Support
Themes:        user/Themes
Tools:         user/Tools

Notice that you could also create a non-predefined section, like Networking, for example.

Building the application

Now the application is properly configured for "Application Manager", building it is done easily with the command:

[sbox-SDK_ARMEL: ~] > dpkg-buildpackage -rfakeroot -us -uc -b

Where -rfakeroot tells the application to use a "fake" root environment (provided by fakeroot tool) in order to build the package, -us and -uc are used to tell that the package and its modifications are unsigned, and finally -b is used to build only the binary file, without source code packaged.

The system displays some output and some warnings near the end of it (regarding the security issue about unsigned package and modifications of it) but that is normal. The parent directory now has a helloworld_0.1-1_armel.deb file - your Debian package. This is the file that is distributed to maemo devices and installed using the Application Manager. You can install and test you package on scratchbox by typing:

[sbox-SDK_ARMEL: ~] > cd ..
[sbox-SDK_ARMEL: ~] > fakeroot dpkg -i helloworld_0.1-1_armel.deb

Low and behold, your helloworld application will install without errors. Packages can be installed in both X86 and ARMEL targets.

Now you are ready to send your helloworld_0.1-1_armel.deb package into your device as in the Compiling and moving application to device section. Then you can install the package on the device with the following line command:

$ sudo gainroot
$ dpkg -i helloworld_0.1-1_armel.deb

Installing the application using Application Manager

Until now, you were installing application packages using the "X terminal" console. This is not a good way for the user to install and remove packages. In order to resolve this, we'll show how to manage applications using "Application Manager".

After sending the application package helloworld_0.1-1_armel.deb, you can use "File Manager" to select it: