Bernd
Pol

# 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 necessary management facilities such as the make system, access to all components and any additional tools needed to get the application up and running.

At organisere udviklingsarbejdet i projekter tillader dig nemt at skifte mellem eksisterende globale opgaver. Dette er rigtigt bekvemt hvis du &eg; arbejder med flere programmer samtidigt, hvilket ofte er tilfældet. Bed &kdevelop; om at åbne projektet du vil arbejde med, og du kan fortsætte i miljøet præcis hvor du tidligere forlod det.

## Nye projekter

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;

&kdevelop; sørger for en nem måde at starte et nyt programmeringsprojekt—programguiden. Du finder programguiden via menupunktet Projekt Nyt projekt.

Det er kun et fåtal af skridt der er nødvendige for at oprette et nyt programmeringsprojekt med programguiden:

1. Vælg programmeringssproget du vil bruge, og type af program som du vil oprette ud fra et sæt fordefinerede skabeloner.

2. Sørg for en del generel information såsom programnavn, mappe hvor programmet skal bygges, &etc;

3. Bestem om du vil bruge et versionskontrolsystem, som &eg; CVS, og sørg for nødvendig information som behøves.

4. Indstil nogle skabeloner for oprindelig deklarationsfil og kildekodefil (om nødvendigt).

5. Bed tilsidst programguiden om at oprette alle nye ting, mappestruktur, startskabeloner for deklarationsfiler og kildekodefiler, og håndteringsværktøj såsom &eg; et startskelet til at bygge programmet, &etc;

Voilà—det er alt. Programguiden har nu givet dig et første fungerende sæt programfiler, hvor du enkelt kan begynde at arbejde.

Lad os nu tage et mere detaljeret kig på alt dette...

### Indledende skridt

For at oprette et nyt projekt i &kdevelop;, vælges Nyt projekt i menuen Projekt. Du vil nu se guiden for at oprette nyt projekt, som vises nedenfor:

Indledende dialog for at oprette et nyt projekt

Som du kan se, er dialogen opdelt i en øvre og en nedre del. I den øverste del kan du bestemme dig for programmeringssprog og programtype. Den nederste del indeholder en del generel information.

#### Vælg programmeringssprog og programtype

Du udfører dine valg på venstresiden længst oppe i dialogen. Når den kommer frem er der en liste med mapper, hver med navnet på et programmeringssprog, som for eksempel:

- Ada

- C

- C++

- Database (SQL-projekter)

- Fortran

- Haskell

- Java

- Pascal

- Perl

- PHP

- Python

- Ruby

- Skal (scripter for Bash skallen)

For at være præcis, indeholder mapperne i virkeligheden ikke rigtige programmeringsværktøjer. De fører til fordefinerede skabeloner som du kan bruge som udgangspunkt for udvikling i et sprog. For at få en idé om hvad der tilbydes, åbn kun en mappe af gangen. Der er en serie af undermapper i visse, men kun en eller flere enkle indgange i andre. Undermapperne du ser organiserer de tilgængelige skabeloner ifølge visse opgaver, de enkle indgange navngiver skabeloner som du kan vælge.

Her kan vi ikke i detalje gå ind på hvilke opgaver hver skabelon sørger for, men det er nemt at finde ud af. Så snart du markerer en skabelonindgang, vises nogen information i feltet til højre. I det nederste felt ser du en kort beskrivelse om hvad skabelonen er beregnet til at gøre. I feltet ovenfor vises et billede, om tilgængelig, med hvordan programmet som skabelonen producerer ser ud hvis du kompilerer og kører den uden ændring. Oftest er det et skærmaftryk af hovedvinduet som programmet viser.

Vælg skabelonen som bedst passer målene for dit program som startpunkt. Indtast derefter information om almene egenskaber i de nederste felter, som vises i næste kapitel.

##### Vælg et projekthåndteringssystem

Hver skabelon er bundet til et bestemt Projekt håndteringssystem. For øjeblikket er der ikke nogen måde frit at vælge et sådant projekthåndteringssystem. Du skal finde en skabelon som passer til dine behov eller ændre dit projekt ifølge et efter oprettelsen.

#### Angiv almen information

Den nederste del af siden Generelt i dialogen Opret nyt projekt er et indrammet felt som hedder Egenskaber. Du skal sørge for en del almen information om projektet, så programguiden ved hvordan den oprindelige struktur skal bygges.

##### Programnavn

Dit program behøver naturligvis et navn. Indtast det i det øverste felt under Egenskaber, som hedder Programnavn. Vi bruger MyApp som eksempel.

