Development/Tutorials/KDevelop/Creating a project template - Revision history

Miha: Fix template description file name

2012-07-11T11:02:39Z

Fix template description file name

Miha: /* The CMake file */

2012-07-11T10:59:22Z

‎The CMake file

Miha: /* The CMake file */

2012-07-11T10:57:29Z

‎The CMake file

Miha: /* The CMake file */

2012-07-11T10:55:39Z

‎The CMake file

Miha: Add note about unreleased version

2012-07-11T06:48:28Z

Add note about unreleased version

Miha: /* With CMake */

2012-07-11T06:45:57Z

‎With CMake

Miha: Created page with "{{Construction}} {{TutorialBrowser| series=KDevelop Templates| name=Creating a project template| pre=| next=| reading=[[Projects/KDevelop4/Project_template_specification|P..."

2012-07-11T06:41:54Z

Created page with "{{Construction}} {{TutorialBrowser| series=KDevelop Templates| name=Creating a project template| pre=| next=| reading=[[Projects/KDevelop4/Project_template_specification|P..."

New page

{{Construction}}

{{TutorialBrowser|

series=KDevelop Templates|

name=Creating a project template|

pre=|

next=|

reading=[[Projects/KDevelop4/Project_template_specification|Project template specification]]
}}

== Introduction ==

'''KDevelop''' uses the same project templates as '''KAppTemplate'''. Those are compressed directories with a description file and any number of content files. When starting a new project, the files are extracted and placeholders replaces with user-specified values.

== Creating the directory structure ==

We will start with an empty directory. Name it something unique, like {{path|kdev_tutorial}}.

=== The description file ===

Every project template needs a description file. It is a regular desktop file, but with an extension of <tt>.kdevtemplate</tt>. Its base name must match the name of the generated archive, so let's call it {{path|kdev_tutorial.desktop}}. Paste in these contents:

<syntaxhighlight lang="ini">
[General]
Name=KDevelop Tutorial
Comment=An example project template
Category=KDE/Tutorial
</syntaxhighlight>

Now, '''KDevelop''' will be able to find our template and offer it for selection when starting a new project. However, using it would create an empty project, as we still need to add files to the template.

=== Template content files ===

We must decide what kind of project do we want to create. For the needs of the tutorial, we will keep it simple and restrict ourselves to four files: Header and implementation for a class, a {{path|main.cpp}} file, and a {{path|CMakeLists.txt}} file for building. It is also recommended to add a {{path|.kdev4}} project file, so that '''KDevelop''' will know what version control system to use.

==== Class header file ====

