# Getting Started—the &appwizard;

In &kdevelop; software development work is organized in projects. 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.

Organizing all development work in projects allows you to easily switch between the global tasks at hand. This is quite handy if you ⪚ work on several applications at the same time as is often the case. Tell &kdevelop; to open the project you want to work at and you may proceed in the environment just where you left.

## New Projects

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;

&kdevelop; provides an easy way to initiate a new programming project—the &appwizard;. You will find the &appwizard; at menu entry Project New Project.

Only a short series of steps is necessary to start a new programming project, using the &appwizard;:

1. Select the programming language you want to use and the type of the application you want to build from a set of predefined templates.

2. Supply some general information as application name, directory where the application shall be built, &etc;

3. Decide whether you want to use a version control system, like ⪚ CVS, and supply the necessary data if needed.

4. Set up some templates for initial header and source files (if applicable).

5. Finally tell &appwizard; to set up all initial stuff, directory structure, starting header/source file templates, and management tools, like ⪚ an initial make skeleton, &etc;

Voilà—that's all. &appwizard; will have provided you with a primary functional set of programming files, where you can readily start working.

Let's look at all this in more detail now ...

### Initial Steps

To create a new project in &kdevelop;, select New Project from the Project menu. The Create New Project dialog will pop up showing an initial General page:

Initial dialog to set up a new project

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.

#### Select Programming Language and Application Type

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:

- Ada

- C

- C++

- Database (SQL Projects)

- Fortran

- Haskell

- Java

- PHP

- Pascal

- Perl

- Python

- Ruby

- Shell (Scripts for the Bash Shell)

To be precise, these folders do not contain real programming tools actually. They do lead to pre-defined templates 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.

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 short description 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 screenshot of the main window the application will display.

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.

#### Selecting a Project Management System

Each template is bound to a specific Project Management System. 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.

#### Provide General Information

The lower part of the Create New Project dialog General page is a framed field labeled Properties. You must provide some general information about your project here so that the &appwizard; knows how to build the initial structure.

#### Application Name

Your application needs a name of course. Enter this in the uppermost Properties field, called Application Name. We use MyApp as an example.

When you do so, you will notice that the &appwizard; refuses to accept special characters of any kind. The only characters accepted are:

- upper and lower case characters

- numbers

- the underline character

One prominent cause of this restriction is that the &appwizard; will use this application name as the basis of some class names 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.

#### The Project Directory

The other prominent cause of this restriction you can see at the bottom line of the Properties area. It is labeled Final location and shows the directory where the &appwizard; will create the application.

As you type the application name you will notice that the &appwizard; repeats your input at the end of the Final location line, using lower case only characters.

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 Next > button deactivated (grayed). Yet, it will warn you in this case by appending (dir/file already exist) to the Final location line.

#### The Starting Path

There are two ways to select another path for your new application. One is to select another name. Yet, this is not always feasible (you might ⪚ set up for another version of an already existing application). As an alternative you may select another path to the application directory.

This is done in the second row input field of the Properties, named Location. What you enter here is the starting path 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 Final location line to give you better control on what is going on.

&appwizard; will copy an initial value to the Location field on start-up. This is taken from what you have chosen in the Default projects directory field during the general configuration steps. In our case we have &kdevelop; set up to use `/home/devel/projects/` as initial path for new projects.

Alter the Location field contents so that the application development directory shown in the Final location line will be unique.

Take care that the path you enter in the Location field already exists. Otherwise you will not be able to continue to the next step. The &appwizard; will warn you about non-existing paths by appending (invalid) to the Final location line.

#### Personal Information

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 Author field, and a valid e-mail address in the Email field, so that users can give you feedback on the application.

1. The &appwizard; fills these fields with some default values, taken from the Email presets in the KDE control center. If these defaults in the Create New Project Author and Email fields do not suit, you may want to have a look at your mail configuration in the KDE control center.

2. 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 `main.cpp` source file.

3. Of all fields, the Email is optional, 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.

#### Version and License Info

Finally enter a starting version number for your new application in the Version field, and select the license under which you want your application be put from the License tab.

