"Hello Moblin"

This tutorial explains the workflow you'll follow when working on a Moblin C application inside the Anjuta IDE.

It explains how to:

1. Start a project using the Linux Project Generator
2. Set up your project in Anjuta
3. Work on your project in Anjuta
4. Build your application from your project
5. Deploy your application to a netbook
6. Run the application on the netbook

The resulting application is trivial (one button inside a window), but it demonstrates general principles you can apply to any Moblin project.

This tutorial gives instructions for developing using graphical tools. Some of the steps (such as using the Moblin Package Creator) may not work as expected if you use the command line. If you want to use the command line to build your project, you will need to first use the Moblin SDK envsetup.sh script to correctly setup the environment: see this tutorial for instructions.

Pre-requisites

This tutorial assumes you have installed each of the components mentioned in the instructions for setting up your development and deployment machines.

Starting a project

We're going to use the Linux Project Generator to create a basic skeleton for our application. From the command line, start the Linux Project Generator with:

You'll see a window like this:

The drop-down box in the Code Language can be left as C.

Fill in the empty text fields with settings appropriate to you and your organization (the image above shows some examples). Hover your mouse pointer over a field to see a tooltip explaining the purpose of and constraints on that field.

The path to your resulting project is based on settings in this tab: <Path>/<Short name>.

Next, the Structure tab enables you to specify whether your project consists of application binaries, libraries, or both:

Leave it on the default setting (Single Application).

Use the Code tab to define the type of code your project will contain:

This setting adds boilerplate code to your generated project, which enables it to either read/print command line arguments (Simple (console)) or display an animated "Hello World" message (Basic Clutter Application).

For the purposes of this tutorial, choose Simple (console).

The Build tab allows you to set parameters which will be added to your autoconf and automake files:

