KDevelop4/Manual/Code generation with templates: Difference between revisions

From KDE UserBase Wiki
m (remove extra s)
No edit summary
 
(One intermediate revision by one other user not shown)
Line 2: Line 2:
<translate>
<translate>


== Code generation with templates ==
== Code generation with templates == <!--T:25-->


<!--T:26-->
'''KDevelop''' uses templates for generating source code files and to avoid writing repeatable code.  
'''KDevelop''' uses templates for generating source code files and to avoid writing repeatable code.  


</translate><span id="Creating a new class"></span><translate>
</translate><span id="Creating a new class"></span><translate>


=== Creating a new class ===
=== Creating a new class === <!--T:27-->


<!--T:28-->
The most common use for code generation is probably writing new classes. To create a new class in an existing project, right click on a project folder and choose <menuchoice>Create from Template</menuchoice>. The same dialog can be started from the menu by clicking <menuchoice>File -> New from Template</menuchoice>, but using a project folder has the benefit of setting a base URL for the output files. Choose <tt>Class</tt> in the category selection view, and the desired language and template in the other two views. After you have selected a class template, you will have to specify the details of the new class.  
The most common use for code generation is probably writing new classes. To create a new class in an existing project, right click on a project folder and choose <menuchoice>Create from Template</menuchoice>. The same dialog can be started from the menu by clicking <menuchoice>File -> New from Template</menuchoice>, but using a project folder has the benefit of setting a base URL for the output files. Choose <tt>Class</tt> in the category selection view, and the desired language and template in the other two views. After you have selected a class template, you will have to specify the details of the new class.  


<!--T:29-->
[[Image:kdevelop-template-selection.png|thumb|500px|center]]
[[Image:kdevelop-template-selection.png|thumb|500px|center]]


<!--T:30-->
First you have to specify an identifier for the new class. This can be a simple name (like <code>Bus</code>) or a complete identifier with namespaces (like <code>Transportation::Bus</code>). In the latter case, '''KDevelop''' will parse the identifier and correctly separate the namespaces from the actual name. On the same page, you can add base classes for the new class. You may notice that some templates choose a base class on their own, you are free to remove it and/or add other bases. You should write the full inheritance statement here, which is language-dependent, such as <code>public QObject</code> for C++, <code>extends SomeClass</code> for PHP or simply the name of the class for Python.  
First you have to specify an identifier for the new class. This can be a simple name (like <code>Bus</code>) or a complete identifier with namespaces (like <code>Transportation::Bus</code>). In the latter case, '''KDevelop''' will parse the identifier and correctly separate the namespaces from the actual name. On the same page, you can add base classes for the new class. You may notice that some templates choose a base class on their own, you are free to remove it and/or add other bases. You should write the full inheritance statement here, which is language-dependent, such as <code>public QObject</code> for C++, <code>extends SomeClass</code> for PHP or simply the name of the class for Python.  


<!--T:31-->
[[Image:kdevelop-template-inheritance.png|thumb|500px|center]]
[[Image:kdevelop-template-inheritance.png|thumb|500px|center]]


<!--T:32-->
In the next page, you are offered a selection of virtual methods from all inherited classes, as well as some default constructors, destructors and operators. Checking the check box next to a method signature will implement this method in the new class.  
In the next page, you are offered a selection of virtual methods from all inherited classes, as well as some default constructors, destructors and operators. Checking the check box next to a method signature will implement this method in the new class.  


<!--T:33-->
Clicking <menuchoice>Next</menuchoice> brings up a page where you can add members to a class. Depending on the selected template, these may appear in the new class as member variables, or the template may create properties with setters and getters for them. In a language where variable types have to be declared, such as C++, you have to specify both the type and the name of the member, such as <code>int number</code> or <code>QString name</code>. In other languages, you may leave out the type, but it is good practice to enter it anyway, because the selected template could still make some use of it.  
Clicking <menuchoice>Next</menuchoice> brings up a page where you can add members to a class. Depending on the selected template, these may appear in the new class as member variables, or the template may create properties with setters and getters for them. In a language where variable types have to be declared, such as C++, you have to specify both the type and the name of the member, such as <code>int number</code> or <code>QString name</code>. In other languages, you may leave out the type, but it is good practice to enter it anyway, because the selected template could still make some use of it.  