If you select an application type for which the &appwizard; provides common source template texts (⪚ C/C++), you may view the license notification text on the third page of this Create New Project dialog (see the Supply header/source templates chapter below).

If you selected Custom from the License tab you must provide a license text on your own.

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.

Once you have correctly entered all this information stuff, press the Next > button to proceed as shown in the following chapters.

### Supply Version System Information

In a second step the &appwizard; will lead you to the Version Control System page where you can decide which version control system you want to use.

This discussion concentrates on the needs for project creation only. For more information on CVS see the Using CVS chapter below.

### No Version Control System Wanted

Initially there is None selected in the Version control system tab, and the page will be empty otherwise. If you don't want to use a version control system, just click the Next > button and go on.

### Using CVS

Otherwise you must reselect the version control system you want to use from the Version control system tab. We use &cvs; for our example. If you select this, the &appwizard; will redisplay the page, now showing a series of fields you must fill in.

Set new project up for CVS

A version control system such as &CVS; (which means Concurrent Versions System) stores copies of selected project files in some sort of a database. If you use &CVS; you can amongst others upload (commit) those files or load them back into your project directory (checkout, or update). 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.

### CVS Root

&cvs; needs to manage the versioning database it keeps from your project files. To accomplish this it keeps some special database information in an own directory, called the &cvs; root. The first step on setting up &cvs; for your new project thus is to tell &kdevelop; where this root is located.

Local &cvs; root. There are two basic possibilities. Either you want to use a local CVS database or you use a database which is held on a remote server. 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 `cvsroot`. This may look as follows:

``/home/devel/cvsroot`` (where `devel` simply denotes the developing user, just for example)

In fact, this is a short form. Exactly, the local &cvs; root should be addressed using the `:local:` prefix. The short form is only allowed in cases where the filename starts with a slash (`/`). The full name for our example local &cvs; root would exactly look like: `:local:/home/devel/cvsroot`

Enter the name of the &cvs; root directory your system has been set up for in the CVS root 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.

Initialize a new &cvs; root. 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 Init root checkbox below the CVS root field.

As said, &kdevelop; only commands 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 Init root on an already existing &cvs; root directory.

Remote &cvs; root. 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 CVS root field. For example, if you want access to the &kde; &cvs; server:

``:pserver:mylogin@cvs.kde.org:/home/kde`` (where `mylogin` denotes the login name set up in your &kde; &cvs; account)

### Remote &cvs; Server Types

Basically there are two widely used remote &cvs; server types, the pserver which uses a password-secured non-encrypted protocol, and the ext server which uses an rsh or ssh encrypted data transfer. They are distinguished by the URL prefix they use:

`:pserver:`

for the password protected server non-encrypted type, and

`:ext:`

for an rsh or ssh encrypted server type. For example

``:ext:mylogin@cvs.cervisia.sourceforge.net:/cvsroot/cervisia``

accesses the &cvs; root of the widely used Cervisia &cvs; management tool on the SourceForge server.

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 `rsh` or `ssh` in the CVS_RSH field of the Create New Project Version Control System page.

There is a caveat if you use an encrypted server for &cvs; from within &kdevelop;. See the Using CVS chapter for details.

### The &cvs; Repository

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

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.

Just enter the repository name you want to use in the CVS repository field of the Create New Project Version Control System page. In our example this is: `MyApp`

Take care not to use a repository which already exists! 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!

### The Remaining Fields

There is not much work left to do. &appwizard; has already set up the remaining fields for you. In detail:

The Vendor field is used for compatibility reasons only. You can stick to the vendor default the &appwizard; puts in here.

The Message field allows you to comment the initial &cvs; contents. Use any text you like or just stick to the new project default the &appwizard; did put in.

The Release tag holds the name which tags the initial state of your project. Such a tag names a certain point within the &CVS; repository by which you can later access this state of your development. (See more in the Using CVS chapter.)

The &appwizard; has put a default start tag in here which is a worthy proposal. Just stick to it.

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

    * cd '/home/devel/test' && cvs -d '/home/devel/mycvsroot' \
      import -m 'new project' '' 'vendor' 'start' &&\
      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 ***

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 New Project from the Project menu.

