diff options
Diffstat (limited to 'doc/kdevelop/getting-started.docbook')
| -rw-r--r-- | doc/kdevelop/getting-started.docbook | 3221 |
1 files changed, 3221 insertions, 0 deletions
diff --git a/doc/kdevelop/getting-started.docbook b/doc/kdevelop/getting-started.docbook new file mode 100644 index 00000000..11a08253 --- /dev/null +++ b/doc/kdevelop/getting-started.docbook @@ -0,0 +1,3221 @@ + +<!-- +Please keep the formatting simple. +Do not indent XML constructs. +Keep lines at 80 characters length maximum. +--> + +<chapter id="getting-started"> + +<chapterinfo> +<authorgroup> +<author><firstname>Bernd</firstname><surname>Pol</surname></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> + +<title>Getting Started with &kdevelop; — a Guided Tour</title> + +<para>Now that you have got your new &kdevelop; &IDE;, how are you going to make +good use of it? As this is a complex application, the learning curve may be +somewhat steep, especially if you are not already used to this type of an +Integrated Development Environment.</para> + +<para>We will try to soften this learning curve a bit by stepping through the +makings of a simple KDE C++ application. Thereby we will have a (cursory) look +at:</para> + +<simplelist> +<member><link linkend="gettingstarted-overview">A first look — the user +interface elements of the &kdevelop; &IDE;.</link></member> +<member><link linkend="gettingstarted-configure">Doing some initial +configuration.</link></member> +<member><link linkend="gettingstarted-new">How to create a new project.</link> +</member> +<member><link linkend="gettingstarted-edit">Some tips about dealing with +documents.</link></member> +<member><link linkend="gettingstarted-compile">How to compile the application in +this project.</link></member> +<member><link linkend="gettingstarted-extend">How to add classes and other +detail to your project.</link></member> +<member><link linkend="gettingstarted-debug">What to do to debug the +application.</link></member> +<member><link linkend="gettingstarted-doc">Some basic tools to build program or +user documentation.</link></member> +<member><link linkend="gettingstarted-keys">Last but not least, keyboard +shortcuts</link></member> +</simplelist> + +<para>Before we start, one important concept should be made clear.</para> + +<formalpara> +<title>What to expect?</title> +<para>As said, &kdevelop; is an <emphasis>Integrated Development +Environment</emphasis>. That means in essence that &kdevelop; is no development +tool by itself but rather a graphical front end to easily access a wide range of +development tools, many of which actually would require complex keyboard +commands run from a text console.</para> +</formalpara> + +<para>While &kdevelop; eases many of those programming tasks, much of the +complexity from this bundle of tools still remains which means that in order to +fully understand the &kdevelop; &IDE; you will still need to comprehend these +tools actually running beneath the surface.</para> + +<para>Hence, we cannot teach you how to build software, but rather introduce you +to some of the ways &kdevelop; was designed to ease such a software building +process. If you want to learn more about what an Integrated Development +Environment is meant for, you might want to have a look at the <link +linkend="unixdev">Development on &UNIX;</link> historical overview and there +especially at the <link linkend="unixdev-ide">Integrating Concepts and +Tools</link> chapter.</para> + +<note> +<para>The following discussions apply to the default case, where &kdevelop; +starts up in the <guilabel>Simplified IDEAl Window Mode</guilabel>. If you +already did switch to another user interface mode some items may not be there as +described or will behave slightly different. If in doubt which user interface +mode your &kdevelop; currently uses, check with the +<menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure +KDevelop...</guimenuitem> <guimenuitem>User Interface</guimenuitem></menuchoice> +dialog.</para> +</note> + +<sect1 id="gettingstarted-overview"> +<title>A Very First Look at &kdevelop;</title> + +<para>This is all about what you will see when you first started &kdevelop;. +You will find preliminary information about:</para> + +<simplelist> +<member><link linkend="gettingstarted-overview-basic">What is there on the +surface?</link></member> +<member><link linkend="gettingstarted-overview-help">How to get some +help.</link></member> +<member><link linkend="gettingstarted-overview-menu">What is in the +menus?</link></member> +<member><link linkend="gettingstarted-overview-tools">What are those tool views +for?</link></member> +</simplelist> + +<sect2 id="gettingstarted-overview-basic"> +<title>On the Surface</title> + +<para>When you start &kdevelop; for the first time you will get a display +similar to this one:</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="empty-ide.png" format="PNG"/> +</imageobject> +<caption> +<para>The &kdevelop; initial layout</para> +<para>(Actually the initial &kdevelop; window will be larger, but the elements +you see are the same.)</para> +</caption> +</mediaobject> +</screenshot> + +<formalpara> +<title>Workspace Area and Tool View Tabs</title> +<para>In this initial case &kdevelop; uses the so-called <link +linkend="uimodes-survey">IDEAl user interface mode</link>. A workspace area of +maximum possible size is surrounded left, bottom, and right by a series of +buttons which act similar to tabs on a tabbed display. If you click on one of +those tabs, a so-called <emphasis>tool view window</emphasis> will open which +allows you to work on a specific task.</para> +</formalpara> + +<formalpara> +<title>Menu and Toolbars</title> +<para>On top there is the usual menubar, followed by several rows of toolbars, +some being initially empty. They will get populated once there is a project open +for actual work.</para> +</formalpara> + +<formalpara> +<title>Status Bar</title> +<para>Finally, there is a status bar on the bottom of the window where short +informations on several tasks will be shown.</para> +</formalpara> +</sect2> + +<sect2 id="gettingstarted-overview-help"> +<title>How to Get Some Help</title> + +<para>Besides the <guimenu>Help</guimenu> menu which offers answers to specific +questions, the status bar and two kinds of tool tips provide some quick +information.</para> + +<formalpara> +<title>What Does This Menu Entry Do?</title> +<para>When you place the mouse cursor on a menu entry, there will usually some +short information be displayed in the status bar. While in most cases this +repeats just the name of the selection, in some cases it will provide additional +information about the purpose of the menu command.</para> +</formalpara> + +<formalpara> +<title>What Is the Name of This Item?</title> +<para>On many items a short function name tool tip will pop up when you place +the cursor on it for a few seconds. This is useful for quick orientation on +toolbar or tool view tabs in IDEAl mode when the &IDE; has been set up to +display icons only on these buttons.</para> +</formalpara> + +<formalpara> +<title>What Does This Item Do?</title> +<para>More information is available through expanded tool tip help for many +items on the &IDE;. Select <menuchoice><guimenu>Help</guimenu> +<guimenuitem>What's This?</guimenuitem></menuchoice> or press +<keycombo><keycap>&Shift;</keycap><keycap>F1</keycap></keycombo>, then with the +question mark cursor select the item you want to know more of. You can as well +open any menu this way and click on a specific menu entry (active as well as +greyed disabled ones) to see if more information is available.</para> +</formalpara> +</sect2> + +<sect2 id="gettingstarted-overview-menu"> +<title>What is in the menus?</title> + +<para>There are ten menus selectable on the menubar. Most of them get fully +populated once a project is open for actual work while others require at least +one document be open in an editor window. In short, they will allow the +following action types.</para> + +<note> +<para>This is only a preliminary overview. For a detailed menu description see +the <link linkend="commands">Command Reference</link>.</para> +</note> + +<variablelist> +<varlistentry> +<term><guimenu>File</guimenu></term> +<listitem> +<formalpara> +<title>Usual Actions</title> +<para>This is pretty standard. It allows to create, open, save, print, and close +document files as well as quitting the &kdevelop; application as usual.</para> +</formalpara> + +<formalpara> +<title>Revert All</title> +<para>This allows to revert all recent, yet unsaved changes by reloading the +file from the disk. This works on any file you edit, not only on those which are +part of a project.</para> +</formalpara> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Edit</guimenu></term> +<listitem> +<para>This menu is useful only if a document is opened.</para> + +<formalpara> +<title>Usual Actions</title> +<para>It provides the usual undo/redo and cut/copy/paste actions. +Furthermore it allows to select text blocks in various ways.</para> +</formalpara> + +<formalpara> +<title>Search and Replace</title> +<para>There are two very powerful search facility available, +<menuchoice><guimenu>Edit</guimenu> <guimenuitem>Find in +Files...</guimenuitem></menuchoice>, and <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Find-Select-Replace...</guimenuitem></menuchoice>. These allow, in +addition to the usual search and replace actions limited to the the current +document, to conduct global search or search-and-replace actions in one single +turn.</para> +</formalpara> + +<formalpara> +<title>Advanced Text Edit</title> +<para>There are provisions to reformat the current document and to automatically +complete partially typed texts in various ways.</para> +</formalpara> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu></term> +<listitem> +<para>Like the <guimenu>Edit</guimenu> menu, this menu is useful only if there +is an open project. I this case there will be the following actions available +(amongst others):</para> + +<formalpara> +<title>Navigation History</title> +<para>Switch back and forth through the documents &etc; you visited.</para> +</formalpara> + +<formalpara> +<title>Error Tracking</title> +<para>Navigate to the source lines of the errors encountered in the most recent +compilation/build process.</para> +</formalpara> + +<formalpara> +<title>Editor Related Actions</title> +<para>Some entries in the <guimenu>View</guimenu> menu control the look and view +of the editor you use. In case of the &kate; Part (Embedded Advanced Text +Editor) there will be the following controls available:</para> +</formalpara> + +<itemizedlist> +<listitem> +<para>Control the word wrap behavior in the document window.</para> +</listitem> +<listitem> +<para>Show or hide several border displays in the document windows: line +numbers, icons, and, additionally, bookmark marks in the scroll bar.</para> +</listitem> +<listitem> +<para>Control the display of folded (temporarily hidden) sections in a source +text.</para> +</listitem> +</itemizedlist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Project</guimenu></term> +<listitem> +<para>All work of &kdevelop; is based on <emphasis>projects</emphasis> which +basically collect source files, build management files, and other information in +one project directory. In this menu you control which project to use, which +properties it has, and some other managing actions. +In particular:</para> + +<formalpara> +<title>Open a Project</title> +<para>Allows to create new projects, open existing ones, and import projects +from other environments.</para> +</formalpara> + +<formalpara> +<title>Project Options</title> +<para>Allows to define a whole bunch of different project properties.</para> +</formalpara> + +<formalpara> +<title>Classes Management</title> +<para>Add new classes to the project and traverse the inheritance tree of a +class.</para> +</formalpara> + +<formalpara> +<title>Distribute Project</title> +<para>Helps to build distribution packages of the project.</para> +</formalpara> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Build</guimenu></term> +<listitem> +<para>This menu is all about compiling and documenting the project. Thus it is +of use only when a project is actually open. In this case it provides the +following actions:</para> + +<formalpara> +<title>Compile, Link, Execute</title> +<para>Allows to compile and link the whole project or parts of it as well as run +the application from within the &IDE;.</para> +</formalpara> + +<formalpara> +<title>Prepare Build Operations</title> +<para>This actually depends on the make system you use for this project. In the +case of automake projects it allows to run <filename>Makefile.cvs</filename> and +<filename>configure</filename> on their own. There are also provisions to remove +translated files from the project in various stages of intensity.</para> +</formalpara> + +<formalpara> +<title>Install the Application</title> +<para>Allows to install the application both in local directories as well as in +system directories only accessible to the root user.</para> +</formalpara> + +<formalpara> +<title>API Documentation</title> +<para>Build or remove a doxygen-based API documentation of the project as +defined in the project options.</para> +</formalpara> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Debug</guimenu></term> +<listitem> +<para>Although this menu will be filled once a project is active, it of course +is useful only if the actual project has been previously compiled with debugging +information (this is basically set up in <menuchoice><guimenu>Project</guimenu> +<guimenuitem>Project Options..</guimenuitem></menuchoice>). There are the +following actions available in this case:</para> + +<formalpara> +<title>Usual Debugger Actions</title> +<para>The first section in the <guimenu>Debug</guimenu> provides a graphical +interface to the GDB &GNU; symbolic debugger. It allows to start and stop your +application in the debugger and step through it in various ways.</para> +</formalpara> + +<formalpara> +<title>Breakpoints</title> +<para>&kdevelop; provides several means to set breakpoints in your application +sources. One is through the use of the <guimenuitem>Toggle +Breakpoint</guimenuitem> menu entry.</para> +</formalpara> + +<formalpara> +<title>Advanced Debugging</title> +<para>Other <guimenu>Debug</guimenu> menu entries allow more sophisticated +program analysis. Use +<keycombo><keycap>&Shift;</keycap><keycap>F1</keycap></keycombo> to get more +information about their purpose.</para> +</formalpara> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Scripts</guimenu></term> +<listitem> +<para>You can call various scripts from this menu to more easily accomplish +tedious actions on the text in the currently selected editor window. The +available actions depend on the selected script, however. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Window</guimenu></term> +<listitem> +<para>This is fairly standard. You may select any open document window as well +as close one or more documents windows in here. You may even select a set of +document windows to be closed in one single turn.</para> + +<para>Depending on the editor plugin you use may there be other menu items as +well. So will the default Kate editor plugin additionally allow to split the +editor window horizontally as well as vertically.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Tools</guimenu></term> +<listitem> +<para>&kdevelop; is highly customizable. +You may select a favorite editor for your documents as well as provide external +and plugged-in tools to extend the basic &IDE; capabilities. The +<guimenu>Tools</guimenu> menu reflects most of this setup.</para> + +<formalpara> +<title>Advanced Editing</title> +<para>The upper set of <guimenu>Tools</guimenu> menu entries will be provided by +the editor plugin which is in use. You may select your favorite editor via +<menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure +KDevelop...</guimenuitem> <guilabel>Editor</guilabel></menuchoice>. Once an +editable document file is selected, the upper part of the +<guimenu>Tools</guimenu> menu will provide advanced editing commands specific to +the editor part in use.</para> +</formalpara> + +<formalpara> +<title>Web Side Handling</title> +<para>In case the active document window contains a HTML page (⪚ displayed +from a <guilabel>Documentation</guilabel> selection), the +<guimenu>Tools</guimenu> will show additional menu entries which provide various +means to handle Web pages.</para> +</formalpara> + +<formalpara> +<title>Other Tools</title> +<para>Usually there will be a bunch of other entries according to the currently +available tools. Use <keycombo><keycap>&Shift;</keycap> +<keycap>F1</keycap></keycombo> to get more information about their +purposes.</para> +</formalpara> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Settings</guimenu></term> +<listitem> +<para>This menu allows you to show and hide menubar, toolbars and statusbar. +Also, you can configure shortcuts, toolbars, notifications, the editor and +&kdevelop;'s general behavior.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Help</guimenu></term> +<listitem> +<para>Here you can open this KDevelop manual, look up terms in various +documentation files, open man pages (the traditional UNIX manual format) and +info pages (the GNU manual format). Furthermore you can report bugs here or get +some info about your current KDevelop version and its authors.</para> +</listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="gettingstarted-overview-tools"> +<title>What are those tool views for?</title> + +<para>In the IDEAl user interface mode the workspace will be surrounded by three +areas of buttons, so-called <emphasis>tool view tabs</emphasis>. They provide +access to <emphasis>tool view windows</emphasis> which accomplish main tasks +during software development. Each of these three tool view areas serves a +different main purpose.</para> + +<itemizedlist> +<listitem> +<formalpara> +<title>Left Side</title> +<para>Provides access to navigation and selection tools</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Bottom</title> +<para>These views display messages produced by various tools.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Right Side</title> +<para>Provides access to documentation and source management tools.</para> +</formalpara> +</listitem> +</itemizedlist> + +<para>The number of tool view tabs shown will change once a project is open for +actual work. More tools to work on that project will be available then. The +actual number of tool views depends on the <link linkend="plugin-tools">Plugin +Tools</link> being currently available to &kdevelop;. You will find more on this +topic in the <link linkend="setup">Configuring KDevelop</link> chapter.</para> + +<para>Currently, with no project open and the default number of plugin tools +loaded, you will find the following tool views. Clicking on a tab will open +respectively close its tool view window.</para> + +<variablelist> +<varlistentry> +<term>Navigation and Selection</term> +<listitem> +<formalpara> +<title>File Selector</title> +<para>Provides a panel to navigate the directory tree and select files for work +just like you do in the &konqueror;. Clicking a file will open it in an +appropriate editor window in the workspace area. A right click in the file +selector area will pop up a navigation and file manipulation menu.</para> +</formalpara> + +<formalpara> +<title>File List</title> +<para>Lists the currently open files. Clicking on a file will usually select its +editor window in the workspace area. Use this to quickly navigate in a large +number of open files. Furthermore this view provides a means to organize the +open files into different <emphasis>sessions</emphasis>. This is particularly +useful in very large and complex projects to help the developer concentrate on +different tasks. Right clicking a file will pop up a file manipulation +menu.</para> +</formalpara> +</listitem> +</varlistentry> + +<varlistentry> +<term>Messages Displays</term> +<listitem> +<formalpara> +<title>Application</title> +<para>Displays the output from an application started from within +&kdevelop;.</para> +</formalpara> + +<formalpara> +<title>Diff</title> +<para>Used to display patch file contents. +Displays the output from the difference viewer tool started from the +<menuchoice><guimenu>Tools</guimenu> <guimenuitem>Difference +Viewer...</guimenuitem></menuchoice> menu.</para> +</formalpara> + +<formalpara> +<title>Messages</title> +<para>Displays messages produced by the build tools called from within +&kdevelop;, usually from the <guimenu>Build</guimenu> menu.</para> +</formalpara> + +<formalpara> +<title>Find in Files</title> +<para>Displays the list of items found by the global search operation started +from the <menuchoice><guimenu>Edit</guimenu> <guimenuitem>Find in +Files...</guimenuitem></menuchoice> menu. Clicking on a line here will +automatically open that file at the specified position in an editor +window.</para> +</formalpara> + +<formalpara> +<title>Replace</title> +<para>Lists the results of the global search-and-replace operation issued from +the <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Find-Select-Replace...</guimenuitem></menuchoice> menu. In this +view you can decide on every found item whether you really want it be replaced +or not.</para> +</formalpara> +<note> +<para>This global search-and-replace facility is actually available only after a +project has been loaded into &kdevelop;. Otherwise the global replace tool in +the <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Find-Select-Replace...</guimenuitem> </menuchoice> menu will in +fact be be disabled.</para> +</note> + +<formalpara> +<title>Konsole</title> +<para>Opens a &kde; <application>Konsole</application> like terminal emulator +window where you can use keyboard commands in a traditional &UNIX; command line +interface.</para> +</formalpara> +</listitem> +</varlistentry> + +<varlistentry> +<term>Documentation and Source Manipulation</term> +<listitem> +<formalpara> +<title>Documentation</title> +<para>&kdevelop; provides access to a whole bunch of documentation through this +tool. You may here access document files, usually online from remote locations, +in a structured way. And there are several ways available to directly access +valuable information from &kde; or &Qt; manuals.</para> +</formalpara> + +<para>See the <link linkend="documentation">Documentation</link> and <link +linkend="setup-docu">Configuring the Documentation</link> chapters for more +details.</para> + +<formalpara> +<title>Code Snippets</title> +<para>This tool allows you to permanently store selected texts for later use in +other editing cycles. It is a very flexible tool, as any text snipped stored +here may contain a set of variables which will get their actual values at the +time when you insert such a snippet in some other text.</para> +</formalpara> +<para>More information on this is available in the <link +linkend="editing-snippets">Code Snippets</link> and <link +linkend="setup-snippets">Setting Up the Code Snippets Tool</link> +chapters.</para> +</listitem> +</varlistentry> +</variablelist> +</sect2> +</sect1> + +<sect1 id="gettingstarted-configure"> +<title>A Bit of Configuration</title> + +<para>Before we actually start a first example project, we should tailor the +&kdevelop; behavior to our needs. Although most of the default settings will be +appropriate for now, there are a few places which better should be +adjusted.</para> + +<note> +<para>If you want to know more about &kdevelop; configuration, have a look at +the <link linkend="setup">Configuring KDevelop</link> chapter.</para> +</note> + +<sect2 id="gettingstarted-configure-general"> +<title>Some General Settings</title> + +<para>To configure &kdevelop;, click the +<menuchoice><guimenu>Settings</guimenu></menuchoice> menu and select +<menuchoice><guimenuitem>Configure KDevelop...</guimenuitem></menuchoice>. The +<guilabel>Configure KDevelop</guilabel> dialog will pop up, showing the +following <guilabel>General</guilabel> settings page to the right.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="configure-general.png" format="PNG"/> +</imageobject> +<caption> +<para>The &kdevelop; general configuration dialog</para> +</caption> +</mediaobject> +</screenshot> + +<para>Most of the defaults will be o.k. +But you will probably want to change two of those settings.</para> + +<formalpara> +<title>Default projects directory</title> +<para>At first start of &kdevelop; this will most likely be preset to your home +directory. Most people however prefer a dedicated projects directory for +software development. Change the text box to your preferred parent development +directory. You may select it from the directory tree if you press the +<guilabel>Open file dialog</guilabel> button labeled with a folder icon to the +right of it.</para> +</formalpara> + +<para>In our examples we will assume a (somewhat artificial) user called +<filename class="directory">devel</filename>. +Thus always replace this <quote>devel</quote> by your user name. Our devel user +will utilize the <filename class="directory">/home/devel/projects</filename> +parent directory for actual development. Again, replace <filename +class="directory">projects</filename> with your development directory name. +</para> + +<para>&kdevelop; will by default set up an own subdirectory below this parent +for every new project you create. So will ⪚ all files of a project named +<quote>Hello</quote> in our case be located in the <filename +class="directory">/home/devel/projects/hello</filename> directory.</para> + +<para>You may of course temporarily override these directory settings if you +need to. See the <link linkend="applicationwizard">&appwizard;</link> chapter +for more info on this.</para> + +<formalpara> +<title>Compiler output</title> +<para>Whenever &kdevelop; compiles some source, it will display the messages of +the <application>make</application>, etc. build tools in the +<guilabel>Messages</guilabel> window in the lower part of the workspace area. +Usually these messages will be overwhelmingly wordy. To keep a better overview +of what happens, &kdevelop; has some means of shortening those messages built +in.</para> +</formalpara> + +<para>Depending on the &kdevelop; version you use, the <guilabel>Compiler +output</guilabel> selection may be preset to <quote>Long</quote>, which will +cause all message contents be fully shown. You may probably want to change this +to the far more convenient <quote>Very Short</quote> setting. Just select this +from the drop down box.</para> + +<caution> +<para>Be aware that only <emphasis>most basic</emphasis> information will be +shown in the <guilabel>Messages</guilabel> window this way. In case of errors +during ⪚ a build run you will most likely want to see more, if not all, of +the message texts. They are not lost, however. Just right click into the +<guilabel>Messages</guilabel> window and select ⪚ <quote>Full Compiler +Output</quote> from the popup menu.</para> +</caution> +</sect2> + +<sect2 id="gettingstarted-configure-search"> +<title>Initializing Documentation Search Indexes</title> + +<para>There is another, not so obvious, item which preferably should be +initialized before you start actual development work. This is because you will +want to perform documentation search regularly during development. &kdevelop; +requires some search indexes be created before such search operations can be +performed. So let's initialize them before we attempt our first steps +toward actual &kdevelop; work.</para> + +<para>Open the <guilabel>Documentation</guilabel> tool view at the right side of +the &kdevelop; main window. There open the <guilabel>Search</guilabel> dialog +page.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="documents-search.png" format="PNG"/> +</imageobject> +<caption><para>Where to generate the search indexes.</para></caption> +</mediaobject> +</screenshot> + +<para>Now press the <guibutton>Update Config</guibutton> button to make sure the +basic search tools are properly set up. A dialog should pop up, telling +<quote>Configuration file updated</quote>. Click <guibutton>OK</guibutton> to +make it disappear.</para> + +<para>This done, &kdevelop; will be ready to parse the documentation it knows of +and build some useful search indexes from it. Press the <guibutton>Update +Index</guibutton> button to the right. Now the <guilabel>Generating Search +Index</guilabel> dialog will pop up showing the progress of the index build +operations.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="configure-docu-indexgen.png" format="PNG"/> +</imageobject> +<caption><para>&kdevelop; is generating documentation search +indexes.</para></caption> +</mediaobject> +</screenshot> + +<para>This will take some time depending on the size of documentation and the +speed of your machine. But finally the <guibutton>Cancel</guibutton> will make +place to <guibutton>OK</guibutton>. Just press this button to proceed.</para> + +<note> +<itemizedlist> +<listitem> +<para>This usually should work out of the box. In some cases the +<application>htdig</application> application &kdevelop; uses to perform its full +text searches might not be properly set up. Refer to the <link +linkend="setup-docu-textsearch">Setting Up Text Search Indexes</link> chapter +for more help in this case.</para> +</listitem> +<listitem> +<para>To be able to look up &kde; and &Qt; specific API documentation, it is +mandatory that the <emphasis>KDELibs Apidocs</emphasis> were present when +&kdevelop; was installed. If you experience problems building the indexes or +perform the <link linkend="gettingstarted-edit-defs">identifier lookup +examples</link> later in this chapter, make sure that this documentation exists +and is accessible to &kdevelop;. See <link linkend="kdevelop-install">Installing +KDevelop</link> fore more detail.</para> +</listitem> +</itemizedlist> +</note> +</sect2> +</sect1> + + +<sect1 id="gettingstarted-new"> +<title>Starting a New Project</title> + +<para>Almost any application will consist of dozens, hundreds, even thousands of +files which need kept structured and maintainable. To accomplish this, +&kdevelop; organizes software development tasks in +<emphasis>projects</emphasis>. Thus the first practical step to develop software +in &kdevelop; usually is to create a new project.</para> + +<para>Fortunately this is fairly easily accomplished. &kdevelop; provides the +so-called &appwizard; tool for this. (See the <link +linkend="applicationwizard">Getting Started — the &appwizard;</link> +chapter for more.)</para> + +<para>We will now start a simple &kde; application project to illustrate how +easily this is accomplished and which files and tools &kdevelop; will have +provided. Thereby we will have a short look at:</para> + +<simplelist> +<member><link linkend="gettingstarted-new-setup">How to create a new project +with the help of the &appwizard;.</link></member> +<member><link linkend="gettingstarted-new-files">Which files the &appwizard; +initially did set up.</link></member> +<member><link linkend="gettingstarted-new-toolviews">What about the additional +tool view shown with the project?</link></member> +</simplelist> + +<sect2 id="gettingstarted-new-setup"> +<title>How to Create a New Project</title> + +<para>Let us create a rather simple <quote>Hello World</quote> &kde; project. +Just follow these steps.</para> + +<procedure> +<step> +<para>To start the &appwizard; click the <menuchoice><guimenu>Project</guimenu> +<guimenuitem>New Project...</guimenuitem></menuchoice> menu.</para> +</step> + +<step> +<para>The <guilabel>Create New Project</guilabel> dialog will pop up. In the +upper left <guilabel>All Projects</guilabel> window there will be a number of +programming languages listed.</para> + +<substeps> +<step> +<para>We want to build a &kde; C++ application as usual, thus click on the +<guilabel>+</guilabel> label left of the <guilabel>C++</guilabel> label to open +this branch.</para> +</step> + +<step> +<para>A series of possible application targets will be displayed. We will build +a &kde; application, thus open the next sub-branch via the +<guilabel>+</guilabel> label next to <guilabel>KDE</guilabel></para> +</step> + +<step> +<para>Now you will be offered a series of possible <emphasis>project +templates</emphasis>. Navigate down to the end of this branch and click +<guilabel>Simple KDE Application</guilabel>.</para> + +<para>A preview and short description of the application this project template +will produce pops up in the two windows to the right.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-new-project.png" format="PNG"/> +</imageobject> +<caption> +<para>Selecting a <quote>Hello World</quote> project template</para> +</caption> +</mediaobject></screenshot> +</step> + +<step> +<para>Our application will need a name. Find the <guilabel>Properties</guilabel> +area on the dialog bottom and enter a suitable name into the +<guilabel>Application name</guilabel> input field.</para> + +<para>We use <quote>Hello</quote> in our example, but you can use whatever you +like, provided the name consists of letters, number digits, and underlines only. +You will find that the &appwizard; rejects any other character.</para> +</step> + +<step> +<para>Make sure the <guilabel>Location</guilabel> text box below the input field +shows the name of your top project directory as set up in the <link +linkend="gettingstarted-configure">A Bit of Configuration</link> chapter above. +If it does not do so, enter a suitable directory name or select one from the +directory list provided by the folder labeled button to the right.</para> + +<para>If all went well, the <guilabel>Final location</guilabel> line at the +bottom will show the directory path your new project will use. In case there was +an <quote>(invalid)</quote> suffix appended, try another name for your project +and/or make sure the top project directory in the <guilabel>Location</guilabel> +text box really exists and is writable.</para> +</step> + +<step> +<para>Once everything is right, the <guibutton>Next</guibutton> button in the +bottom row of the dialog will be enabled. Click it to proceed.</para> +</step> +</substeps> +</step> + +<step> +<para>This will lead you to the <guilabel>Project Options</guilabel> dialog +page. Make sure the <guilabel>Author</guilabel> and <guilabel>Email</guilabel> +text boxes are properly filled in. Usually they will default to your general +&kde; user settings as given in the <guilabel>Password & User +Account</guilabel> dialog of the &kde; Control Center. If not, change them to +some settings you prefer for your application.</para> + +<screenshot id="gettingstarted-new-setup-options"> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-hello-options.png" format="PNG"/> +</imageobject> +<caption> +<para>Provide your name and (optionally) email address.</para> +</caption> +</mediaobject> +</screenshot> + +<note> +<para>You must provide an <guilabel>Author</guilabel> name at least. This is +mandatory for the application files setup.</para> +</note> + +<para>If all is right, the <guibutton>Next</guibutton> button will be enabled. +Click it to further proceed.</para> +</step> + +<step> +<para>The following <guilabel>Version Control System</guilabel>, +<guilabel>Template for .h Files</guilabel>, and <guilabel>Template for .cpp +Files</guilabel> dialog pages are not of interest for now. Skip them by clicking +the <guibutton>Next</guibutton> buttons and, finally, the +<guibutton>Finish</guibutton> button.</para> +</step> +</procedure> + +<para>That was all! +The &appwizard; will take over and construct a series of initial files in the +<guilabel>Final location</guilabel> directory you provided in step 2c +above.</para> + +<para>Once this file creation phase is finished, &kdevelop; will open an editor +window for the <emphasis>application main window</emphasis> implementation file +(which is <filename>hello.cpp</filename> in our example), so you can readily +proceed.</para> +</sect2> + +<sect2 id="gettingstarted-new-files"> +<title>Initial Project Files</title> + +<para>Even if our sample Hello project is fairly simple, the &appwizard; did +create a whole bunch of source and project management files. You will most +easily list them if you open the <guilabel>File Tree</guilabel> tool view on the +bottom left. This will open a file list similar to the one below.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-hello-new.png" format="PNG"/> +</imageobject> +<caption> +<para>Initial files in our <quote>Hello World</quote> project</para> +</caption> +</mediaobject> +</screenshot> + +<para>To demonstrate the main bunch of files the &appwizard; produced, we did +open most of the directory branches in the left-hand <guilabel>File +Tree</guilabel> tool view window. Just click the branch names in the tree to see +for yourself.</para> + +<para>Additionally, just for demonstration, we did as well open most of the +branches the <guilabel>Automake Manager</guilabel> tool view window to the right +where some of the project sources are listed, too.</para> + +<sect3 id="gettingstarted-new-files-copyright"> +<title>Copyright Issues</title> + +<para>All &GNU; conformant applications must be copyrighted. There are two +levels which require copyright notices, <emphasis>individual source +files</emphasis> and <emphasis>run-time application level</emphasis>. The +&appwizard; did already put appropriate copyright and licensing information into +the project files.</para> + +<formalpara> +<title>Source File Level Copyrights</title> +<para>Do you remember the <link linkend="gettingstarted-new-setup-options"> +<guilabel>Project Options</guilabel></link> dialog page in the new project +setup? You had to provide your (the developer's) name and optionally an +email address there. Now refer to the top of the <guilabel>hello.cpp</guilabel> +editor window currently displayed in the workspace area. The &appwizard; did +enter these statements on top of the licensing header of every source file it +created.</para> +</formalpara> + +<programlisting> +/*************************************************************************** + * Copyright (C) 2006 by Joe User * + * joe@user.com * + * * + * This program is free software; you can redistribute it and/or modify * +</programlisting> + +<para>You will find exactly the same text headers in every source file you will +create inside &kdevelop; (provided you use the proper built in tools for file +creation). &kdevelop; remembers these settings in some template files you may +find in the <filename class="directory">templates</filename> directory.</para> + +<formalpara> +<title>Application Run-Time Copyrights</title> +<para>Once your &kde; application runs, the user may display some +<guilabel>About</guilabel> data, usually from the <guimenu>Help</guimenu> menu. +The &appwizard; did also take care of this. If you have a look at the +<filename>main.cpp</filename> file, you will find an entry similar to the one +below.</para> +</formalpara> + +<programlisting> +int main(int argc, char **argv) +{ + KAboutData about("hello", I18N_NOOP("Hello"), version, description, + KAboutData::License_GPL, "(C) 2006 Joe User", 0, 0, + "joe@user.com"); + about.addAuthor( "Joe User", 0, "joe@user.com" ); +</programlisting> + +<para>This will put the main developer's name (<quote>Joe User</quote> in +our case) and email address into the <guilabel>About</guilabel> copyright page +in the display and list this name and address on the +<guilabel>Authors</guilabel> page there as well.</para> + +<important> +<para>Whenever you make substantial changes to an existing project, be sure to +enter your name and email address to the copyright notices on every file you +changed and to the run-time copyright display as well. Don't be shy, you +help the open source society considerably if you do so.</para> +</important> +</sect3> + +<sect3 id="gettingstarted-new-files-source"> +<title>Initial Source Files</title> + +<para>The &appwizard; did put the source files into the <filename +class="directory">src</filename> sub-directory of the project's directory. +You will find the <filename>main.cpp</filename>, <filename>hello.h</filename>, +and <filename>hello.cpp</filename> files there as you may have possibly +expected.</para> + +<para>There are some additional files you usually will find in a typical &kde; +application, namely</para> + +<itemizedlist> +<listitem> +<para><filename>hello.desktop</filename> contains some meta data used by +&kdevelop; to maintain and start the application.</para> +</listitem> + +<listitem> +<para><filename>hi16-app-hello.png</filename>, and +<filename>hi32-app-hello.png</filename> contain some initial default icons, +&kdevelop; will use for application display.</para> +</listitem> + +<listitem> +<para>Finally, <filename>helloui.rc</filename> contains a description of the +application's user interface, currently the menus the application will +provide.</para> +</listitem> +</itemizedlist> +</sect3> + +<sect3 id="gettingstarted-new-files-doc"> +<title>Initial Application Documentation</title> + +<para>In the <filename class="directory">doc/en</filename> subdirectory of the +project you will find the <filename>index.docbook</filename> file. This is a +default template from where you can start to write a suitable user +documentation.</para> +</sect3> + +<sect3 id="gettingstarted-new-files-project"> +<title>Project and Auxiliary Files</title> + +<para>You will have noted that the files we introduced so far are listed in +boldface in the <guilabel>File Tree</guilabel> tool view while most of the other +files are not. This depicts the substantially different tasks these files are +used for. The contents of those bold listed files directly influence the +application. Source files will produce the code to be run, others will provide +necessary data or documentation. These files must be maintained and orderly +processed in the build stages by the project, hence they are called +<emphasis>project files</emphasis>.</para> + +<para>If you have a look at the lower <guilabel>Automake Manager</guilabel> +window to the right of the workspace area you will find all project files listed +as well. The &automanag; tool uses this knowledge to take care of the build +control as we shortly will see.</para> + +<para>The other, non-bold listed files are of more auxiliary nature. They belong +to several distinctive classes as follows:</para> + +<itemizedlist> +<listitem> +<formalpara> +<title>Project Build Control</title> +<para>These files control the compile, install, documentation building, &etc; +processes. If the project utilizes the &GNU; +<application>autotools</application> machinery as our example does, you will +find a <filename>Makefile.am</filename> file in each project directory. These +are kind of basic make core files which contain build control commands and will +be processed in conjunction with various <filename>configure</filename> files +during the build stages. Such a build produces a final +<filename>Makefile</filename> in every directory. And from these in turn the +<application>make</application> utility will finally build the binaries of the +application.</para> +</formalpara> + +<para>Those <filename>Makefile.am</filename> files need to be maintained +throughout the development process. Luckily, &kdevelop; relieves you of most of +this burden by the &automanag; tool, which basically is a graphical front end to +maintain <filename>Makefile.am</filename> contents.</para> + +<para>Other project build control files currently listed are +<filename>configure.in.in</filename> and <filename>subdirs</filename> in the +project root directory. They will be processed by some of the files in the +<filename class="directory">admin</filename> &kde; specific administration +directory to produce more <filename>configure</filename> and +<filename>Makefile</filename> type files and finally the application's +binaries.</para> +</listitem> + +<listitem> +<formalpara> +<title>&kdevelop; Control Files</title> +<para>&kdevelop; needs some control and administration data on its own. These +are located in the project root directory, in our example +<filename>hello.kdevelop</filename>, <filename>hello.kdevelop.pcs</filename>, +and <filename>hello.kdevses</filename>.</para> +</formalpara> + +<para>Of particular importance in each project is the +<filename>xxx.kdevelop</filename> (where <quote>xxx</quote> denotes the project +name) file. It is the main <emphasis>KDevelop 3 Project File</emphasis> and +needed if you later want load this project into the &IDE;.</para> + +<warning> +<para>Never do manually modify, rename, or even delete any of these &kdevelop; +control files! The &IDE; will most likely not function properly on your project +afterwards.</para> +</warning> +</listitem> + +<listitem> +<formalpara> +<title>GNU Project Description Files</title> +<para>Some files in the project root directory are mandatory in any &GNU; +conformant application. These are: <filename>AUTHORS</filename>, +<filename>ChangeLog</filename>, <filename>INSTALL</filename>, +<filename>COPYING</filename> (which contains the GNU GENERAL PUBLIC LICENSE), +<filename>INSTALL</filename>, <filename>NEWS</filename>, +<filename>README</filename>, and <filename>TODO</filename>.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Other Files</title> +<para>A few more files, not mentioned yet, are:</para> +</formalpara> + +<itemizedlist> +<listitem> +<para><filename>Doxyfile</filename> controls the creation of the project +specific &API; internal programming interface documentation.</para> +</listitem> + +<listitem> +<para>The <filename class="directory">templates</filename> directory containes +file templates the &IDE; uses as stubs to create new source files. +You may at any time edit these templates. The new contents will be reflected in +the next source files you create of the related types.</para> + +<para>You may ⪚ want to realign the right hand stars in the copyright lines +the &appwizard; inserted into the <filename>cpp</filename> and +<filename>h</filename> template files, so the source files created from them +will look less awkward.</para> +</listitem> + +<listitem> +<para>The <filename class="directory">po</filename> directory will be used for +localization purposes. It is essentially part of the project files (contains a +<filename>Makefile.am</filename>) but will mainly be used in translation +processing. Not of main interest to the application developer, however.</para> +</listitem> + +<listitem> +<para>Finally, the <filename class="directory">admin</filename> directory is +specially needed in &kde; oriented applications. It provides a whole bunch of +files necessary to maintain the application's sources and binaries so they +will integrate properly into the &kde; environment.</para> +</listitem> +</itemizedlist> + +</listitem> +</itemizedlist> +</sect3> +</sect2> + +<sect2 id="gettingstarted-new-toolviews"> +<title>Additional Tool Views</title> + +<para>As you will have noticed, as soon as the &appwizard; had the new project +ready, several additional tool views were provided. These make sense during +project development only and, in short, provide the following +functionality.</para> + +<note> +<para>The tool views actually visible depend on the plugins currently loaded +into &kdevelop;. There are ways to control this. See the <link +linkend="setup-plugins">Plugin Tools</link> chapter for instructions.</para> +</note> + +<sect3 id="gettingstarted-new-toolviews-left"> +<title>Navigation and Selection Tools (left side)</title> + +<itemizedlist> +<listitem> +<formalpara> +<title>Bookmarks</title> +<para>You can mark any text file line in order to quickly return to this +position from everywhere. &kdevelop; will remember all those +<emphasis>bookmarks</emphasis>, even if you close the editor window afterwards. +The <guilabel>Bookmarks</guilabel> tool view lists all those bookmarks by file +name and line number. You need only click such an entry to open the editor +window accordingly and position the cursor on that line.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Classes</title> +<para>Lists classes, methods, &etc; known in the project. Clicking the entry +opens the appropriate header or source file in an editor window and positions +the cursor at the respective declaration or definition.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>File Groups</title> +<para>Sorts the files in the projects into various utility groups, &ie; Sources, +User Interface, Icons, Translations, and Others. Clicking an entry opens that +file in an editor window.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Variables</title> +<para>This is used by the debugger tool to display, evaluate, and watch +variables during debug runs.</para> +</formalpara> +</listitem> +</itemizedlist> +</sect3> + +<sect3 id="gettingstarted-new-toolviews-bottom"> +<title>Messages (bottom)</title> + +<itemizedlist> +<listitem> +<formalpara> +<title>Valgrind</title> +<para><application>Valgrind</application> is a run-time program analyzer. This +tool view lists the results of such an analyze run. It is used ⪚ to find +memory leaks.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Security Problems</title> +<para>There is a <guilabel>Security Checker</guilabel> plugin tool for +&kdevelop;. It analyzes the currently edited source file for several common +security problems which may occur in the application and notifies the user in +this tool view window.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Breakpoints</title> +<para>This tool view allows to explicitly set, clear, and manage debug +breakpoints in the application source files. It is used in conjunction with the +debugger.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>CTags</title> +<para>Allows to create a database of identifier indexes using the popular +<application>CTags</application> application. This tags database may then be +used from out this tool view window to look up any needed identifier in the +project sources. Clicking a thus found item line will open an editor window and +position the cursor on the appropriate identifier there.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Problems</title> +<para>&kdevelop; keeps track of common programming problems in the currently +edited source file and notifies the user in this tool view window.</para> +</formalpara> +</listitem> +</itemizedlist> +</sect3> + +<sect3 id="gettingstarted-new-toolviews-right"> +<title>Source Management (right side)</title> + +<itemizedlist> +<listitem> +<formalpara> +<title>Automake Manager</title> +<para>The &automanag; tool is basically a graphical front end to maintain the +contents of the <filename>Makefile.am</filename> files located in each project +directory. This tool view uses two windows to control its work. The upper window +mirrors part of the project subdirectories, namely those which explicitly +contain <emphasis>project files</emphasis>. Each subdirectory of this kind must +contain a <filename>Makefile.am</filename> file and is termed a +<emphasis>subproject</emphasis> in the &automanag; context.</para> +</formalpara> + +<para>Clicking a subproject entry opens a suitable display of the project files +in this subproject in the lower window. The files listed there will be grouped +according to their <filename>Makefile.am</filename> functionality in this +subproject.</para> + +<para>The &automanag; is a very powerful tool to manage the project and its +subprojects as well as the roles project files play in building the application. +We will have a short look at a few major details <link +linkend="gettingstarted-extend-automake">below</link>. See the <link +linkend="project-management">Building and Project Management</link> chapter for +a more extensive description.</para> +</listitem> +</itemizedlist> +</sect3> +</sect2> +</sect1> + + +<sect1 id="gettingstarted-edit"> +<title>Some Tips About Dealing With Documents</title> + +<para>In our example project the &appwizard; did leave the +<filename>hello.cpp</filename> file open in an editor window, so you can +immediately start working. Now, we may well assume your are knowledgeable about +using an editor, so we do not need talk much about this here. But there are some +handy &kdevelop; specifics about dealing with such tabbed editor windows and the +documents you are working on. We will have a short look at some of them, +namely:</para> + +<simplelist> +<member><link linkend="gettingstarted-edit-headers">How to easily switch between +header and implementation files.</link></member> +<member><link linkend="gettingstarted-edit-defs">How to quickly access +declarations and definitions.</link></member> +<member><link linkend="gettingstarted-edit-arrange">How to arrange editor +windows to your current needs.</link></member> +<member><link linkend="gettingstarted-edit-problems">How to keep an eye on +common problems.</link></member> +</simplelist> + +<sect2 id="gettingstarted-edit-headers"> +<title>Switching Between Header and Implementation Files</title> + +<para>&kdevelop; provides a quick and easy way to switch from a given +implementation (<filename>.cpp</filename>) file to the corresponding header +(<filename>.h</filename>) file and vice versa. Just right click into the editor +window you want to switch. A menu similar to the following will pop up.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="editor-switch-header.png" format="PNG"/> +</imageobject> +<caption><para>How to switch between implementation and header +files.</para></caption> +</mediaobject> +</screenshot> + +<para>Find the <guimenuitem>Switch header/implementation</guimenuitem> entry and +select it. &kdevelop; will look up the corresponding header or implementation +file and open it in another editor window. In our example, if you did right +click into the <filename>hello.cpp</filename> source, the +<filename>hello.h</filename> file will be displayed and the cursor positioned +there.</para> + +<para>There is even more. If you do right click inside the text of a class +implementation, &kdevelop; will position the cursor on the corresponding +declaration line in the header file. And vice versa, right clicking on a +declaration line will bring you to the corresponding class +implementation.</para> + +<para>If the editor window with the file to be switched to already exists, +&kdevelop; will of course activate this one and reposition the cursor there if +necessary.</para> +</sect2> + +<sect2 id="gettingstarted-edit-defs"> +<title>How to Access Declarations and Definitions</title> + +<para>But what if you are working on a source file and want to look up the +declaration or definition of an identifier you just found there? Well, this is +equally easily accomplished. Basically all you need to do is to right click on +the identifier in question.</para> + +<para>There are two different cases to consider, however, namely:</para> +<simplelist> +<member><link linkend="gettingstarted-edit-defs-external">Accessing externally +defined identifiers</link>, and</member> +<member><link linkend="gettingstarted-edit-defs-project">dealing with project +internal text items</link>.</member> +</simplelist> + +<sect3 id="gettingstarted-edit-defs-external"> +<title>External Declarations and Definitions</title> + +<para>In a most common case you want to look up an identifier which was defined +externally to your project. In &kde; projects such identifiers are most likely +documented in various &kde; or &Qt; libraries. If &kde; and &kdevelop; were +properly installed, &kdevelop; will be able to access such so-called API +documentation and be able to search it for identifiers of this kind.</para> + +<para>Let us look at an example. In the <filename>hello.cpp</filename> editor +window find the following lines.</para> + +<programlisting> +Hello::Hello() + : KMainWindow( 0, "Hello" ) +{ +</programlisting> + +<para>Right click on <classname>KMainWindow</classname>. +A menu will pop up. There select the <guimenuitem>Search in Documentation: +KMainWindow</guimenuitem> entry and release the mouse button. Now the +<guilabel>Documentation</guilabel> tool view will open, showing the +<classname>KMainWindow</classname> entry as search item on the +<guilabel>Search</guilabel> sub-page. And a short while after another editor +window will open in the workspace area, showing the KDE API Reference page of +the <classname>KMainWindow</classname> class.</para> + +<para>This all will look like the following. (We deliberately opened the +<guilabel>Documentation</guilabel>, <guilabel>Search</guilabel> page already to +illustrate the result of the menu selection.)</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="editor-search-doc.png" format="PNG"/> +</imageobject> +<caption><para>How to look up an externally documented +identifier.</para></caption> +</mediaobject> +</screenshot> + +<para>You might as well select <guimenuitem>Find Documentation: +KMainWindow</guimenuitem>. In this case the <guilabel>Finder</guilabel> sub-page +of the <guilabel>Documentation</guilabel> tool view will show up, usually +providing a selection of pages containing the search term. (In our example this +will probably be the <classname>KMainWindow</classname> and +<classname>KMainWindowInterface</classname> classes. Select the one you are +interested in and the corresponding documentation will be displayed in an editor +window.</para> + +<note> +<para>If this did not work, then there is probably no documents index yet. Did +you initialize the indexes as shown <link +linkend="gettingstarted-configure-search">above</link>? If not, please do so, +then come back here and try again.</para> +</note> +</sect3> + +<sect3 id="gettingstarted-edit-defs-project"> +<title>Project Internal Declarations and Definitions</title> + +<para>Such search facilities in external documentation have their limitations, +however. Of course one cannot look up an identifier externally if it is only +defined and used inside the current project. But there is help. &kdevelop; can +use indexes built by the <application>CTags</application> application to search +the sources in your project.</para> + +<para>Before we can use this on our Hello example project, we must however first +generate a suitable index. This is done by the <guilabel>CTags</guilabel> tool +view at the bottom of the workspace area.</para> + +<para>When you click the <guibutton>CTags</guibutton> tab, a dialog window will +open where you will find the following key in the lower right corner.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="editor-ctags-regenerate.png" format="PNG"/> +</imageobject> +<caption><para>Build a CTags index with the <guibutton>Regenerate</guibutton> +key.</para></caption> +</mediaobject> +</screenshot> + +<para>Press the <guibutton>Regenerate</guibutton> button and wait a few seconds. +Then the <guilabel>No CTags Database Found</guilabel> will be replaced by the +current date. Now you are ready to perform some identifier look ups in your +project source.</para> + +<tip> +<para>The date next to the <guilabel>Regenerate</guilabel> button is there to +remind you of possibly too old indexes. Whenever you are obviously not able to +look up some identifier in your project, consider regenerating the index. On +large projects this might take considerable time, but you should make it a habit +to regenerate the index regularly after extensive source file changes.</para> +</tip> + +<para>To look up an identifier in your project sources there are several +possibilities.</para> + +<itemizedlist> +<listitem> +<formalpara> +<title>Use the CTags tool view</title> +<para>This is easy. +Just start typing the identifier name you are interested in into the +<guilabel>Lookup</guilabel> input field in the bottom left. &kdevelop; will try +to complete the word you have typed so far and show all occurrences of those +identifiers which start with this character sequence.</para> +</formalpara> + +<para>If for example you want to know wherever the <quote>Hello</quote> +identifier was used in our example project, type an "H" into the +<guilabel>Lookup</guilabel> input field. &kdevelop; will immediately start +working and present you a result like this:</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="editor-ctags-lookup.png" format="PNG"/> +</imageobject> +<caption><para>How to look up an identifier in the <guilabel>CTags</guilabel> +tool view.</para></caption> +</mediaobject> +</screenshot> + +<para>If you click one of the listed entries, &kdevelop; will open an editor +window with this file and position the cursor on the appropriate place.</para> +</listitem> + +<listitem> +<formalpara> +<title>Use a context menu in a source file</title> +<para>This is handy while you are working on a certain source file. +Assume you are studying the <filename>main.cpp</filename> file of our Hello +example project. There you find the following line</para> +</formalpara> +<programlisting> + Hello *mainWin = 0; +</programlisting> +<para>and wonder whatever the <quote>Hello</quote> was used for in the program. +To find out, simply right click on this Hello identifier. A menu will pop up in +response to this right mouse click, featuring the following lines near the +bottom.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="editor-ctags-menu.png" format="PNG"/> +</imageobject> +<caption><para>Getting <application>CTags</application> information on a project +internal identifier.</para></caption> +</mediaobject> +</screenshot> + +<para>Click what you are interested in, say <guilabel>CTags - Go to Definition: +Hello</guilabel>, and &kdevelop; will immediately open the +<filename>hello.cpp</filename> editor window and position the cursor right in +front of this class definition:</para> +<programlisting> +Hello::Hello() + : KMainWindow( 0, "Hello" ) +{ +</programlisting> +</listitem> + +<listitem> +<formalpara> +<title>Do a global search</title> +<para>This is especially useful if you want to look up arbitrary text in your +project source. There are two possibilities to start a global search from within +&kdevelop;.</para> +</formalpara> +<itemizedlist> +<listitem> +<para>Start a global search from the <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Find in Files...</guimenuitem></menuchoice> menu. +Or</para> +</listitem> +<listitem> +<para>Directly make use of the context menu with a right mouse click in the +editor window.</para> +</listitem> +</itemizedlist> + +<para>We will illustrate the second possibility on our Hello example project. +The outcome of the menu call will essentially be the same. Let us assume you are +studying the <filename>hello.cpp</filename> source file and have the cursor +positioned on the first Hello occurrence there. Now you wonder, where this one +word <quote>Hello</quote> was used in the project source and how many +occurrences there are. This is a typical case where to use &kdevelop;'s +global search facilities.</para> + +<para>Now, still keeping the cursor somewhere on this <quote>Hello</quote> in +the source text, click the right mouse button. The now well known context menu +will pop up, where you should select the <guilabel>Grep: Hello</guilabel> +line.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="editor-find-menu.png" format="PNG"/> +</imageobject> +<caption><para>Initiating a global search from within an editor +window.</para></caption> +</mediaobject> +</screenshot> + +<para>This will pop up the following <guilabel>Find in Files</guilabel> dialog +(exactly the same as if you did use the <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Find in Files...</guimenuitem></menuchoice> menu).</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="find-in-files.png" format="PNG"/> +</imageobject> +<caption><para>A versatile graphical front end to perform global searches in the +project.</para></caption> +</mediaobject> +</screenshot> + +<para>As you see, this is a very versatile tool to initiate +<application>find</application>-and-<application>grep</application> searches +throughout your project. We won't delve further into details here, but you +may want to experiment with this facility on your own. For the moment, there +should be our <quote>Hello</quote> be preselected in the +<guilabel>Pattern</guilabel> field. If it is not, just type it in, then press +the <guibutton>Search</guibutton> button at the bottom right.</para> + +<para>Now the <guilabel>Find in Files</guilabel> tool view will open at the +bottom, showing you file names and lines of all literal occurrences of +<quote>Hello</quote> in our example project. As usual, if you click an entry, +&kdevelop; will get you to exactly that position in an editor window in the +workspace area.</para> + +<para>There are two lines of special interest in the tool view window.</para> +<itemizedlist> +<listitem> +<para>Right on top you will find the command sequences &kdevelop; did actually +use to perform the search. This will be useful to more precisely control the +search outcome.</para> +</listitem> + +<listitem> +<para>On bottom the number of occurrences found in these search run will be +listed. In our example this should read <quote>*** 11 matches found +***</quote>.</para> +</listitem> +</itemizedlist> + +<para>&kdevelop; will remember these search results throughout the currently +running session. If you initiate another global search, its results will display +in another tabbed window in the <guilabel>Find in Files</guilabel> tool view +window.</para> +</listitem> +</itemizedlist> +</sect3> +</sect2> + +<sect2 id="gettingstarted-edit-arrange"> +<title>Arranging Editor Windows</title> + +<para>When your work with large complex projects you will often end up with +quite a lot of tabbed editor windows residing on the tab bar. This makes +specific facilities to clean up, order, and group all those editor tabs +necessary. &kdevelop; provides several means for this. We will have a short look +at some of them.</para> +<simplelist> +<member><link linkend="gettingstarted-edit-arrange-clean">How to remove unneeded +tabs.</link></member> +<member><link linkend="gettingstarted-edit-arrange-tabs">How to rearrange the +tabs.</link></member> +<member><link linkend="gettingstarted-edit-arrange-split">How to view several +files simultaneously in the workspace area.</link></member> +<member><link +linkend="gettingstarted-edit-arrange-sourceheader">How to edit +C++ source and header files simultaneously</link></member> +<member><link linkend="gettingstarted-edit-arrange-group">How to group source +files into development sessions.</link></member> +</simplelist> + +<sect3 id="gettingstarted-edit-arrange-clean"> +<title>Cleaning up the Tabs Row</title> + +<para>If the vast amount of editor window tabs becomes badly arranged at all, +you usually may want to close all those tabs you really do not need any more. +&kdevelop; provides several facilities to do so, the usual way of bulk closing +open editor windows and a more specific approach where you can expressly command +which ones to close and which to keep open.</para> + +<formalpara> +<title>Closing Several Tabs At Once</title> +<para>This is kind of a bulk approach to close unnecessarily open tabs which you +may find in other &kde; applications as well. You can use the +<guimenu>Window</guimenu> menu or right click on a tab to either</para> +</formalpara> +<itemizedlist> +<listitem> +<para>close the currently selected editor window,</para> +</listitem> +<listitem> +<para>close all other open editor windows, or</para> +</listitem> +<listitem> +<para>close all editor windows at once (available from the +<guimenu>Window</guimenu> menu only).</para> +</listitem> +</itemizedlist> + +<formalpara> +<title>Closing Selected Sets of Tabs</title> +<para>The step-by-step approach of closing individual editor window tabs can +become awkward if there are a great number of tabs from which you want to still +keep several open. Instead of searching and closing one editor window tab after +another &kdevelop; provides a means to select the candidates from a list and +close those, and only those, with one single mouse click.</para> +</formalpara> + +<para>Let us illustrate this on a simple example. +In our Hello example project let us assume there were several files open for +edit: <filename>hello.cpp</filename>, <filename>hello.h</filename>, +<filename>helloui.rc</filename>, <filename>hello.desktop</filename>, and +<filename>main.cpp</filename>. Now you want to close all of them except +<filename>hello.cpp</filename> and <filename>hello.h</filename>. The easiest way +to do so is with the <guilabel>File List</guilabel> tool view. Because this list +of open files is alphabetically ordered you can more easily find the ones you +want to be closed. Proceed as follows:</para> + +<procedure> +<step> +<para>Open <guilabel>File List</guilabel> and, with the <keycap>Ctrl</keycap> +key held down, click the files you want to be closed in the list.</para> +</step> +<step> +<para>Then, keeping the mouse pointer on a file name in the list, click the +right mouse button.</para> +</step> +<step> +<para>From the <guimenu>File List</guimenu> popup menu select <guimenuitem>Close +Selected</guimenuitem>.</para> +</step> +</procedure> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="file-list-close-selected.png" format="PNG"/> +</imageobject> +<caption><para>How to close selected editor windows in one +step.</para></caption> +</mediaobject> +</screenshot> +<para>That was all. +&kdevelop; will have closed all editor windows at your wish, and you are ready +to proceed with a clean tab bar again.</para> +</sect3> + +<sect3 id="gettingstarted-edit-arrange-tabs"> +<title>How to Rearrange Edit Window Tabs</title> + +<para>Even if you have only the really necessary editor windows open you may +still want to have their tabs arranged in some logical way. &kdevelop; provides +some common means to do so, in short:</para> + +<formalpara> +<title>Basic Setup — Where to Position New Tabs</title> + +<para>By default, when you open a new editor window, its tab will be inserted to +the right of the editor window tab currently in use. This can be changed so that +the new tab will open to the far right on the tab bar.</para> +</formalpara> +<para>You must change a basic user interface setting in &kdevelop; to enable +this behavior.</para> +<procedure> +<step> +<para>Select <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure +KDevelop...</guimenuitem></menuchoice></para> +</step> +<step> +<para>In the left hand icon bar on the dialog popup click the <guilabel>User +Interface</guilabel> icon. The <guilabel>User Interface</guilabel> dialog page +will be now shown.</para> +</step> +<step> +<para>In the left bottom corner there find the section labeled <guilabel>Tabbed +Browsing</guilabel>. Remove the check mark on the <guilabel>Open new tab after +current tab</guilabel> line.</para> +</step> +<step> +<para>Close &kdevelop; and restart it again. Now the new editor window tabs will +open at the far right end of the current tabs row.</para> +</step> +</procedure> + +<para>Unfortunately, this setting cannot be changed on the fly during a +development session. You must make up your mind which behavior you prefer in the +long run and then stick to it, at least until the next start of +&kdevelop;.</para> + +<formalpara> +<title>How to Rearrange the Tabs</title> +<para>As development tasks do vary over time, the need to rearrange the tabbed +editor windows will more or less often arise. This is easily accomplished in +&kdevelop;.</para> +</formalpara> +<para> +Just click the tab you want to move with the middle mouse button and move the +mouse a short distance. The cursor will change to a crossed-arrow pattern. You +can now drag this tab, holding the middle mouse button down, until it did skip +into the place where you want it to be.</para> +</sect3> + +<sect3 id="gettingstarted-edit-arrange-split"> +<title>Viewing Several Files Simultaneously</title> + +<para>At first sight there is always at most one single editor window open to +work on a source file. Although you may fast switch the tabbed windows, there +are times where you want have several files open at once, ⪚ for reference +purposes or to keep complex tasks under better control. To accomplish this, +&kdevelop; provides a way to split the workspace area into different, +simultaneously visible sections which each can hold their own series of tabbed +windows.</para> + +<para>There are two split commands which you can reach either through the +<guimenu>Window</guimenu> menu or by right clicking either into a tabbed window +or on the window tab itself. We will illustrate this splitting behavior again +with our Hello example project.</para> + +<para>Assume there are two source files open on the tab bar, +<filename>hello.cpp</filename> and <filename>hello.h</filename>. Now, while +working on the <filename>hello.cpp</filename> source, you often need to refer to +the declarations in the <filename>hello.h</filename> headers file, so you want +to keep both files open simultaneously.</para> + +<para>To get this done, right click on the tab of, say, +<filename>hello.h</filename>. The following menu will then pop up.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="split-workspace.png" format="PNG"/> +</imageobject> +<caption><para>How to split the current workspace area into two +parts.</para></caption> +</mediaobject> +</screenshot> + +<para>Select the <guimenuitem>Split Horizontal</guimenuitem> entry. This will +split the current workspace area in the middle and move the tabbed editor window +holding the <filename>hello.h</filename> file into the lower part.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="split-windows.png"/> +</imageobject> +<caption><para>The workspace has been split horizontally.</para></caption> +</mediaobject> +</screenshot> + +<para>Note the dotted separator line between both windows. You can grab it with +the mouse and adjust the heights of the editor windows according to your +needs.</para> + +<para>There are a few points to note.</para> +<itemizedlist> +<listitem> +<para>The split workspace areas are fully functional at their own. This means, +new tabbed windows will open in the workspace which contains the currently +active editor window. And you can split any sub-area again to your wish, thus +keeping as much windows open simultaneously as you need.</para> +</listitem> + +<listitem> +<para>Any split will move the currently active editor window into the new +workspace sub-area, either downward or to the right. The other tabbed windows +all remain where they were. You cannot directly move tabbed windows between +split areas, instead you need to explicitly close the window in one workspace +area and reopen it in another to regroup.</para> +</listitem> + +<listitem> +<para>Also, there is no direct way to close a split area again. +It closes automatically, once the last tabbed window in it was closed.</para> +</listitem> +</itemizedlist> +</sect3> + +<sect3 id="gettingstarted-edit-arrange-sourceheader"> +<title>Edit C++ Source and Header Files Simultaneously</title> + +<para>There is a neat application of the above mentioned workspace split +feature built into &kdevelop;. It allows to automatically keep a +<filename>.cpp</filename> source and its accompanying +<filename>.h</filename> header file side by side open in the workspace area. +And, optionally, it allows to work on both files synchronously, such that if +you select a declaration in the header file &kdevelop; will navigate to the +respective definition in the source file and vice versa.</para> + +<para>This feature is however deactivated by default. If you want to use it in +your project you need to activate it.</para> + +<para>Select <menuchoice><guibutton>Project</guibutton> +<guimenuitem>Project Options</guimenuitem></menuchoice>. The +<guilabel>Project Options</guilabel> dialog will pop up. In the left hand icon +bar there select <guiicon>C++ Support</guiicon> and subsequently the +<guilabel>Navigation</guilabel> tab on the dialog page which will display on +the right side.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="split-source-header.png" format="PNG"/> +</imageobject> +<caption><para>Have C++ source and header files be displayed side by +side.</para></caption> +</mediaobject> +</screenshot> + +<para>Now check the <guilabel>Enable split of Header/Source files</guilabel> +box. This will enable <guilabel>Automatic Synchronize</guilabel> +and <guilabel>Vertical</guilabel> by default. Keep these settings for now and +press <guibutton>OK</guibutton>.</para> + +<para>To illustrate this feature, now close in our example Hello project +both the <filename>hello.cpp</filename> and <filename>hello.h</filename> editor +windows, if necessary. Then select <filename>hello.cpp</filename> again from the +<filename class="directory">src</filename> subdirectory of the project. The +editor window will open as usual. But if you now open the +<filename>hello.h</filename> belonging to it, &kdevelop; will automatically +split the workspace and open this header file editor window just beneath the +<filename>hello.cpp</filename> window.</para> + +<para>There is even more, as we mentioned already. In the +<filename>hello.cpp</filename> editor find ⪚ this constructor definition +line:</para> +<programlisting> +Hello::Hello() +</programlisting> +<para>and put the cursor there. Then look at the <filename>hello.h</filename> +window below and note how &kdevelop; did navigate to the corresponding default +constructor declaration line.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="split-source-header-navigate.png" format="PNG"/> +</imageobject> +<caption><para>&kdevelop; automatically navigated to the constructor +declaration.</para></caption> +</mediaobject> +</screenshot> + +<para>This works vice versa as well. Whenever you put the cursor somewhere into +a construct in one editor window, &kdevelop; will navigate to the corresponding +construct in the other.</para> +</sect3> + +<sect3 id="gettingstarted-edit-arrange-group"> +<title>Grouping Source Files Into Development Sessions</title> + +<para>When your project grows larger, and the development tasks become more and +more complex and force you to often switch between different, even distinct sets +of files, it is about time to organize your development work into distinct +sessions. The <guilabel>File List</guilabel> tool view of &kdevelop; allows you +do to just this.</para> + +<para>On top of the <guilabel>File List</guilabel> tool view window there is a +tool bar where you can create, save, select, and remove such sessions. Or +alternatively use the <menuchoice><guimenu>View</guimenu> <guimenuitem>View +Sessions</guimenuitem></menuchoice> sub-menu.</para> + +<para>We will illustrate this facility again with our Hello example project. +Assume you want to always open the <filename>hello.cpp</filename>, +<filename>hello.h</filename>, and <filename>main.cpp</filename> files all in one +step, no matter what development task you just did perform in the project. To +accomplish this, you first need to create a new development session named, say, +<quote>sources</quote>.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="file-list-session-create.png" format="PNG"/> +</imageobject> +<caption><para>Use development sessions to remember groups of +files.</para></caption> +</mediaobject> +</screenshot> + +<para>This is a multiple step approach as follows.</para> +<procedure> +<step> +<para>Create a new session</para> +<substeps> +<step> +<para>Click the <guiicon>New Session</guiicon> icon top left in the +<guilabel>File List</guilabel> tool view window.</para> +</step> +<step> +<para>A dialog will pop up. In the <guilabel>Enter the name of the +session</guilabel> input field give your new session a name, ⪚ +<quote>sources</quote>.</para> +</step> +<step> +<para>Close the dialog with <guibutton>OK</guibutton>. The new session will now +be listed in the drop down box on the toolbar.</para> +</step> +</substeps> +</step> +<step> +<para>This new session will initially be empty. You must populate it with the +files you want to be kept there.</para> +<substeps> +<step> +<para>Open all files you want to be grouped in this development session. In our +example we decided to keep <filename>hello.cpp</filename>, +<filename>hello.h</filename>, and <filename>main.cpp</filename> there as +planned.</para> +</step> +<step> +<para>Once your file list is complete, click the <guiicon>Save Session</guiicon> +icon in the toolbar. Do not skip this step, &kdevelop; will forget the file list +otherwise.</para> +</step> +</substeps> +</step> +</procedure> + +<para>That was it. Whenever you select the <guilabel>sources</guilabel> session +from the <guilabel>Open Session</guilabel> drop down box, &kdevelop; will close +all currently open editor windows and open the remembered ones +(<filename>hello.cpp</filename>, <filename>hello.h</filename>, and +<filename>main.cpp</filename> in our example) instead.</para> + +<para>You can define as many sessions as you wish in the context of your +project. If you want to change the session's contents, just update the +remembered file list with a <guiicon>Save Session</guiicon> click. And if you +want get rid of a session, select it in the drop down box, then click the +<guiicon>Delete Session</guiicon> icon in the toolbar right.</para> + +<para>There is even more. You can force &kdevelop; to open a given session by +default when it loads the project. Just select the session in the drop down box +on the <menuchoice><guimenu>Projects</guimenu> <guimenuitem>Project +Options</guimenuitem> <guimenuitem>File List</guimenuitem></menuchoice> project +options configuration page.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="file-list-session-default.png" format="PNG"/> +</imageobject> +<caption><para>Let &kdevelop; open a specific session when the project is +loaded.</para></caption> +</mediaobject> +</screenshot> +</sect3> +</sect2> + +<sect2 id="gettingstarted-edit-problems"> +<title>Keeping an Eye on Common Problems</title> + +<para>When you open an editor window containing a source file, &kdevelop; will +parse its contents. This allows the built in <emphasis>problem +reporter</emphasis> to scan the source text for some common errors it knows of. +And it can alert the user of different places which have been marked for special +treatment.</para> + +<para>Let us illustrate this facility with our Hello example project.</para> + +<itemizedlist> +<listitem> +<para>Open an editor window with the <filename>main.cpp</filename> source +file.</para> +</listitem> + +<listitem> +<para>Make sure it still contains the following line somewhere towards the +end:</para> +<programlisting> + /// @todo do something with the command line args here +</programlisting> +<para>This was inserted by the &appwizard; when you created the Hello project in +the <link linkend="gettingstarted-new">Starting a New Project</link> chapter +above.</para> +</listitem> + +<listitem> +<para>Now open the <guilabel>Problems</guilabel> tool view in the bottom tabs +row. If all went right, it will currently report this todo:</para> +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="problem-report-todo.png"/> +</imageobject> +<caption><para>&kdevelop; is alerting a source code line containing a todo +mark.</para></caption> +</mediaobject> +</screenshot> +</listitem> +</itemizedlist> + +<para>The format of the <computeroutput>/// @todo</computeroutput> command is +for special treatment by the <application>Doxygen</application> code documenter, +which we will look at briefly in the <link +linkend="gettingstarted-doc">Documentation</link> section below. It is not +mandatory that you use this format, the more common +<computeroutput>TODO</computeroutput> and <computeroutput>FIXME</computeroutput> +comment marks will be recognized as well.</para> + +<para>If you ⪚ insert the following <computeroutput>TODO</computeroutput> and +<computeroutput>FIXME</computeroutput> comment lines in our +<filename>hello.cpp</filename> example file</para> +<programlisting> +Hello::Hello() + : KMainWindow( 0, "Hello" ) +{ + // set the shell's ui resource file + // TODO check the user interface + setXMLFile("helloui.rc"); + + // FIXME change to a better suited greeting + new QLabel( "Hello World", this, "hello label" ); +} +</programlisting> +<para>you will find them listed in the <guilabel>Problems</guilabel> tool view +as well:</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="problem-report-marks.png" format="PNG"/> +</imageobject> +<caption><para>The problem reporter listing lines which require attention in the +currently edited file.</para></caption> +</mediaobject> +</screenshot> + +<para>Note the other tabs in the <guilabel>Problem</guilabel> reporter tool view +window, especially <guilabel>Fixme</guilabel>, and <guilabel>Todo</guilabel>. If +you open them, you will find all <computeroutput>FIXME</computeroutput> and +<computeroutput>TODO</computeroutput> marked lines, &kdevelop; has found so far +in this session. For example the <computeroutput>TODO</computeroutput> alerts +will currently look thus:</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="problem-report-all-todos.png" format="PNG"/> +</imageobject> +<caption><para>The problem reporter has collected the +<computeroutput>TODO</computeroutput> alerts.</para></caption> +</mediaobject> +</screenshot> + +<para>The <guilabel>Errors</guilabel> tab will however not list every coding +error you make. This is the job of other tools in ⪚ the build process. But +you will find here alerts of some common programming mistakes which would likely +go unnoticed otherwise and probably be catched with difficulties during complex +debugging session.</para> + +<para>You will find the &kdevelop; problem reporter facility a very valuable +tool, so check the <guilabel>Problems</guilabel> tool view regularly in the +development process.</para> +</sect2> +</sect1> + +<sect1 id="gettingstarted-compile"> +<title>How to Compile a Project</title> + +<para>Compiling a project in &kdevelop; requires several setup steps and then +building the application. All these are available through the +<guimenu>Build</guimenu> menu.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="build-menu.png" format="PNG"/> +</imageobject> +<caption><para>Building a project requires several steps.</para></caption> +</mediaobject> +</screenshot> + +<para>We are interested for now in the upper section only of this menu. The +entries there are sorted in order of their importance. Thus the most often +needed command is on top, the <guimenuitem>Build Project</guimenuitem> entry, +which will cause all of the project be initialized, compiled and linked as +needed. Other entries are there to compile selected project portions or a single +file only, to perform several initialization sequences, or to install the +completed application binaries.</para> + +<para>For now we will concentrate on several facilities which &kdevelop; +provides for project setup, initializing, building, and running an application. +In general, this includes:</para> + +<simplelist> +<member><link linkend="gettingstarted-compile-basic">Looking briefly at the +basic build cycle.</link></member> +<member><link linkend="gettingstarted-compile-setup">Looking at some basic +means to configure a project.</link></member> +</simplelist> + +<sect2 id="gettingstarted-compile-basic"> +<title>The Basic Build Cycle</title> + +<para>Once you created a new project you usually want to check if everything +went right so far. This implies a first build and test run of the application, +which we will do now. In order to initially compile a project there are several +steps to perform, which we will briefly look at.</para> +<simplelist> +<member><link linkend="gettingstarted-compile-basic-init">How to initialize the +project for a first build.</link></member> +<member><link linkend="gettingstarted-compile-basic-config">How to do the +initial configuration.</link></member> +<member><link linkend="gettingstarted-compile-basic-build">How to build the +project.</link></member> +<member><link linkend="gettingstarted-compile-basic-run">How to run the +application from within &kdevelop;.</link></member> +</simplelist> + +<note> +<para>This discussion implies that your project is based on the &GNU; autotools, +which enabled the &automanag; tool in &kdevelop; as our example Hello project +does. If you created another type project, ⪚ for the &Qt; based +<application>QMake</application> project manager, there will be other facilities +available in the menus or perhaps even none of them. You will have to consult +the respective vendor documentation on project management and application +building in these cases.</para> +</note> + +<sect3 id="gettingstarted-compile-basic-init"> +<title>Initialize the Project for the Build</title> + +<para>When the &appwizard; created our Hello example project, it left it in a +sort of raw, <quote>virgin</quote> state. The &GNU; autotools chain dictates +several initialization steps to be performed before the application could be +actually compiled and linked. If you try to build a project in such a raw state, +⪚ by selecting the <menuchoice><guimenu>Build</guimenu> <guimenuitem>Build +Project</guimenuitem></menuchoice> menu or pressing the <keycap>F8</keycap> +function key, you will get the following warning.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="raw-project-warning.png" format="PNG"/> +</imageobject> +<caption><para>Trying to build a raw automake based project.</para></caption> +</mediaobject> +</screenshot> + +<para>You may press the <guibutton>Run Them</guibutton> button in which case +&kdevelop; will try to automatically run all required setup steps prior to +compiling and linking the application. But we will look at those initial steps +in sequence, so cancel the dialog by pressing <guibutton>Do Not run</guibutton>. +</para> + +<para>As mentioned already, compiling and linking the application is done +through the <guimenu>Build</guimenu> menu. Call it up and select +<guimenuitem>Run automake and friends</guimenuitem>.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="build-menu-automake.png" format="PNG"/> +</imageobject> +<caption><para>Initiating a basic initialization run.</para></caption> +</mediaobject> +</screenshot> + +<para> +&kdevelop; will now open the <guilabel>Messages</guilabel> tool view window at +the bottom and list a series of messages produced by several make tools. If +everything went right, the final line will read +<quote><computeroutput>*** Success ***</computeroutput></quote>.</para> + +<para>If you scroll back to the top, you will find the command line, &kdevelop; +issued to call up the tools beneath the surface:</para> + +<programlisting> +cd '/home/devel/projects/hello' && \ +WANT_AUTOCONF_2_5="1" WANT_AUTOMAKE_1_6="1" gmake -f Makefile.cvs +</programlisting> + +<para>This basically tells that &kdevelop; first switched to the root directory +of our example project. Then it set up a dedicated environment, advising the +make system of the <application>autoconf</application> and +<application>automake</application> tool revisions used for this initialization. +And finally it instructed the make tool (&GNU; <application>gmake</application> +in this case) to process the <filename>Makefile.cvs</filename> make file.</para> + +<para>This make file was automatically set up when you created the Hello +project. It contains all the commands necessary to properly initialize the +project so the resulting application will run under &kde;. Especially this will +create the <filename>configure</filename> skript file necessary to perform the +next setup step.</para> +</sect3> + +<sect3 id="gettingstarted-compile-basic-config"> +<title>Initial Hello Configuration</title> + +<para>Configuring means to tailor the build process to the hardware and software +peculiarities of your system. This is a basic requirement in build processes +based on the &GNU; autotools scheme as you probably will know.</para> + +<para>You can command a configure sequence once the basic automake +initialization has been successfully finished because only after this +initial run the necessary <filename>configure</filename> files will be +available. This done, select the <menuchoice><guimenu>Build</guimenu> +<guimenuitem>Run Configure</guimenuitem></menuchoice> menu entry to initiate a +configuration sequence.</para> + +<para>&kdevelop; opened the <guilabel>Messages</guilabel> tool view +window again if necessary and listed the messages of the configure run therein. +If all went right, the final messages will be <quote><computeroutput>Good - your +configure finished. Start make now</computeroutput></quote> (which was issued by +configure) followed by the &kdevelop; <quote><computeroutput>*** Success +***</computeroutput></quote> message.</para> + +<para id="gettingstarted-compile-basic-config-cmd">On top of the +<guilabel>Messages</guilabel> window you will again find +the command line, &kdevelop; used to initiate this configuration run:</para> + +<programlisting> +mkdir '/home/devel/projects/hello/debug' && \ +cd '/home/devel/projects/hello/debug' && \ +CXXFLAGS="-O0 -g3" "/home/devel/projects/hello/configure" --enable-debug=full +</programlisting> + +<para>You can tell several interesting details from these commands.</para> + +<informaltable frame="none"> +<tgroup cols="2"><tbody><row> +<entry> +<mediaobject> +<imageobject> +<imagedata fileref="tutorial-debug-tree.png"/> +</imageobject> +</mediaobject> +</entry> +<entry> +<itemizedlist> +<listitem> +<para>First, &kdevelop; uses a dedicated subdirectory in the project directory +tree for the build process. This <filename class="directory">debug</filename> +build directory (shown to the left) mirrors the basic project structure and +contains some set of build related files, such as several +<filename>configure</filename> based files and additionally a +<filename>Makefile</filename> in each subdirectory.</para> +</listitem> +<listitem> +<para>In the <link linkend="gettingstarted-compile-setup">Configuring the +Project</link> +section shortly below we will have a brief look at the motivations why +&kdevelop; uses separate build directories in cases like this one. For the +moment it is enough to know that &kdevelop; created this <filename +class="directory">debug</filename> directory — if necessary — prior +to the configure call and that the <filename>configure</filename> script did +build the sub structure and all the <filename>Makefiles</filename> in +there.</para> +</listitem> +<listitem> +<para>Next, from within the <filename class="directory">debug</filename> build +directory, &kdevelop; called the <filename>configure</filename> script in the +root directory of our project using a dedicated environment, where the +<computeroutput>CXXFLAGS="-O0 -g3"</computeroutput> flags will later signal the +&gcc; compiler that it should not optimize the resulting binaries and include +full debugging information with them.</para> +</listitem> +<listitem> +<para>Finally the <filename>configure</filename> script was called with the +<computeroutput>--enable-debug=full</computeroutput> option which instructs it +to create each <filename>Makefile</filename> so that later compilation and +linking will have all necessary debugging information be built in and +usable.</para> +</listitem> +</itemizedlist> +</entry> +</row></tbody></tgroup> +</informaltable> + +<para>All these settings are configurable on a per project basis. You will learn +more about this in the <link linkend="project-management">Project +Management</link> chapter.</para> +</sect3> + +<sect3 id="gettingstarted-compile-basic-build"> +<title>Build the Project</title> + +<para>Once you got this far you will be ready to actually build, &ie; +compile and link the application. Looking at the <guimenu>Build</guimenu> menu, +there are three such compile options from which to select.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="build-commands.png" format="PNG"/> +</imageobject> +<caption><para>&kdevelop; commands to build binaries.</para></caption> +</mediaobject> +</screenshot> + +<para>Going from bottom to top, there are:</para> +<itemizedlist> +<listitem> +<para><guimenuitem>Compile File</guimenuitem> — This will compile the +source file in the currently open editor window. Mostly used for quick error +checks.</para> +</listitem> +<listitem> +<para><guimenuitem>Build Active Target</guimenuitem> — This is mainly used +in conjunction with the <link linkend="gettingstarted-extend-automake">Automake +Manager</link> which we will briefly look at below.</para> +</listitem> +<listitem> +<para><guimenuitem>Build Project</guimenuitem> — Now this is what we +currently are interested in. It will iterate over the whole project, compiling +and linking all files as necessary.</para> +</listitem> +</itemizedlist> + +<para>It might be interesting to watch what happens to the +<filename class="directory">Debug</filename> directory created in the former +<filename>configure</filename> run. So best keep it open with all +subdirectories unfolded just as shown above. Then select +<menuchoice><guimenu>Build</guimenu> <guimenuitem>Build +Project</guimenuitem></menuchoice> (or press the <keycap>F8</keycap> key) to +initiate the build sequence. As before, the <guilabel>Messages</guilabel> tool +view window will open at the bottom and list the outcome of this build run. And +additionally some files will appear on the <filename +class="directory">Debug</filename> subtree.</para> + +<para id="gettingstarted-compile-basic-build-cmd">There are not many source +files in our Hello example project, so the <guilabel>Messages</guilabel> window +will contain only a few lines. On top of them again find the command line +&kdevelop; issued to the underlying shell.</para> + +<programlisting> +cd '/home/devel/projects/hello/debug' && \ +WANT_AUTOCONF_2_5="1" WANT_AUTOMAKE_1_6="1" gmake -k +</programlisting> + +<para>Not very surprisingly, &kdevelop; switched to the <filename +class="directory">Debug</filename> subtree root in order to run the +<filename>Makefile</filename> located there. A dedicated sub-environment was +set up again as before in the <link +linkend="gettingstarted-compile-basic-init">Initialization step</link> in which +then the <application>gmake</application> tool was called.</para> + +<para>Note the <computeroutput>-k</computeroutput> option in the +<application>gmake</application> call. It forces the build process to continue +up to its very end, even if errors will occur. This makes sense as &kdevelop; +will list all error messages in the <guilabel>Messages</guilabel> window. If +there are any, use the virtues of an &IDE;: Just click on the error message in +the <guilabel>Messages</guilabel> window and &kdevelop; will take you to +exactly the position where the error occurred in the source file.</para> + +<para>And what did happen inside the <filename +class="directory">Debug</filename> subtree? Not very much. A few files showed up +on the <filename class="directory">doc/en</filename> and <filename +class="directory">src</filename> branches, most notably the +<filename>hello</filename> file in <filename +class="directory">/home/devel/projects/hello/debug/src/</filename>. This, +finally, is the application binary we were looking for. All what is left +to do in our initial project check is to run this +<filename>hello</filename>.</para> +</sect3> + +<sect3 id="gettingstarted-compile-basic-run"> +<title>Run the Application</title> + +<para>There are no extra steps involved to run this new Hello +application. Either select <menuchoice><guimenu>Build</guimenu> +<guimenuitem>Execute Program</guimenuitem></menuchoice> or press +<keycombo><keycap>Shift</keycap> <keycap>F9</keycap></keycombo> or use the +<guibutton>Execute program</guibutton> button on the <guilabel>Build +Toolbar</guilabel> shown below.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="run-button.png"/> +</imageobject> +<caption><para>Running an application form the <guilabel>Build +Toolbar</guilabel>.</para> +</caption> +</mediaobject> +</screenshot> + +<para>That was all. &kdevelop; will now start the new application in +the dedicated console window which opens as <guilabel>Application</guilabel> +tool view on the bottom. There the command &kdevelop; issued to execute the +program will be shown in the top line:</para> + +<programlisting> +./hello +</programlisting> + +<para>showing that the &IDE; has a notion about where the executable it +shall run resides. This notion can be widely configured. See more about +this in the <link linkend="project-management">Project +Management</link> chapter.</para> + +<para>The <computeroutput>./hello</computeroutput> line will most likely +be followed by a warning message. Ignore this for now. It does not keep +our <application>Hello</application> form running.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="hello-world-app.png" format="PNG"/> +</imageobject> +<caption> +<para>Our initial <application>Hello</application> application.</para> +</caption> +</mediaobject> +</screenshot> + +<para>Close the <application>Hello</application> application window as +usual. If no errors occurred, &kdevelop; will report this as +<quote><computeroutput>*** Exited normally ***</computeroutput></quote> +in the <guilabel>Application</guilabel> tool view window.</para> +</sect3> +</sect2> + +<sect2 id="gettingstarted-compile-setup"> +<title>Configuring the Project</title> + +<para>In &kdevelop; there are numerous ways how you can manage your project. +This behavior is configurable on a per-project basis and mostly of interest to +the advanced developer. Yet there are a few project specific settings you +should know of right from the beginning. +</para> + +<simplelist> +<member><link linkend="gettingstarted-compile-setup-build">Of what use are build +configurations?</link></member> + +<member><link linkend="gettingstarted-compile-setup-config">Where to the define +the behavior of the <filename>configure</filename> script.</link></member> + +<member><link linkend="gettingstarted-compile-setup-make">Some considerations +how <application>make</application> should run.</link></member> + +<member><link linkend="gettingstarted-compile-setup-run">Where should the +executable be and how should it be called?</link></member> +</simplelist> + +<sect3 id="gettingstarted-compile-setup-build"> +<title>Build Configurations</title> + +<para>When we did a first run of the <filename>configure</filename> script in +the <link linkend="gettingstarted-compile-basic-config">Initial Hello +Configuration</link> section above, we noted that &kdevelop; had set up a +dedicated <filename class="directory">debug</filename> subdirectory for this +purpose. In this section we will briefly consider some consequences of +this feature.</para> + +<para>First of all, &kdevelop; does not necessarily use dedicated build +directories apart from the source. The preparations to automatically use +dedicated build configurations is done through templates the &appwizard; uses +when creating a new project.</para> + +<para>To find out which build configurations currently are available, have a +look at the <menuchoice><guimenu>Project</guimenu> <guisubmenu>Build +Configuration</guisubmenu></menuchoice> menu.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="build-configurations.png" format="PNG"/> +</imageobject> +<caption><para>There are various build configurations available +for this project.</para></caption> +</mediaobject> +</screenshot> + +<para>In this case, like our Hello example project, there are three different +build configurations available. In other cases, there may — initially +— be only one such build configuration, namely +<guimenuitem>default</guimenuitem>.</para> + +<para>The currently used build configuration has a check mark left to it. In +order to switch to another build configuration simply select its menu +entry.</para> + +<para>Now let us have a brief look at what these build configurations +provide.</para> + +<variablelist id="gettingstarted-compile-setup-build-configs"> +<varlistentry> +<term><guimenuitem>debug</guimenuitem></term> +<listitem> +<para>You should use this as the standard build configuration during the +development process. The build occurs separately from the source directories in +the dedicated <filename class="directory">debug</filename> subdirectory, &ie; +all object, auxiliary, and executable files will be put in the subdirectories +there instead of their counterparts in the project root. The +<filename>configure</filename> script will be given the +<computeroutput>--enable-debug=full</computeroutput> option and the +<computeroutput>CXXFLAGS="-O0 -g3"</computeroutput> will signal the &gcc; +compiler to not optimize the code and to insert extensive debug information +into the resulting binaries.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>optimized</guimenuitem></term> +<listitem> +<para>This is used to build a final C++ application. The build occurs +separately from the source directories in the dedicated <filename +class="directory">optimized</filename> subdirectory. No specific arguments to +the <filename>configure</filename> script will be preset, yet the +<computeroutput>CXXFLAGS="-O2 -g0"</computeroutput> will signal the &gcc; +compiler to optimize the code and to not insert debug information into the +resulting binaries.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>default</guimenuitem></term> +<listitem> +<para>The term <quote>default</quote> denotes the standard setup when you build +an application from the console using ⪚ the &GNU; +<application>configure</application> and +<application>make</application>/<application>gmake</application> command line +oriented build tools. Other than <guimenuitem>debug</guimenuitem> or +<guimenuitem>optimize</guimenuitem> no dedicated build directory will be used. +The application will by default be built in the sources directories instead. +There are no special configuration switches predefined. Building and running the +application will use the default settings of the underlying tools (e.g. &gcc;, +etc.).</para> + +<warning> +<para>Think twice before you decide to use the +<guimenuitem>default</guimenuitem> build environment!</para> + +<para>It cannot be used in parallel to the dedicated +<guimenuitem>debug</guimenuitem> or <guimenuitem>optimized</guimenuitem> ones. +<emphasis>Any build operation using <guimenuitem>default</guimenuitem> will +render both of the other build environments unusable.</emphasis> This is caused +by some peculiarities of the <filename>Makefile</filename> construction process +using the +<application>automake</application>/<application>autoconf</application> +machinery, which cannot be easily overcome.</para> +</warning> +</listitem> +</varlistentry> +</variablelist> + +<para>Now, why does one one want to use different build configurations at all, +when they even appear to be not compatible to each other? The answer is — +it simplifies edit-compile-debug cycles. The extra debug instructions +inserted into the binaries as well as all those subtle structure changes to +the program code made during optimizations will effect the run time behavior of +the resulting application. So in many cases, when the logical structure of some +routine appears to be correct, you may want to test whether it still behaves +correctly under more practical conditions.</para> + +<para>This is where the build configurations of &kdevelop; step in. Because +the built object and executable files in each dedicated build directory and the +build commands are kept separately from each other only source changes need +to be handled when you switch between these build configurations.</para> + +<para>Thus instead of cleaning up and recompile everything from scratch with +alternate options, you need only switch from the +<guimenuitem>debug</guimenuitem> to the <guimenuitem>optimize</guimenuitem> +build configuration, have the source changes compiled in and then retest the +application under these circumstances. If anything inappropriate shows up, +simply switch back to <guimenuitem>debug</guimenuitem> and immediately continue +your work there.</para> + +<para>A final note — many build configuration settings are configurable. +You can even define your own build configurations if your development process +requires some. We will briefly look at these possibilities in the next +section.</para> +</sect3> + +<sect3 id="gettingstarted-compile-setup-config"> +<title>Project Configure Options</title> + +<para>Configuring the application properly is vital in the &GNU; +autotools building chain. This is usually guided by option definitions to the +<filename>configure</filename> script and/or specific flags settings in the +environment prior to running <filename>configure</filename> as ⪚ the +<computeroutput>CXXFLAGS</computeroutput> in our previous discussions.</para> + +<para>You may set most of the configuring options for a given project from +within &kdevelop; &GUI;. Select +<menuchoice><guimenu>Project</guimenu> +<guimenuitem>Project Options</guimenuitem></menuchoice> and then from the +icon bar on the left of the dialog the <guiicon>Configure Options</guiicon> +icon. The <guilabel>Configure Options</guilabel> dialog featuring several tabbed +windows will display on the right handed side.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="configure-project-configure.png" format="PNG"/> +</imageobject> +<caption><para>Most configure options can be defined here.</para></caption> +</mediaobject> +</screenshot> + +<para>As you see, there are quite a lot of options you can set up in this +dialog. For now we will briefly look at only a few of them with regard to our +Hello example project. For detailed instructions see the <link +linkend="projects-configure">Configuring Projects</link> chapter. If you +want to know more about the meaning of the various flags which can be +set, look up <command>info make</command> from the console (or +<command>info:make</command> from within &konqueror;) and there the +<menuchoice><guimenu>Implicit Rules</guimenu> +<guimenuitem>Implicit Variables</guimenuitem></menuchoice> section.</para> + +<para>There are several tabbed dialog setup windows from which the first +one, <guilabel>General</guilabel>, refers to commonly used settings, +while the others are rather compiler specific. In all cases, however, will the +actual contents of those dialogs be governed by the given build +configuration.</para> + +<para>You select the build configuration whose configuration settings +have to be defined from the <guilabel>Configuration</guilabel> combo box +on top of the <guilabel>Configure Options</guilabel> dialog.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="configure-project-buildconfig.png" format="PNG"/> +</imageobject> +<caption><para>Select the build configuration whose settings to +define.</para></caption> +</mediaobject> +</screenshot> + +<para>Now select another build configuration from this combo box and note how +the contents of ⪚ the <guilabel>Configure arguments</guilabel> and +<guilabel>Build directory</guilabel> text boxes change according to the +settings we mentioned in the <link +linkend="gettingstarted-compile-setup-build-configs"> build +configurations list</link> above.</para> + +<sect4 id="gettingstarted-compile-setup-config-general"> +<title>General Configuration Settings</title> + +<para>On the <guilabel>General</guilabel> dialog page, these +configuration options can be defined:</para> + +<itemizedlist> +<listitem> +<formalpara> +<title>Configure arguments</title> +<para>These are the options &kdevelop; assigns to the +<filename>configure</filename> script call in the build process. See the +<link linkend="gettingstarted-compile-basic-config-cmd">example</link> in +the <quote>Initial Hello Configuration</quote> section above.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Build directory</title> +<para>This is the subdirectory in the current project root, where &kdevelop; +will put all files created in the build process. Ideally, this should +correspond to the name of the build configuration in use, but you are +free to use any name you like, provided it is different from any other +build configuration directory.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Top source directory</title> +<para>You won't need this one often. It defaults to the project root +directory and needs only be redefined if your project sources are located +in another place.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>C/C++ preprocessor flags (CPPFLAGS)</title> +<para>Put specific instructions for the preprocessor here. &kdevelop; will +use this to set up a temporary environment before it calls the actual +build tool. Again, see the <link +linkend="gettingstarted-compile-basic-config-cmd">example</link> in +the <quote>Initial Hello Configuration</quote> section above how this is +done.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Linker flags (LDFLAGS)</title> +<para>This is extra information for the <application>ld</application> linker +tool where it should look for additional libraries. It is used to build the +temporary build environment as well.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Environment Variables</title> +<para>Here you may define additional variables to be set up in the +temporal build environment, &kdevelop; will set up before calling the +respective build tool. Again, you must define these environment variables for +every build configuration where they are to be used.</para> +</formalpara> +</listitem> +</itemizedlist> +</sect4> + +<sect4 id="gettingstarted-compile-setup-config-spec"> +<title>Compiler Specific Settings</title> + +<para>The other tabs on the <guilabel>Configure Options</guilabel> dialog +page are for compiler specific settings. They are similarly structured, +so it suffices to have a brief look at the <guilabel>C++</guilabel> page.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="configure-project-cpp.png" format="PNG"/> +</imageobject> +<caption><para>Select the compiler and its working environment &kdevelop; shall +use here.</para></caption> +</mediaobject> +</screenshot> + +<para>This is what you can set up from here:</para> + +<itemizedlist> +<listitem> +<formalpara> +<title>C++ compiler</title> +<para>Select the C++ compiler &kdevelop; should regularly use from this +combo box. It however lists only those compilers &kdevelop; really knows +of.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Compiler command (CXX)</title> +<para>Only for experts. This is only needed if the C++ compiler is not standard. +Put the name by which it is called here.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Compiler flags (CXXFLAGS)</title> +<para>Here you can enter any extra option &kdevelop; shall pass (via the +<filename>Makefile</filename>) to the compiler. Some option values will be +preset according to the build configuration selected in the +<guilabel>Configuration</guilabel> combo box.</para> +</formalpara> + +<para>Note, that many common compiler options can be selected from a +dialog which will pop up when you press the <guibutton>...</guibutton> button to +the right of the text box.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="configure-project-cppoptions.png" format="PNG"/> +</imageobject> +<caption><para>Use this dialog to define the &GNU; C++ compiler +behavior.</para></caption> +</mediaobject> +</screenshot> + +<para>We deliberately selected the <guilabel>Optimization</guilabel> tab +here. Note how the <guilabel>No Optimization</guilabel> option has been +preselected (according to the <computeroutput>-O0</computeroutput> +option preset in the <computeroutput>debug</computeroutput> build +configuration).</para> + +<para>Unfortunately you cannot currently select all options from this +dialog. The <computeroutput>-g3</computeroutput> option ⪚ used by the +<computeroutput>debug</computeroutput> build +configuration would have to be altered manually if ever needed.</para> +</listitem> +</itemizedlist> +</sect4> +</sect3> + +<sect3 id="gettingstarted-compile-setup-make"> +<title>How Make Should Build the Program</title> + +<para>You can as well configure the way &kdevelop; will call the +<application>make</application> tool in the project build. Select +<menuchoice><guimenu>Project</guimenu> +<guimenuitem>Project Options</guimenuitem></menuchoice> and then the +<guiicon>Make Options</guiicon> icon from the left dialog window side. The +<guilabel>Make Options</guilabel> dialog page will then be displayed to +the right.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="configure-project-make.png" format="PNG"/> +</imageobject> +<caption><para>Define how &kdevelop; will call the +<application>make</application> tool.</para></caption> +</mediaobject> +</screenshot> + +<para>There is not much to do here for now. The only setting of interest in +most cases will be the <guilabel>Abort on first error</guilabel> switch. +You will find it deactivated in most projects. This corresponds to the +<computeroutput>-k</computeroutput> option in the +<application>gmake</application> call we found in the <link +linkend="gettingstarted-compile-basic-build-cmd">initial build</link> of +our example Hello project.</para> + +<para>This makes sense in an &IDE; like &kdevelop; which will protocol any +error message during the build. After the build process you may easily +navigate to any error message in the <guilabel>Messages</guilabel> tool +window. Use <menuchoice><guimenu>View</guimenu> +<guimenuitem>Next Error</guimenuitem></menuchoice> and +<menuchoice><guimenu>View</guimenu> <guimenuitem>Previous +Error</guimenuitem></menuchoice> or respectively the <keycap>F4</keycap> and +<keycombo><keycap>Shift</keycap> <keycap>F4</keycap></keycombo> keys for this. +&kdevelop; will automatically activate the editor window of the source file in +question and put the cursor on the error line.</para> + +<para>If on the other hand you rather want the build be stopped on whenever an +error occurs, check the <guilabel>Abort on first error</guilabel> option +in this dialog. &kdevelop; will then call <application>gmake</application> +without the <computeroutput>-k</computeroutput> option.</para> +</sect3> + +<sect3 id="gettingstarted-compile-setup-run"> +<title>How to Run the Executable</title> + +<para>Once the build is complete, you can easily run the application from within +&kdevelop;. Use either <menuchoice><guimenu>Build</guimenu> +<guimenuitem>Execute Program</guimenuitem></menuchoice>, the +<keycombo><keycap>Shift</keycap> <keycap>F9</keycap></keycombo> keys, or the +<guibutton>Execute program</guibutton> button in the <guilabel>Build +Toolbar</guilabel> of &kdevelop;.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="run-button.png" format="PNG"/> +</imageobject> +<caption><para>Run the program from here.</para></caption> +</mediaobject> +</screenshot> + +<para>But where is the executable located which should be run? How does +one have &kdevelop; append options to the call? Or, how can I have the +application executed in a terminal by its own to test its console interactive +behavior?</para> + +<para>All this can be solved by configuring some project oriented run options in +&kdevelop;. Select <menuchoice><guimenu>Project</guimenu> +<guimenuitem>Project Options</guimenuitem></menuchoice> and then the +<guiicon>Run Options</guiicon> icon from the icon bar on the left dialog window +side. The <guilabel>Run Options</guilabel> dialog page will display to the +right.</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="configure-project-run.png" format="PNG"/> +</imageobject> +<caption><para>Define where and how your program shall be run.</para></caption> +</mediaobject> +</screenshot> + +<para>Now, there is quite a lot which can be set up from this dialog. +Basically there are four groups of configuration items.</para> + +<itemizedlist> +<listitem> +<formalpara> +<title>Directory</title> +<para>This tells &kdevelop; where it basically shall assume the +executable to be called. There are three possibilities you can select +from.</para> +</formalpara> + +<para>Note however that only root directories are defined here. +&kdevelop; usually looks for the executable in some subdirectory +given in the next configuration group.</para> + +<itemizedlist> +<listitem> +<para>Run from the directory, where the executable was build the last +time. This is the default. You can keep this for now.</para> +</listitem> + +<listitem> +<para>Run from the build directory according to the currently selected +<link linkend="gettingstarted-compile-setup-build">build configuration</link>. +The name of this directory was set up on the <link +linkend="gettingstarted-compile-setup-config-general">General +Configuration</link> dialog page.</para> + +<para>This is the root where &kdevelop; will find the executable. It +changes automatically with the selection you made in +<menuchoice><guimenu>Project</guimenu> +<guisubmenu>Build Configurations</guisubmenu></menuchoice> menu. Try it.</para> + +<para>Other than always running the most recently built executable according to +the setting above, this allows you to switch the program to be executed by +simply selecting another build configuration from the <guimenu>Project</guimenu> +menu.</para> +</listitem> + +<listitem> +<para>Run the executable found in a fixed custom directory. Again +this is the root only from where the actual executable is to be +found.</para> + +<para>Use this if you ⪚ want to run the actually installed program instead of +the version located in the project directories.</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<formalpara> +<title>Program</title> +<para>This tells &kdevelop; the relative position and name of the +program it shall actually call. This is relative to the root directory +defined in the configuration group above. Furthermore you can define any +argument &kdevelop; will pass to the program when it is actually called.</para> +</formalpara> + +<note> +<para>If leave the <guilabel>Main program</guilabel> text box empty, the +<emphasis>active target</emphasis> settings of the &automanag; will be used. +Although this is an expert setting, inadvertently leaving this input +field blank is a common cause of problems. Check this setting if &kdevelop; +appears not to call the executable you wanted.</para> +</note> +</listitem> + +<listitem> +<formalpara> +<title>Environment Variables</title> +<para>&kdevelop; will set up a dedicated shell environment to run the +program in. Define any extra environment variable in this configuration +group.</para> +</formalpara> +</listitem> + +<listitem> +<formalpara> +<title>Miscellaneous</title> +<para>Two more check boxes are located at the bottom of this dialog page.</para> +</formalpara> + +<itemizedlist> +<listitem> +<para><guilabel>Automatically compile before execution</guilabel> comes +in handy most of time. &kdevelop; will check the project for changes and +perform necessary configure and build steps for you any time you command +it to run the program.</para> + +<para>Uncheck this in case you want to run the program version prior to the +last change.</para> +</listitem> + +<listitem> +<para><guilabel>Start in external terminal</guilabel> is interesting if +you want to test the input/output behavior of non-&GUI; programs in a console +terminal. This is unchecked by default, so &kdevelop; does start the program in +a window of its own without console terminal I/O capabilities.</para> +</listitem> +</itemizedlist> +</listitem> +</itemizedlist> +</sect3> +</sect2> +</sect1> + +<sect1 id="gettingstarted-extend"> +<title>How to Extend a Project — the &automanag;</title> + +<para>(- to be written -)</para> + +<sect2 id="gettingstarted-extend-automake"> +<title>A Short Look at the Automake Machinery</title> + +<para>(- to be written -)</para> +</sect2> + +<sect2 id="gettingstarted-extend-pics"> +<title>How to Place Icons in a Separate Directory</title> + +<para>(- to be written -)</para> +</sect2> + +<sect2 id="gettingstarted-extend-class"> +<title>How to Add New Classes</title> + +<para>(- to be written -)</para> + +<caution><para> +Be careful when you select your class file names. It is extremely difficult to +change them later.</para></caution> +</sect2> + +<sect2 id="gettingstarted-extend-subproject"> +<title>What is in a Subproject?</title> + +<para>(- to be written -)</para> + +<sect3 id="gettingstarted-extend-subproject-active"> +<title>Concentrate on Your Work — the Active Target</title> + +<para>(- to be written -)</para> +</sect3> +</sect2> + +<sect2 id="gettingstarted-extend-restructure"> +<title>Some Steps to Restructure a Project</title> + +<para>(- to be written -)</para> +</sect2> +</sect1> + + +<sect1 id="gettingstarted-debug"> +<title>How to Debug</title> + +<para>(- to be written -)</para> +</sect1> + + +<sect1 id="gettingstarted-doc"> +<title>A Note on Your Project Documentation</title> + +<para>The &kde; project uses <ulink +url="http://www.docbook.org/tdg5/en/html/docbook.html">docbook</ulink> for +generating your project handbook (&ie; the user manual). The user manual is +available through your application menubar by choosing +<menuchoice><guimenu>Help</guimenu> +<guimenuitem><replaceable>YourApplication</replaceable> +Handbook</guimenuitem></menuchoice > when your &kde; GUI application is running. +After building your project, the user manual is displayed in &kde; +&khelpcenter;. It should explain to the user how your application works, what +are the main features and how to configure it. It should also explain the +advanced features if any. +</para> +<para>All &kde; based templates in &kdevelop; have a doc subdir which contains +a <filename>index.docbook</filename> template in the en folder to get you +started in writing the user manual. You should edit this +<filename>index.docbook</filename> in &kdevelop; and start changing personal +details such as name, email, &etc;. Look at the comments in this file and try +following these indications to start your application documentation. Rebuild +your project to see the changes in &khelpcenter;.</para> +<note><para>You need to install your project using +<menuchoice><guimenu>Build</guimenu> +<guimenuitem>Install</guimenuitem></menuchoice > or <guimenuitem>Install (as +root user)</guimenuitem> in &kdevelop; to see the user manual in +&khelpcenter;.</para></note> +<para>You can find more about the docbook syntax on <ulink +url="http://l10n.kde.org/docs/markup/index.html">the &kde; documentation +website</ulink>.</para> +</sect1> + +<sect1 id="gettingstarted-keys"> +<title>Last But Not Least, Keyboard Shortcuts</title> + +<para>(- to be written -)</para> +</sect1> + +<sect1 id="gettingstarted-whereto"> +<title>Where to go from here</title> + +<para>(- to be written -)</para> + +<sect2 id="gettingstarted-whereto-faq"> +<title>Frequently Encountered Problems</title> + +<simplelist> +<member>The nutshell chapter</member> +<member>FAQ pages</member> +<member>Forum</member> +<member>Mailing lists</member> +</simplelist> +</sect2> + +<sect2 id="gettingstarted-whereto-projects"> +<title>Working With Projects</title> + +<para>(- to be written -)</para> + +<sect3 id="gettingstarted-whereto-projects-open"> +<title>Using Existing &kdevelop; Projects</title> + +<para>(- to be written -)</para> +</sect3> + +<sect3 id="gettingstarted-whereto-projects-import"> +<title>Importing External Projects</title> + +<para>(- to be written -)</para> +</sect3> +</sect2> +</sect1> + +</chapter> |