<!--T:34-->
[[Image:kdevelop-template-members.png|thumb|500px|center]]
[[Image:kdevelop-template-members.png|thumb|500px|center]]


<!--T:35-->
In the following pages, you can choose a license for you new class, set any custom options required by the selected template, and configure output locations for all the generated files. By clicking <menuchoice>Finish</menuchoice>, you complete the assistant and create the new class. The generated files will be opened in the editor, so you can start adding code right away.  
In the following pages, you can choose a license for you new class, set any custom options required by the selected template, and configure output locations for all the generated files. By clicking <menuchoice>Finish</menuchoice>, you complete the assistant and create the new class. The generated files will be opened in the editor, so you can start adding code right away.  


<!--T:36-->
After creating a new C++ class, you will be given an option of adding the class to a project target. Choose a target from the dialog page, or dismiss the page and add the files to a target manually.  
After creating a new C++ class, you will be given an option of adding the class to a project target. Choose a target from the dialog page, or dismiss the page and add the files to a target manually.  


<!--T:37-->
If you chose the <tt>Qt Object</tt> template, checked some of the default methods, and added two member variables, the output should look like on the following picture.  
If you chose the <tt>Qt Object</tt> template, checked some of the default methods, and added two member variables, the output should look like on the following picture.  


<!--T:38-->
[[Image:kdevelop-template-result.png|thumb|500px|center]]
[[Image:kdevelop-template-result.png|thumb|500px|center]]


<!--T:39-->
You can see that data members are converted into Qt properties, with accessor functions and the Q_PROPERTY macros. Arguments to setter functions are even passed by const-reference, where appropriate. Additionally, a private class is declared, and a private pointer created with Q_DECLARE_PRIVATE. All this is done by the template, choosing a different template in the first step could completely change the output.  
You can see that data members are converted into Qt properties, with accessor functions and the Q_PROPERTY macros. Arguments to setter functions are even passed by const-reference, where appropriate. Additionally, a private class is declared, and a private pointer created with Q_DECLARE_PRIVATE. All this is done by the template, choosing a different template in the first step could completely change the output.  


</translate><span id="Creating a new unit test"></span><translate>
</translate><span id="Creating a new unit test"></span><translate>


=== Creating a new unit test ===
=== Creating a new unit test === <!--T:40-->


<!--T:41-->
Even though most testing frameworks require each test to also be a class, '''KDevelop''' includes a method to simplify the creation of unit tests. To create a new test, right click on a project folder and choose <menuchoice>Create from Template</menuchoice>. In the template selection page, choose <tt>Test</tt> as the category, then choose your programming language and template and click <menuchoice>Next</menuchoice>.  
Even though most testing frameworks require each test to also be a class, '''KDevelop''' includes a method to simplify the creation of unit tests. To create a new test, right click on a project folder and choose <menuchoice>Create from Template</menuchoice>. In the template selection page, choose <tt>Test</tt> as the category, then choose your programming language and template and click <menuchoice>Next</menuchoice>.  


<!--T:42-->
You will be prompted for the test name and a list of test cases. For the test cases, you only have to specify a list of names. Some unit testing frameworks, such as PyUnit and PHPUnit, require that test cases start with a special prefix. In '''KDevelop''', the template is responsible for adding the prefix, so you do not have to prefix the test cases here. After clicking <menuchoice>Next</menuchoice>, specify the license and output locations for the generated files, and the test will be created.  
You will be prompted for the test name and a list of test cases. For the test cases, you only have to specify a list of names. Some unit testing frameworks, such as PyUnit and PHPUnit, require that test cases start with a special prefix. In '''KDevelop''', the template is responsible for adding the prefix, so you do not have to prefix the test cases here. After clicking <menuchoice>Next</menuchoice>, specify the license and output locations for the generated files, and the test will be created.  


