Development/Tutorials/KDevelop/Creating a class template

    From KDE TechBase
     
    Under Construction
    This is a new page, currently under construction!


    Creating a project template
    Tutorial Series   KDevelop Templates
    Previous   Grantlee for theme artists, Django template language
    What's Next  
    Further Reading   Class template specification

    Introduction

    In this tutorial, we will create a template for a basic C++ class. It will demonstrate using the Grantlee template language, as well features specific to KDevelop class templates.

    We chose C++ because even the simplest class definition often consists of two separate files, header and implementation. It is possible to include any number of files in a class template (there should be at least one, obviously).

    Creating the directory structure

    Note
    There is a project template for a C++ class template available here. The resulting project is similar to what we will create here. You may use it to create the files but still follow this tutorial for explanation.


    We will start with an empty directory. Name it something unique, like kdev_class_tutorial.

    The description file

    Every class template needs a description file. It is a regular desktop file with an extension of .desktop. Its base name must match the name of the generated archive, so let's call it kdev_class_tutorial.desktop. Paste in these contents:

    [General]
    Name=Tutorial
    Comment=An example C++ class template, suitable for a tutorial
    Category=C++
    Files=Header,Implementation
    
    [Header]
    Name=Header
    File=class.h
    OutputFile={{ name }}.h
    
    [Implementation]
    Name=Implementation
    File=class.cpp
    OutputFile={{ name }}.cpp
    

    You can see there are three sections in the description file: one for general properties, and one for each output file. In order for a file to be generated, it has to be listed in the Files entry, as well as have its own section with the same name.

    In the output file sections, we already used template variables: {{ name }} will be replaced with the class name. The actual generated header file will not be {{ name }}.h, but rather Exmample.h, assuming we name our class Example.

    The class header file

    Now, let's move on to the class declaration.

    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 kdev_tutorial directory. Many archive formats are accepted, but for best compatibility use .zip in Windows and .tar.bz2 everywhere else. In Dolphin, this can be achieved by right clicking within the directory, choosing Compress -> Compress To..., and entering the filename as kdev_tutorial.tar.bz2.

    Now copy the new archive somewhere where KDevelop will find it. It looks for template archives in the ${PREFIX}/share/apps/kdevappwizard/templates, where prefix is either the system directory where KDE is installed (for example /usr) or the the local KDE configuration (for example ~/.kde or ~/.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 kbuildsycoca4, KDevelop should pick up and offer you new template when creating a new project.

    From KDevelop

    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.


    You can have KDevelop do all this. Select Project -> New From Template, then in the dialog click the Load Template From File. Navigate to the kdev_tutorial directory, and open the kdev_tutorial.kdevtemplate file. Your template directory will be compressed and install into the local directory (usually ~/.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 KDevPlatformMacros.cmake and put it into your project.

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

    project(kdevelop_template_tutorial)
    
    find_package(KDE4 REQUIRED)
    find_package(KDevPlatform REQUIRED)
    
    set(TEMPLATE_DIRS kdev_tutorial)
    kdevplatform_add_app_templates(${TEMPLATE_DIRS})
    

    Build and install the project with the usual CMake steps

    mkdir build
    cd build
    cmake ..
    make
    make install
    

    Note that this will install the template into ${CMAKE_INSTALL_PREFIX}, for which you may need root privileges.