path: root/doc/kdevelop/applicationwizard.docbook

<chapter id="applicationwizard">

<chapterinfo>
  <authorgroup>
    <author><firstname>Bernd</firstname><surname>Pol</surname></author>
    <!-- ROLES_OF_TRANSLATORS -->
  </authorgroup>
</chapterinfo>

<title>Getting Started &mdash; the &appwizard;</title>
<!-- FIXME (bp, 2006-06-18) This is a misnomer. It should be something like -->
<!-- Working With Projects -->
<!-- featuring the application manager as part of the New Projects section. -->

<indexterm zone="applicationwizard">
  <primary>&appwizard;</primary></indexterm>

<para>
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.
</para>
<para>
Organizing all development work in projects allows you to easily switch between the global tasks at hand. This is quite handy if you &eg; 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.
</para>

<sect1 id="new-projects">
<title>New Projects</title>

<!-- TODO (bp, 2006-06-18) This whole section must be completely rewritten. -->
<!-- There is no need for a tutorial habit anymore. -->

<indexterm zone="new-projects">
  <primary>project</primary>
  <secondary>new</secondary></indexterm>

<para>
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;
</para>
<para>
&kdevelop; provides an easy way to initiate a new programming project&mdash;the <emphasis>&appwizard;</emphasis>. You will find the &appwizard; at menu entry <menuchoice><guimenu>Project</guimenu> <guimenuitem>New Project</guimenuitem></menuchoice>.
</para>
<para>
Only a short series of steps is necessary to start a new programming project, using the &appwizard;:
</para>
<orderedlist>
  <listitem><para>
  <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.
  </para></listitem>
  <listitem><para>
  <link linkend="new-projects-start-general">Supply some general information</link> as application name, directory where the application shall be built, &etc;
  </para></listitem>
  <listitem><para>
  Decide whether you want to use a <link linkend="new-projects-start-cvs">version control system</link>, like &eg; CVS, and supply the necessary data if needed.
  </para></listitem>
  <listitem><para>
  Set up some templates for <link linkend="new-projects-start-templates">initial header and source files</link> (if applicable).
  </para></listitem>
  <listitem><para>
  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 &eg; an initial make skeleton, &etc;
  </para></listitem>
</orderedlist>
<para>
Voil&agrave;&mdash;that's all. &appwizard; will have provided you with a primary functional set of programming files, where you can readily start working.
</para>
<para>
Let's look at all this in more detail now ...
</para>

<sect2 id="new-projects-start">
<title>Initial Steps</title>

<indexterm zone="new-projects-start">
  <primary>dialog</primary>
  <secondary>create new project</secondary></indexterm>
<indexterm zone="new-projects-start">
  <primary>project</primary>
  <secondary>create new project</secondary>
  <tertiary>dialog</tertiary></indexterm>
<indexterm zone="new-projects-start">
  <primary>project</primary>
  <secondary>templates</secondary></indexterm>
<indexterm zone="new-projects-start">
  <primary>templates</primary>
  <secondary>project</secondary></indexterm>

<para>
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:
</para>

<screenshot id="screenshot-newprojectwizard">
  <mediaobject>
    <imageobject>
      <imagedata fileref="create-new-project.png" format="PNG"/>
    </imageobject>
    <caption><para>
    Initial dialog to set up a new project
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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.
</para>

<sect3 id="new-projects-start-type">
<title>Select Programming Language and Application Type</title>

<indexterm zone="new-projects-start-type">
  <primary>project</primary>
  <secondary>application type</secondary></indexterm>
<indexterm zone="new-projects-start-type">
  <primary>project</primary>
  <secondary>programming language</secondary></indexterm>
<indexterm zone="new-projects-start-type">
  <primary>project</primary>
  <secondary>language</secondary></indexterm>
<indexterm zone="new-projects-start-type">
  <primary>language</primary></indexterm>
<indexterm zone="new-projects-start-type">
  <primary>programming language</primary></indexterm>
<indexterm zone="new-projects-start-type">
  <primary>application</primary>
  <secondary>type</secondary></indexterm>

<para>
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:
</para>

<itemizedlist>
  <listitem><para>
    Ada
    <indexterm>
      <primary>Ada</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    C
    <indexterm>
      <primary>C</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    C++
    <indexterm>
      <primary>C++</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    Database (SQL Projects)
    <indexterm>
      <primary>SQL</primary>
      <secondary>new project</secondary></indexterm>
    <indexterm>
      <primary>Database</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    Fortran
    <indexterm>
      <primary>Fortran</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    Haskell
    <indexterm>
      <primary>Haskell</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    Java
    <indexterm>
      <primary>Java</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    PHP
    <indexterm>
      <primary>PHP</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    Pascal
    <indexterm>
      <primary>Pascal</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    Perl
    <indexterm>
      <primary>Perl</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    Python
    <indexterm>
      <primary>Python</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    Ruby
    <indexterm>
      <primary>Ruby</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
  <listitem><para>
    Shell (Scripts for the Bash Shell)
    <indexterm>
      <primary>Bash</primary>
      <secondary>new project</secondary></indexterm>
    <indexterm>
      <primary>shell</primary>
      <secondary>new project</secondary></indexterm>
  </para></listitem>
