Difference between revisions of "Projects/KDevelop4/Project template specification"

Jump to: navigation, search
(KDevPlatform Macro)
 
(5 intermediate revisions by one user not shown)
Line 1: Line 1:
 +
{{ Construction }}
 +
 
=== File structure ===
 
=== File structure ===
  
Line 60: Line 62:
 
|PROJECTDIR
 
|PROJECTDIR
 
|Absolute path to the directory where the project is being created
 
|Absolute path to the directory where the project is being created
|/home/<user>/projects/Example
+
|{{path|/home/<user>/projects/Example}}
 
|-
 
|-
 
|PROJECTDIRNAME
 
|PROJECTDIRNAME
 
|The name of the directory where the project is being created
 
|The name of the directory where the project is being created
|Example
+
|{{path|Example}}
 
|-
 
|-
 
|VERSIONCONTROLPLUGIN
 
|VERSIONCONTROLPLUGIN
 
|The version control plugin, chosen in the assistant dialog
 
|The version control plugin, chosen in the assistant dialog
|kdevgit,kdevsvn,kdevcvs, or empty of no version control was selected
+
|<tt>kdevgit</tt>, <tt>kdevsvn</tt>, <tt>kdevcvs</tt>, or empty of no version control was selected
 
|-
 
|-
 
|}
 
|}
Line 78: Line 80:
 
Here is an example template description file
 
Here is an example template description file
  
{{Input|1=<nowiki>
+
<syntaxhighlight lang="ini">
 
[General]
 
[General]
 
Name=Simple C++ application
 
Name=Simple C++ application
Line 84: Line 86:
 
ShowFilesAfterGeneration=%{PROJECTDIR}/src/%{APPNAMELC}.cpp
 
ShowFilesAfterGeneration=%{PROJECTDIR}/src/%{APPNAMELC}.cpp
 
Category=KDE/Examples
 
Category=KDE/Examples
</nowiki>}}
+
</syntaxhighlight>
  
 
The name and comment can be translated, as they are in all <tt>.desktop</tt> 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.
 
The name and comment can be translated, as they are in all <tt>.desktop</tt> 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.
Line 108: Line 110:
 
These templates can be compressed with the following CMake commands
 
These templates can be compressed with the following CMake commands
  
{{Input|1=<nowiki>
+
<syntaxhighlight lang="cmake">
 
set(example_template_DIRS
 
set(example_template_DIRS
 
     example/basic_cpp_example
 
     example/basic_cpp_example
Line 115: Line 117:
  
 
kdevplatform_add_app_templates(${example_template_DIRS})
 
kdevplatform_add_app_templates(${example_template_DIRS})
</nowiki>}}
+
</syntaxhighlight>
  
 
Note that <tt>kdevplatform_add_app_templates</tt> 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.
 
Note that <tt>kdevplatform_add_app_templates</tt> 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.

Latest revision as of 10:42, 10 July 2012

Under construction.png
 
Under Construction
This is a new page, currently under construction!


Contents

[edit] 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.

[edit] 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

[edit] 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.

[edit] CMake 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.

[edit] Using the templates

Instructions for starting a new project from a template are avaliable in the Userbase section Setting up a new project. If you installed the template using a CMake script, it should be picked up by KDevelop immediately (or after running kbuildsycoca4).


This page was last modified on 10 July 2012, at 10:42. This page has been accessed 2,678 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal