KDevelop4/Manual/Working with templates
Working with templates
Some of KDevelop's code generation features use templates. These define the output structure, while you supply the needed parameters and data.
Using templates instead of fixed functionality allows greater flexibility and customizability. Templates can be chosen and modified to suite your particular needs, programming language and coding style. In the cases of project and class templates, they can be shared and downloaded, providing additional functionality to KDevelop without extra code.
Project Templates
Instructions for starting a new project are avaliable in the section Setting up a new project.
File structure
A project template is a compressed archives with specific contents. Every template needs a description file with the same base name as the archive itself, and an extension ".kdevtemplate". Other files are treated as template contents and will be present in the generated project.
The directory structure within the archive can be similar to this
my_template.tar.bz2
|-- my_template.kdevtemplate
|-- src/
| |-- CMakeLists.txt
| |-- main.cpp
| |-- %{APPNAMELC}.h
| +-- %{APPNAMELC}.cpp
+-- CMakeLists.txt
+-- %{PROJECTDIRNAME}.kdev4
Let's say we create the project using the above template and application name Example. The resulting project tree will look like this
~/projects/Example |-- src/ | |-- CMakeLists.txt | |-- main.cpp | |-- example.h | +-- example.cpp +-- CMakeLists.txt +-- Example.kdev4
The .kdevtemplate description file was removed, as it is used to describe the template, not the resulting project. Other files have been copied from the archive to the project folder. Variables in files names have been replaced with their values. Although not visible from the file structure, variables in the files' contents have been replaced as well.
Variables
Project templates in KDevelop, just like in KAppTemplate, use KMacroExpander to substitute variable placeholders with their real values. This means that when generating a project, strings of the form %{VARIABLE_NAME} will be replaced with the value of VARIABLE_NAME.
The recognized variables in KDevelop are
| Variable name | Description | Example value |
|---|---|---|
| APPNAME | The application name, specified when starting a project | Example |
| APPNAMELC | The application name in lowercase | example |
| APPNAMEUC | The application name in uppercase | EXAMPLE |
| APPNAMEID | The application name with all non-alphanumeric characters replaced with undescores. Useful for identifiers. | Example |
| PROJECTDIR | Absolute path to the directory where the project is being created | /home/<user>/projects/Example |
| PROJECTDIRNAME | The name of the directory where the project is being created | Example |
| VERSIONCONTROLPLUGIN | The version control plugin, chosen in the assistant dialog | kdevgit,kdevsvn,kdevcvs, or empty of no version control was selected |
Description file structure
Template description files, with the extension of ".kdevtemplate", follow the freedesktop.org desktop file specification. They are quite simple, with a single category, and four entries.
Here is an example template description file
[General]
Name=Simple C++ application
Comment=An example C++ application, showing the features of templates for project generation.
ShowFilesAfterGeneration=%{PROJECTDIR}/src/%{APPNAMELC}.cpp
Category=KDE/Examples
The name and comment can be translated, as they are in all .desktop files, by appending locale-specific identifier to the keys. The other two entries are read by KDevelop and are used mainly for user convenience. If a ShowFileAfterGeneration key entry is present, the specified file is opened after the project is created. The Category serves to better divide templates in a tree view for selection. It can contain any number of levels, separated by slashes, but it is recommended to always use two levers for consistency.
KDevPlatform Macro
Keeping source code in compressed archives is an inconvenience, both for version control systems and for users when trying to edit these templates. For that reason, KDevPlatform includes a convenience CMake macro that compresses and installs a directory as a template archive.
For instance, a number of templates can be kept in a directory structure such as this
templates/ |-- example/ | |-- basic_cpp_example/ | | |-- basic_cpp_example.kdevtemplate | | +-- other files | +-- kde_cpp_example/ | |-- kde_cpp_example.kdevtemplate | +-- other files |-- CMakeLists.txt
These templates can be compressed with the following CMake commands
set(example_template_DIRS
example/basic_cpp_example
example/kde_cpp_example
)
kdevplatform_add_app_templates(${example_template_DIRS})
Note that kdevplatform_add_app_templates also adds the templates to the list of install targets, so you do not have to install them yourself. They are installed into a directory where KDevelop will detect and load them.
Class Templates
Class templates use the Grantlee library for rendering templates. It has more features than KMacroExpander, the most important being loops and the ability to expose custom data types from C++ code to templates. The use of Grantlee makes templates more powerful, but also more difficult to write.
For information regarding Grantlee templates in general, refer to its documentation.
File Structure
Like project templates, class templates are compressed directories, and they too contain a special description file and any number of content files. It is recommended that the description file has a ".desktop" extension instead of ".kdevtemplate", although both are supported.
Unlike with project templates, not all files from the archive are copied to the output directory. Because Grantlee supports template inheritance and inclusions, class templates may contain helper files that only serve for convenience and produce no actual output. The actual output files have to be specified in the template description.