</itemizedlist>

<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>

<formalpara>
<title>Selecting a Project Management System</title>
<para>
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.
</para>
</formalpara>

</sect3> <!-- new-projects-start-type -->

<sect3 id="new-projects-start-general">
<title>Provide General Information</title>

<indexterm zone="new-projects-start-general">
  <primary>project</primary>
  <secondary>properties</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>properties</primary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>application</primary>
  <secondary>name</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>name</primary>
  <secondary>application</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>project</primary>
  <secondary>directory</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>directory</primary>
  <secondary>project</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>path</primary>
  <secondary>new project</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>project</primary>
  <secondary>author</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>project</primary>
  <secondary>email</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>author</primary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>email</primary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>project</primary>
  <secondary>main.cpp</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>main.cpp</primary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>project</primary>
  <secondary>license</secondary></indexterm>
<indexterm zone="new-projects-start-general">
  <primary>license</primary></indexterm>

<para>
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.
</para>
<formalpara>
<title>Application Name</title>
<para>
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.
</para>
</formalpara>
<para>
When you do so, you will notice that the &appwizard; refuses to accept special characters of any kind. The only characters accepted are:
<itemizedlist>
  <listitem><para>upper and lower case characters</para></listitem>
  <listitem><para>numbers</para></listitem>
  <listitem><para>the underline character</para></listitem>
</itemizedlist>
</para>
<para>
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.
</para>
<formalpara>
<title>The Project Directory</title>
<para>
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.
</para>
</formalpara>
<para>
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.
</para>
<para>
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 &gt;</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.
</para>

<formalpara>
<title>The Starting Path</title>
<para>
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 &eg; set up for another version of an already existing application). As an alternative you may select another path to the application directory.
</para>
</formalpara>
<para>
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.
</para>
<para>
&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.
</para>
<para>
Alter the <guilabel>Location</guilabel> field contents so that the application development directory shown in the <guilabel>Final location</guilabel> line will be unique.
</para>
<!--TODO add tab description Project Options -->
<note><para>
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.
</para></note>

<screenshot id="screenshot-createnewprojectoptions">
  <mediaobject>
    <imageobject>
      <imagedata fileref="createnewprojectoptions.png" format="PNG"/>
    </imageobject>
    <caption><para>
    Set new project up for CVS
    </para></caption>
  </mediaobject>
</screenshot>

<formalpara>
<title>Personal Information</title>
<para>
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.
</para>
</formalpara>

<note>
<orderedlist>
  <listitem><para>
  The &appwizard; fills these fields with some default values, taken from
  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;.
  </para></listitem>
  <listitem><para>
  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.
  </para></listitem>
  <listitem><para>
  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.
  </para></listitem>
</orderedlist>
</note>

<formalpara>
<title>Version and License Info</title>
<para>
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.
</para>
</formalpara>

<para>
If you select an application type for which the &appwizard; provides common source template texts (&eg; 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).
</para>
<para>
If you selected <quote>Custom</quote> from the <guilabel>License</guilabel> tab you must provide a license text on your own.
</para>

<note><para>
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.
</para></note>

<para>
Once you have correctly entered all this information stuff, press the <guibutton>Next &gt;</guibutton> button to proceed as shown in the following chapters.
</para>
</sect3> <!-- new-projects-start-general -->

</sect2> <!-- new-projects-start -->

<sect2 id="new-projects-start-cvs">
<title>Supply Version System Information</title>

<indexterm zone="new-projects-start-cvs">
  <primary>CVS</primary>
  <secondary>new project</secondary></indexterm>
<indexterm zone="new-projects-start-cvs">
  <primary>project</primary>
  <secondary>CVS</secondary></indexterm>
<indexterm zone="new-projects-start-cvs">
  <primary>database</primary>
  <secondary>CVS</secondary></indexterm>
<indexterm zone="new-projects-start-cvs">
  <primary>version</primary>
  <secondary>database</secondary></indexterm>
<indexterm zone="new-projects-start-cvs">
  <primary>version</primary>
  <secondary>CVS</secondary></indexterm>

<para>
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.
</para>

<note><para>
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.
</para></note>

<formalpara>
<title>No Version Control System Wanted</title>
<para>
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.
</para>
</formalpara>

<formalpara>
<title>Using &CVS;</title>
<para>
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.
</para>
</formalpara>

