Opie development - PDA development for Compaq IPAQ and Sharp ZAURUS: Distribute Opie software

9. Distribute Opie software

This chapter describes the items relatet to Opie software dirstribution. Its goal is to supply the developer (especially me) with all necessary information, howto integrate its own project into Opie (and vice versa).

The chapter will start with a description of the actually used Opie build system and how to integrate your software into.

The next section will explain, how you can convert your kdevelop application into an Opie compliant source structure (and vice versa). not startet ...

Finally a section describing the CVS upload and all related stuff will be documented. not startet ...

9.1 The Opie build system

This section describes, why we need such a build system instead of just using GNU autoconf/make and configure and what are the benefits for the user as well as for the developer.

The section content was send to me from Holger Freyter.

Why do we use a build system like this

Opie is a closed, coherend software project. Large parts of opie depend on other parts of opie. Nearly all applications depend on libqte, libqpe and libopie.

A common buildsystem like the opie build system guanrantees a common software structure, minimizes duplication of software parts and helps to sample commons ata central point.

Beside that, it helps to build the total opie project, even, if one component is at the time not compilable (which happens often, when using CVS). Just deactivate the component in the central configuration and recompile (if it is not a central component).

The target dependend configuration options are covered behand the buildsystem. Just choose your target, set the CompilerPath and compile ;-).

If you are experienced with the opie 0.8 versions (and before) you will be happy to have that kind of build system, because it was a mess to get the old system compilable (if errors occured).

How does the build system work

The build system configuration tool works like the kernel config tool. It stores its configuration in .config.

See here for downloading and building the different Opie targets.

There are two ways to configure the build-system.

Menuconfig

MenuConfig needs ncurses installed (also the devel package), which will be installed with the most distributions standardwise. Especially, if you do kernel compilation, it should be already installed. If not, install it dependend on your distribution.

Just call make menuconfig (as superuser) and a ncurses screen will open. You can select single items by walking through the tree.

Cursor UP/DOWN walk through the open tree.
Cursor LEFT/RIGHT toggle between the Select, Exit, Help options.
Enter opens the subtree (if existing).
Blank or MenuEntry Select select/deselects and entry.
Esc or MenuEntry Exit close the open branch and also the config tool (if no open branch has left).

The next paragraph shows the menuconfig target selection.

The user may answer the final question Do you wish to save the configuration with yes or no.

Xconfig instead of menuconfig

Dont use the SuperuserMode (or allow the superuser to have access to your XServer). Configure sudo (see sudo howto) appropriate and call sudo make xconfig.

A X-Window will open, which contains qconf, the xtools for configuration. You can select single items by walking through the tree.

The next paragraph shows the xconfig target selection.

User benefits

The user may want to design its own UserOpie. He is able to deselect the packets he does not wants using make menuconfig and can build e.g. an extremly small opie fitting his needs.

As the Opie build systems knows its dependencies, it is e.g possible to deselect libopie. In this case the user is not able to select applications which require libopie.

If the user wants to have only XYZ, he has to build only XYZ and its dependencies. In this case the user has to supply its own external libraries (if needed), the build system will care for the dependencies.

To compile it is enough to set QTDIR (and PATH for cross-compilation) and to select the target from the build system. OPIEDIR, PLATFORM, QMAKESPEC, ... dont have to be set (which minimizes build errors).

Last but not least, the user has the chance to build a single application or a single apps tree bei entering make SUBDIRS=/path/to/selected/app. Also a make install or make ipkg is possible (last one creates an ipkg automatically).

Developer benefits and integration HowTo

This section describes the benefits, developer have from the Opie buildsystem and howto integrate a user project. We will use the above already discussed kdevelop project testopie as an example here as well.

The main goal is, that it is easy and a standard way to integrate your own application into the Opie system. Dont care for dependencies. The buildsystem will guarantee for that.

Follow the setps described below (assuming, you use the noncore/apps path for your application).

Create a directory testopie in $OPIEDIR/pics and copy all used application pictures (backgound, icons ...) into this dir.
Note that you need min. a desktop icon stored here, which is referenced in the below mentioned desktop file.
And heres the desktop icon ;-).

Create a testopie.desktop file and copy it to $OPIEDIR/apps/Applications.
Heres the testopie.desktop files content.


[Desktop Entry]
Comment=comment
Exec=testopie
Icon=testopie
Type=Application
Name=testopie

Create a directory testopie in e.g. $OPIEDIR/noncore/apps and copy all used application sources (*.cpp, *.h, *.ui) and eventually used subdirs (like pics) into this dir. If it is a kdevelop application you have to copy config.h as well. This file is generated from kdevelop during its own build process. It can be found (if not done a make clean before) in the kdevelop project dir.
Hint
I have to work on this part to get it more Opie compatible. Will follow later ...

Create a control file and copy it to $OPIEDIR/noncore/apps/testopie/testopie.control.
Heres the testopie.control files content.


Package: testopie
Version: 0.1
Depends: opie-base
Section: qpe/applications
Source: http://www.uv-av.de/testopie/testopie-SRC-0.1.tgz
Priority: optional
Architecture: arm
Maintainer: Werner Schulte - werner@schulte-ac.de
Description: Testopie is an example program for
 Opiedevelopment using kdevelop 2.1.5

Important hint
All entries (incl comment) have to be filled with data. Otherwise the ipkg-build script will fail.

Copy a *.pro file from an existing application and adopt to your needs ($OPIEDIR/noncore/apps/testopie/testopie.pro).
Heres the testopie.pro files content.


TEMPLATE        = app
CONFIG          = qt warn_on release QWS_OPIE
DESTDIR         = $(OPIEDIR)/bin
HEADERS         = testopie.h \
                testopiedoc.h \
                testopieview.h
SOURCES         = main.cpp \
                testopie.cpp \
                testopiedoc.cpp \
                testopieview.cpp
INTERFACES      =
INCLUDEPATH     += $(OPIEDIR)/include .
DEPENDPATH      += $(OPIEDIR)/include .
LIBS            += -lqpe -lopie
TARGET          = testopie



include ( $(OPIEDIR)/include.pro )

Copy a config.in file from an existing application and adopt to your needs ($OPIEDIR/noncore/apps/testopie/config.in).
Heres the config.in files content.


  config TESTOPIE
    boolean "testopie"
    default "n"
    depends ( LIBQPE || LIBQPE-X11 ) && LIBOPIE && LIBKATE

# source "noncore/apps/testopie/anylib/config.in"

Insert a line into $OPIEDIR/packages with your projects data. (CONFIG_TESTOPIE<tab> noncore/apps/testopie<tab> testopie.pro)
Call make clean-configs, which cleans the config tree.
Call make menuconfig or xconfig. The system asks during startup what should happen with the new testopie implementation. Just press enter and select your application from the menuconfig apps branch. Store the config file.
Call make SUBDIRS=noncore/apps/testopie and watch the compilation.

Note
The steps above were tested with a 099_BRANCH version of OPIE CVS-Download. It worked after patching the noncore/apps/Makefile and inserting a -DQWS_OPIE flag (which I use for OPIE/NONOPIE Differences) and inserting #include config.h without #ifdef HAVE_CONFIG (used from kdevelop).

I will provide a script for that things and will think about automatisation. See also for more info.