wiki:Developing your own applications

Creating a Hello World application

This guide is aimed at the complete beginner who would like to know how to develop their own applications for SHR. Taking the usual Hello World program as an example, it will use Vala as the programming language which should be familiar to Java developers.

It is assumed that the reader has already successfully built SHR using the instructions at Building SHR . So we assume that we've already changed to shr build  chroot enviroment with :

sudo shr-chroot.sh  #---> enter the chroot
su - bitbake        #---> change to bitbake user

1. Creating a source folder

$ cd /OE
$ mkdir myfirstapp
$ cd myfirstapp

2. Writing Hello World in Vala

Create and enter a sub folder for the source:

$ mkdir src
$ cd src

Create a file called myfirstapp.vala and insert the following text:

class Demo.HelloWorld : GLib.Object
{
    public static int main(string[] args)
    {
        stdout.printf("Hello, World\n");
        return 0;
    }
}

More information about Vala can be found here:  http://live.gnome.org/Vala/Tutorial

3. Setting up autotools

Create a file called Makefile.am and insert the following text:

bin_PROGRAMS = myfirstapp

AM_CFLAGS = $(DEPS_CFLAGS)
AM_LIBS = $(DEPS_LIBS) $(DEPS_LIBS)

AM_VALAFLAGS = --pkg "gio-2.0" --pkg "glib-2.0"

myfirstapp_SOURCES = myfirstapp.vala
myfirstapp_LDADD = $(INTI_LIBS)

myfirstapp_LDFLAGS = $(AM_LIBS)

clean:
	rm -f *.c *.o *.stamp

Go back to the previous folder:

$ cd ..

Create another file called Makefile.am and insert the following text:

SUBDIRS = src

Create a file called configure.ac and insert the following text:

AC_INIT([myfirstapp],0.1)
AM_INIT_AUTOMAKE
AC_CONFIG_SRCDIR([src/myfirstapp.vala])

AC_PROG_CC
m4_pattern_allow
AM_PROG_VALAC

PKG_CHECK_MODULES([DEPS], [glib-2.0 gio-2.0])

AC_OUTPUT([Makefile src/Makefile])

Run the following commands:

$ aclocal
$ autoconf
$ touch AUTHORS NEWS README ChangeLog
$ automake --add-missing

4. Adding a bitbake recipe

Enter the third party recipes folder:

$ cd /OE/meta-smartphone/meta-shr/recipes-shr/3rdparty

The above directory is used when we have build shr-core which uses OE-core. If we've build shr-unstable then OE-classic is used and the directory to put your recipe is /path/to/shr/build/shr-unstable/openembedded/recipes/openmoko-3rdparty

Create a file called myfirstapp_0.1.bb and insert the following text:

DESCRIPTION = "A hello world program written in Vala"
LICENSE = "GPLv3"
LIC_FILES_CHKSUM = "file://COPYING;md5=d32239bcb673463ab874e80d47fae504"
PR = "r0"

S = "${WORKDIR}/myfirstapp"

SRC_URI = "file:///OE/myfirstapp"

inherit autotools vala
  • Note 1: For building from local sources you can also use "inherit srctree" as it's used in conf/local-builds.conf
  • Note 2:In the LIC_FILES_CHKSUM line you calculate the md5 as follows:
    $ cd myfirstapp
    $ md5sum COPYING    //will give a md5 string. 
    

5. Building a package

$ cd /path/to/shr/build/shr-unstable
$ . setup-env
$ bitbake myfirstapp

You should find that you now have an ipk package like this: /path/to/shr/build/shr-unstable/tmp/deploy/ipk/armv4t/myfirstapp_0.1-r0.6_armv4t.ipk

In order to test your program, simply install this package on your phone and run "/usr/bin/myfirstapp".


Graphical User Interface

Once you have successfully completed the steps above, you may wish to know how to add a Graphical User Interface (GUI). This section will show you how to do this using the Elementary widget set, which is utilised by the core SHR phone applications.

1. Creating a source folder

$ cd /path/to/shr/build
$ mkdir myfirstgui
$ cd myfirstgui

2. Writing a Hello World GUI in Vala and Elementary

Create and enter a sub folder for the source:

$ mkdir src
$ cd src

Create a file called myfirstgui.vala and insert the following text:

using Elm;

private void win_del()
{
	Elm.exit();
}

class Demo.HelloWorldGui : GLib.Object
{
	public static int main(string[] args)
	{
		Elm.init(args);

		Win win = new Win(null, "hello", WinType.BASIC);
		win.title_set("Hello");
		win.smart_callback_add("delete,request", win_del);
    
		Bg bg = new Bg(win);
		bg.size_hint_weight_set(1.0, 1.0);
		win.resize_object_add(bg);
		bg.show();

		Label lb = new Label(win);
		lb.text_set("Hello World!");
		lb.size_hint_weight_set(1.0, 1.0);
		win.resize_object_add(lb);
		lb.show();

		win.show();

		Elm.run();
		Elm.shutdown();

		return 0;
	}
}

More information about Elementary can be found here:  http://trac.enlightenment.org/e/wiki/Elementary

3. Setting up autotools

Create a file called Makefile.am and insert the following text:

bin_PROGRAMS = myfirstgui

AM_CFLAGS = $(DEPS_CFLAGS)
AM_LIBS = $(DEPS_LIBS) $(DEPS_LIBS)

AM_VALAFLAGS = --pkg "gio-2.0" --pkg "glib-2.0" --pkg "elementary"

myfirstgui_SOURCES = myfirstgui.vala
myfirstgui_LDADD = $(INTI_LIBS) -levas
 
myfirstgui_LDFLAGS = $(AM_LIBS)  

clean:
	rm -f *.c *.o *.stamp

Go back to the previous folder:

$ cd ..

Create another file called Makefile.am and insert the following text:

SUBDIRS = src

Create a file called configure.ac and insert the following text:

AC_INIT([myfirstgui],0.1)
AM_INIT_AUTOMAKE
AC_CONFIG_SRCDIR([src/myfirstgui.vala])

AC_PROG_CC
m4_pattern_allow
AM_PROG_VALAC

PKG_CHECK_MODULES([DEPS], [glib-2.0 gio-2.0 elementary])

AC_CHECK_LIB(libeflvala)

AC_OUTPUT([Makefile src/Makefile])

Run the following commands:

$ aclocal
$ autoconf
$ touch AUTHORS NEWS README ChangeLog
$ automake --add-missing

4. Adding a bitbake recipe

Enter the third party recipes folder:

$ cd /OE/meta-smartphone/meta-shr/recipes-shr/3rdparty

The above directory is used when we have build shr-core which uses OE-core. If we've build shr-unstable then OE-classic is used and the directory to put your recipe is /path/to/shr/build/shr-unstable/openembedded/recipes/openmoko-3rdparty

Create a file called myfirstgui_0.1.bb and insert the following text:

DESCRIPTION = "A GUI hello world program written in Vala"
LICENSE = "GPLv3"
LIC_FILES_CHKSUM = "file://COPYING;md5=d32239bcb673463ab874e80d47fae504"
PR = "r0"
DEPENDS = "libeflvala elementary"

S = "${WORKDIR}/myfirstgui"

SRC_URI = "file:///OE/myfirstgui"

inherit autotools vala
  • Note 1: For building from local sources you can also use "inherit srctree" as it's used in conf/local-builds.conf
  • Note 2:In the LIC_FILES_CHKSUM line you calculate the md5 as follows:
    $ cd myfirstgui
    $ md5sum COPYING    //will give a md5 string. 
    

5. Building a package

$ cd /path/to/shr/build/shr-unstable
$ . setup-env
$ bitbake myfirstgui

You should find that you now have an ipk package like this: /path/to/shr/build/shr-unstable/tmp/deploy/ipk/armv4t/myfirstgui_0.1-r0.6_armv4t.ipk

In order to test your program, simply install this package on your phone and run "/usr/bin/myfirstgui".


FSO Support

You might like to add some support for FSO in your app such as registering resources. On the other hand, you may want to be able to run it in other devices or desktops which don't use nor have FSO installed. So what we are going to do here is adding a configure flag so we can decide wether it will have FSO support integrated or not at build time.

1. Setting up autotools

First, you should add this to your configure.ac file:

AC_ARG_ENABLE([fso],
   [AC_HELP_STRING([--enable-fso], [enable FSO support])],
   [
    if test "x${enableval}" = "xyes" ; then
       enable_fso="yes"
    else
       enable_fso="no"
    fi
   ],
   [enable_fso="no"])


MYAPP_VALAFLAGS=""
if test "x$enable_fso" = "xyes" ; then
	echo "ADDING FSO SUPPORT FOR THIS BUILD..."
	EMTOOTH2_VALAFLAGS="--define=_HAVE_FSO_"
fi
AC_SUBST(MYAPP_VALAFLAGS)

Then, in your src/Makefile.am, add the macro MYAPP_VALAFLAGS to the VALAFLAGS env var. For example:

AM_VALAFLAGS = --pkg "gio-2.0" --pkg "glib-2.0" @MYAPP_VALAFLAGS@

What we have done so far is defining the define _HAVE_FSO_ in the vala compiler if we build the app using

./configure --enable-fso

2. Adding optional FSO code to the sources

Now it's time to use this macro in our code. As we said before, typical use for FSO in most apps can be registering CPU Resource so the phone doesn't suspend if our app is running. We'll implement the code here. This code is using gdbus, so before be sure "--pkg gio" is present in your VALAFLAGS in Makefile.am and that the package is checked in configure.ac

We'll first add a new vala file named fso.vala (remember adding it to Makefile.am) which will contain the dbus interfaces which will be responsibles of requesting the resource. Note too how we use the defines we generated with the configure scripts:

#if _HAVE_FSO_
[DBus (name = "org.freesmartphone.Usage", timeout = 120000)]
public interface FSOusaged: GLib.Object {

	public abstract void request_resource(string resource) throws IOError;
	public abstract void release_resource(string resource) throws IOError;


}
#endif

Now we will use this interface in our code. For example, we are going to register CPU resource in main.vala when we start the app:

#if _HAVE_FSO_
    /* Get CPU resource if fso is running */
    public FSOusaged fso;
    try {
			stdout.printf ("Requesting \"CPU\" resource to org.freesmartphone.ousaged...\n");
			fso = Bus.get_proxy_sync (BusType.SYSTEM, "org.freesmartphone.ousaged", "/org/freesmartphone/Usage");
			fso.request_resource("CPU");
		} catch (IOError e) {
			stderr.printf ("ERR: Could not get access to org.freesmartphone.ousaged: %s\n", e.message);
		}
#endif

/* ... here some code of the app ... */

/* we arrive to the end of main... we now release CPU resource before quitting the app: */ 

#if _HAVE_FSO_    
	try {
		stdout.printf ("Releasing \"CPU\" resource...\n");
		fso.release_resource("CPU");
	} catch (IOError e) {
		stderr.printf ("Could not get access to org.freesmartphone.ousaged: %s\n", e.message);
	}
#endif