Development/Tutorials/KDevelop/Creating a project template: Difference between revisions

    From KDE TechBase
    (Add note about unreleased version)
    Line 103: Line 103:
    ==== The CMake file ====
    ==== 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">
    <syntaxhighlight lang="cmake">

    Revision as of 10:55, 11 July 2012

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


    Creating a project template
    Tutorial Series   KDevelop Templates
    Previous  
    What's Next  
    Further Reading   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 kdev_tutorial.

    The description file

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

    [General]
    Name=KDevelop Tutorial
    Comment=An example project template
    Category=KDE/Tutorial
    

    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 main.cpp file, and a CMakeLists.txt file for building. It is also recommended to add a .kdev4 project file, so that KDevelop will know what version control system to use.

    Class header file

    As explained in the [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 %{APPNAMELC}.h and %{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

    #ifndef %{APPNAMEUC}_H
    #define %{APPNAMEUC}_H
    
    class %{APPNAMEID}
    {
    public:
        %{APPNAMEID}();
        ~%{APPNAMEID}();
    };
    
    #endif // %{APPNAMEUC}_H
    

    Class implementation

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

    #include "%{APPNAMELC}.h"
    
    %{APPNAMEID}::%{APPNAMEID}()
    {
    
    }
    
    %{APPNAMEID}::~%{APPNAMEID}()
    {
    
    }
    

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

    The main.cpp file

    In the main file, we define the main() function and use the above class.

    #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";
    }
    

    The CMake file

    The source files can be compiled manually, but for the user's convenience we will use CMake. The CMakeLists.txt file for such a simple project will be short

    project(%{APPNAMEID})
    
    set(%{APPNAMEID}_SRCS
        %{APPNAMELC}.cpp
        main.cpp
    )
    
    add_executable(%{APPNAMELC} %{APPNAMEID}_SRCS)
    install(TARGETS %{APPNAMELC} DESTINATION bin)
    

    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 %{PROJECTDIRNAME}.kdev4 and paste in these contents

    [Project]
    Name=%{APPNAME}
    Manager=KDevCMakeManager
    VersionControl=%{VERSIONCONTROLPLUGIN}
    

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

    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.