For now (and unless you really know what you're doing), leave these at the defaults.

Finally, the License tab enables you to specify the license under which your project will be released:

Selecting a license here creates a COPYING file in the root directory of your project, containing the license; and adds licensing statements to the top of any generated source files.

Note that if you don't intend to open source your project, selecting a license here doesn't bind you to releasing your project as open source in future. You can remove the COPYING file and any corresponding statements in source files if you so wish.

Once you've set up your project, click on the Create button to generate it. If your project was successfully created, you should see this dialog box:

Close the dialog box.

Generated project structure

Browse to your generated project using a file browser and you'll see quite a lot of files:

• ChangeLog, AUTHORS, COPYING, INSTALL, NEWS, and README should be familiar to you if you've ever installed any GNU software before. They make up the basic documentation for your project. It's up to you whether you maintain these files or leave them as they are. The GNU Coding Standards gives you the reasons why you should maintain them.
• autogen.sh, configure.ac, and Makefile.am are configuration files used by the GNU autotools. You can leave these files alone for long stretches of time, but might occasionally need to edit them.
• The src directory is very important. It contains another Makefile.am file which you'll need to edit, as well as the C source files for your project and other assets.

To see how these files are used, browse to your project directory on the command line and run this command:

This applies the configure.ac and Makefile.am files to generate the traditional configure and Makefile files for your project. These are the files which can actually be used to build it.

Once you've run the autogen.sh script, you should be able to compile your project sources with:

This outputs the binary files into the directory where the source code is (it doesn't permanently install the application). You should now be able to run your application and see its output like this:

Note that an application compiled like this may or may not run on a Moblin machine. The machine you're using to compile the code has a set of libraries and header files to compile code against, but it's unlikely to have the full set of libraries a Moblin machine has, or the same versions of them. The application might work on a Moblin machine, but not reliably or consistently.

In the next section, we'll see how to compile an application against the right libraries by using the Moblin toolchain.

Setting up the project in Anjuta

We're going to use Anjuta to code this project. Start it up, either from the menu (in Gnome, it's under Programming) or from the command line with:

Once Anjuta has started, from the File menu select New > Project from Existing Souces.

Enter the project name, using the same short name you used in the Linux Project Generator (hellomoblin). Select the Import from folder radio button and use the drop-down box to browse to and select the directory containing the project. Finally, click on Create to create the project.

Next, we'll configure the project to use the Moblin SDK plugin. Go to Edit > Preferences, then click on the Installed plugins tab. Scroll through the list to the Moblin SDK plugin and mark the checkbox next to that entry.

Now the plugin is active. Scroll down the list of plugins on the left of the preferences dialog and click on the Moblin SDK entry. Fill in the fields as follows:

• Cross-compiler options: Select Use an external toolchain and browse to the moblin-cross-toolchain directory (inside the directory where you installed the SDK). Set the Toolchain triplet to i586-moblin-linux.
• Target options: Select Use an external device and set the IP address to your deployment machine's IP address. (If you're not sure of the deployment machine's IP address, open a terminal on the machine and use /sbin/ifconfig to display the network settings.)

The completed settings should look like this:

Click Close once you've completed these steps.

Coding

The source files for your project are in the src directory. At the moment, there's just one, main.c. Open that file and replace the code (below the license declaration) with the following:

The first line pulls in the nbtk.h header file, which enables us to make use of Clutter and the Netbook Toolkit for creating Moblin UI elements. It's unlikely your development machine has this library installed, so building this project against your local libraries will probably fail.

To make the nbtk library available to our project build, we need to amend the build configuration file configure.ac in the project root directory.

Open configure.ac in Anjuta and change this line:

to

This enables the compiler to link against the nbtk-1.2 library while compiling your code.

You can now build the project: from the Build menu, select Configure Project to display this dialog box:

Mark the Regenerate project checkbox then click on the Execute button. The Configure options have the following effects:

• --enable-maintainer-mode ensures that any changes to the configure.ac and Makefile.am files are picked up during the build. This in turn ensures that the configure and Makefile scripts are updated if their related files have changed.
• --prefix=/usr configures the installation prefix for the build. In our case, the files will packaged so that they install into the /usr directory once we get them to the deployment machine.

If you change configure.ac or Makefile.am, choose Build > Configure Project and tick the Regenerate project to regenerate the build scripts again.

Finally, to compile the project, from the Build menu, select Build Project. This runs the make command against your project sources. A good visual check that your code is being compiled using the Moblin toolchain is to look at the console output, scanning for moblin-cross-toolchain, such as

Deploying your application

Once you have a compiled application, you can deploy it to a machine running Moblin. There are two ways to do this:

1. Copy the compiled code directly across onto the filesystem (the Anjuta plugin can do this). This method is good for fast deployment, but can leave orphaned files scattered around the filesystem.
2. Create a package and install it using Moblin's package manager. The Moblin Package Creator can be used to create an RPM package, which can then be copied to the deployment machine and installed using yum. This is the cleanest method (easy to uninstall), but slower and more awkward than direct copying.

Whichever method you choose, you'll need to set up your deployment machine for remote access before you do either.

Deploying from Anjuta

In Anjuta (with the Moblin SDK plugin configured), go to the Tools menu and select Deploy. You'll be prompted for the root password on the deployment machine:

Enter the password and click OK. In the console, you should see the output as the files are copied (by SSH) to the deployment machine, for example:

The files are just copied to the /usr directory on the deployment machine. (Destination directory is set by the --prefix option passed when configuring the project.) If you need to clean the files up, it's up to you to work out what went where.

To redeploy, just rebuild then run Tools > Deploy again.

Creating and deploying an RPM

This approach uses the Moblin Package Creator (MPC) to generate an RPM package. It's more complicated, but generates a package which can be distributed and should be installable on many different Moblin machines.

Before trying to use the MPC to create a package, ensure that you've done a configure and build on your project in Anjuta.

Open a command line and go to your project directory; then start MPC:

Then fill the fields in MPC's Main tab with values appropriate to your project. A sample is shown below:

The Project root path setting should point at the root directory of your project.

Another field which may not be obvious is Requires. Use this to specify any libraries which your application needs at runtime. In the case of our application, we specify the it requires a version of nbtk >= the version shipped with Moblin 2.1 (that is version 1.1.13). (The application should also work with older versions of the nbtk API, but we're specifying this version for demonstration purposes.) BuildRequires is specific to creating deb files, so we won't be using it.

Next, fill in the Build Control tab:

Set the SDK path by browsing to the root directory of your SDK installation; the Output directory can be set to the project directory; and you can deselect all the check boxes except for RPM (.rpm).

Then fill in the License Details tab:

Choose the same license type as you selected when generating the project, and enter other details as appropriate. For the Upstream options, you can use your own name and website if you are distributing your own code (rather than just packaging someone else's).

Finally, click on Create. A terminal window should pop up and show the output from the package build, ending with something like this:

You should also see a prompt which says:

Package created successfully in <project directory>.

If this fails, try reconfiguring and rebuilding your project in Anjuta, then following these steps again.

Once the build is successful, click on Quit to close the MPC.

Copy the resulting RPM file over to the deployment machine by whatever means you have at your disposal. For example, you could SCP the RPM file from the development machine to the deployment machine:

(where ~/Download is a valid directory on the deployment machine).

Once you've copied the file over, switch to a command line on the deployment machine and install the RPM with:

You can remove the RPM (for example, if you need to redeploy it) with:

Running the application

Now for the finale: running the application on the netbook.

The Linux Project Generator provides the menu entry and icon files for the application, so when you installed it on the netbook, it should magically appear in the applications zone, ready to run. Click on the Other category in the applications zone and hopefully you'll see your application's icon:

Click on the icon to start the application and you should see this:

Your first Moblin application, done. (By the way, the button doesn't do anything.)