<screenshot id="screenshot-newproject-cvs">
  <mediaobject>
    <imageobject>
      <imagedata fileref="create-new-project-cvs.png" format="PNG"/>
    </imageobject>
    <caption><para>
    Set new project up for CVS
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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.
</para>

<indexterm zone="new-projects-start-cvs-root">
  <primary>CVS</primary>
  <secondary>root</secondary></indexterm>
<indexterm zone="new-projects-start-cvs-root">
  <primary>root</primary>
  <secondary>CVS</secondary></indexterm>
<indexterm zone="new-projects-start-cvs-root">
  <primary>CVS</primary>
  <secondary>local</secondary></indexterm>
<indexterm zone="new-projects-start-cvs-root">
  <primary>CVS</primary>
  <secondary>remote</secondary></indexterm>
<indexterm zone="new-projects-start-cvs-root">
  <primary>local CVS</primary></indexterm>
<indexterm zone="new-projects-start-cvs-root">
  <primary>:local:</primary></indexterm>
<indexterm zone="new-projects-start-cvs-root">
  <primary>CVS</primary>
  <secondary>:local:</secondary></indexterm>

<formalpara id="new-projects-start-cvs-root">
<title>&CVS; Root</title>
<para>
&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.
</para>
</formalpara>

<para>
<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:
</para>
<para><userinput><filename class="directory">/home/devel/cvsroot</filename></userinput> (where <filename>devel</filename> simply denotes the <quote>developing</quote> user, just for example)
</para>

<note><para>
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>
</para></note>

<para>
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.
</para>
<para>
<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.
</para>
<note><para>
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.
</para></note>

<para>
<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:
</para>
<para>
<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)
</para>

<indexterm zone="new-projects-start-cvs-remote">
  <primary>remote CVS</primary></indexterm>
<indexterm zone="new-projects-start-cvs-remote">
  <primary>:pserver:</primary></indexterm>
<indexterm zone="new-projects-start-cvs-remote">
  <primary>:ext:</primary></indexterm>
<indexterm zone="new-projects-start-cvs-remote">
  <primary>CVS</primary>
  <secondary>:local:</secondary></indexterm>
<indexterm zone="new-projects-start-cvs-remote">
  <primary>CVS</primary>
  <secondary>:pserver:</secondary></indexterm>
<indexterm zone="new-projects-start-cvs-remote">
  <primary>CVS</primary>
  <secondary>:ext:</secondary></indexterm>

<formalpara id="new-projects-start-cvs-remote">
<title>Remote &CVS; Server Types</title>
<para>
Basically there are two widely used remote &CVS; server types, the
<emphasis>pserver</emphasis> which uses a password-secured non-encrypted
protocol, and the <emphasis>ext</emphasis> server which uses an rsh or ssh
encrypted data transfer. They are distinguished by the &URL; prefix they use:
</para>
</formalpara>
<para>
<filename>:pserver:</filename>
</para>
<para>
for the <quote>password protected server</quote> non-encrypted type, and
</para>
<para>
<filename>:ext:</filename>
</para>
<para>
for an rsh or ssh encrypted server type. For example
</para>
<para>
<userinput><filename class="directory">:ext:<replaceable>mylogin</replaceable>@cvs.cervisia.sourceforge.net:/cvsroot/cervisia</filename></userinput>
</para>
<para>
accesses the &CVS; root of the widely used <application>Cervisia</application> &CVS; management tool on the SourceForge server.
</para>
<para>
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.
</para>

<note><para>
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.
</para></note>

<indexterm zone="new-projects-start-cvs-repository">
  <primary>CVS</primary>
  <secondary>repository</secondary></indexterm>
<indexterm zone="new-projects-start-cvs-repository">
  <primary>repository</primary>
  <secondary>CVS</secondary></indexterm>

<formalpara id="new-projects-start-cvs-repository">
<title>The &CVS; Repository</title>
<para>
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>.
</para>
</formalpara>
<para>
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.
</para>
<para>
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>
</para>

<warning><para>
<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!
</para></warning>

<formalpara>
<title>The Remaining Fields</title>
<para>
There is not much work left to do. &appwizard; has already set up the remaining fields for you. In detail:
</para>
</formalpara>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.)
</para>
<para>
The &appwizard; has put a default <quote>start</quote> tag in here which is a worthy proposal. Just stick to it.
</para>

<note>
<para>
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:
</para>

<screen><computeroutput>
* cd '/home/devel/test' &amp;&amp; cvs -d '/home/devel/mycvsroot' \
  import -m 'new project' '' 'vendor' 'start' &amp;&amp;\
  sh /opt/kde3/share/apps/kdevcvs/buildcvs.sh . '' \
  '/home/devel/mycvsroot'
* cvs [import aborted]: /home/devel/mycvsroot/CVSROOT: No such file or
  directory
