← Back to branch summary

~ubuntu-branches/debian/sid/kdevelop/sid

« back to all changes in this revision

Viewing changes to doc/api/HowToAddApplicationTemplates.dox

  • Committer: Bazaar Package Importer
  • Author(s): Jeremy Lainé
  • Date: 2006-05-23 18:39:42 UTC
  • Revision ID: james.westby@ubuntu.com-20060523183942-hucifbvh68k2bwz7
Tags: upstream-3.3.2
Import upstream version 3.3.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/api/HowToAddApplicationTemplates.dox
 
1
/** \file HowToAddApplicationTemplates.dox
 
2
  * \brief How to add application templates to the application wizard part
 
3
  */
 
4
/** \page howToAddApplicationTemplates How to add application templates to the application wizard part
 
5
 
 
6
Project templates provide the developer with a basic application framework.
 
7
This is necessary for rapid application development (RAD) and makes it even possible
 
8
for an inexperienced 3rd party developer to create standard conforming
 
9
applications like kedit as well as plugins for example for kdevelop or noatun.\n\n
 
10
\ref templates_1\n
 
11
    - \ref templates_1_1
 
12
    - \ref templates_1_2
 
13
        - \ref templates_1_2a
 
14
        - \ref templates_1_2b
 
15
        - \ref templates_1_2c
 
16
        - \ref templates_1_2d
 
17
        - \ref templates_1_2e
 
18
        .
 
19
    .
 
20
\ref templates_2\n
 
21
\ref templates_3\n
 
22
\ref templates_4\n
 
23
<!-- @todo <b>Developer information:</b> The documentation for the related
 
24
<code>"Project"->"Import Existing Project..."</code> is available here: \ref appwizard_imports
 
25
-->
 
26
<hr>
 
27
 
 
28
\section templates_1 I. Example: How To Create a Simple KDE Application Template "KHello"
 
29
 
 
30
You can find this template in <code>$KDEDIR/share/apps/kdevappwizard/template-khello</code>.
 
31
 
 
32
\subsection templates_1_1 I.1. Step 1: Basic Skeleton
 
33
 
 
34
Create a directory <code>template-khello</code> with the files
 
35
<code><pre>
 
36
    - template-khello/app.cpp
 
37
    - template-khello/app.h
 
38
    - template-khello/app.desktop
 
39
    - template-khello/app.kdevelop
 
40
    - template-khello/appui.rc
 
41
    - template-khello/khello
 
42
    - template-khello/main.cpp
 
43
    - template-khello/preview.png
 
44
    - template-khello/script
 
45
    - template-khello/src-Makefile.am
 
46
    - template-khello/subdirs
 
47
    .
 
48
</pre></code>
 
49
\note The directory name must begin with <code>"template-"</code>.
 
50
 
 
51
\subsection templates_1_2 I.2. Step 2: The Files in Detail
 
52
 
 
53
Have a look into the files! There are some variables which the application
 
54
wizard will replace:
 
55
<code><pre>
 
56
    - \%{AUTHOR} ...... by the author
 
57
    - \%{EMAIL} ....... by the e-mail address 
 
58
    - \%{VERSION} ..... by the version
 
59
    - \%{APPNAME} ..... by the project name (KHello)
 
60
    - \%{APPNAMELC} ... by the project name in lowercase (khello)
 
61
    - \%{APPNAMEUC} ... by the project name in uppercase (KHELLO)
 
62
    - \%{LICENSE} ..... by the license (GPL, BSD, QPL, LGPL, ...)
 
63
    - \%{LICENSEFILE} . by the licensefile
 
64
    - \%{YEAR} ........ by the year
 
65
    .
 
66
</pre></code>
 
67
All this can be found in <code>$KDEDIR/share/apps/kdevappwizard/template-common/kdevelop.pm</code>.
 
68
\subsubsection templates_1_2a I.2.1. The Source Files
 
69
 
 
70
The files <code>template-khello/app.cpp, template-khello/app.h</code> and
 
71
<code>template-khello/main.cpp</code> contain the source code that should not
 
72
be too special so that the user can implement his own ideas.\n
 
73
(There may be variables included - see \ref templates_1_2 "Step 2: The Files in Detail").
 
74
 
 
75
\subsubsection templates_1_2b I.2.2. The File template-khello/khello
 
76
 
 
77
It may look like this:
 
78
\verbinclude khello/khello
 
79
 
 
80
The application wizard looks into this file to get
 
81
    - the information where to integrate the plugin into the the listview (<code>Category=</code>)
 
82
    - the name (<code>Name=</code>) and the comment (<code>Comment=</code>)
 
83
    - the preview image (<code>Icon=</code>)
 
84
    - and the file templates the project uses (<code>FileTemplates=</code>).
 
85
    .
 
86
Further information could be (not required):
 
87
    - <code>Comment=</code> a small comment for the template. Longer comments should go into a README.devel and shown on startup
 
88
    - <code>ShowFilesAfterGeneration=</code> a comma-separated list (without whitespaces) of files that should be opened immediately after the generation, for instance a README.devel or a source file the user has to modify, the path is relative to the project directory (example: <code>ShowFilesAfterGeneration=src/main.cpp,src/plugin.cpp</code>). And
 
89
        - <code>APPNAMEUC</code> will be replaced with the projectname in uppercase,
 
90
        - <code>APPNAMELC</code> will be replaced with the projectname in lowercase,
 
91
        - <code>APPNAME</code> will be replaced with the projectname.
 
92
        .
 
93
    - <code>DefaultDestinatonDir</code> changes the default destination dir for the project (~) to your value, whereas <code>HOMEDIR</code> is a keyword
 
94
    .
 
95
 
 
96
\attention The file <code>template-khello/khello</code> must have the same name as
 
97
the right half of the directory! If the directory is <code>template-foobar</code>
 
98
the file must be <code>template-foobar/foobar</code>.
 
99
 
 
100
\see AppWizardPart for more information.
 
101
 
 
102
\subsubsection templates_1_2c I.2.3. Some Additional Files
 
103
 
 
104
The file
 
105
    - <code>template-khello/appui.rc</code> contains information about the toolbar and the menu.
 
106
    - <code>template-khello/preview.png</code> will be shown in the aplication wizard.
 
107
    - <code>template-khello/app.desktop</code> describes the application.
 
108
    - <code>template-khello/subdirs</code> contains a list of the subdirectories (usually <code>doc, po, src</code>) and can be found in the project root directory. It is necessary for the autotools.
 
109
    .
 
110
 
 
111
\subsubsection templates_1_2d I.2.4. The File template-khello/src-Makefile.am
 
112
 
 
113
This file will be copied to the <code>$PROJECTDIR/src/</code>.
 
114
\verbinclude khello/src-Makefile.am
 
115
 
 
116
\subsubsection templates_1_2e I.2.5. The File template-khello/script
 
117
 
 
118
The following script is used to install the template and replaces all
 
119
variables by the corresponding value. The result is a hopefully working
 
120
kdevelop project!
 
121
\verbinclude khello/script
 
122
<br>
 
123
\note There are several application templates which use some identical
 
124
files - that's why some files are taken from the <code>"template-common"</code>-directory.
 
125
 
 
126
\section templates_2 II. Registration/Installation Of The Application Template
 
127
 
 
128
The easiest way to install your template is to provide an "install.sh" shell script.\n
 
129
Example:
 
130
\code
 
131
#!/bin/sh
 
132
 
 
133
kde_prefix=`kde-config --prefix`
 
134
if  [ `id -u` = 0 ]; then
 
135
  # we are root so install the template into the global kde directory
 
136
  kde_dir=`kde-config --prefix`
 
137
else
 
138
  # we are a user so install it into $HOME/.kde/share/apps/kdevappwizard directory
 
139
  kde_dir=`kde-config --localprefix`
 
140
  echo "Note: It would be better to install as root. Press CTRL+C to abort"
 
141
fi
 
142
 
 
143
# use usual path or another one?
 
144
echo "Install dir [${kde_dir}/share/apps/kdevappwizard]:"
 
145
read newdir
 
146
 
 
147
if [ "$newdir"a = a ]; then newdir="${kde_dir}/share/apps/kdevappwizard/"; fi
 
148
 
 
149
# make sure the directories exist
 
150
if [ ! -e "${newdir}/template-khello" ]; then mkdir -p "${newdir}/template-khello" ; fi;
 
151
if [ ! -e "${newdir}/templates" ]; then mkdir -p "${newdir}/templates" ; fi;
 
152
if [ ! -e "${newdir}" ]; then mkdir -p "$newdir" ; fi;
 
153
if [ ! -e "${newdir}/template-common" ]; then ln -s "${kde_prefix}/share/apps/kdevappwizard/template-common" "${newdir}/template-common" ; fi;
 
154
 
 
155
# install now
 
156
cp -R --target-directory "$newdir" template-khello
 
157
# the file template-khello/khello must go to the "templates" directory that
 
158
# kdevelop knows that it exists
 
159
mv "$newdir/template-khello/khello" "$newdir/templates/"
 
160
echo "done"
 
161
\endcode
 
162
\n
 
163
\attention Please test your template whether it installs and behaves correctly! Test, test and test again! ;)
 
164
 
 
165
\section templates_3 III. How To Add The Template To KDevelop CVS HEAD
 
166
 
 
167
This section is for kdevelop developers only. Most probably you don't have to read this!.\n
 
168
Move the directory <code>"template-khello"</code> to <code>kdevelop/languages/cpp/app_templates/</code>
 
169
and then add the following files in <code>kdevelop/languages/cpp/app_templates/template-khello/</code>
 
170
(in this example the language is c++ if you use other language replace cpp with the language name):
 
171
    - <code>".kdev_ignore"</code> is an empty file. It prevents KDevelop's
 
172
    C++-parser from parsing the C++ template files. This is necessary because the template files are just code templates and not real code (yet).
 
173
    - <code>".cvsignore"</code> looks like this:
 
174
\code
 
175
Makefile
 
176
Makefile.in
 
177
script.local
 
178
\endcode
 
179
    - <code>"Makefile.am"</code> looks like this:
 
180
    \verbinclude khello/Makefile.am
 
181
    .
 
182
Finally add <code>"template-khello"</code> to "SUBDIRS = " in <code>kdevelop/languages/cpp/app_templates/Makefile.am</code>.\n
 
183
\attention Please test your template whether it installs and behaves correctly!
 
184
Test, test and test again! It works? Well - now talk to the kdevelop guys so
 
185
that they know what's going on and probably you may commit. ;)
 
186
 
 
187
\section templates_4 IV. Changes to the template system (VERY IMPORTANT)
 
188
 
 
189
The entire app template system described above has been changed.
 
190
To port a template to the new system the
 
191
information from the script file will need to be moved into the ini file.
 
192
The example is as follows:
 
193
\code
 
194
install(
 
195
"${src}/template-chello/app.kdevelop","${dest}/${APPNAMELC}.kdevelop" );
 
196
\endcode
 
197
becomes
 
198
\code
 
199
[PROJECT]
 
200
Type=install
 
201
Source=%{src}/template-chello/app.kdevelop
 
202
Dest=%{dest}/%{APPNAMELC}.kdevelop
 
203
\endcode
 
204
 
 
205
Things like <code>installIncAdmin();</code> and <code>installGNU();</code> now involve unpacking
 
206
the tar archives.  This is done by creating a target in the ini file as
 
207
follows:
 
208
\code
 
209
[GNU]
 
210
Type=install archive
 
211
Source=%{src}/template-common/gnu.tar.gz
 
212
Dest=%{dest}
 
213
\endcode
 
214
 
 
215
The popular script functions convert as follows:
 
216
\code
 
217
installIncAdmin(); %{src}/template-common/incadmin.tar.gz
 
218
installGNU();  %{src}/template-common/gnu.tar.gz
 
219
installAdmin(); %{src}/template-common/admin.tar.gz
 
220
installGnome(); %{src}/template-common/gnome.tar.gz
 
221
installWX(); %{src}/template-common/wxwidgets.tar.gz
 
222
\endcode
 
223
 
 
224
 
 
225
To create directories is now:
 
226
\code
 
227
[SRC]
 
228
Type= mkdir
 
229
Dir=%{dest}/src
 
230
\endcode
 
231
 
 
232
New additions are as follows:
 
233
\code
 
234
[MGS]
 
235
Type=message
 
236
Comment=A simple C project was created in %{dest}.
 
237
\endcode
 
238
 
 
239
Will allow you to display a custom message when the template has
 
240
finished installing.  This is very handy for projects that require
 
241
custom variables to be set.
 
242
 
 
243
The concept of custom variables was also introduced.  To create a
 
244
variable that can be edited from the project wizard you need to add an
 
245
entry as follows:
 
246
\code
 
247
[LIBS]
 
248
Type = value
 
249
ValueType=<Qt Data type>
 
250
Value= <Value Name that will be substituted in the code>
 
251
Comment= <The label in the UI>
 
252
Default= <The default value>
 
253
\endcode
 
254
 
 
255
One special value can be used to turn targets on and off.  This is done
 
256
by adding a value as follows:
 
257
\code
 
258
[DOCSOPT]
 
259
Type = value
 
260
ValueType=bool
 
261
Value=INSTALL_DOCS
 
262
Comment= Install Docbook documentation templates.
 
263
Default=true
 
264
\endcode
 
265
 
 
266
Then in the targets you wish to make optional you add the Option
 
267
property with the value's name as the data. This will look as follows:
 
268
\code
 
269
[DOCSDIREN]
 
270
Type=mkdir
 
271
Dir=%{dest}/doc/en
 
272
Option=INSTALL_DOCS
 
273
\endcode
 
274
 
 
275
The Option target is available to the mkdir, install, and install
 
276
archive targets.
 
277
 
 
278
The last new addition is the optional post processing of the files as
 
279
they are copied.  For install and install archive you can add a
 
280
<code>Process=true</code> or <code>Process=false</code> to turn the processing on or off.
 
281
 
 
282
A note on the UI. its not final, it will get better.  Suggestions or
 
283
bugs should be noted asap.
 
284
 
 
285
*/