After you have entered all &CVS; related information, click the Next > to go on.

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

### Supply Header/Source Templates

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.

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.

If the page is used, &appwizard; will fill in some common header comment which for a C++ based application might look like:

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

Other templates will provide similar information in a format according to the definitions of the programming language you want to use.

As you might have noticed, the applications manager did readily fill in some information you provided on the first General page of the Create New Project dialog, namely the contents of the Author and Email fields. Also proper license information will have been inserted according to your selection in the License tab.

#### How to Edit the Templates

The templates you set up in the Create New Project 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.

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 Author, Email, and License informations into the initial template text.

#### Include &doxygen; File Information

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:

    /**
     * \file $MODULE$.cpp
     * \brief (put some short descripion here).
     **/

Whenever you create a new source file, &kdevelop; will replace the `$MODULE$` variable by the name body of the newly created file. For example, if you created a new C++ class named `ASimpleTest` you will see the following lines in the `asimpletest.cpp` file:

    /**
     * \file asimpletest.cpp
     * \brief (put some short descripion here).
     **/

You will still have to provide the short description after the \brief keyword, but part of the job is automatically done for you.

#### The License Text File

As another example you could include an explicit hint to the license text you want to use into the template. Use the `$LICENSEFILE$` variable for this and add for example this line:

    //   See $LICENSEFILE$ for the full license text.

The &appwizard; will replace the `$LICENSEFILE$` with the name of the file where the full license text is to be found, namely:

    //   See COPYING for the full license text.

for the GPL license, or

    //   See LICENSE.BSD for the full license text.

if you decided to put your application under the BSD license.

Thee are of course more variables &kdevelop; knows of. See the Editing the templates section in the Editing tools chapter for what is possible.

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.

### Build the Initial Project Files

Almost everything is done now. On the last templates page the Next > button will have changed to read Finish now.

Think twice before you click on it! You still have the option to revise everything by repeatedly using the < Back 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 CVS repository name (there should be no subdirectory with that name in the CVS root directory already—if it does, try another repository name).

If ever you don't want the new project be built, abort the Create New Project dialog by the Cancel button. Otherwise click Finish and watch in the Messages window how the &appwizard; initiates the project.

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

In many cases when your new project has been set up this way, &kdevelop; will automatically load the source file(s) of one or more basically important modules so you can readily start work. (Which source modules will be displayed—if any at all—however depends on the template initially selected in the &appwizard;.)

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 `templates` subdirectory in your project directory. Some simple copy operations will mostly suffice.

Then it is adviceable that you compile the initial project 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.

Before you compile your new project the first time, have a look at Project Build Configuration. If there are three selections displayed: default, optimized, and debug, with debug selected, by all means stick to this, or use optimized instead.

Due to some limitations in the current autoconf/automake setup you should by no means build in the default configuration. This will corrupt some internal directory settings, thus making `configure` complain when you try to use it in the optimized, or debug build configuration afterwards.

(This applies to these multiselection capabilities only. If the application type you selected provides a default build configuration only, you should of course use this one.)

## Behind the Scenes

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

If your project was set up for local &CVS; you will have got two series of messages of which the first set most probably was gone before you could thoroughly read, as &CVS; used the Messages window for its own purposes. So we caught both series in separate runs—set up the application twice, one time without &CVS;, then removed the directory and started over, this time setting the application up with &CVS;.

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.

We will have look at the Messages outputs of both steps:

- Setting up the application as well as

- Setting up &CVS;.

### Setting Up the Application

If you set up MyApp 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):

    * perl /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'
    * Making destination directory
    * Installing file templates
    * Installing license file
    * Installing admin directory
    * Installing &GNU; coding standard files
    * Installing Docbook template
    * Installing project file
    * Installing application framework
    * Installing application sources
    * Finished
    * *** Success ***

### A &perl; Script Called

As you see from the first line, the &appwizard; did construct a &perl; program call from the settings you made in the Create New Project dialog. The called `script` resides in a directory which was determined from the application type template you selected in the upper part of the Create New Project dialog General page.