Unit tests created this way will not be added to any target automatically. If you are using CTest or some other testing framework, make sure to add the new files to a target.  
<!--T:43-->
Unit tests created this way will not be added to any target automatically. If you are using CTest or some other testing framework, make sure to add the new files to a target. KDevelop provides a [[KDevelop4/Manual/Tool_list/Unit_Tests|Unit Tests toolview]] that integrates with CTest.  


</translate><span id="Other files"></span><translate>
</translate><span id="Other files"></span><translate>


=== Other files ===
=== Other files === <!--T:44-->


<!--T:45-->
While classes and unit tests receive special attention when generating code from templates, the same method can be used for any kind of source code files. For example, one could use a template for a CMake Find module or a .desktop file. This can be done by choosing <menuchoice>Create from Template</menuchoice>, and selecting the wanted category and template. If the selected category is neither <tt>Class</tt> nor <tt>Test</tt>, you will only have the option of choosing the license, any custom options specified by the template, and the output file locations. As with classes and tests, finishing the assistant will generate the files and open them in the editor.  
While classes and unit tests receive special attention when generating code from templates, the same method can be used for any kind of source code files. For example, one could use a template for a CMake Find module or a .desktop file. This can be done by choosing <menuchoice>Create from Template</menuchoice>, and selecting the wanted category and template. If the selected category is neither <tt>Class</tt> nor <tt>Test</tt>, you will only have the option of choosing the license, any custom options specified by the template, and the output file locations. As with classes and tests, finishing the assistant will generate the files and open them in the editor.  


</translate><span id="Managing templates"></span><translate>
</translate><span id="Managing templates"></span><translate>


=== Managing templates ===
=== Managing templates === <!--T:46-->


<!--T:47-->
From the <menuchoice>File -> New from Template</menuchoice> assistant, you can also download additional file templates by clicking the <menuchoice>Get more Templates...</menuchoice> button. This opens a Get Hot New Stuff dialog, where you can install additional templates, as well as update or remove them. There is also a configuration module for template, which can be reached by clicking <menuchoice>Settings -> Configure KDevelop -> Templates</menuchoice>. From there, you can manage both file templates (explained above) and project templates (used for creating new projects).  
From the <menuchoice>File -> New from Template</menuchoice> assistant, you can also download additional file templates by clicking the <menuchoice>Get more Templates...</menuchoice> button. This opens a Get Hot New Stuff dialog, where you can install additional templates, as well as update or remove them. There is also a configuration module for template, which can be reached by clicking <menuchoice>Settings -> Configure KDevelop -> Templates</menuchoice>. From there, you can manage both file templates (explained above) and project templates (used for creating new projects).  


<!--T:48-->
[[Image:kdevelop-template-manager.png|thumb|500px|center]]
[[Image:kdevelop-template-manager.png|thumb|500px|center]]


