doc/api

How to add application templates to the application wizard part

Project templates provide the developer with a basic application framework.

This is necessary for rapid application development (RAD) and makes it even possible for an inexperienced 3rd party developer to create standard conforming applications like kedit as well as plugins for example for kdevelop or noatun.

I. Example: How To Create a Simple KDE Application Template "KHello"

II. Registration/Installation Of The Application Template
III. How To Add The Template To KDevelop CVS HEAD
IV. Changes to the template system (VERY IMPORTANT)

I. Example: How To Create a Simple KDE Application Template "KHello"

You can find this template in $KDEDIR/share/apps/kdevappwizard/template-khello.

I.1. Step 1: Basic Skeleton

Create a directory template-khello with the files


template-khello/app.cpp
template-khello/app.h
template-khello/app.desktop
template-khello/app.kdevelop
template-khello/appui.rc
template-khello/khello
template-khello/main.cpp
template-khello/preview.png
template-khello/script
template-khello/src-Makefile.am
template-khello/subdirs

Note:: The directory name must begin with "template-".

I.2. Step 2: The Files in Detail

Have a look into the files! There are some variables which the application wizard will replace:


%{AUTHOR} ...... by the author
%{EMAIL} ....... by the e-mail address
%{VERSION} ..... by the version
%{APPNAME} ..... by the project name (KHello)
%{APPNAMELC} ... by the project name in lowercase (khello)
%{APPNAMEUC} ... by the project name in uppercase (KHELLO)
%{LICENSE} ..... by the license (GPL, BSD, QPL, LGPL, ...)
%{LICENSEFILE} . by the licensefile
%{YEAR} ........ by the year

All this can be found in $KDEDIR/share/apps/kdevappwizard/template-common/kdevelop.pm.

I.2.1. The Source Files

The files template-khello/app.cpp, template-khello/app.h and template-khello/main.cpp contain the source code that should not be too special so that the user can implement his own ideas.
(There may be variables included - see Step 2: The Files in Detail).

I.2.2. The File template-khello/khello

It may look like this:

The application wizard looks into this file to get

the information where to integrate the plugin into the the listview (Category=)
the name (Name=) and the comment (Comment=)
the preview image (Icon=)
and the file templates the project uses (FileTemplates=).

Further information could be (not required):

Comment= a small comment for the template. Longer comments should go into a README.devel and shown on startup
ShowFilesAfterGeneration= a comma-separated list (without whitespaces) of files that should be opened immediately after the generation, for instance a README.devel or a source file the user has to modify, the path is relative to the project directory (example: ShowFilesAfterGeneration=src/main.cpp,src/plugin.cpp). And
- APPNAMEUC will be replaced with the projectname in uppercase,
- APPNAMELC will be replaced with the projectname in lowercase,
- APPNAME will be replaced with the projectname.
DefaultDestinatonDir changes the default destination dir for the project (~) to your value, whereas HOMEDIR is a keyword

Attention:: The file template-khello/khello must have the same name as the right half of the directory! If the directory is template-foobar the file must be template-foobar/foobar.

See also:: AppWizardPart for more information.

I.2.3. Some Additional Files

The file

template-khello/appui.rc contains information about the toolbar and the menu.
template-khello/preview.png will be shown in the aplication wizard.
template-khello/app.desktop describes the application.
template-khello/subdirs contains a list of the subdirectories (usually doc, po, src) and can be found in the project root directory. It is necessary for the autotools.

I.2.4. The File template-khello/src-Makefile.am

This file will be copied to the $PROJECTDIR/src/.

I.2.5. The File template-khello/script

The following script is used to install the template and replaces all variables by the corresponding value. The result is a hopefully working kdevelop project!

Note:: There are several application templates which use some identical files - that's why some files are taken from the "template-common"-directory.

II. Registration/Installation Of The Application Template

The easiest way to install your template is to provide an "install.sh" shell script.
Example:

#!/bin/sh

kde_prefix=`kde-config --prefix`
if  [ `id -u` = 0 ]; then
  # we are root so install the template into the global kde directory
  kde_dir=`kde-config --prefix`
else
  # we are a user so install it into $HOME/.kde/share/apps/kdevappwizard directory
  kde_dir=`kde-config --localprefix`
  echo "Note: It would be better to install as root. Press CTRL+C to abort"
fi

