KDevelop5/Project template specification: Difference between revisions

    From KDE TechBase
    (Syntax highlight for desktop file)
    (Improve/Update)
     
    (5 intermediate revisions by 2 users not shown)
    Line 3: Line 3:
    === File structure ===
    === 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.  
    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>. Optionally there can also be an image file which will be used as preview or symbolic display with the description (preferred size: 200 pixels width). 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
    The directory structure within the archive can be similar to this
    Line 9: Line 9:
    {{Input|1=<nowiki>
    {{Input|1=<nowiki>
    my_template.tar.bz2
    my_template.tar.bz2
    |-- my_template.kdevtemplate
    +-- my_template.kdevtemplate
    +-- my_template.png
    |-- src/
    |-- src/
    |  |-- CMakeLists.txt
    |  |-- CMakeLists.txt
    Line 32: Line 33:
    </nowiki>}}
    </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.
    The <tt>.kdevtemplate</tt> description file was removed, as it is used to describe the template, not the resulting project. The same was done to the file <tt>my_template.png</tt> (which is referred to from the description file). 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 ===
    === 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.  
    Project templates in '''KDevelop''', just like in '''KAppTemplate''', use [https://api.kde.org/frameworks/kcoreaddons/html/namespaceKMacroExpander.html KMacroExpander] to substitute variable placeholders with their real values. This means that when generating a project, strings of the form <tt>%{VARIABLE_NAME}</tt> will be replaced with the value of <tt>VARIABLE_NAME</tt>.  


    The recognized variables in '''KDevelop''' are
    The recognized variables in '''KDevelop''' are
    Line 62: Line 63:
    |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 76: Line 77:
    === Description file structure ===
    === 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.  
    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 three required entries (Name, Comment, Category) and two optional (ShowFilesAfterGeneration, Icon).


    Here is an example template description file
    Here is an example template description file:


    <syntaxhighlight lang="ini">
    <syntaxhighlight lang="ini">
    Line 84: Line 85:
    Name=Simple C++ application
    Name=Simple C++ application
    Comment=An example C++ application, showing the features of templates for project generation.  
    Comment=An example C++ application, showing the features of templates for project generation.  
    ShowFilesAfterGeneration=%{PROJECTDIR}/src/%{APPNAMELC}.cpp
    Icon=SimpleApp.png
    Category=KDE/Examples
    ShowFilesAfterGeneration=src/%{APPNAMELC}.cpp
    Category=Qt/Examples
    </syntaxhighlight>
    </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 entries can be translated, like they are in all <tt>.desktop</tt> files, by appending locale-specific identifier to the keys. The other three entries are read by '''KDevelop''' and are used mainly for user convenience. The entry 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.
    If a ShowFilesAfterGeneration entry is present, the specified files are opened after the project is created. If an Icon entry is present, the specified file will be used as preview image and not copied into the generated sources.


    === CMake macro ===
    === CMake macro ===
    Line 110: Line 113:
    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 117: Line 120:


    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.


    === Using the templates ===
    === 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>).
    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 will be picked up by '''KDevelop''' immediately when you (re-)open the "Create New Project" dialog.

    Latest revision as of 14:47, 1 May 2017

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


    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. Optionally there can also be an image file which will be used as preview or symbolic display with the description (preferred size: 200 pixels width). 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
    +-- my_template.png
    |-- 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. The same was done to the file my_template.png (which is referred to from the description file). 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 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

    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 three required entries (Name, Comment, Category) and two optional (ShowFilesAfterGeneration, Icon).

    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. 
    Icon=SimpleApp.png
    ShowFilesAfterGeneration=src/%{APPNAMELC}.cpp
    Category=Qt/Examples
    

    The Name and Comment entries can be translated, like they are in all .desktop files, by appending locale-specific identifier to the keys. The other three entries are read by KDevelop and are used mainly for user convenience. The entry 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. If a ShowFilesAfterGeneration entry is present, the specified files are opened after the project is created. If an Icon entry is present, the specified file will be used as preview image and not copied into the generated sources.

    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.

    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 will be picked up by KDevelop immediately when you (re-)open the "Create New Project" dialog.