Projects/KDevelop4/Project template specification - Revision history

Miha: moved Development/KDevelop/Project template specification to Projects/KDevelop4/Project template specification: Move it together with other KDevelop pages

2012-07-10T09:42:49Z

moved Development/KDevelop/Project template specification to Projects/KDevelop4/Project template specification: Move it together with other KDevelop pages

Miha: Format paths

2012-07-10T09:25:14Z

Format paths

Miha: Format VCS plugin names

2012-07-10T09:24:23Z

Format VCS plugin names

Miha: Syntax highlight for CMake code

2012-07-10T09:23:17Z

Syntax highlight for CMake code

Miha: Syntax highlight for desktop file

2012-07-10T09:19:07Z

Syntax highlight for desktop file

Miha at 07:49, 10 July 2012

2012-07-10T07:49:26Z

Miha: /* KDevPlatform Macro */

2012-07-10T07:09:11Z

‎KDevPlatform Macro

Miha: Created page with "=== 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,..."

2012-07-10T07:08:32Z

Created page with "=== 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,..."

New page

=== 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 <tt>.kdevtemplate</tt>. 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

{{Input|1=<nowiki>
my_template.tar.bz2
|-- my_template.kdevtemplate
|-- src/
| |-- CMakeLists.txt
| |-- main.cpp
| |-- %{APPNAMELC}.h
| +-- %{APPNAMELC}.cpp
+-- CMakeLists.txt
+-- %{PROJECTDIRNAME}.kdev4
</nowiki>}}

Let's say we create the project using the above template and application name <code>Example</code>. The resulting project tree will look like this

{{Output|1=<nowiki>
~/projects/Example
|-- src/
| |-- CMakeLists.txt
| |-- main.cpp
| |-- example.h
| +-- example.cpp
+-- CMakeLists.txt
+-- Example.kdev4
</nowiki>}}

The <tt>.kdevtemplate</tt> 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 [http://api.kde.org/4.8-api/kdelibs-apidocs/kdecore/html/namespaceKMacroExpander.html 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
{| class="wikitable"
!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 <tt>.kdevtemplate</tt>, 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

{{Input|1=<nowiki>
[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
</nowiki>}}

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.

=== 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

{{Input|1=<nowiki>
templates/
|-- example/
| |-- basic_cpp_example/
| | |-- basic_cpp_example.kdevtemplate
| | +-- other files
| +-- kde_cpp_example/
| |-- kde_cpp_example.kdevtemplate
| +-- other files
|-- CMakeLists.txt
</nowiki>}}

These templates can be compressed with the following CMake commands

{{Input|1=<nowiki>
set(example_template_DIRS
example/basic_cpp_example
example/kde_cpp_example
)

kdevplatform_add_app_templates(${example_template_DIRS})
</nowiki>}}

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.

=== Using the templates ===
Instructions for starting a new project from a template are avaliable in the Userbase section [http://userbase.kde.org/special:myLanguage/KDevelop4/Manual/Setting_up_a_new_project_from_scratch 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 <tt>kbuildsycoca4</tt>).

← Older revision		Revision as of 07:49, 10 July 2012
Line 1:		Line 1:
		+	{{ Construction }}
		+
	=== File structure ===		=== File structure ===

@@ Line 62: / Line 62: @@
 |PROJECTDIR
 |Absolute path to the directory where the project is being created
-|/home/<user>/projects/Example
+|{{path|/home/<user>/projects/Example}}
 |-
 |PROJECTDIRNAME
 |The name of the directory where the project is being created
-|Example
+|{{path|Example}}
 |-
 |VERSIONCONTROLPLUGIN

@@ Line 70: / Line 70: @@
 |VERSIONCONTROLPLUGIN
 |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 110: / Line 110: @@
 These templates can be compressed with the following CMake commands
-{{Input|1=<nowiki>
+<syntaxhighlight lang="cmake">
 set(example_template_DIRS
      example/basic_cpp_example
@@ Line 117: / Line 117: @@
 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.

@@ Line 80: / Line 80: @@
 Here is an example template description file
-{{Input|1=<nowiki>
+<syntaxhighlight lang="ini">
 [General]
 Name=Simple C++ application
@@ Line 86: / Line 86: @@
 ShowFilesAfterGeneration=%{PROJECTDIR}/src/%{APPNAMELC}.cpp
 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.

@@ Line 88: / Line 88: @@
 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.
-=== KDevPlatform Macro ===
+=== 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.