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 tdevelop 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 TDevelop 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 $TDEDIR/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 $TDEDIR/share/apps/kdevappwizard/template-common/tdevelop.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 startupShowFilesAfterGeneration=
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
). AndAPPNAMEUC
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, whereasHOMEDIR
is a keyword
- Attention
- The file
template-khello/khello
must have the same name as the right half of the directory! If the directory istemplate-foobar
the file must betemplate-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 (usuallydoc, 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 tdevelop 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:
- Attention
- Please test your template whether it installs and behaves correctly! Test, test and test again! ;)
III. How To Add The Template To TDevelop CVS HEAD
This section is for tdevelop developers only. Most probably you don't have to read this!.
Move the directory "template-khello"
to tdevelop/languages/cpp/app_templates/
and then add the following files in tdevelop/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 TDevelop'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:MakefileMakefile.inscript.local"Makefile.am"
looks like this:
Finally add "template-khello"
to "SUBDIRS = " in tdevelop/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 tdevelop 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:
becomes
Things like installIncAdmin();
and installGNU();
now involve unpacking the tar archives. This is done by creating a target in the ini file as follows:
The popular script functions convert as follows:
To create directories is now:
New additions are as follows:
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:
One special value can be used to turn targets on and off. This is done by adding a value as follows:
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:
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.