<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>

<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 necessary management facilities such as the make system, 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>

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

<para>
Whenever you want to initiate a new programming project several formal setup procedures need to be completed. 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="createnewproject.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>
    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>
    PHP
    <indexterm>
      <primary>PHP</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 (&eg; you might set up a new project 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>

<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>

<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 <application>KDE control center</application>. 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 KDE control center.
  </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 the only <emphasis>optional</emphasis> field, 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 be integrated into the starting templates in a format suiting the application type you selected.
</para></note>

<para>
Once you have correctly entered all the information, 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 &gt;</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:mylogin@cvs.kde.org:/home/kde</filename></userinput> (where <filename>mylogin</filename> 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:mylogin@cvs.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>
If any information about version control is wrong &kdevelop; usually will not know 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><literal>
* 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 ***
</literal></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 <guibutton>Next &gt;</guibutton> to proceed.
</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 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>

<formalpara>
<title>Include &doxygen; File Information</title>
<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>
</formalpara><screen><computeroutput><literal>
/**
 * \file $MODULE$.cpp
 * \brief (put some short descripion here).
 **/
</literal></computeroutput></screen>
<para>
Whenever you create a new source file, &kdevelop; will replace the <computeroutput>$MODULE$</computeroutput> 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><literal>
/**
 * \file asimpletest.cpp
 * \brief (put some short descripion here).
 **/
</literal></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>
<formalpara>
<title>The License Text File</title>
<para>
As another example you could include an explicit hint to the license text you want to use into the template. Use the <computeroutput>$LICENSEFILE$</computeroutput> variable for this and add for example this line:
</para>
</formalpara>
<screen><computeroutput><literal>
//   See $LICENSEFILE$ for the full license text.
</literal></computeroutput></screen>
<para>
The &appwizard; will replace the <computeroutput>$LICENSEFILE$</computeroutput> with the name of the file where the full license text is to be found, namely:
</para>
<screen><computeroutput><literal>
//   See COPYING for the full license text.
</literal></computeroutput></screen>
<para>
for the GPL license, or
</para>
<screen><computeroutput><literal>
//   See LICENSE.BSD for the full license text.
</literal></computeroutput></screen>
<para>
if you decided to put your application under the BSD license.
</para>
<para>
There 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>

<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 adviceable 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 determine 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="applicationwizard-behind">
<title>Behind the Scenes</title>

<indexterm zone="applicationwizard-behind">
  <primary>project</primary>
  <secondary>new</secondary>
  <tertiary>build</tertiary></indexterm>
<indexterm zone="applicationwizard-behind">
  <primary>CVS</primary>
  <secondary>new project</secondary>
  <tertiary>build</tertiary></indexterm>

<para>
It is always advisable to look at the messages output and try to understand what has happened. At least in principle you should know what has been done when the &appwizard; initiated your new project. We cannot go into the details but will have an overview of those messages to get an idea of what was going on behind the scenes.
</para>

<tip>
<para>
If your project was set up for local &CVS; you will have received two series of messages of which the first set most probably was gone before you could thoroughly read, as &CVS; used the <guilabel>Messages</guilabel> window for its own purposes. So we caught both series in separate runs&mdash;set up the application twice, one time without &CVS;, then removed the directory and started over, this time setting the application up with &CVS;.
</para>
<para>
You may want to follow this same procedure if anything weird happened and you just could not catch the messages of the first setup step.
</para>
</tip>
<para>
We will have look at the <guilabel>Messages</guilabel> outputs of both steps:
<itemizedlist>
  <listitem><para>
    <link linkend="applicationwizard-behind-app">Setting up the application</link> as well as
  </para></listitem>
  <listitem><para>
    <link linkend="applicationwizard-behind-cvs">Setting up &CVS;</link>.
  </para></listitem>
</itemizedlist>
</para>

<sect2 id="applicationwizard-behind-app">
<title>Setting Up the Application</title>

<indexterm zone="applicationwizard-behind-app">
  <primary>Perl</primary>
  <secondary>new project</secondary></indexterm>
<indexterm zone="applicationwizard-behind-app">
  <primary>Perl</primary>
  <secondary>kdevelop.pm</secondary></indexterm>
<indexterm zone="applicationwizard-behind-app">
  <primary>kdevelop.pm</primary></indexterm>
<indexterm zone="applicationwizard-behind-app">
  <primary>project</primary>
  <secondary>kdevelop.pm</secondary></indexterm>

<para>
If you set up <quote>MyApp</quote> as in our previous example the &appwizard; should have printed the following messages (we re-arranged the output a bit for readability and you may click on a line to directly jump to its description):
</para>
<screen><computeroutput>
* <link linkend="applicationwizard-behind-app-perl">perl</link> /opt/kde3/share/apps/kdevappwizard/template-kapp/script \
  --author='Your Name' \
  --email='you@you.com' \
  --version='0.1' \
  --appname='MyApp' \
  --dest='/home/devel/projects/myapp' \
  --source='/opt/kde3/share/apps/kdevappwizard' \
  --license='GPL' \
  --licensefile='COPYING' \
  --filetemplates='h,/tmp/kde-devel/kdevelopcDE5Ja.tmp,\
                   cpp,/tmp/kde-devel/kdevelopsRrLab.tmp'
* <link linkend="applicationwizard-behind-app-base">Making destination directory</link>
* <link linkend="applicationwizard-behind-app-templates">Installing file templates</link>
* <link linkend="applicationwizard-behind-app-license">Installing license file</link>
* <link linkend="applicationwizard-behind-app-admin">Installing admin directory</link>
* <link linkend="applicationwizard-behind-app-gnu">Installing &GNU; coding standard files</link>
* <link linkend="applicationwizard-behind-app-doc">Installing Docbook template</link>
* <link linkend="applicationwizard-behind-app-project">Installing project file</link>
* <link linkend="applicationwizard-behind-app-framework">Installing application framework</link>
* <link linkend="applicationwizard-behind-app-sources">Installing application sources</link>
* Finished
* *** Success ***
</computeroutput></screen>
<formalpara id="applicationwizard-behind-app-perl">
<title>A &perl; Script Called</title>
<para>
As you see from the first line, the &appwizard; did construct a &perl; program call from the settings you made in the <guilabel>Create New Project</guilabel> dialog. The called <filename>script</filename> resides in a directory which was determined from the application type template you selected in the upper part of the <guilabel>Create New Project</guilabel> dialog <guilabel>General</guilabel> page.
</para>
</formalpara>
<para>
In our case this <filename>script</filename> is located in the <filename class="directory">/opt/kde3/share/apps/kdevappwizard/template-kapp/</filename> directory. Just replace <filename class="directory">/opt/kde3/</filename> by the &kde; directory on your system.
</para>
<para>
This &perl; <filename>script</filename> is called with a series of parameters, all marked by <quote><computeroutput>--</computeroutput></quote> prefixes, wherein the &appwizard; put information from the other selections you made in the <guilabel>Create New Project</guilabel> dialog.
</para>
<para>
The exact series of initialization steps depends on which &perl; <filename>script</filename> was called. If you want to check, just look into the <filename>script</filename> file the <computeroutput>perl</computeroutput> command on the first <guilabel>Messages</guilabel> window line called.
</para>
<note><para>
The setup scripts make use of a set of &perl; subroutines collected in the <filename>kdevelop.pm</filename> file which you may find in the <filename class="directory">share/apps/kdevwizard/template-common/</filename> subdirectory of your &kde; installation.
</para></note>

<formalpara id="applicationwizard-behind-app-base">
<title>The Application Base Directory</title>
<para>
When the &perl; script is run, you get a series of messages of what is <emphasis>about to be done</emphasis> in the next installation step. At first a <computeroutput>destination directory</computeroutput> will be set up. This is the base directory of your application, just what you got displayed in the <guilabel>Final location</guilabel> line on the <guilabel>Create New Project</guilabel> dialog <guilabel>General</guilabel> page. The script uses the value of the <computeroutput>--dest</computeroutput> parameter in the &perl; command above.
</para>
</formalpara>

<indexterm zone="applicationwizard-behind-app-templates">
  <primary>project</primary>
  <secondary>templates</secondary></indexterm>
<indexterm zone="applicationwizard-behind-app-templates">
  <primary>templates</primary>
  <secondary>project</secondary></indexterm>

<formalpara id="applicationwizard-behind-app-templates">
<title>The File Templates</title>
<para>
In the next step the file templates you set up in the <guilabel>Create New Project</guilabel> dialog will be copied to the <filename class="directory">templates</filename> subdirectory of this destination directory. As you can see from the <computeroutput>--filetemplates</computeroutput> parameter, the templates are submitted in pairs&mdash;the suffixes they are used for first, followed by the name of a temporary file in which the &appwizard; has copied the contents of the templates dialog pages. These suffixes will be taken as the filenames of where to store the template texts.
</para>
</formalpara>
<para>
In our example two such template files were installed, namely <filename>templates/h</filename> for C++ header and <filename>templates/cpp</filename> for C++ source files.
</para>

<indexterm zone="applicationwizard-behind-app-license">
  <primary>project</primary>
  <secondary>license</secondary></indexterm>
<indexterm zone="applicationwizard-behind-app-license">
  <primary>license</primary></indexterm>

<formalpara id="applicationwizard-behind-app-license">
<title>The License File</title>
<para>
On the <guilabel>General</guilabel> page of the <guilabel>Create New Project</guilabel> dialog you selected the license you want to put your application under. The &appwizard; initiated two actions from this. One was the license indication it put into the templates. The other action causes the according license file to be copied in your application base directory.
</para>
</formalpara>
<para>
The <computeroutput>--licensefile</computeroutput> parameter tells the &perl; <filename>script</filename> which license text file to copy. In our example the <filename>/home/devel/projects/myapp/COPYING</filename> file will have been installed in this step.
</para>

<indexterm zone="applicationwizard-behind-app-admin">
  <primary>project</primary>
  <secondary>administration</secondary></indexterm>
<indexterm zone="applicationwizard-behind-app-admin">
  <primary>administration</primary></indexterm>

<formalpara id="applicationwizard-behind-app-admin">
<title>The Administration Directory</title>
<para>
&kdevelop; needs a bunch of files to administrate the project. These are put in the <filename class="directory">admin</filename> subdirectory of your application base directory.
</para>
</formalpara>
<para>
&appwizard; creates the <filename class="directory">admin</filename> subdirectory in this step and extracts the standard set of files it needs from the <filename>share/apps/kdevappwizard/template-common/admin.tar.gz</filename> tarball in your &kde; directory.
</para>
<note><para>
&kdevelop; always uses the same set of standard files for its administration purposes. Hence no parameter is needed in the &perl;  <filename>script</filename> call to set up the <filename class="directory">admin</filename> subdirectory.
</para></note>

<indexterm zone="applicationwizard-behind-app-gnu">
  <primary>GNU</primary>
  <secondary>coding standard</secondary></indexterm>

<formalpara id="applicationwizard-behind-app-gnu">
<title>The &GNU; Coding Standard Files</title>
<para>
There are several standard files to be distributed with every application which conforms to the &GNU; coding standard. The &perl; <filename>script</filename> extracts these files from the <filename>share/apps/kdevappwizard/template-common/gnu.tar.gz</filename> tarball of your &kde; installation directory and customizes them according to the information you provided in the <guilabel>Create New Page</guilabel> dialog.
</para>
</formalpara>
<para>
After this step you will find the following files in your application base directory:
<itemizedlist>
  <listitem><para>
    <filename>AUTHORS</filename>, initially containing information from the <computeroutput>--author</computeroutput> and <computeroutput>--email</computeroutput> parameters.
  </para></listitem>
  <listitem><para>
    <filename>COPYING</filename>, this is the general &GNU; license, which all &GNU; conforming applications must contain&mdash;even if you decided to put your application under another license.
  </para></listitem>
  <listitem><para>
    <filename>ChangeLog</filename>, initially empty&mdash;you should protocol all major changes here.
  </para></listitem>
  <listitem><para>
    <filename>INSTALL</filename> contains generic installation instructions&mdash;modify this if special precautions and/or procedures are needed to install your application.
  </para></listitem>
  <listitem><para>
    <filename>README</filename>, initially empty&mdash;put any information here the user should know before installing your application.
  </para></listitem>
  <listitem><para>
    <filename>TODO</filename>, initially empty&mdash;put information here about what has to be done to further develop your application. You can use this as a notebook for your own purposes, but it is also really helpful once you have put your application in public domain.
  </para></listitem>
</itemizedlist>
</para>

<indexterm zone="applicationwizard-behind-app-doc">
  <primary>project</primary>
  <secondary>documentation</secondary></indexterm>
<indexterm zone="applicationwizard-behind-app-doc">
  <primary>documentation</primary>
  <secondary>project</secondary></indexterm>

<formalpara id="applicationwizard-behind-app-doc">
<title>The Initial Application Documentation</title>
<para>
Every project you set up will contain an initial <emphasis>DocBook</emphasis> template from where you can start to write your application documentation. The &perl; <filename>script</filename> will in this step have set up <filename class="directory">doc</filename> and <filename class="directory">doc/en</filename> subdirectories of the application base directory with an initial <filename>doc/en/index.docbook</filename> template and some &automake; <filename>Makefile.am</filename> files from which &kdevelop; can later build help system files.
</para>
</formalpara>

<indexterm zone="applicationwizard-behind-app-project">
  <primary>project</primary>
  <secondary>project file</secondary></indexterm>
<indexterm zone="applicationwizard-behind-app-project">
  <primary>&kdevelop;</primary>
  <secondary>project file</secondary></indexterm>

<formalpara id="applicationwizard-behind-app-project">
<title>The Project File</title>
<para>
Up to here most of the more global stuff has been set up, things which more or less are to be found in any &kdevelop; project. With this step the more application-specific setup processes start. These may vary upon the type of application you selected. Have a look at the actual &perl; <filename>script</filename> the &appwizard; called up for your new application if you want to lookup details. We will continue to follow the example steps listed above.
</para>
</formalpara>
<para>
In the first step of these the <emphasis>&kdevelop; project management file</emphasis> is copied out of the template directory, where the &perl; <filename>script</filename> resides. In our case the <filename>share/apps/kdevappwizard/template-kapp/app.kdevelop</filename> file was copied into the application base directory and then customized according to the selections made in the <guilabel>Create New Project</guilabel> dialog.
</para>

<note><para>
You may want to have a look at the resulting project file which in our case was saved as <filename>/home/devel/projects/myapp/myapp.kdevelop</filename>. It is written in XML format and easily to be displayed with <application>Kate</application> or any other text editor. But take care nothing to change as &kdevelop; relies on its contents.
</para></note>

<indexterm zone="applicationwizard-behind-app-framework">
  <primary>project</primary>
  <secondary>framework</secondary></indexterm>
<indexterm zone="applicationwizard-behind-app-framework">
  <primary>project</primary>
  <secondary>application framework</secondary></indexterm>
<indexterm zone="applicationwizard-behind-app-framework">
  <primary>framework</primary></indexterm>
<indexterm zone="applicationwizard-behind-app-framework">
  <primary>application</primary>
  <secondary>framework</secondary></indexterm>

<formalpara id="applicationwizard-behind-app-framework">
<title>The Application Framework</title>
<para>Now it is about time that the directory structures and other maintenance files be set up to put the new application in and have it maintained. A so-called <emphasis>application framework</emphasis> will be set up in this step. Its structure basically depends on the type of application you selected in the <guilabel>Create New Project</guilabel> dialog, but parts of it are common enough to be found in other projects, too.
</para>
</formalpara>
<para>
In our case the following directory structure has been created in the <filename class="directory">/home/devel/projects/myapp/</filename> application base directory:
<itemizedlist>
  <listitem><para>
    The <filename>src</filename> subdirectory is meant to hold the source files of your application.
  </para></listitem>
  <listitem><para>
    The <filename>debug</filename> subdirectory will hold the compiled output of the <emphasis><quote>debug</quote> build configuration</emphasis>. (See the <link linkend="buildconfigurations">Build configurations</link> chapter to learn more about that.) As the name says, you should use this directory for debug purposes.
  </para></listitem>
  <listitem><para>
    The <filename>optimized</filename> subdirectory will hold the compiled output of the <emphasis><quote>optimized</quote> build configuration</emphasis>. You should test an optimized version of your application from within here.
  </para></listitem>
  <listitem><para>
    The <filename>po</filename> subdirectory is meant for <emphasis>translation purposes</emphasis>. It will hold so-called <quote>Portable Object</quote> files (<filename>.po</filename> files) and templates (<filename>.pot</filename> files) which will be processed by a translation program as &eg; <application>KBabel</application>.
  </para></listitem>
</itemizedlist>
</para>
<para>
All these directories will not be kept empty but filled with a series of <filename>Makefile</filename> and other files &kdevelop; uses to process the sources of the application. Also some initial icon files for the new application will have been put into the <filename>src</filename> subdirectory, if applicable. In our case you will find two of them: <filename>src/hi16-app-myapp.png</filename> and <filename>src/hi32-app-myapp.png</filename> which both hold standard &kde; application icons.
</para>

<formalpara id="applicationwizard-behind-app-sources">
<title>Application Sources Installed</title>
<para>
This framework finally will be used to put the <emphasis>initial source files</emphasis> of your new project in the <filename class="directory">src</filename> directory. The actual files highly depend on the application type you selected in the <guilabel>Create New Project</guilabel> dialog. You will soon see yourself as this is the stuff you will actually have to work on.
</para>
</formalpara>

</sect2> <!-- applicationwizard-behind-app -->

<sect2 id="applicationwizard-behind-cvs">
<title>Setting Up &CVS;</title>

<indexterm zone="applicationwizard-behind-cvs">
  <primary>CVS</primary>
  <secondary>new project</secondary>
  <tertiary>build</tertiary></indexterm>
<indexterm zone="applicationwizard-behind-cvs">
  <primary>project</primary>
  <secondary>CVS</secondary></indexterm>

<para>
Now let us have a look at what the <guilabel>Messages</guilabel> window will contain when the &appwizard; continues to build our example project. If no error occurred during the first pass, the <guilabel>Messages</guilabel> contents will revert to create the local &cvs; repository.
</para>
<para>
As before we reformatted the output lines a bit for readability. And we removed some superfluous lines (where the <quote>. . .</quote> dots are).
</para>

<screen><computeroutput>
* cd '/home/devel/projects/myapp' \
  &amp;&amp; cvs -d '/home/devel/cvsroot' \
         import -m 'new project' \
                'MyApp' \
                'vendor' \
                'start' \
  &amp;&amp; sh /opt/kde3/share/apps/kdevcvs/buildcvs.sh . \
                                                 'MyApp' \
                                                 '/home/devel/cvsroot'
  . . .
* N MyApp/NEWS
* N MyApp/TODO
* N MyApp/README
  . . .
* N MyApp/admin/configure.in.bot.end
* N MyApp/templates/h
* N MyApp/templates/cpp
*
* No conflicts created by this import
*
* *** Success ***
</computeroutput></screen>

<para>
As you see from the first message line, the &appwizard; built another shell command line which conducts the &cvs; work to be done. At first the shell changes to the newly created application base directory to use it as default in the following steps.
</para>

<formalpara>
<title>Building the &cvs; Repository</title>
<para>
In the second command line part the &CVS; application will be called to <emphasis>import</emphasis> the initial project contents into the wanted repository. Again, the work in detail is commanded by a series of command line arguments to the &CVS; application call.
</para>
</formalpara>
<itemizedlist>
  <listitem><para>
    <computeroutput>-d '/home/devel/cvsroot'</computeroutput>&mdash;the <computeroutput>-d</computeroutput> option tells &CVS; which root directory is to be used. In our case this is the <emphasis>local &cvs; root</emphasis> located in <filename class="directory">/home/devel/cvsroot</filename>.
  </para></listitem>
  <listitem><para>
    <computeroutput>import</computeroutput>&mdash;tells the &CVS; application which operation to perform in this root. We want to <emphasis>import</emphasis> files into the &cvs; database. To accomplish this, the <computeroutput>import</computeroutput> command needs some arguments of its own:
    <itemizedlist>
      <listitem><para>
        <computeroutput>-m 'new project'</computeroutput>&mdash;the <computeroutput>-m</computeroutput> option provides import some <emphasis>message text</emphasis> for this action. It will be stored in the database and can later be recalled to identify the data which was kept in this step. In our case <quote><computeroutput>new project</computeroutput></quote> denotes the storage of our first files in the database.
      </para></listitem>
      <listitem><para>
        <computeroutput>'MyApp'</computeroutput>&mdash;the second argument tells &CVS; which <emphasis>repository</emphasis> to use. If it does not exist, it will be created prior to the file import actions. In this case the <filename>MyApp</filename> repository will be created.
      </para></listitem>
      <listitem><para>
        <computeroutput>'vendor'</computeroutput>&mdash;this following argument is a <emphasis>tag</emphasis>, a symbolic name which marks a series of files in the directory. There are several different meanings such a tag can have (see <link linkend="cvs">Using CVS</link> for more information), this one in principle marks the whole bunch of files which subsequently will ever be stored in this repository. It is of no particular use to us, so <quote><computeroutput>vendor</computeroutput></quote> is as good a name as any other.
      </para></listitem>
      <listitem><para>
        <computeroutput>'start'</computeroutput>&mdash;is another tag. It marks the <emphasis>release</emphasis>, in easy words a series of subsequently saved files which belong together. We used <quote><computeroutput>start</computeroutput></quote> here, a meaningful description of the use of this initial series.
      </para></listitem>
    </itemizedlist>
  </para></listitem>
</itemizedlist>

<formalpara>
<title>The Imported Files</title>
<para>
The &CVS; application will create the repository and then start to import all files from our <filename class="directory">/home/devel/projects/myapp</filename> directory. It subsequently reports any file which is loaded&mdash;this is the contents of the whole bunch of <quote><computeroutput>N</computeroutput></quote> lines following in the <guilabel>Messages</guilabel> window. The <computeroutput>N</computeroutput> denotes that this file was newly imported into the repository.
</para>
</formalpara>
<para>
Depending on the type of the new application there will be quite a lot of those <quote><computeroutput>N</computeroutput></quote> lines. We truncated the output showing only the first and last three lines as an example.
</para>

<formalpara>
<title>The &CVS; Success Message</title>
<para>
&CVS; always reports when an operation was successfully performed. In our case the <quote><computeroutput>No conflicts created by this import</computeroutput></quote> message was printed, followed by the general <quote><computeroutput>*** Success ***</computeroutput></quote> line as no other operation had to be performed.
</para>
</formalpara>

<note><para>
There <emphasis>could</emphasis> have been some error messages about conflicting files if the repository already existed because &CVS; checks the file contents according to some formal criteria and will report any conflict it possibly finds.
</para></note>

<formalpara>
<title>Building the &cvs; Administration Entries</title>
<para>
The &CVS; import operation is concluded at this point. The repository has been set up and all files we want to be kept were stored in the database. Yet there is more work to do, because the &CVS; application needs some administration information kept in every directory of the application. It uses this information later to communicate with the cvs root and repository.
</para>
</formalpara>
<para>
If we were working with &CVS; alone we had to provide a means for &CVS; to store this information in our working directory. For instance we could <emphasis>check out</emphasis> the files again in an empty base directory in which case &CVS; automatically would write all administrative operation together with the checked out files.
</para>
<para>
In &kdevelop; fortunately there is an easier way. It provides the <filename>buildcvs.sh</filename> shell script in the <filename class="directory">/opt/kde3/share/apps/kdevcvs/</filename> directory (again replace <filename class="directory">/opt/kde</filename> with your &kde; installation directory), which the &appwizard; called after the &CVS; application had successfully finished its work.
</para>
<para>
The <filename>buildcvs.sh</filename> script mainly will put a <filename class="directory">CVS</filename> subdirectory into each directory of the application framework. Each of these  <filename class="directory">CVS</filename> subdirectories will hold three file entries as follows:
</para>
<itemizedlist>
  <listitem><para>
    <filename>Root</filename> holds the name of the server on which the &cvs; root is located. In our case this is the local <filename>/home/devel/cvsroot</filename> root. The rationale behind this is to always use the same repository for these files, because &CVS; does not store them as a whole but will record only the <emphasis>differences</emphasis> of the subsequent parts. This will save lots of disk space yet makes it mandatory that all subsequent information be kept together under all circumstances.
  </para></listitem>
  <listitem><para>
    <filename>Repository</filename> serves the same purpose. &CVS; keeps the name of the repository to use herein, <filename>MyApp</filename> in our case.
  </para></listitem>
  <listitem><para>
    <filename>Entries</filename> holds the names and some other data about the files &CVS; will care of in this directory. This is because &CVS; does not necessarily keep every application file in the repository. You can tell it which files to store and which to ignore&mdash;this information is kept in the <filename>Entries</filename> file.
  </para>
  </listitem>
</itemizedlist>

<para>
All these efforts are necessary because &CVS;'s work is <emphasis>directory-oriented</emphasis>. As &CVS; previously had stored all files in the <filename>MyApp</filename> framework, the <filename>buildcvs.sh</filename> script simply scans every directory and puts the names of all application files it finds into the according <filename>CVS/Entries</filename> file.
</para>
<para>
The script runs silently, just closing without any more line in the <guilabel>Messages</guilabel> window when the work was done.
</para>

</sect2> <!-- applicationwizard-behind-cvs -->

</sect1> <!-- applicationwizard-behind -->

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