1
<chapter id="applicationwizard">
5
<author><firstname>Bernd</firstname><surname>Pol</surname></author>
6
<!-- ROLES_OF_TRANSLATORS -->
10
<title>Getting Started — the &appwizard;</title>
11
<!-- FIXME (bp, 2006-06-18) This is a misnomer. It should be something like -->
12
<!-- Working With Projects -->
13
<!-- featuring the application manager as part of the New Projects section. -->
15
<indexterm zone="applicationwizard">
16
<primary>&appwizard;</primary></indexterm>
19
In &kdevelop; software development work is organized in <emphasis>projects</emphasis>. Such a project keeps everything together which belongs to a complete programming task: source files, additional data files, any actually needed management facilities as the make system as well as access to all components and any additional tools needed to get the application up and running.
22
Organizing all development work in projects allows you to easily switch between the global tasks at hand. This is quite handy if you ⪚ work on several applications at the same time as is often the case. Tell &kdevelop; to open the project you want to work at and you may proceed in the environment just where you left.
25
<sect1 id="new-projects">
26
<title>New Projects</title>
28
<!-- TODO (bp, 2006-06-18) This whole section must be completely rewritten. -->
29
<!-- There is no need for a tutorial habit anymore. -->
31
<indexterm zone="new-projects">
32
<primary>project</primary>
33
<secondary>new</secondary></indexterm>
36
Whenever you want to initiate a new programming project quite a lot of formal setup procedures need to be done. An initial directory structure has to be set up, initial header and source files must be provided, the make system has to be initialized, &etc;
39
&kdevelop; provides an easy way to initiate a new programming project—the <emphasis>&appwizard;</emphasis>. You will find the &appwizard; at menu entry <menuchoice><guimenu>Project</guimenu> <guimenuitem>New Project</guimenuitem></menuchoice>.
42
Only a short series of steps is necessary to start a new programming project, using the &appwizard;:
46
<link linkend="new-projects-start-type">Select the programming language</link> you want to use and the type of the application you want to build from a set of predefined templates.
49
<link linkend="new-projects-start-general">Supply some general information</link> as application name, directory where the application shall be built, &etc;
52
Decide whether you want to use a <link linkend="new-projects-start-cvs">version control system</link>, like ⪚ CVS, and supply the necessary data if needed.
55
Set up some templates for <link linkend="new-projects-start-templates">initial header and source files</link> (if applicable).
58
Finally tell &appwizard; to <link linkend="new-projects-start-build">set up all initial stuff</link>, directory structure, starting header/source file templates, and management tools, like ⪚ an initial make skeleton, &etc;
62
Voilà—that's all. &appwizard; will have provided you with a primary functional set of programming files, where you can readily start working.
65
Let's look at all this in more detail now ...
68
<sect2 id="new-projects-start">
69
<title>Initial Steps</title>
71
<indexterm zone="new-projects-start">
72
<primary>dialog</primary>
73
<secondary>create new project</secondary></indexterm>
74
<indexterm zone="new-projects-start">
75
<primary>project</primary>
76
<secondary>create new project</secondary>
77
<tertiary>dialog</tertiary></indexterm>
78
<indexterm zone="new-projects-start">
79
<primary>project</primary>
80
<secondary>templates</secondary></indexterm>
81
<indexterm zone="new-projects-start">
82
<primary>templates</primary>
83
<secondary>project</secondary></indexterm>
86
To create a new project in &kdevelop;, select <guimenuitem>New Project</guimenuitem> from the <guimenu>Project</guimenu> menu. The <guilabel>Create New Project</guilabel> dialog will pop up showing an initial <guilabel>General</guilabel> page:
89
<screenshot id="screenshot-newprojectwizard">
92
<imagedata fileref="create-new-project.png" format="PNG"/>
95
Initial dialog to set up a new project
101
As you see, this dialog is divided into an upper and a lower part. In the upper part you can decide on the programming language and application type, the lower part holds some general information.
104
<sect3 id="new-projects-start-type">
105
<title>Select Programming Language and Application Type</title>
107
<indexterm zone="new-projects-start-type">
108
<primary>project</primary>
109
<secondary>application type</secondary></indexterm>
110
<indexterm zone="new-projects-start-type">
111
<primary>project</primary>
112
<secondary>programming language</secondary></indexterm>
113
<indexterm zone="new-projects-start-type">
114
<primary>project</primary>
115
<secondary>language</secondary></indexterm>
116
<indexterm zone="new-projects-start-type">
117
<primary>language</primary></indexterm>
118
<indexterm zone="new-projects-start-type">
119
<primary>programming language</primary></indexterm>
120
<indexterm zone="new-projects-start-type">
121
<primary>application</primary>
122
<secondary>type</secondary></indexterm>
125
The left hand side of the upper part in this dialog is where you do the selection work. When it shows up, you'll find there a list of folders each labeled with a programming language, as there are:
132
<primary>Ada</primary>
133
<secondary>new project</secondary></indexterm>
139
<secondary>new project</secondary></indexterm>
144
<primary>C++</primary>
145
<secondary>new project</secondary></indexterm>
148
Database (SQL Projects)
150
<primary>SQL</primary>
151
<secondary>new project</secondary></indexterm>
153
<primary>Database</primary>
154
<secondary>new project</secondary></indexterm>
159
<primary>Fortran</primary>
160
<secondary>new project</secondary></indexterm>
165
<primary>Haskell</primary>
166
<secondary>new project</secondary></indexterm>
171
<primary>Java</primary>
172
<secondary>new project</secondary></indexterm>
177
<primary>PHP</primary>
178
<secondary>new project</secondary></indexterm>
183
<primary>Pascal</primary>
184
<secondary>new project</secondary></indexterm>
189
<primary>Perl</primary>
190
<secondary>new project</secondary></indexterm>
195
<primary>Python</primary>
196
<secondary>new project</secondary></indexterm>
201
<primary>Ruby</primary>
202
<secondary>new project</secondary></indexterm>
205
Shell (Scripts for the Bash Shell)
207
<primary>Bash</primary>
208
<secondary>new project</secondary></indexterm>
210
<primary>shell</primary>
211
<secondary>new project</secondary></indexterm>
216
To be precise, these folders do not contain real programming tools actually. They do lead to pre-defined <emphasis>templates</emphasis> you can use as a starting point for development in that language. To get an idea of what is provided, just open the folders one after the other. There will be a series of subfolders on some, one or more simple entries only on others. The subfolders you see organize the available templates according to some tasks, the simple entries name the templates you may select.
219
We cannot go into detail here on which tasks each template provides, but it's easy to find out. Whenever you select a template entry some information is displayed in the fields to the right. In the lower field you will find a <emphasis>short description</emphasis> on what the template is supposed to do. In the field above that a picture will be shown, if available, about the outcome of the application this template produces if you compile and run it unmodified. Usually this is a <emphasis>screenshot</emphasis> of the main window the application will display.
222
Select the template which best fits your application's goals as a starting point. Then enter the general properties information in the lower field as shown in the next chapter.
226
<title>Selecting a Project Management System</title>
228
Each template is bound to a specific <link linkend="makesystems">Project Management System</link>. Currently there is no direct means to freely select such a Project Management System. You have to find a template which suits your needs or alter your project accordingly after creation.
232
</sect3> <!-- new-projects-start-type -->
234
<sect3 id="new-projects-start-general">
235
<title>Provide General Information</title>
237
<indexterm zone="new-projects-start-general">
238
<primary>project</primary>
239
<secondary>properties</secondary></indexterm>
240
<indexterm zone="new-projects-start-general">
241
<primary>properties</primary></indexterm>
242
<indexterm zone="new-projects-start-general">
243
<primary>application</primary>
244
<secondary>name</secondary></indexterm>
245
<indexterm zone="new-projects-start-general">
246
<primary>name</primary>
247
<secondary>application</secondary></indexterm>
248
<indexterm zone="new-projects-start-general">
249
<primary>project</primary>
250
<secondary>directory</secondary></indexterm>
251
<indexterm zone="new-projects-start-general">
252
<primary>directory</primary>
253
<secondary>project</secondary></indexterm>
254
<indexterm zone="new-projects-start-general">
255
<primary>path</primary>
256
<secondary>new project</secondary></indexterm>
257
<indexterm zone="new-projects-start-general">
258
<primary>project</primary>
259
<secondary>author</secondary></indexterm>
260
<indexterm zone="new-projects-start-general">
261
<primary>project</primary>
262
<secondary>email</secondary></indexterm>
263
<indexterm zone="new-projects-start-general">
264
<primary>author</primary></indexterm>
265
<indexterm zone="new-projects-start-general">
266
<primary>email</primary></indexterm>
267
<indexterm zone="new-projects-start-general">
268
<primary>project</primary>
269
<secondary>main.cpp</secondary></indexterm>
270
<indexterm zone="new-projects-start-general">
271
<primary>main.cpp</primary></indexterm>
272
<indexterm zone="new-projects-start-general">
273
<primary>project</primary>
274
<secondary>license</secondary></indexterm>
275
<indexterm zone="new-projects-start-general">
276
<primary>license</primary></indexterm>
279
The lower part of the <guilabel>Create New Project</guilabel> dialog <guilabel>General</guilabel> page is a framed field labeled <guilabel>Properties</guilabel>. You must provide some general information about your project here so that the &appwizard; knows how to build the initial structure.
282
<title>Application Name</title>
284
Your application needs a name of course. Enter this in the uppermost <guilabel>Properties</guilabel> field, called <guilabel>Application Name</guilabel>. We use <quote>MyApp</quote> as an example.
288
When you do so, you will notice that the &appwizard; refuses to accept special characters of any kind. The only characters accepted are:
290
<listitem><para>upper and lower case characters</para></listitem>
291
<listitem><para>numbers</para></listitem>
292
<listitem><para>the underline character</para></listitem>
296
One prominent cause of this restriction is that the &appwizard; will use this application name as the <emphasis>basis of some class names</emphasis> it will construct when it sets up an initial project. Thus the name of the application must stick to the rules of the programming language you use.
299
<title>The Project Directory</title>
301
The other prominent cause of this restriction you can see at the bottom line of the <guilabel>Properties</guilabel> area. It is labeled <guilabel>Final location</guilabel> and shows the directory where the &appwizard; will create the application.
305
As you type the application name you will notice that the &appwizard; repeats your input at the end of the <guilabel>Final location</guilabel> line, using lower case only characters.
308
Thus you must select the name of your new application with care. If you end up with an already used directory the &appwizard; will not allow you to continue to the next step, keeping the <guibutton>Next ></guibutton> button deactivated (grayed). Yet, it will <emphasis>warn</emphasis> you in this case by appending <quote>(dir/file already exist)</quote> to the <guilabel>Final location</guilabel> line.
312
<title>The Starting Path</title>
314
There are two ways to select another path for your new application. One is to select another name. Yet, this is not always feasible (you might ⪚ set up for another version of an already existing application). As an alternative you may select another path to the application directory.
318
This is done in the second row input field of the <guilabel>Properties</guilabel>, named <guilabel>Location</guilabel>. What you enter here is the <emphasis>starting path</emphasis> of the new application development directory. The &appwizard; appends the application name to this path when it initializes the new project. The result is shown in the <guilabel>Final location</guilabel> line to give you better control on what is going on.
321
&appwizard; will copy an <emphasis>initial value</emphasis> to the <guilabel>Location</guilabel> field on start-up. This is taken from what you have chosen in the <guilabel>Default projects directory</guilabel> field during the <link linkend="setup-general">general configuration steps</link>. In our case we have &kdevelop; set up to use <filename class="directory">/home/devel/projects/</filename> as initial path for new projects.
324
Alter the <guilabel>Location</guilabel> field contents so that the application development directory shown in the <guilabel>Final location</guilabel> line will be unique.
326
<!--TODO add tab description Project Options -->
328
Take care that the path you enter in the <guilabel>Location</guilabel> field already exists. Otherwise you will not be able to continue to the next step. The &appwizard; will <emphasis>warn</emphasis> you about non-existing paths by appending <quote>(invalid)</quote> to the <guilabel>Final location</guilabel> line.
331
<screenshot id="screenshot-createnewprojectoptions">
334
<imagedata fileref="createnewprojectoptions.png" format="PNG"/>
337
Set new project up for CVS
343
<title>Personal Information</title>
345
The fields following this are not so critical. Just supply your name (&ie; the name of the person who is responsible for the application) in the <guilabel>Author</guilabel> field, and a valid e-mail address in the <guilabel>Email</guilabel> field, so that users can give you feedback on the application.
352
The &appwizard; fills these fields with some default values, taken from
353
the Email presets in the &kcontrolcenter;. If these defaults in the <guilabel>Create New Project</guilabel> <guilabel>Author</guilabel> and <guilabel>Email</guilabel> fields do not suit, you may want to have a look at your mail configuration in the &kcontrolcenter;.
356
The &appwizard; will integrate this information into the starting program templates if applicable. In &kde; C++ programs for instance you will find it near the beginning of the <filename>main.cpp</filename> source file.
359
Of all fields, the <guilabel>Email</guilabel> is <emphasis>optional</emphasis>, reflecting the fact that not every developer may have access to the internet. You may keep this field empty if you wish and proceed nevertheless.
365
<title>Version and License Info</title>
367
Finally enter a starting version number for your new application in the <guilabel>Version</guilabel> field, and select the license under which you want your application be put from the <guilabel>License</guilabel> tab.
372
If you select an application type for which the &appwizard; provides common source template texts (⪚ C/C++), you may view the license notification text on the third page of this <guilabel>Create New Project</guilabel> dialog (see the <link linkend="new-projects-start-templates">Supply header/source templates</link> chapter below).
375
If you selected <quote>Custom</quote> from the <guilabel>License</guilabel> tab you must provide a license text on your own.
379
Both version and license information will as well be integrated into the starting templates in a suiting format the application type you selected does provide.
383
Once you have correctly entered all this information stuff, press the <guibutton>Next ></guibutton> button to proceed as shown in the following chapters.
385
</sect3> <!-- new-projects-start-general -->
387
</sect2> <!-- new-projects-start -->
389
<sect2 id="new-projects-start-cvs">
390
<title>Supply Version System Information</title>
392
<indexterm zone="new-projects-start-cvs">
393
<primary>CVS</primary>
394
<secondary>new project</secondary></indexterm>
395
<indexterm zone="new-projects-start-cvs">
396
<primary>project</primary>
397
<secondary>CVS</secondary></indexterm>
398
<indexterm zone="new-projects-start-cvs">
399
<primary>database</primary>
400
<secondary>CVS</secondary></indexterm>
401
<indexterm zone="new-projects-start-cvs">
402
<primary>version</primary>
403
<secondary>database</secondary></indexterm>
404
<indexterm zone="new-projects-start-cvs">
405
<primary>version</primary>
406
<secondary>CVS</secondary></indexterm>
409
In a second step the &appwizard; will lead you to the <guilabel>Version Control System</guilabel> page where you can decide which version control system you want to use.
413
This discussion concentrates on the needs for project creation only. For more information on &CVS; see the <link linkend="cvs">Using &CVS;</link> chapter below.
417
<title>No Version Control System Wanted</title>
419
Initially there is <quote>None</quote> selected in the <guilabel>Version control system</guilabel> tab, and the page will be empty otherwise. If you don't want to use a version control system, just click the <guibutton>Next ></guibutton> button and go on.
424
<title>Using &CVS;</title>
426
Otherwise you must reselect the version control system you want to use from the <guilabel>Version control system</guilabel> tab. We use <quote>&cvs;</quote> for our example. If you select this, the &appwizard; will redisplay the page, now showing a series of fields you must fill in.
430
<screenshot id="screenshot-newproject-cvs">
433
<imagedata fileref="create-new-project-cvs.png" format="PNG"/>
436
Set new project up for CVS
442
A version control system such as &CVS; (which means <quote>Concurrent Versions System</quote>) stores copies of selected project files in some sort of a database. If you use &CVS; you can amongst others upload (<quote>commit</quote>) those files or load them back into your project directory (<quote>checkout</quote>, or <quote>update</quote>). The special thing about this is that the files in the versioning database are stored in a structured way which allows you to always revert to an earlier development state if you need so. And &CVS; allows multiple designers to fairly easily collaborate on a big project (such as &kdevelop;) without disturbing each others work.
445
<indexterm zone="new-projects-start-cvs-root">
446
<primary>CVS</primary>
447
<secondary>root</secondary></indexterm>
448
<indexterm zone="new-projects-start-cvs-root">
449
<primary>root</primary>
450
<secondary>CVS</secondary></indexterm>
451
<indexterm zone="new-projects-start-cvs-root">
452
<primary>CVS</primary>
453
<secondary>local</secondary></indexterm>
454
<indexterm zone="new-projects-start-cvs-root">
455
<primary>CVS</primary>
456
<secondary>remote</secondary></indexterm>
457
<indexterm zone="new-projects-start-cvs-root">
458
<primary>local CVS</primary></indexterm>
459
<indexterm zone="new-projects-start-cvs-root">
460
<primary>:local:</primary></indexterm>
461
<indexterm zone="new-projects-start-cvs-root">
462
<primary>CVS</primary>
463
<secondary>:local:</secondary></indexterm>
465
<formalpara id="new-projects-start-cvs-root">
466
<title>&CVS; Root</title>
468
&CVS; needs to <emphasis>manage</emphasis> the versioning database it keeps from your project files. To accomplish this it keeps some special database information in an own directory, called the <emphasis>&CVS; root</emphasis>. The first step on setting up &CVS; for your new project thus is to tell &kdevelop; where this root is located.
473
<emphasis>Local &CVS; root.</emphasis> There are two basic possibilities. Either you want to use a <emphasis>local</emphasis> &CVS; database or you use a database which is held on a <emphasis>remote server</emphasis>. If you develop for your own, you may want use the &CVS; database as some sort of a backup system on your own computer. Usually this is set up in your home directory root and given the name <filename>cvsroot</filename>. This may look as follows:
475
<para><userinput><filename class="directory">/home/devel/cvsroot</filename></userinput> (where <filename>devel</filename> simply denotes the <quote>developing</quote> user, just for example)
479
In fact, this is a short form. Exactly, the local &CVS; root should be addressed using the <computeroutput>:local:</computeroutput> prefix. The short form is only allowed in cases where the filename starts with a slash (<computeroutput>/</computeroutput>). The full name for our example local &CVS; root would exactly look like: <filename class="directory">:local:/home/devel/cvsroot</filename>
483
Enter the name of the &CVS; root directory your system has been set up for in the <guilabel>CVS root</guilabel> field. In principle you can select any name, even use multiple &CVS; databases, but it is advisable that you stick to the &CVS; root once set up.
486
<emphasis>Initialize a new &CVS; root.</emphasis> If there does not exist a &CVS; root yet, &kdevelop; can command the &CVS; system to create one for you in the given directory. Just check the <guilabel>Init root</guilabel> checkbox below the <guilabel>CVS root</guilabel> field.
489
As said, &kdevelop; only <emphasis>commands</emphasis> the &CVS; system to initialize a new &CVS; root. It does nothing by itself to this directory. Fortunately &CVS; is clever enough to check whether the &CVS; root directory already exists. Hence it does no harm if you should have inadvertently checked <guilabel>Init root</guilabel> on an already existing &CVS; root directory.
493
<emphasis>Remote &CVS; root.</emphasis> There are occasions where the &CVS; database is to be kept on a remote server, especially when several developers work at the same project. Then you must enter the &CVS; root &URL; of this server in the <guilabel>CVS root</guilabel> field. For example, if you want access to the &kde; &CVS; server:
496
<userinput><filename class="directory">:pserver:<replaceable>mylogin</replaceable>@cvs.kde.org:/home/kde</filename></userinput> (where <replaceable>mylogin</replaceable> denotes the login name set up in your &kde; &CVS; account)
499
<indexterm zone="new-projects-start-cvs-remote">
500
<primary>remote CVS</primary></indexterm>
501
<indexterm zone="new-projects-start-cvs-remote">
502
<primary>:pserver:</primary></indexterm>
503
<indexterm zone="new-projects-start-cvs-remote">
504
<primary>:ext:</primary></indexterm>
505
<indexterm zone="new-projects-start-cvs-remote">
506
<primary>CVS</primary>
507
<secondary>:local:</secondary></indexterm>
508
<indexterm zone="new-projects-start-cvs-remote">
509
<primary>CVS</primary>
510
<secondary>:pserver:</secondary></indexterm>
511
<indexterm zone="new-projects-start-cvs-remote">
512
<primary>CVS</primary>
513
<secondary>:ext:</secondary></indexterm>
515
<formalpara id="new-projects-start-cvs-remote">
516
<title>Remote &CVS; Server Types</title>
518
Basically there are two widely used remote &CVS; server types, the
519
<emphasis>pserver</emphasis> which uses a password-secured non-encrypted
520
protocol, and the <emphasis>ext</emphasis> server which uses an rsh or ssh
521
encrypted data transfer. They are distinguished by the &URL; prefix they use:
525
<filename>:pserver:</filename>
528
for the <quote>password protected server</quote> non-encrypted type, and
531
<filename>:ext:</filename>
534
for an rsh or ssh encrypted server type. For example
537
<userinput><filename class="directory">:ext:<replaceable>mylogin</replaceable>@cvs.cervisia.sourceforge.net:/cvsroot/cervisia</filename></userinput>
540
accesses the &CVS; root of the widely used <application>Cervisia</application> &CVS; management tool on the SourceForge server.
543
If you want to use an rsh or ssh encrypted server for &CVS; access you must tell &kdevelop; the encryption protocol to be used. Just enter <userinput>rsh</userinput> or <userinput>ssh</userinput> in the <guilabel>CVS_RSH</guilabel> field of the <guilabel>Create New Project</guilabel> <guilabel>Version Control System</guilabel> page.
547
There is a caveat if you use an encrypted server for &CVS; from within &kdevelop;. See the <link linkend="cvs">Using &CVS;</link> chapter for details.
550
<indexterm zone="new-projects-start-cvs-repository">
551
<primary>CVS</primary>
552
<secondary>repository</secondary></indexterm>
553
<indexterm zone="new-projects-start-cvs-repository">
554
<primary>repository</primary>
555
<secondary>CVS</secondary></indexterm>
557
<formalpara id="new-projects-start-cvs-repository">
558
<title>The &CVS; Repository</title>
560
So far you have told &kdevelop; where the &CVS; root resides which manages the versioning database and how to access it. Now you need to tell &kdevelop; under which name you want &CVS; save your project files in that database. Such a place your project files will be held in &CVS; is called a <emphasis>repository</emphasis>.
564
In principle you can use any name for the &CVS; repository of your project files as long as it adheres to the specifications of naming a file. Yet, most developers simply use the name of the application itself. &CVS; will build a directory with this name in the &CVS; root, hence it is more easily found if you keep the application name for it.
567
Just enter the repository name you want to use in the <guilabel>CVS repository</guilabel> field of the <guilabel>Create New Project</guilabel> <guilabel>Version Control System</guilabel> page. In our example this is: <userinput>MyApp</userinput>
571
<emphasis>Take care not to use a repository which already exists!</emphasis> The &CVS; system does not warn about duplicate files but will shovel everything in which does not produce a formal conflict. You will mess up everything!
575
<title>The Remaining Fields</title>
577
There is not much work left to do. &appwizard; has already set up the remaining fields for you. In detail:
581
The <guilabel>Vendor</guilabel> field is used for compatibility reasons only. You can stick to the <quote>vendor</quote> default the &appwizard; puts in here.
584
The <guilabel>Message</guilabel> field allows you to comment the initial &CVS; contents. Use any text you like or just stick to the <quote>new project</quote> default the &appwizard; did put in.
587
The <guilabel>Release tag</guilabel> holds the name which tags the initial state of your project. Such a <emphasis>tag</emphasis> names a certain point within the &CVS; repository by which you can later access this state of your development. (See more in the <link linkend="cvs">Using &CVS;</link> chapter.)
590
The &appwizard; has put a default <quote>start</quote> tag in here which is a worthy proposal. Just stick to it.
595
When any information of all these is wrong &kdevelop; usually will not know about until project construction time. It is the &CVS; system which will figure out those errors when it tries to build the repository. Hence you must keep an eye to the <guilabel>Messages</guilabel> window of &kdevelop; when the project is created in the final setup step. If anything was in error with &CVS; you will in most cases see an error message like this:
598
<screen><computeroutput>
599
* cd '/home/devel/test' && cvs -d '/home/devel/mycvsroot' \
600
import -m 'new project' '' 'vendor' 'start' &&\
601
sh /opt/kde3/share/apps/kdevcvs/buildcvs.sh . '' \
602
'/home/devel/mycvsroot'
603
* cvs [import aborted]: /home/devel/mycvsroot/CVSROOT: No such file or
605
* *** Exited with status: 1 ***
606
</computeroutput></screen>
609
If this happens you will have to either manually set up &CVS; (&kdevelop; should have successfully initialized your project files at this time) or delete the project directory and start over again with <guimenuitem>New Project</guimenuitem> from the <guimenu>Project</guimenu> menu.
614
After you have entered all &CVS; related information, click the <guibutton>Next ></guibutton> to go on.
618
If you want to correct an error on the previous <guilabel>Create New Project</guilabel> page, just press the <guibutton>< Back</guibutton> button. The &appwizard; will remember your settings on the current page, so you can easily proceed when you come back.
621
</sect2> <!-- new-projects-start-cvs -->
623
<sect2 id="new-projects-start-templates">
624
<title>Supply Header/Source Templates</title>
627
The next step brings you to a series of pages where you can set up common information you want to include in your source and header files, if the task at hand allows.
630
Both header and source templates are provided for C and C++ applications, each on its own page. For other languages there may be source templates only. And in some cases you will even find this template page empty.
633
If the page is used, &appwizard; will fill in some common header comment which for a C++ based application might look like:
636
<screen><computeroutput><literal>
637
/***************************************************************************
638
* Copyright (C) 2003 by Your Name *
641
* This program is free software; you can redistribute it and/or modify *
642
* it under the terms of the GNU General Public License as published by *
643
* the Free Software Foundation; either version 2 of the License, or *
644
* (at your option) any later version. *
646
* This program is distributed in the hope that it will be useful, *
647
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
648
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
649
* GNU General Public License for more details. *
651
* You should have received a copy of the GNU General Public License *
652
* along with this program; if not, write to the *
653
* Free Software Foundation, Inc., *
654
* 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
655
***************************************************************************/
656
</literal></computeroutput></screen>
659
Other templates will provide similar information in a format according to the definitions of the programming language you want to use.
662
As you might have noticed, the applications manager did readily fill in some information you provided on the first <guilabel>General</guilabel> page of the <guilabel>Create New Project</guilabel> dialog, namely the contents of the <guilabel>Author</guilabel> and <guilabel>Email</guilabel> fields. Also proper license information will have been inserted according to your selection in the <guilabel>License</guilabel> tab.
665
<sect3 id="new-projects-start-templates-edit">
666
<title>How to Edit the Templates</title>
668
<indexterm zone="new-projects-start-templates-edit">
669
<primary>templates</primary>
670
<secondary>project</secondary>
671
<tertiary>edit</tertiary></indexterm>
672
<indexterm zone="new-projects-start-templates-edit">
673
<primary>project</primary>
674
<secondary>templates</secondary>
675
<tertiary>edit</tertiary></indexterm>
678
The templates you set up in the <guilabel>Create New Project</guilabel> dialog will later be processed whenever you command &kdevelop; to set up a new source and/or header file. The information you provided here will be included at top as a documentation header, before the code parts begin.
681
You are not restricted to plain text however. &kdevelop; knows of several variables which allow you to include actual information in the file. The &appwizard; did in fact use some such variables to insert the <guilabel>Author</guilabel>, <guilabel>Email</guilabel>, and <guilabel>License</guilabel> informations into the initial template text.
686
<term>Include &doxygen; File Information</term>
689
If, for example, you want the &doxygen;-built &API; documentation to display some further information about the file's contents in its filenames list, you may include the following lines in the source file template:
691
<screen><computeroutput>
694
* \brief (put some short descripion here).
696
</computeroutput></screen>
698
Whenever you create a new source file, &kdevelop; will replace the <varname>$MODULE$</varname> variable by the name body of the newly created file. For example, if you created a new C++ class named <classname>ASimpleTest</classname> you will see the following lines in the <filename>asimpletest.cpp</filename> file:
700
<screen><computeroutput>
702
* \file asimpletest.cpp
703
* \brief (put some short descripion here).
705
</computeroutput></screen>
707
You will still have to provide the short description after the <quote>\brief</quote> keyword, but part of the job is automatically done for you.
713
<term>The License Text File</term>
716
As another example you could include an explicit hint to the license text you want to use into the template. Use the <varname>$LICENSEFILE$</varname> variable for this and add for example this line:
719
<screen><computeroutput>
720
// See $LICENSEFILE$ for the full license text.
721
</computeroutput></screen>
723
The &appwizard; will replace the <varname>$LICENSEFILE$</varname> with the name of the file where the full license text is to be found, namely:
725
<screen><computeroutput>
726
// See COPYING for the full license text.
727
</computeroutput></screen>
729
for the <acronym>GPL</acronym> license, or
731
<screen><computeroutput>
732
// See LICENSE.BSD for the full license text.
733
</computeroutput></screen>
735
if you decided to put your application under the <acronym>BSD</acronym> license.
738
Thee are of course more variables &kdevelop; knows of. See the <link linkend="newfiles-edittemplates">Editing the templates</link> section in the <link linkend="editing">Editing tools</link> chapter for what is possible.
745
The templates you define here will come in effect only after the &appwizard; has created the new project. You will find this information on top of the files you created yourself in the development process. When creating the initial files the &appwizard; will use some predefined standard templates. You will have to manually adapt those initial files to your needs.
748
</sect3> <!-- new-projects-start-templates-edit -->
749
</sect2> <!-- new-projects-start-templates -->
751
<sect2 id="new-projects-start-build">
752
<title>Build the Initial Project Files</title>
754
<indexterm zone="new-projects-start-build">
755
<primary>project</primary>
756
<secondary>new</secondary>
757
<tertiary>build</tertiary></indexterm>
758
<indexterm zone="new-projects-start-build">
759
<primary>project</primary>
760
<secondary>initial build</secondary></indexterm>
763
Almost everything is done now. On the last templates page the <guibutton>Next ></guibutton> button will have changed to read <guibutton>Finish</guibutton> now.
766
<emphasis>Think twice before you click on it!</emphasis> You still have the option to revise everything by repeatedly using the <guibutton>< Back</guibutton> button. As the &appwizard; remembers all information you did input so far, it may be advisable for you to take the time and look back once again. In case you use local &CVS;, do not forget to double-check the <emphasis>&CVS; repository</emphasis> name (there should be no subdirectory with that name in the &CVS; root directory already—if it does, try another repository name).
769
If ever you don't want the new project be built, abort the <guilabel>Create New Project</guilabel> dialog by the <guibutton>Cancel</guibutton> button. Otherwise click <guibutton>Finish</guibutton> and watch in the <guilabel>Messages</guilabel> window how the &appwizard; initiates the project.
772
If you want to use a versioning system (&CVS;) there will be two runs actually. &appwizard; will first build the project directories and files and then call up the &CVS; program which restarts the <guilabel>Messages</guilabel> window with its own contents. If any error occurs in either of these runs, the process will stop showing you an according error message in the window.
776
In many cases when your new project has been set up this way, &kdevelop; will automatically load the source file(s) of one or more basically important modules so you can readily start work. (Which source modules will be displayed—if any at all—however depends on the template initially selected in the &appwizard;.)
780
Do not forget to initially check what the &appwizard; has provided. For example you may want to change the initial heading informations according to your own templates. Usually you will find these in a <filename class="directory">templates</filename> subdirectory in your project directory. Some simple copy operations will mostly suffice.
783
Then it is advisable that you <emphasis>compile the initial project</emphasis> before you attempt to change any code. In most cases this initial compilation should be possible. Thus you can make up whether the project really was set up according to your needs. If it was not, simply remove the project directory (in your local &CVS; root as well if you use one) and start over again.
786
<warning id="defaultbuild-warning"> <!-- ### remove this when "default" works again -->
788
<indexterm zone="defaultbuild-warning">
789
<primary>default build configuration</primary>
790
<secondary>warning</secondary></indexterm>
791
<indexterm zone="defaultbuild-warning">
792
<primary>build configurations</primary>
793
<secondary>default build warning</secondary></indexterm>
794
<indexterm zone="defaultbuild-warning">
795
<primary>warning</primary>
796
<secondary>default build configuration</secondary></indexterm>
799
Before you compile your new project the first time, have a look at <menuchoice><guimenu>Project</guimenu> <guimenuitem>Build Configuration</guimenuitem></menuchoice>. If there are three selections displayed: <guimenuitem>default</guimenuitem>, <guimenuitem>optimized</guimenuitem>, and <guimenuitem>debug</guimenuitem>, with <guimenuitem>debug</guimenuitem> selected, by all means stick to this, or use <guimenuitem>optimized</guimenuitem> instead.
802
Due to some limitations in the current autoconf/automake setup you should <emphasis>by no means</emphasis> build in the <guimenuitem>default</guimenuitem> configuration. This will corrupt some internal directory settings, thus making <command>configure</command> complain when you try to use it in the <guimenuitem>optimized</guimenuitem>, or <guimenuitem>debug</guimenuitem> build configuration afterwards.
805
(This applies to these multiselection capabilities only. If the application type you selected provides a <guimenuitem>default</guimenuitem> build configuration only, you should of course use this one.)
809
</sect2> <!-- new-projects-start-build -->
811
</sect1> <!-- new-projects -->
813
<sect1 id="projects-configure">
814
<title>Configuring Projects</title>
816
<para>(... to be written ...)</para>
820
</chapter> <!-- applicationwizard -->
added
removed
doc/kdevelop/applicationwizard.docbook