As explained in the [[http://techbase.kde.org/Projects/KDevelop4/Project_template_specification#Variables|template variables]] section, '''KDevelop''' will replace certain placeholders with suitable values. We will use some of this placeholders now.

The placeholders are replaced in both file names and contents. In this tutorial, we will create a class with the same name as the application itself, and use the convention of lowercase file names. The header and implementation files will thus be named {{path|%{APPNAMELC}.h}} and {{path|%{APPNAMELC}.cpp}}, respectively.

The header file contents can also include placeholders. For this tutorial, let's create an empty class with a constructor and a destructor

<syntaxhighlight lang="cpp-qt">
#ifndef %{APPNAMEUC}_H
#define %{APPNAMEUC}_H

class %{APPNAMEID}
{
public:
%{APPNAMEID}();
~%{APPNAMEID}();
};

#endif // %{APPNAMEUC}_H

</syntaxhighlight>

==== Class implementation ====

The correspending implementation must include the header and implement the two declared methods.

<syntaxhighlight lang="cpp-qt">
#include "%{APPNAMELC}.h"

%{APPNAMEID}::%{APPNAMEID}()
{

}

%{APPNAMEID}::~%{APPNAMEID}()
{

}
</syntaxhighlight>

Placeholders are always replaced in the same way, so the <tt>#include</tt> line will always match the header file.

==== The {{path|main.cpp}} file ====

In the main file, we define the <tt>main()</tt> function and use the above class.

<syntaxhighlight lang="cpp-qt">
#include "%{APPNAMELC}.h"
#include <iostream>

using namespace std;

int main(int argc, char** argv)
{
%{APPNAMEID}* instance = new %{APPNAMEID};
cout << "Created an instance of %{APPNAMEID}";
delete instance;
cout << "Deleted the instance";
}
</syntaxhighlight>

==== The CMake file ====

We could build this manually, but for convenience we will use CMake. The {{path|CMakeLists.txt}} file for such a simple project will be short

<syntaxhighlight lang="cmake">
project(%{APPNAMEID})

set(%{APPNAMEID}_SRCS
%{APPNAMELC}.cpp
main.cpp
)

add_executable(%{APPNAMELC} %{APPNAMEID}_SRCS)
install(TARGETS %{APPNAMELC} DESTINATION bin)
</syntaxhighlight>

==== The project file ====

Including a project file is necessary for '''KDevelop''' to initialize a version control system for the new project. It should be named like the project directory name, so we use the %{PROJECTDIRNAME} placeholder. Create a file {{path|%{PROJECTDIRNAME}.kdev4}} and paste in these contents

<syntaxhighlight lang="ini">
[Project]
Name=%{APPNAME}
Manager=KDevCMakeManager
VersionControl=%{VERSIONCONTROLPLUGIN}
</syntaxhighlight>

If you do not wish to use CMake in generated project, replace <tt>KDevCMakeManager</tt> with <tt>KDevGenericManager</tt>.

== Installing the template ==

Now we have all the template contents prepared. We only need to compress the directory and make it available to '''KDevelop'''.

There are three ways for doing that:
* compressing and loading it manually
* loading it from within '''KDevelop'''
* using a CMake macro.

=== Manually ===

First create an archive out of the {{path|kdev_tutorial}} directory. Many archive formats are accepted, but for best compatibility use {{path|.zip}} in Windows and {{path|.tar.bz2}} everywhere else. In '''Dolphin''', this can be achieved by right clicking within the directory, choosing <menuchoice>Compress -> Compress To...</menuchoice>, and entering the filename as {{path|kdev_tutorial.tar.bz2}}.

Now copy the new archive somewhere where '''KDevelop''' will find it. It looks for template archives in the {{path|${PREFIX}/share/apps/kdevappwizard/templates}}, where prefix is either the system directory where KDE is installed (for example {{path|/usr}}) or the the local KDE configuration (for example {{path|~/.kde}} or {{path|~/.kde4}}). Copying our template to either is fine, choose dependeng on whether you want the template available only to you or all users on your computer.

After a run of <tt>kbuildsycoca4</tt>, '''KDevelop''' should pick up and offer you new template when creating a new project.

=== From '''KDevelop''' ===

You can have '''KDevelop''' do all this. Select <menuchoice>Project -> New From Template</menuchoice>, then in the dialog click the <menuchoice>Load Template From File</menuchoice>. Navigate to the {{path|kdev_tutorial}} directory, and open the {{path|kdev_tutorial.kdevtemplate}} file. Your template directory will be compressed and install into the local directory (usually {{path|~/.kde/share/apps/kdevappwizard/templates}}).

=== With CMake ===

'''KDevPlatform''' includes a CMake macro that takes care of compressing and installing templates. This has the disadvantage of requiring a large library for installing a simple archive file, but may be useful especially for project that already depend on it. Alternatively, you may copy [https://projects.kde.org/projects/extragear/kdevelop/kdevplatform/repository/revisions/master/entry/cmake/modules/KDevPlatformMacros.cmake KDevPlatformMacros.cmake] and put it into your project.

The macro requires that each template is in a separate directory, so create a new {{path|kdev_tutorial_templates}} directory and move {{path|kdev_tutorial}} into it. Then add the following {{path|CMakeLists.txt}} file to the top-level directory

<syntaxhighlight lang="cmake">
project(kdevelop_template_tutorial)

find_package(KDE4 REQUIRED)
find_package(KDevPlatform REQUIRED)

set(TEMPLATE_DIRS kdev_tutorial)
kdevplatform_add_app_templates(${TEMPLATE_DIRS})
</syntaxhighlight>

@@ Line 117: / Line 117: @@
 </syntaxhighlight>
-It is important to note the diffirence between CMake's syntax for accessing variables (${VARIABLE}) and placeholders used in project templates (%{VARIABLE}). Because of this difference we can use both in the same file.
+It is important to note the diffirence between CMake's syntax for accessing variables (${VARIABLE}) and placeholders used in project templates (%{VARIABLE}). Percent-prefixed placeholders will be expanded first, when the project is generated, while CMake's variables are only read when <tt>cmake</tt> is run. Because of this difference we can use both in the same file.
 ==== The project file ====

← Older revision		Revision as of 06:45, 11 July 2012
Line 166:		Line 166:
	kdevplatform_add_app_templates(${TEMPLATE_DIRS})		kdevplatform_add_app_templates(${TEMPLATE_DIRS})
	</syntaxhighlight>		</syntaxhighlight>
		+
		+	Build and install the project with the usual CMake steps
		+
		+	{{Input\|1=<nowiki>
		+	mkdir build
		+	cd build
		+	cmake ..
		+	make
		+	make install
		+	</nowiki>}}
		+
		+	Note that this will install the template into {{path\|<nowiki>${CMAKE_INSTALL_PREFIX}</nowiki>}}, for which you may need root privileges.

@@ Line 24: / Line 24: @@
 === The description file ===
-Every project template needs a description file. It is a regular desktop file, but with an extension of <tt>.kdevtemplate</tt>. Its base name must match the name of the generated archive, so let's call it {{path|kdev_tutorial.desktop}}. Paste in these contents:
+Every project template needs a description file. It is a regular desktop file, but with an extension of <tt>.kdevtemplate</tt>. Its base name must match the name of the generated archive, so let's call it {{path|kdev_tutorial.kdevtempate}}. Paste in these contents:
 <syntaxhighlight lang="ini">
@@ Line 33: / Line 33: @@
 </syntaxhighlight>
 Now, '''KDevelop''' will be able to find our template and offer it for selection when starting a new project. However, using it would create an empty project, as we still need to add files to the template.
 === Template content files ===

@@ Line 113: / Line 113: @@
+)
-add_executable(%{APPNAMELC} %{APPNAMEID}_SRCS)
+add_executable(%{APPNAMELC} ${%{APPNAMEID}_SRCS})
 install(TARGETS %{APPNAMELC} DESTINATION bin)
 </syntaxhighlight>
 ==== The project file ====

@@ Line 103: / Line 103: @@
 ==== The CMake file ====
-We could build this manually, but for convenience we will use CMake. The {{path|CMakeLists.txt}} file for such a simple project will be short
+The source files can be compiled manually, but for the user's convenience we will use CMake. The {{path|CMakeLists.txt}} file for such a simple project will be short
 <syntaxhighlight lang="cmake">

@@ Line 149: / Line 149: @@
 === From '''KDevelop''' ===
-You can have '''KDevelop''' do all this. Select <menuchoice>Project -> New From Template</menuchoice>, then in the dialog click the <menuchoice>Load Template From File</menuchoice>. Navigate to the {{path|kdev_tutorial}} directory, and open the {{path|kdev_tutorial.kdevtemplate}} file. Your template directory will be compressed and install into the local directory (usually {{path|~/.kde/share/apps/kdevappwizard/templates}}).
+{{Note|This method requires an unreleased version of KDevelop. If you are not using the latest development version, use one of the other two options. }}
 === With CMake ===