In our case this `script` is located in the `/opt/kde3/share/apps/kdevappwizard/template-kapp/` directory. Just replace `/opt/kde3/` by the &kde; directory on your system.

This &perl; `script` is called with a series of parameters, all marked by `--` prefixes, wherein the &appwizard; put information from the other selections you made in the Create New Project dialog.

The exact series of initialization steps depends on which &perl; `script` was called. If you want to check, just look into the `script` file the `perl` command on the first Messages window line did call.

The setup scripts make use of a set of &perl; subroutines collected in the `kdevelop.pm` file which you may find in the `share/apps/kdevwizard/template-common/` subdirectory of your &kde; installation.

### The Application Base Directory

When the &perl; script is run, you get a series of messages of what is about to be done in the next installation step. At first a `destination directory` will be set up. This is the base directory of your application, just what you got displayed in the Final location line on the Create New Project dialog General page. The script uses the value of the `--dest` parameter in the &perl; command above.

### The File Templates

In the next step the file templates you set up in the Create New Project dialog will be copied to the `templates` subdirectory of this destination directory. As you can see from the `--filetemplates` parameter, the templates are submitted in pairs—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.

In our example two such template files were installed, namely `templates/h` for C++ header and `templates/cpp` for C++ source files.

### The License File

On the General page of the Create New Project 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.

The `--licensefile` parameter tells the &perl; `script` which license text file to copy. In our example the `/home/devel/projects/myapp/COPYING` file will have been installed in this step.

### The Administration Directory

&kdevelop; needs a bunch of files to administrate the project. These are put in the `admin` subdirectory of your application base directory.

&appwizard; creates the `admin` subdirectory in this step and extracts the standard set of files it needs from the `share/apps/kdevappwizard/template-common/admin.tar.gz` tarball in your &kde; directory.

&kdevelop; always uses the same set of standard files for its administration purposes. Hence no parameter is needed in the &perl; `script` call to set up the `admin` subdirectory.

### The &GNU; Coding Standard Files

There are several standard files to be distributed with every application which conforms to the &GNU; coding standard. The &perl; `script` extracts these files from the `share/apps/kdevappwizard/template-common/gnu.tar.gz` tarball of your &kde; installation directory and customizes them according to the information you provided in the Create New Page dialog.

After this step you will find the following files in your application base directory:

- `AUTHORS`, initially containing information from the `--author` and `--email` parameters.

- `COPYING`, this is the general &GNU; license, which all &GNU; conforming applications must contain—even if you decided to put your application under another license.

- `ChangeLog`, initially empty—you should protocol all major changes here.

- `INSTALL` contains generic installation instructions—modify this if special precautions and/or procedures are needed to install your application.

- `README`, initially empty—put any information here the user should know before installing your application.

- `TODO`, initially empty—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 all the well really helpful once you have put your application in public domain.

### The Initial Application Documentation

Every project you set up will contain an initial DocBook template from where you can start to write your application documentation. The &perl; `script` will in this step have set up `doc` and `doc/en` subdirectories of the application base directory with an initial `doc/en/index.docbook` template and some &automake; `Makefile.am` files from which &kdevelop; can later build help system files.

### The Project File

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; `script` the &appwizard; called up for your new application if you want to lookup details. We will continue to follow the example steps listed above.

In the first step of these the &kdevelop; project management file is copied out of the template directory, where the &perl; `script` resides. In our case the `share/apps/kdevappwizard/template-kapp/app.kdevelop` file was copied into the application base directory and then customized according to the selections made in the Create New Project dialog.

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

### The Application Framework

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 application framework will be set up in this step. Its structure basically dependends on the type of application you selected in the Create New Project dialog, but parts of it are common enough to be found in other projects, too.

In our case the following directory structure has been created in the `/home/devel/projects/myapp/` application base directory:

- The `src` subdirectory is meant to hold the source files of your application.

- The `debug` subdirectory will hold the compiled output of the debug build configuration. (See the Build configurations chapter to learn more about that.) As the name says, you should use this directory for debug purposes.