# use usual path or another one?
echo "Install dir [${kde_dir}/share/apps/kdevappwizard]:"
read newdir

if [ "$newdir"a = a ]; then newdir="${kde_dir}/share/apps/kdevappwizard/"; fi

# make sure the directories exist
if [ ! -e "${newdir}/template-khello" ]; then mkdir -p "${newdir}/template-khello" ; fi;
if [ ! -e "${newdir}/templates" ]; then mkdir -p "${newdir}/templates" ; fi;
if [ ! -e "${newdir}" ]; then mkdir -p "$newdir" ; fi;
if [ ! -e "${newdir}/template-common" ]; then ln -s "${kde_prefix}/share/apps/kdevappwizard/template-common" "${newdir}/template-common" ; fi;

# install now
cp -R --target-directory "$newdir" template-khello
# the file template-khello/khello must go to the "templates" directory that
# kdevelop knows that it exists
mv "$newdir/template-khello/khello" "$newdir/templates/"
echo "done"

Attention:: Please test your template whether it installs and behaves correctly! Test, test and test again! ;)

III. How To Add The Template To KDevelop CVS HEAD

This section is for kdevelop developers only. Most probably you don't have to read this!.
Move the directory "template-khello" to kdevelop/languages/cpp/app_templates/ and then add the following files in kdevelop/languages/cpp/app_templates/template-khello/ (in this example the language is c++ if you use other language replace cpp with the language name):

".kdev_ignore" is an empty file. It prevents KDevelop's C++-parser from parsing the C++ template files. This is necessary because the template files are just code templates and not real code (yet).
".cvsignore" looks like this:
```
Makefile
Makefile.in
script.local
```
"Makefile.am" looks like this:

Finally add "template-khello" to "SUBDIRS = " in kdevelop/languages/cpp/app_templates/Makefile.am.

Attention:: Please test your template whether it installs and behaves correctly! Test, test and test again! It works? Well - now talk to the kdevelop guys so that they know what's going on and probably you may commit. ;)

IV. Changes to the template system (VERY IMPORTANT)

The entire app template system described above has been changed. To port a template to the new system the information from the script file will need to be moved into the ini file. The example is as follows:

install(
"${src}/template-chello/app.kdevelop","${dest}/${APPNAMELC}.kdevelop" );

becomes

[PROJECT]
Type=install
Source=%{src}/template-chello/app.kdevelop
Dest=%{dest}/%{APPNAMELC}.kdevelop

Things like installIncAdmin(); and installGNU(); now involve unpacking the tar archives. This is done by creating a target in the ini file as follows:

[GNU]
Type=install archive
Source=%{src}/template-common/gnu.tar.gz
Dest=%{dest}

The popular script functions convert as follows:

installIncAdmin(); %{src}/template-common/incadmin.tar.gz
installGNU();  %{src}/template-common/gnu.tar.gz
installAdmin(); %{src}/template-common/admin.tar.gz
installGnome(); %{src}/template-common/gnome.tar.gz
installWX(); %{src}/template-common/wxwidgets.tar.gz

To create directories is now:

[SRC]
Type= mkdir
Dir=%{dest}/src

New additions are as follows:

[MGS]
Type=message
Comment=A simple C project was created in %{dest}.

Will allow you to display a custom message when the template has finished installing. This is very handy for projects that require custom variables to be set.

The concept of custom variables was also introduced. To create a variable that can be edited from the project wizard you need to add an entry as follows:

[LIBS]
Type = value
ValueType=<Qt Data type>
Value= <Value Name that will be substituted in the code>
Comment= <The label in the UI>
Default= <The default value>

One special value can be used to turn targets on and off. This is done by adding a value as follows:

[DOCSOPT]
Type = value
ValueType=bool
Value=INSTALL_DOCS
Comment= Install Docbook documentation templates.
Default=true

Then in the targets you wish to make optional you add the Option property with the value's name as the data. This will look as follows:

[DOCSDIREN]
Type=mkdir
Dir=%{dest}/doc/en
Option=INSTALL_DOCS

The Option target is available to the mkdir, install, and install archive targets.

The last new addition is the optional post processing of the files as they are copied. For install and install archive you can add a Process=true or Process=false to turn the processing on or off.

A note on the UI. its not final, it will get better. Suggestions or bugs should be noted asap.

doc/api

doc/api

API Reference