* *** Exited with status: 1 ***
</computeroutput></screen>

<para>
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.
</para>
</note>

<para>
After you have entered all &CVS; related information, click the <guibutton>Next &gt;</guibutton> to go on.
</para>

<note><para>
If you want to correct an error on the previous <guilabel>Create New Project</guilabel> page, just press the <guibutton>&lt; Back</guibutton> button. The &appwizard; will remember your settings on the current page, so you can easily proceed when you come back.
</para></note>

</sect2> <!-- new-projects-start-cvs -->

<sect2 id="new-projects-start-templates">
<title>Supply Header/Source Templates</title>

<para>
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.
</para>
<para>
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.
</para>
<para>
If the page is used, &appwizard; will fill in some common header comment which for a C++ based application might look like:
</para>

<screen><computeroutput><literal>
/***************************************************************************
 *   Copyright (C) 2003 by Your Name                                       *
 *   you@you.com                                                           *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
 ***************************************************************************/
</literal></computeroutput></screen>

<para>
Other templates will provide similar information in a format according to the definitions of the programming language you want to use.
</para>
<para>
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.
</para>

<sect3 id="new-projects-start-templates-edit">
<title>How to Edit the Templates</title>

<indexterm zone="new-projects-start-templates-edit">
  <primary>templates</primary>
  <secondary>project</secondary>
  <tertiary>edit</tertiary></indexterm>
<indexterm zone="new-projects-start-templates-edit">
  <primary>project</primary>
  <secondary>templates</secondary>
  <tertiary>edit</tertiary></indexterm>

<para>
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.
</para>
<para>
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.
</para>

<variablelist>
<varlistentry>
<term>Include &doxygen; File Information</term>
<listitem>
<para>
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:
</para>
<screen><computeroutput>
/**
 * \file $MODULE$.cpp
 * \brief (put some short descripion here).
 **/
</computeroutput></screen>
<para>
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:
</para>
<screen><computeroutput>
/**
 * \file asimpletest.cpp
 * \brief (put some short descripion here).
 **/
</computeroutput></screen>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>The License Text File</term>
<listitem>
<para>
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:
</para>

<screen><computeroutput>
//   See $LICENSEFILE$ for the full license text.
</computeroutput></screen>
<para>
The &appwizard; will replace the <varname>$LICENSEFILE$</varname> with the name of the file where the full license text is to be found, namely:
</para>
<screen><computeroutput>
//   See COPYING for the full license text.
</computeroutput></screen>
<para>
for the <acronym>GPL</acronym> license, or
</para>
<screen><computeroutput>
//   See LICENSE.BSD for the full license text.
</computeroutput></screen>
<para>
if you decided to put your application under the <acronym>BSD</acronym> license.
</para>
<para>
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.
</para>
</listitem>
</varlistentry>
</variablelist>

<note><para>
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.
</para></note>

</sect3> <!-- new-projects-start-templates-edit -->
</sect2> <!-- new-projects-start-templates -->

<sect2 id="new-projects-start-build">
<title>Build the Initial Project Files</title>

<indexterm zone="new-projects-start-build">
  <primary>project</primary>
  <secondary>new</secondary>
  <tertiary>build</tertiary></indexterm>
<indexterm zone="new-projects-start-build">
  <primary>project</primary>
  <secondary>initial build</secondary></indexterm>

<para>
Almost everything is done now. On the last templates page the <guibutton>Next &gt;</guibutton> button will have changed to read <guibutton>Finish</guibutton> now.
</para>
<para>
<emphasis>Think twice before you click on it!</emphasis> You still have the option to revise everything by repeatedly using the <guibutton>&lt; 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&mdash;if it does, try another repository name).
</para>
<para>
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.
</para>
<para>
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.
</para>

<note><para>
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&mdash;if any at all&mdash;however depends on the template initially selected in the &appwizard;.)
</para></note>

<para>
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.
</para>
<para>
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.
</para>

<warning id="defaultbuild-warning"> <!-- ### remove this when "default" works again -->

  <indexterm zone="defaultbuild-warning">
    <primary>default build configuration</primary>
    <secondary>warning</secondary></indexterm>
  <indexterm zone="defaultbuild-warning">
    <primary>build configurations</primary>
    <secondary>default build warning</secondary></indexterm>
  <indexterm zone="defaultbuild-warning">
    <primary>warning</primary>
    <secondary>default build configuration</secondary></indexterm>

  <para>
  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.
  </para>
  <para>
  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.
  </para>
  <para>
  (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.)
  </para>
</warning>

</sect2> <!-- new-projects-start-build -->

</sect1> <!-- new-projects -->

<sect1 id="projects-configure">
<title>Configuring Projects</title>

<para>(... to be written ...)</para>

</sect1>

</chapter> <!-- applicationwizard -->