Når du gør det, mærker du at programguiden nægter at acceptere specialtegn af nogen slags. De eneste tegn som accepteres er:

- små og store bogstaver

- tal

- tegnet understregning

En fremtrædende grund til begrænsningen er at programguiden vil bruge programnavnet som basis for visse klassenavn som den laver når den opbygger projektet fra begyndelsen. Altså skal projektets navn følge reglerne for programsproget som bruges.

##### Projektmappen

Den anden udmærkede grund for begrænsningen ser du på nederste linje i området Egenskaber. Den hedder Endeligt sted, og viser mappen hvor programguiden laver programmet.

Når du indskriver programmets navn mærker du at programguiden gentager det du indskriver længst nede på linjen Endeligt sted, men kun med små bogstaver.

Altså skal du vælge navnet på det nye program med forsigtighed. Hvis du ender med en mappe som allerede bruges, lader programguiden dig ikke fortsætte til næste skridt, ved at beholde knappen Næste > inaktiv (grå). Den advarer dig også ved at tilføje (fil eller mappe findes allerede) sidst på linjen Endeligt sted.

##### Startsøgesti

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.

Det gøres i den anden linjes indtastningsfelt under Egenskaber, som hedder Sted. Det du skriver her er startsøgestien for det nye programs udviklingsmappe. Programguiden tilføjer programnavnet sidst i søgestien når det nye projekt laves. Resultatet vises på linjen Endeligt sted for at bedre vise hvad der sker.

Programguiden kopierer en startværdi til feltet Sted fra begyndelsen. Det hentes fra det du har valgt under feltet Standardprojektmappe under de generelle indstillinger. I vores tilfælde har vi &kdevelop; sat op til at bruge `/home/devel/projects/` som oprindelig sti for nye projekter.

Ændr indholdet i feltet Sted, så udviklingsmappen for programmet som vises på linjen Endeligt sted er entydig.

Sørg for at søgestien du skriver ind i feltet Sted allerede findes. Ellers kommer du ikke til at kunne fortsætte til næste skridt. Programguiden advarer dig om søgestier som ikke findes, ved at tilføje (ugyldig) sidst på linjen Endeligt sted.

##### Personlig information

Felterne som følger er ikke så kritiske. Angiv blot dit navn (&ie; navnet på personen som er ansvarlig for programmet) i feltet Forfatter, og en gyldig e-mail-adresse i feltet E-mail, så brugere kan give dig tilbagemeldinger om programmet.

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. Programguiden sammenstiller informationen til en startprogramskabelon hvis det er muligt. For KDE C++ programmer, finder du den for eksempel i begyndelsen af kildekodefilen `main.cpp`.

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

##### Versions- og licensinformation

Indskriv til sidst startversion for det nye program i feltet Version, og vælg licensen du vil skal gælde for dit program i dropned-feltet Licens.

Hvis du vælger en programtype hvor programguiden sørger for fælles kildekodetekstskabeloner (&eg; C/C++), bør du kigge på licensinformationsteksten på tredje side i dialogen Opret nyt projekt (se kapitlet Angiv skabeloner for deklarationer og kildekode nedenfor).

Hvis du valgte Egen i dropned-feltet Licens skal du selv sørge for en licenstekst.

Both version and license information will be integrated into the starting templates in a format suiting the application type you selected.

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

### Angiv information om versionssystem

I det andet skridt, leder programguiden dig til siden Versionskontrolsystem, hvor du kan bestemme hvilket versionskontrolsystem du vil bruge.

Denne beskrivelse koncentreres kun om behovene for at oprette projekter. For mere information om CVS, se kapitlet Brug af CVS nedenfor.

#### Intet versionskontrolsystem ønskes

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.

#### Brug af CVS

Ellers skal du vælge versionskontrolsystemet som du vil bruge i dropned-feltet Versionskontrolsystem. For øjeblikket er kun &cvs; tilgængeligt. Hvis du vælger det, viser programguiden siden igen, men nu indeholder den et antal felter som du skal udfylde.

Indstil et nyt projekt for CVS

Et versionskontrolsystem som &CVS; (hvilket betyder Concurrent Versions System) opbevarer kopier af udvalgte projektfiler i en slags database. Hvis du bruger &CVS;, kan du blandt andet overføre (arkivere) filerne eller tage dem ned til din projektmappe (tjekke ud, eller opdatere). Det særlige ved dette er at filerne i versionsdatabasen opbevares på en struktureret måde, hvilket gør at du altid kan gå tilbage til et tidligere udviklingstrin hvis du behøver det. &CVS; tillader også flere udviklere nemt at samarbejde i et stort projekt (såsom &kdevelop;), uden at forstyrre hinandens arbejde.

#### CVS-rod

&cvs; skal håndtere versionsdatabasen som den har fra dine projektfiler. For at opnå dette har den en del speciel databaseinformation i en egen mappe, som kaldes &cvs;-roden. Det første skridt for at indstille &cvs; for det nye projekt, er altså at fortælle &kdevelop; hvor roden findes.

Lokal &cvs;-rod. Der er to grundlæggende muligheder. Enten vil du bruge en lokal CVS-database, eller du vil bruge en database som findes på en fjernserver. Hvis du udvikler på egen hånd, vil du måske bruge &cvs;-databasen som en slags sikkerhedskopieringssystem på din egen maskine. Oftest laves den i din hjemmemappe og gives navnet `cvsroot`. Det kan se ud på følgende måde:

``/home/udvikling/cvsroot`` (hvor `udvikling` simpelthen angiver brugeren udvikling, kun som et eksempel)

I virkeligheden er dette en forkortet form. Mere fuldstændigt skal den lokale &cvs;-rod adresseres med præfikset `:local:`. Den forkortede form tillades kun i tilfælde hvor filnavnet begynder med en skråstreg (`/`). Det fuldstændige navn på vor lokale &cvs;-rod i eksemplet ville se nøjagtigt ud som: `:local:/home/udvikling/cvsroot`.

Indtast navnet på &cvs;-rodmappen som systemet har indstillet for i feltet CVS-rod. I princippet kan du vælge hvilket som helst navn, og til og med bruge flere &cvs;-databaser, men det er tilrådeligt at beholde &cvs;-roden når den først er blevet sat op.

Initiér en ny &cvs;-rod. Hvis der ikke er en&cvs;-root, endnu kan &kdevelop; indstille &CVS;-systemet til at oprette en for dig i den givne mappe. Markér blot afkrydsningsfeltet Initiér rod under feltet CVS-rod.

Som sagt, beordrer &kdevelop; kun &CVS;-systemet til at initiere en ny &cvs;-rod. Den gør ingenting selv med mappen. Heldigvis er &cvs; smart nok til at kontrollere om &cvs;-rodmappen allerede findes. Derfor gør det ingen skade hvis du skulle have markeret Initiér rod for en eksisterende &cvs;-rodmappe.

Ekstern &cvs;-rod. Der er tilfælde hvor &cvs;-databasen skal være på en fjernserver, især når flere udviklere arbejder med samme projekt. Så skal du indtaste &cvs;-rodens URL for serveren i feltet CVS-rod. Hvis du for eksempel vil have adgang til &kde;'s &cvs;-server:

``:pserver:mit_brugernavn@cvs.kde.org:/home/kde`` (hvor `mit_brugernavn` angiver brugernavnet som er indstillet i din &kde; &cvs;-konto)

#### Servertyper for fjern-&cvs;

Det er i hovedsagen to fjernservertyper for &cvs; med udbredt brug: pserver som bruger en kodeordssikret ukrypteret protokol, og ext-serveren som bruger krypteret dataoverførsel via rsh eller ssh. De adskilles af URL-præfikset de bruger:

`:pserver:`

for den ukrypterede kodeordsbeskyttede server type, og

`:ext:`

for en servertype krypteret med rsh eller ssh. For eksempel

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

får adgang til &cvs;-roden for det meget brugte &cvs;-håndteringsværktøj Cervisia på serveren SourceForge.

Hvis du vil bruge en krypteret server via rsh eller ssh for adgang til &cvs;, skal du fortælle &kdevelop; hvilken krypteringsprotokol der skal bruges. Indskriv blot `rsh` eller `ssh` i feltet CVS_RSH på siden Versionskontrolsystem i Opret nyt projekt.

Der er et problem hvis du bruger en krypteret server for &cvs; inde i &kdevelop;. Se kapitlet Brug af CVS for detaljeret information.

#### &cvs;-arkivet

Hidtil har du fortalt &kdevelop; hvor &cvs;-roden er, som håndterer versionsdatabasen og hvordan du har adgang til den. Nu skal du fortælle &kdevelop; hvilket navn du ønsker at &CVS; skal bruge for at gemme dine projektfiler i databasen. Et sådant sted hvor projektfilerne opbevares i &cvs;, kaldes et arkiv.

I princippet kan du bruge et hvilket som helst navn for projektfilernes &cvs;-arkiv, så længe det opfylder specifikationerne for at navngive en fil. Oftest bruger de fleste udviklere alligevel selve programmets navn. &CVS; bygger en mappe med navnet under &cvs;-roden, derfor er det nemmere hvis du beholder programnavnet for det.

Indskriv blot arkivnavnet som du vil bruge i feltet CVS-arkiv på siden Versionskontrolsystem under Opret nyt projekt. I vort eksempel er det `Mit_nye_program`.

Sørg for ikke at bruge et arkiv som allerede findes!. &CVS;-systemet advarer ikke om duplikerede filer, men smider alting ind som ikke producerer en formel konflikt. Du vil lave rod i alting!

#### Tilbageværende felter

Der er ikke meget arbejde tilbage. Programguiden har allerede indstillet de øvrige felter for dig. Mere detaljeret:

Feltet Leverandør bruges kun af kompatibilitetsgrunde. Du kan beholde standardværdien leverandør som programguiden har skrevet her.

Feltet Meddelelse gør det muligt at indtaste en kommentar om indholdet i &cvs; fra begyndelsen. Brug hvilken som helst tekst du vil, eller behold blot standardværdien nyt projekt som programguiden har skrevet ind.

Udgavemærke indeholder navnet som bruges som mærke for den oprindelige tilstand af projektet. Et sådant mærke navngiver en vis tilstand i &CVS;-arkivet, som du senere kan bruge til at komme tilbage til den tilstand for udviklingen. (Se videre i kapitlet Brug af CVS.)

Programguiden har indskrevet standardmærket start her, som er et værdigt forslag. Behold det blot.

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 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/udvikling/test' && cvs -d '/home/udvikling/min_cvsrod' \
      import -m 'nyt projekt' '' 'leverandør' 'start' &&\
      sh /opt/kde3/share/apps/kdevcvs/buildcvs.sh . '' \
      '/home/udvikling/min_cvsrod'
    * cvs [import aborted]: /home/udvikling/min_cvsrod/CVSROOT: No such file or
      directory
    * *** Exited with status: 1 ***

Hvis dette sker, skal du enten indstille &cvs; manuelt (det skal være lykkedes for &kdevelop; at initiere dine projektfiler på dette tidspunkt) eller fjerne projektmappen og begynde forfra igen med Nyt projekt i menuen Projekt.

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

Hvis du vil rette en fejl på foregående side i Opret nyt projekt, så tryk blot på knappen < Tilbage. Programguiden husker dine indstillinger på nuværende side, så du kan nemt fortsætte når du kommer tilbage.

### Angiv skabeloner for deklarationer og kildekode

Næste skridt tager dig til en serie sider, hvor du kan indstille almindelig information som du vil inkludere i dine kildekode- og deklarationsfiler, hvis opgaven det drejer sig om tillader det.

Både deklarationsskabeloner og kildekodeskabeloner sørges der for for C og C++ programmer, hver og sin egen side. For andre sprog er der måske kun kildekodeskabeloner. I visse tilfælde ser du til og med at skabelonsiden er tom.

Hvis siden bruges, udfylder programguiden nogle almindelige kommentarer i sidehovedet, som kan se sådan her ud for et C++ baseret program:

    /***************************************************************************
     *   Copyright (C) 2003 by Dit navn                                       *
     *   dig@dig.dk                                                           *
     *                                                                         *
     *   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.             *
     ***************************************************************************/

Andre skabeloner sørger for lignende information på et format ifølge definitionen af programmeringssproget du vil bruge.

As you might have noticed, the applications manager did 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.

#### Hvordan skabelonerne kan redigeres

Skabelonerne som du indstiller i dialogen Opret nyt projekt behandles hver gang du beder &kdevelop; om at oprette en ny kildekodefil og/eller deklarationsfil. Informationen som du angiver her, inkluderes længst oppe i et dokumentationshovede, inden koden begynder.

Du er dog ikke begrænset til ren tekst. &kdevelop; kender til flere variabler, som lader dig inkludere rigtig information i filen. Programguiden bruger i virkeligheden blot nogle sådanne variabler for at inkludere information om Forfatter, E-mail og Licens i den oprindelige skabelonteksten.

##### Indsæt filinformation fra &doxygen;

Hvis du for eksempel ønsker at dokumentationen af programgrænsefladen som &doxygen; laver, skal vise yderligere information om filens indhold i listen med filnavne, kan du tilføje følgende linjer til kildekodefilens skabelon:

    /**
     * \file $MODULE$.cpp
     * \brief (skriv en kort beskrivelse her).
     **/

Så snart du laver en ny kildekodefil, erstatter &kdevelop; variablen `$MODULE$` med navnet på den nyoprettede fil. Hvis du for eksempel laver en ny C++ klasse som hedder `EnEnkelTest`, ser du følgende linjer i filen `enenkeltest.cpp`:

    /**
     * \file enenkeltest.cpp
     * \brief (skriv en kort beskrivelse her).
     **/

Du skal stadigvæk sørge for den korte beskrivelse efter nøgleordet \brief, men en del af jobbet er allerede gjort automatisk for dig.

##### Tekstfilen med licensen

Som et andet eksempel kunne du inkludere en eksplicit reference til licensteksten som du vil bruge i skabelonen. Brug variablen `$LICENSEFILE$` til dette, og tilføj for eksempel følgende linje:

    //   Se $LICENSEFILE$ for den fuldstændige licenstekst.

Programguiden erstatter `$LICENSEFILE$` med navnet på filen hvor den fuldstændige licenstekst findes, nemlig:

    //   Se COPYING for den fuldstændige licenstekst.

for GPL-licensen, eller

    //   Se LICENSE.BSD for den fuldstændige licenstekst.

hvis du bestemmer dig for at bruge BSD-licensen for programmet.

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

Skabelonerne som du definerer her får ingen virkning førend programguiden har lavet det nye projekt. Du finder informationen længst oppe i filerne som du selv laver under udviklingsprocessen. Når de oprindelige filer laves, bruger programguiden nogle fordefinerede standardskabeloner. Du skal indstille de oprindelige filer til dine behov manuelt.

### Byg de oprindelige projektfiler

Nu er næsten alt klart. På den sidste side i skabelonen, er knappen Næste > ændret så den nu lyder Afslut.

Tænk dig om to gange inden du klikker på den! Du har stadigvæk mulighed for at undersøge alting ved at bruge knappen < Tilbage gentagne gange. Eftersom programguiden husker al information du hidtil har indtastet, kan det være passende at tage sig tid til at kigge tilbage en gang til. Hvis du bruger lokal CVS, så glem ikke at kontrollere navnet på CVS-arkivet igen (der skal ikke allerede findes nogen undermappe med det navn i CVS-rodmappen—hvis der gør det, så forsøg med et andet arkivnavn).

Hvis du nogensinde ikke ønsker at det nye projekt skal bygges, så afbryd dialogen Opret nyt projekt med knappen Afbryd. Klik ellers på Afslut, og se i vinduet Meddelelser hvordan programguiden laver projektet.

Hvis du vil bruge et versionshåndteringssystem (&CVS;), sker det i virkeligheden i to kørsler. Programguiden bygger først projektmapperne og kalder siden &CVS;-programmet som starter vinduet Meddelelser med sit eget indhold. Hvis nogen fejl opstår i en af kørslerne, stopper processen og viser dig en tilsvarende fejlmeddelelse i vinduet.

I mange tilfælde når dit nye projekt er blevet sat op på denne måde, vil &kdevelop; automatisk indlæse kildefiler for en eller flere af de basalt vigtige moduler så du kan begynde at arbejde med det samme. (Hvilke kildemoduler vil blive vist—hvis der er nogen—det afhænger imidlertid af den skabelon der blev valgt oprindeligt i programguiden.)

Glem ikke at kontrollere hvad programguiden sørger for fra begyndelsen. Du vil måske for eksempel ændre den oprindelige information i filhovederne ifølge dine egne skabeloner. Oftest finder du dem i undermappen `templates` i projektmappen. Nogle enkle kopieringshandlinger er oftest utilstrækkeligt.

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

Inden du kompilerer det nye projekt første gang, kig så på Projekt Byggeindstilling. Hvis der er tre valgmuligheder som vises: default, optimized og debug, med debug markeret, så behold det endelig, eller brug optimized i stedet for.

På grund af visse begrænsninger i den nuværende indstilling af autoconf og automake, skal du under ingen omstændigheder bygge med indstillingen default. Det forstyrrer visse interne mappeindstillinger, og gør at `configure` klager når du senere forsøger at bruge den med byggeindstillingerne optimized eller debug.

(Dette gælder kun for disse flervalgsmuligheder. Hvis programtypen du valgte kun sørger for byggeindstillingen default, skal du naturligvis bruge den.)

## Behind the Scenes

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.

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

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 also 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 depends 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 &eg; KBabel.

All these directories will not be 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.