<!--T:49-->
Of course, if none of the available template suit your project, you can always create new ones. The easiest way is probably to copy and modify an existing template, while a short [http://techbase.kde.org/Development/Tutorials/KDevelop/Creating_a_class_template tutorial] and a longer [http://techbase.kde.org/Projects/KDevelop4/File_template_specification specification document] are there to help you. To copy an installed template, open the template manager by clicking <menuchoice>Settings -> Configure KDevelop... -> Templates</menuchoice>, select the template you wish to copy, then click the <menuchoice>Extract Template</menuchoice> button. Select a destination folder, then click <menuchoice>OK</menuchoice>, and the contents of the template will be extracted into the selected folder. Now you can edit the template by opening the extracted files and modifying them. After you are done, you can import your new template into '''KDevelop''' by opening the template manager, activating the appropriate tab (either <menuchoice>Project Templates</menuchoice> or <menuchoice>File Templates</menuchoice>) and clicking <menuchoice>Load Template</menuchoice>. Open the template description file, which is the one with the suffix either <code>.kdevtemplate</code> or <code>.desktop</code>. '''KDevelop''' will compress the files into a template archive and import the template.  
Of course, if none of the available template suit your project, you can always create new ones. The easiest way is probably to copy and modify an existing template, while a short [http://techbase.kde.org/Development/Tutorials/KDevelop/Creating_a_class_template tutorial] and a longer [http://techbase.kde.org/Projects/KDevelop4/File_template_specification specification document] are there to help you. To copy an installed template, open the template manager by clicking <menuchoice>Settings -> Configure KDevelop... -> Templates</menuchoice>, select the template you wish to copy, then click the <menuchoice>Extract Template</menuchoice> button. Select a destination folder, then click <menuchoice>OK</menuchoice>, and the contents of the template will be extracted into the selected folder. Now you can edit the template by opening the extracted files and modifying them. After you are done, you can import your new template into '''KDevelop''' by opening the template manager, activating the appropriate tab (either <menuchoice>Project Templates</menuchoice> or <menuchoice>File Templates</menuchoice>) and clicking <menuchoice>Load Template</menuchoice>. Open the template description file, which is the one with the suffix either <code>.kdevtemplate</code> or <code>.desktop</code>. '''KDevelop''' will compress the files into a template archive and import the template.  


<!--T:50-->
{{Note|1=When copying an existing template, make sure you rename it before importing it again. Otherwise, you will either overwrite the old template, or will end up with two templates with identical names. To rename a template, rename the description file to something unique (but keep the suffix), and change the <tt>Name</tt> entry in the description file. }}
{{Note|1=When copying an existing template, make sure you rename it before importing it again. Otherwise, you will either overwrite the old template, or will end up with two templates with identical names. To rename a template, rename the description file to something unique (but keep the suffix), and change the <tt>Name</tt> entry in the description file. }}


<!--T:51-->
If you want to write a template from scratch, you can start with a sample C++ class template by [[Special:myLanguage/KDevelop4/Manual/Sessions and projects#Creating projects from scratch|creating a new project]] and selecting the <tt>C++ Class Template</tt> project in category <tt>KDevelop</tt>.  
If you want to write a template from scratch, you can start with a sample C++ class template by [[Special:myLanguage/KDevelop4/Manual/Sessions and projects#Creating projects from scratch|creating a new project]] and selecting the <tt>C++ Class Template</tt> project in category <tt>KDevelop</tt>.  


<!--T:52-->
{{Prevnext2
{{Prevnext2
| prevpage=Special:MyLanguage/KDevelop4/Manual/Working with source code | nextpage=Special:MyLanguage/KDevelop4/Manual/Building_(compiling)_projects_with_custom_Makefiles
| prevpage=Special:MyLanguage/KDevelop4/Manual/Working with source code | nextpage=Special:MyLanguage/KDevelop4/Manual/Building_(compiling)_projects_with_custom_Makefiles

Latest revision as of 10:21, 27 November 2014

Other languages:

Code generation with templates

KDevelop uses templates for generating source code files and to avoid writing repeatable code.

Creating a new class

The most common use for code generation is probably writing new classes. To create a new class in an existing project, right click on a project folder and choose Create from Template. The same dialog can be started from the menu by clicking File -> New from Template, but using a project folder has the benefit of setting a base URL for the output files. Choose Class in the category selection view, and the desired language and template in the other two views. After you have selected a class template, you will have to specify the details of the new class.

First you have to specify an identifier for the new class. This can be a simple name (like Bus) or a complete identifier with namespaces (like Transportation::Bus). In the latter case, KDevelop will parse the identifier and correctly separate the namespaces from the actual name. On the same page, you can add base classes for the new class. You may notice that some templates choose a base class on their own, you are free to remove it and/or add other bases. You should write the full inheritance statement here, which is language-dependent, such as public QObject for C++, extends SomeClass for PHP or simply the name of the class for Python.

In the next page, you are offered a selection of virtual methods from all inherited classes, as well as some default constructors, destructors and operators. Checking the check box next to a method signature will implement this method in the new class.

Clicking Next brings up a page where you can add members to a class. Depending on the selected template, these may appear in the new class as member variables, or the template may create properties with setters and getters for them. In a language where variable types have to be declared, such as C++, you have to specify both the type and the name of the member, such as int number or QString name. In other languages, you may leave out the type, but it is good practice to enter it anyway, because the selected template could still make some use of it.

In the following pages, you can choose a license for you new class, set any custom options required by the selected template, and configure output locations for all the generated files. By clicking Finish, you complete the assistant and create the new class. The generated files will be opened in the editor, so you can start adding code right away.

After creating a new C++ class, you will be given an option of adding the class to a project target. Choose a target from the dialog page, or dismiss the page and add the files to a target manually.

If you chose the Qt Object template, checked some of the default methods, and added two member variables, the output should look like on the following picture.

You can see that data members are converted into Qt properties, with accessor functions and the Q_PROPERTY macros. Arguments to setter functions are even passed by const-reference, where appropriate. Additionally, a private class is declared, and a private pointer created with Q_DECLARE_PRIVATE. All this is done by the template, choosing a different template in the first step could completely change the output.

Creating a new unit test

Even though most testing frameworks require each test to also be a class, KDevelop includes a method to simplify the creation of unit tests. To create a new test, right click on a project folder and choose Create from Template. In the template selection page, choose Test as the category, then choose your programming language and template and click Next.

You will be prompted for the test name and a list of test cases. For the test cases, you only have to specify a list of names. Some unit testing frameworks, such as PyUnit and PHPUnit, require that test cases start with a special prefix. In KDevelop, the template is responsible for adding the prefix, so you do not have to prefix the test cases here. After clicking Next, specify the license and output locations for the generated files, and the test will be created.

Unit tests created this way will not be added to any target automatically. If you are using CTest or some other testing framework, make sure to add the new files to a target. KDevelop provides a Unit Tests toolview that integrates with CTest.

Other files

While classes and unit tests receive special attention when generating code from templates, the same method can be used for any kind of source code files. For example, one could use a template for a CMake Find module or a .desktop file. This can be done by choosing Create from Template, and selecting the wanted category and template. If the selected category is neither Class nor Test, you will only have the option of choosing the license, any custom options specified by the template, and the output file locations. As with classes and tests, finishing the assistant will generate the files and open them in the editor.

Managing templates

From the File -> New from Template assistant, you can also download additional file templates by clicking the Get more Templates... button. This opens a Get Hot New Stuff dialog, where you can install additional templates, as well as update or remove them. There is also a configuration module for template, which can be reached by clicking Settings -> Configure KDevelop -> Templates. From there, you can manage both file templates (explained above) and project templates (used for creating new projects).

Of course, if none of the available template suit your project, you can always create new ones. The easiest way is probably to copy and modify an existing template, while a short tutorial and a longer specification document are there to help you. To copy an installed template, open the template manager by clicking Settings -> Configure KDevelop... -> Templates, select the template you wish to copy, then click the Extract Template button. Select a destination folder, then click OK, and the contents of the template will be extracted into the selected folder. Now you can edit the template by opening the extracted files and modifying them. After you are done, you can import your new template into KDevelop by opening the template manager, activating the appropriate tab (either Project Templates or File Templates) and clicking Load Template. Open the template description file, which is the one with the suffix either .kdevtemplate or .desktop. KDevelop will compress the files into a template archive and import the template.

Note

When copying an existing template, make sure you rename it before importing it again. Otherwise, you will either overwrite the old template, or will end up with two templates with identical names. To rename a template, rename the description file to something unique (but keep the suffix), and change the Name entry in the description file.


If you want to write a template from scratch, you can start with a sample C++ class template by creating a new project and selecting the C++ Class Template project in category KDevelop.