- The `optimized` subdirectory will hold the compiled output of the optimized build configuration. You should test an optimized version of your application from within here.

- The `po` subdirectory is meant for translation purposes. It will hold so-called Portable Object files (`.po` files) and templates (`.pot` files) which will be processed by a translation program as ⪚ KBabel.

All these directories will not kept empty but filled with a series of `Makefile` 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 `src` subdirectory, if applicable. In our case you will find two of them: `src/hi16-app-myapp.png` and `src/hi32-app-myapp.png` which both hold standard &kde; application icons.

### Application Sources Installed

This framework finally will be used to put the initial source files of your new project in the `src` directory. The actual files highly depend on the application type you selected in the Create New Project dialog. You will soon see yourself as this is the stuff you will actually have to work on.

### Setting Up &CVS;

Now let us have a look at what the Messages window will contain when the &appwizard; continues to build our example project. If no error occurred during the first pass, the Messages contents will revert to create the local &cvs; repository.

As before we reformatted the output lines a bit for readability. And we removed some superfluous lines (where the . . . dots are).

    * cd '/home/devel/projects/myapp' \
      && cvs -d '/home/devel/cvsroot' \
             import -m 'new project' \
                    'MyApp' \
                    'vendor' \
                    'start' \
      && 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 ***

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.

### Building the &cvs; Repository

In the second command line part the &CVS; application will be called to import 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.

- `-d '/home/devel/cvsroot'`—the `-d` option tells &CVS; which root directory is to be used. In our case this is the local &cvs; root located in `/home/devel/cvsroot`.

- `import`—tells the &CVS; application which operation to perform in this root. We want to import files into the &cvs; database. To accomplish this, the `import` command needs some arguments of its own:

  - `-m 'new project'`—the `-m` option provides import some message text 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 `new project` denotes the storage of our first files in the database.

  - `'MyApp'`—the second argument tells &CVS; which repository to use. If it does not exist, it will be created prior to the file import actions. In this case the `MyApp` repository will be created.

  - `'vendor'`—this following argument is a tag, a symbolic name which marks a series of files in the directory. There are several different meanings such a tag can have (see Using CVS 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 `vendor` is as good a name as any other.

  - `'start'`—is another tag. It marks the release, in easy words a series of subsequently saved files which belong together. We used `start` here, a meaningful description of the use of this initial series.

### The Imported Files

The &CVS; application will create the repository and then start to import all files from our `/home/devel/projects/myapp` directory. It subsequently reports any file which is loaded—this is the contents of the whole bunch of `N` lines following in the Messages window. The `N` denotes that this file was newly imported into the repository.

Depending on the type of the new application there will be quite a lot of those `N` lines. We truncated the output showing only the first and last three lines as an example.

### The &CVS; Success Message

&CVS; always reports when an operation was successfully performed. In our case the `No conflicts created by this import` message was printed, followed by the general `*** Success ***` line as no other operation had to be performed.

There could 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.

### Building the &cvs; Administration Entries

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.

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 check out the files again in an empty base directory in which case &CVS; automatically would write all administrative operation together with the checked out files.

In &kdevelop; fortunately there is an easier way. It provides the `buildcvs.sh` shell script in the `/opt/kde3/share/apps/kdevcvs/` directory (again replace `/opt/kde` with your &kde; installation directory), which the &appwizard; called after the &CVS; application had successfully finished its work.

The `buildcvs.sh` script mainly will put a `CVS` subdirectory into each directory of the application framework. Each of these `CVS` subdirectories will hold three file entries as follows:

- `Root` holds the name of the server on which the &cvs; root is located. In our case this is the local `/home/devel/cvsroot` 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 differences 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.

- `Repository` serves the same purpose. &CVS; keeps the name of the repository to use herein, `MyApp` in our case.

- `Entries` 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—this information is kept in the `Entries` file.

All these efforts are necessary because &CVS;'s work is directory-oriented. As &CVS; previously had stored all files in the `MyApp` framework, the `buildcvs.sh` script simply scans every directory and puts the names of all application files it finds into the according `CVS/Entries` file.

The script runs silently, just closing without any more line in the Messages window when the work was done.