From 114a878c64ce6f8223cfd22d76a20eb16d177e5e Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdevelop@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/kdevelop/getting-started.docbook | 3221 ++++++++++++++++++++++++++++++++++ 1 file changed, 3221 insertions(+) create mode 100644 doc/kdevelop/getting-started.docbook (limited to 'doc/kdevelop/getting-started.docbook') 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 @@ + + + + + + + +BerndPol + + + + +Getting Started with &kdevelop; — a Guided Tour + +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. + +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: + + +A first look — the user +interface elements of the &kdevelop; &IDE;. +Doing some initial +configuration. +How to create a new project. + +Some tips about dealing with +documents. +How to compile the application in +this project. +How to add classes and other +detail to your project. +What to do to debug the +application. +Some basic tools to build program or +user documentation. +Last but not least, keyboard +shortcuts + + +Before we start, one important concept should be made clear. + + +What to expect? +As said, &kdevelop; is an Integrated Development +Environment. 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. + + +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. + +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 Development on &UNIX; historical overview and there +especially at the Integrating Concepts and +Tools chapter. + + +The following discussions apply to the default case, where &kdevelop; +starts up in the Simplified IDEAl Window Mode. 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 +Settings Configure +KDevelop... User Interface +dialog. + + + +A Very First Look at &kdevelop; + +This is all about what you will see when you first started &kdevelop;. +You will find preliminary information about: + + +What is there on the +surface? +How to get some +help. +What is in the +menus? +What are those tool views +for? + + + +On the Surface + +When you start &kdevelop; for the first time you will get a display +similar to this one: + + + + + + + +The &kdevelop; initial layout +(Actually the initial &kdevelop; window will be larger, but the elements +you see are the same.) + + + + + +Workspace Area and Tool View Tabs +In this initial case &kdevelop; uses the so-called IDEAl user interface mode. 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 tool view window will open which +allows you to work on a specific task. + + + +Menu and Toolbars +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. + + + +Status Bar +Finally, there is a status bar on the bottom of the window where short +informations on several tasks will be shown. + + + + +How to Get Some Help + +Besides the Help menu which offers answers to specific +questions, the status bar and two kinds of tool tips provide some quick +information. + + +What Does This Menu Entry Do? +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. + + + +What Is the Name of This Item? +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. + + + +What Does This Item Do? +More information is available through expanded tool tip help for many +items on the &IDE;. Select Help +What's This? or press +&Shift;F1, 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. + + + + +What is in the menus? + +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. + + +This is only a preliminary overview. For a detailed menu description see +the Command Reference. + + + + +File + + +Usual Actions +This is pretty standard. It allows to create, open, save, print, and close +document files as well as quitting the &kdevelop; application as usual. + + + +Revert All +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. + + + + + +Edit + +This menu is useful only if a document is opened. + + +Usual Actions +It provides the usual undo/redo and cut/copy/paste actions. +Furthermore it allows to select text blocks in various ways. + + + +Search and Replace +There are two very powerful search facility available, +Edit Find in +Files..., and Edit +Find-Select-Replace.... 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. + + + +Advanced Text Edit +There are provisions to reformat the current document and to automatically +complete partially typed texts in various ways. + + + + + +View + +Like the Edit menu, this menu is useful only if there +is an open project. I this case there will be the following actions available +(amongst others): + + +Navigation History +Switch back and forth through the documents &etc; you visited. + + + +Error Tracking +Navigate to the source lines of the errors encountered in the most recent +compilation/build process. + + + +Editor Related Actions +Some entries in the View 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: + + + + +Control the word wrap behavior in the document window. + + +Show or hide several border displays in the document windows: line +numbers, icons, and, additionally, bookmark marks in the scroll bar. + + +Control the display of folded (temporarily hidden) sections in a source +text. + + + + + + +Project + +All work of &kdevelop; is based on projects 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: + + +Open a Project +Allows to create new projects, open existing ones, and import projects +from other environments. + + + +Project Options +Allows to define a whole bunch of different project properties. + + + +Classes Management +Add new classes to the project and traverse the inheritance tree of a +class. + + + +Distribute Project +Helps to build distribution packages of the project. + + + + + +Build + +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: + + +Compile, Link, Execute +Allows to compile and link the whole project or parts of it as well as run +the application from within the &IDE;. + + + +Prepare Build Operations +This actually depends on the make system you use for this project. In the +case of automake projects it allows to run Makefile.cvs and +configure on their own. There are also provisions to remove +translated files from the project in various stages of intensity. + + + +Install the Application +Allows to install the application both in local directories as well as in +system directories only accessible to the root user. + + + +API Documentation +Build or remove a doxygen-based API documentation of the project as +defined in the project options. + + + + + +Debug + +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 Project +Project Options..). There are the +following actions available in this case: + + +Usual Debugger Actions +The first section in the Debug 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. + + + +Breakpoints +&kdevelop; provides several means to set breakpoints in your application +sources. One is through the use of the Toggle +Breakpoint menu entry. + + + +Advanced Debugging +Other Debug menu entries allow more sophisticated +program analysis. Use +&Shift;F1 to get more +information about their purpose. + + + + + +Scripts + +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. + + + + + +Window + +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. + +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. + + + + +Tools + +&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 +Tools menu reflects most of this setup. + + +Advanced Editing +The upper set of Tools menu entries will be provided by +the editor plugin which is in use. You may select your favorite editor via +Settings Configure +KDevelop... Editor. Once an +editable document file is selected, the upper part of the +Tools menu will provide advanced editing commands specific to +the editor part in use. + + + +Web Side Handling +In case the active document window contains a HTML page (⪚ displayed +from a Documentation selection), the +Tools will show additional menu entries which provide various +means to handle Web pages. + + + +Other Tools +Usually there will be a bunch of other entries according to the currently +available tools. Use &Shift; +F1 to get more information about their +purposes. + + + + + +Settings + +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. + + + + +Help + +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. + + + + + + +What are those tool views for? + +In the IDEAl user interface mode the workspace will be surrounded by three +areas of buttons, so-called tool view tabs. They provide +access to tool view windows which accomplish main tasks +during software development. Each of these three tool view areas serves a +different main purpose. + + + + +Left Side +Provides access to navigation and selection tools + + + + + +Bottom +These views display messages produced by various tools. + + + + + +Right Side +Provides access to documentation and source management tools. + + + + +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 Plugin +Tools being currently available to &kdevelop;. You will find more on this +topic in the Configuring KDevelop chapter. + +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. + + + +Navigation and Selection + + +File Selector +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. + + + +File List +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 sessions. 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. + + + + + +Messages Displays + + +Application +Displays the output from an application started from within +&kdevelop;. + + + +Diff +Used to display patch file contents. +Displays the output from the difference viewer tool started from the +Tools Difference +Viewer... menu. + + + +Messages +Displays messages produced by the build tools called from within +&kdevelop;, usually from the Build menu. + + + +Find in Files +Displays the list of items found by the global search operation started +from the Edit Find in +Files... menu. Clicking on a line here will +automatically open that file at the specified position in an editor +window. + + + +Replace +Lists the results of the global search-and-replace operation issued from +the Edit +Find-Select-Replace... menu. In this +view you can decide on every found item whether you really want it be replaced +or not. + + +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 Edit +Find-Select-Replace... menu will in +fact be be disabled. + + + +Konsole +Opens a &kde; Konsole like terminal emulator +window where you can use keyboard commands in a traditional &UNIX; command line +interface. + + + + + +Documentation and Source Manipulation + + +Documentation +&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. + + +See the Documentation and Configuring the Documentation chapters for more +details. + + +Code Snippets +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. + +More information on this is available in the Code Snippets and Setting Up the Code Snippets Tool +chapters. + + + + + + + +A Bit of Configuration + +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. + + +If you want to know more about &kdevelop; configuration, have a look at +the Configuring KDevelop chapter. + + + +Some General Settings + +To configure &kdevelop;, click the +Settings menu and select +Configure KDevelop.... The +Configure KDevelop dialog will pop up, showing the +following General settings page to the right. + + + + + + + +The &kdevelop; general configuration dialog + + + + +Most of the defaults will be o.k. +But you will probably want to change two of those settings. + + +Default projects directory +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 +Open file dialog button labeled with a folder icon to the +right of it. + + +In our examples we will assume a (somewhat artificial) user called +devel. +Thus always replace this devel by your user name. Our devel user +will utilize the /home/devel/projects +parent directory for actual development. Again, replace projects with your development directory name. + + +&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 +Hello in our case be located in the /home/devel/projects/hello directory. + +You may of course temporarily override these directory settings if you +need to. See the &appwizard; chapter +for more info on this. + + +Compiler output +Whenever &kdevelop; compiles some source, it will display the messages of +the make, etc. build tools in the +Messages 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. + + +Depending on the &kdevelop; version you use, the Compiler +output selection may be preset to Long, which will +cause all message contents be fully shown. You may probably want to change this +to the far more convenient Very Short setting. Just select this +from the drop down box. + + +Be aware that only most basic information will be +shown in the Messages 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 +Messages window and select ⪚ Full Compiler +Output from the popup menu. + + + + +Initializing Documentation Search Indexes + +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. + +Open the Documentation tool view at the right side of +the &kdevelop; main window. There open the Search dialog +page. + + + + + + +Where to generate the search indexes. + + + +Now press the Update Config button to make sure the +basic search tools are properly set up. A dialog should pop up, telling +Configuration file updated. Click OK to +make it disappear. + +This done, &kdevelop; will be ready to parse the documentation it knows of +and build some useful search indexes from it. Press the Update +Index button to the right. Now the Generating Search +Index dialog will pop up showing the progress of the index build +operations. + + + + + + +&kdevelop; is generating documentation search +indexes. + + + +This will take some time depending on the size of documentation and the +speed of your machine. But finally the Cancel will make +place to OK. Just press this button to proceed. + + + + +This usually should work out of the box. In some cases the +htdig application &kdevelop; uses to perform its full +text searches might not be properly set up. Refer to the Setting Up Text Search Indexes chapter +for more help in this case. + + +To be able to look up &kde; and &Qt; specific API documentation, it is +mandatory that the KDELibs Apidocs were present when +&kdevelop; was installed. If you experience problems building the indexes or +perform the identifier lookup +examples later in this chapter, make sure that this documentation exists +and is accessible to &kdevelop;. See Installing +KDevelop fore more detail. + + + + + + + + +Starting a New Project + +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 +projects. Thus the first practical step to develop software +in &kdevelop; usually is to create a new project. + +Fortunately this is fairly easily accomplished. &kdevelop; provides the +so-called &appwizard; tool for this. (See the Getting Started — the &appwizard; +chapter for more.) + +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: + + +How to create a new project +with the help of the &appwizard;. +Which files the &appwizard; +initially did set up. +What about the additional +tool view shown with the project? + + + +How to Create a New Project + +Let us create a rather simple Hello World &kde; project. +Just follow these steps. + + + +To start the &appwizard; click the Project +New Project... menu. + + + +The Create New Project dialog will pop up. In the +upper left All Projects window there will be a number of +programming languages listed. + + + +We want to build a &kde; C++ application as usual, thus click on the ++ label left of the C++ label to open +this branch. + + + +A series of possible application targets will be displayed. We will build +a &kde; application, thus open the next sub-branch via the ++ label next to KDE + + + +Now you will be offered a series of possible project +templates. Navigate down to the end of this branch and click +Simple KDE Application. + +A preview and short description of the application this project template +will produce pops up in the two windows to the right. + + + + + + + +Selecting a Hello World project template + + + + + +Our application will need a name. Find the Properties +area on the dialog bottom and enter a suitable name into the +Application name input field. + +We use Hello 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. + + + +Make sure the Location text box below the input field +shows the name of your top project directory as set up in the A Bit of Configuration 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. + +If all went well, the Final location line at the +bottom will show the directory path your new project will use. In case there was +an (invalid) suffix appended, try another name for your project +and/or make sure the top project directory in the Location +text box really exists and is writable. + + + +Once everything is right, the Next button in the +bottom row of the dialog will be enabled. Click it to proceed. + + + + + +This will lead you to the Project Options dialog +page. Make sure the Author and Email +text boxes are properly filled in. Usually they will default to your general +&kde; user settings as given in the Password & User +Account dialog of the &kde; Control Center. If not, change them to +some settings you prefer for your application. + + + + + + + +Provide your name and (optionally) email address. + + + + + +You must provide an Author name at least. This is +mandatory for the application files setup. + + +If all is right, the Next button will be enabled. +Click it to further proceed. + + + +The following Version Control System, +Template for .h Files, and Template for .cpp +Files dialog pages are not of interest for now. Skip them by clicking +the Next buttons and, finally, the +Finish button. + + + +That was all! +The &appwizard; will take over and construct a series of initial files in the +Final location directory you provided in step 2c +above. + +Once this file creation phase is finished, &kdevelop; will open an editor +window for the application main window implementation file +(which is hello.cpp in our example), so you can readily +proceed. + + + +Initial Project Files + +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 File Tree tool view on the +bottom left. This will open a file list similar to the one below. + + + + + + + +Initial files in our Hello World project + + + + +To demonstrate the main bunch of files the &appwizard; produced, we did +open most of the directory branches in the left-hand File +Tree tool view window. Just click the branch names in the tree to see +for yourself. + +Additionally, just for demonstration, we did as well open most of the +branches the Automake Manager tool view window to the right +where some of the project sources are listed, too. + + +Copyright Issues + +All &GNU; conformant applications must be copyrighted. There are two +levels which require copyright notices, individual source +files and run-time application level. The +&appwizard; did already put appropriate copyright and licensing information into +the project files. + + +Source File Level Copyrights +Do you remember the +Project Options 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 hello.cpp +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. + + + +/*************************************************************************** + * Copyright (C) 2006 by Joe User * + * joe@user.com * + * * + * This program is free software; you can redistribute it and/or modify * + + +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 templates directory. + + +Application Run-Time Copyrights +Once your &kde; application runs, the user may display some +About data, usually from the Help menu. +The &appwizard; did also take care of this. If you have a look at the +main.cpp file, you will find an entry similar to the one +below. + + + +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" ); + + +This will put the main developer's name (Joe User in +our case) and email address into the About copyright page +in the display and list this name and address on the +Authors page there as well. + + +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. + + + + +Initial Source Files + +The &appwizard; did put the source files into the src sub-directory of the project's directory. +You will find the main.cpp, hello.h, +and hello.cpp files there as you may have possibly +expected. + +There are some additional files you usually will find in a typical &kde; +application, namely + + + +hello.desktop contains some meta data used by +&kdevelop; to maintain and start the application. + + + +hi16-app-hello.png, and +hi32-app-hello.png contain some initial default icons, +&kdevelop; will use for application display. + + + +Finally, helloui.rc contains a description of the +application's user interface, currently the menus the application will +provide. + + + + + +Initial Application Documentation + +In the doc/en subdirectory of the +project you will find the index.docbook file. This is a +default template from where you can start to write a suitable user +documentation. + + + +Project and Auxiliary Files + +You will have noted that the files we introduced so far are listed in +boldface in the File Tree 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 +project files. + +If you have a look at the lower Automake Manager +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. + +The other, non-bold listed files are of more auxiliary nature. They belong +to several distinctive classes as follows: + + + + +Project Build Control +These files control the compile, install, documentation building, &etc; +processes. If the project utilizes the &GNU; +autotools machinery as our example does, you will +find a Makefile.am 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 configure files +during the build stages. Such a build produces a final +Makefile in every directory. And from these in turn the +make utility will finally build the binaries of the +application. + + +Those Makefile.am 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 Makefile.am contents. + +Other project build control files currently listed are +configure.in.in and subdirs in the +project root directory. They will be processed by some of the files in the +admin &kde; specific administration +directory to produce more configure and +Makefile type files and finally the application's +binaries. + + + + +&kdevelop; Control Files +&kdevelop; needs some control and administration data on its own. These +are located in the project root directory, in our example +hello.kdevelop, hello.kdevelop.pcs, +and hello.kdevses. + + +Of particular importance in each project is the +xxx.kdevelop (where xxx denotes the project +name) file. It is the main KDevelop 3 Project File and +needed if you later want load this project into the &IDE;. + + +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. + + + + + +GNU Project Description Files +Some files in the project root directory are mandatory in any &GNU; +conformant application. These are: AUTHORS, +ChangeLog, INSTALL, +COPYING (which contains the GNU GENERAL PUBLIC LICENSE), +INSTALL, NEWS, +README, and TODO. + + + + + +Other Files +A few more files, not mentioned yet, are: + + + + +Doxyfile controls the creation of the project +specific &API; internal programming interface documentation. + + + +The templates 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. + +You may ⪚ want to realign the right hand stars in the copyright lines +the &appwizard; inserted into the cpp and +h template files, so the source files created from them +will look less awkward. + + + +The po directory will be used for +localization purposes. It is essentially part of the project files (contains a +Makefile.am) but will mainly be used in translation +processing. Not of main interest to the application developer, however. + + + +Finally, the admin 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. + + + + + + + + + +Additional Tool Views + +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. + + +The tool views actually visible depend on the plugins currently loaded +into &kdevelop;. There are ways to control this. See the Plugin Tools chapter for instructions. + + + +Navigation and Selection Tools (left side) + + + + +Bookmarks +You can mark any text file line in order to quickly return to this +position from everywhere. &kdevelop; will remember all those +bookmarks, even if you close the editor window afterwards. +The Bookmarks 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. + + + + + +Classes +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. + + + + + +File Groups +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. + + + + + +Variables +This is used by the debugger tool to display, evaluate, and watch +variables during debug runs. + + + + + + +Messages (bottom) + + + + +Valgrind +Valgrind is a run-time program analyzer. This +tool view lists the results of such an analyze run. It is used ⪚ to find +memory leaks. + + + + + +Security Problems +There is a Security Checker 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. + + + + + +Breakpoints +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. + + + + + +CTags +Allows to create a database of identifier indexes using the popular +CTags 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. + + + + + +Problems +&kdevelop; keeps track of common programming problems in the currently +edited source file and notifies the user in this tool view window. + + + + + + +Source Management (right side) + + + + +Automake Manager +The &automanag; tool is basically a graphical front end to maintain the +contents of the Makefile.am 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 project files. Each subdirectory of this kind must +contain a Makefile.am file and is termed a +subproject in the &automanag; context. + + +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 Makefile.am functionality in this +subproject. + +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 below. See the Building and Project Management chapter for +a more extensive description. + + + + + + + + +Some Tips About Dealing With Documents + +In our example project the &appwizard; did leave the +hello.cpp 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: + + +How to easily switch between +header and implementation files. +How to quickly access +declarations and definitions. +How to arrange editor +windows to your current needs. +How to keep an eye on +common problems. + + + +Switching Between Header and Implementation Files + +&kdevelop; provides a quick and easy way to switch from a given +implementation (.cpp) file to the corresponding header +(.h) file and vice versa. Just right click into the editor +window you want to switch. A menu similar to the following will pop up. + + + + + + +How to switch between implementation and header +files. + + + +Find the Switch header/implementation 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 hello.cpp source, the +hello.h file will be displayed and the cursor positioned +there. + +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. + +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. + + + +How to Access Declarations and Definitions + +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. + +There are two different cases to consider, however, namely: + +Accessing externally +defined identifiers, and +dealing with project +internal text items. + + + +External Declarations and Definitions + +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. + +Let us look at an example. In the hello.cpp editor +window find the following lines. + + +Hello::Hello() + : KMainWindow( 0, "Hello" ) +{ + + +Right click on KMainWindow. +A menu will pop up. There select the Search in Documentation: +KMainWindow entry and release the mouse button. Now the +Documentation tool view will open, showing the +KMainWindow entry as search item on the +Search sub-page. And a short while after another editor +window will open in the workspace area, showing the KDE API Reference page of +the KMainWindow class. + +This all will look like the following. (We deliberately opened the +Documentation, Search page already to +illustrate the result of the menu selection.) + + + + + + +How to look up an externally documented +identifier. + + + +You might as well select Find Documentation: +KMainWindow. In this case the Finder sub-page +of the Documentation tool view will show up, usually +providing a selection of pages containing the search term. (In our example this +will probably be the KMainWindow and +KMainWindowInterface classes. Select the one you are +interested in and the corresponding documentation will be displayed in an editor +window. + + +If this did not work, then there is probably no documents index yet. Did +you initialize the indexes as shown above? If not, please do so, +then come back here and try again. + + + + +Project Internal Declarations and Definitions + +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 CTags application to search +the sources in your project. + +Before we can use this on our Hello example project, we must however first +generate a suitable index. This is done by the CTags tool +view at the bottom of the workspace area. + +When you click the CTags tab, a dialog window will +open where you will find the following key in the lower right corner. + + + + + + +Build a CTags index with the Regenerate +key. + + + +Press the Regenerate button and wait a few seconds. +Then the No CTags Database Found will be replaced by the +current date. Now you are ready to perform some identifier look ups in your +project source. + + +The date next to the Regenerate 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. + + +To look up an identifier in your project sources there are several +possibilities. + + + + +Use the CTags tool view +This is easy. +Just start typing the identifier name you are interested in into the +Lookup 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. + + +If for example you want to know wherever the Hello +identifier was used in our example project, type an "H" into the +Lookup input field. &kdevelop; will immediately start +working and present you a result like this: + + + + + + +How to look up an identifier in the CTags +tool view. + + + +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. + + + + +Use a context menu in a source file +This is handy while you are working on a certain source file. +Assume you are studying the main.cpp file of our Hello +example project. There you find the following line + + + Hello *mainWin = 0; + +and wonder whatever the Hello 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. + + + + + + +Getting CTags information on a project +internal identifier. + + + +Click what you are interested in, say CTags - Go to Definition: +Hello, and &kdevelop; will immediately open the +hello.cpp editor window and position the cursor right in +front of this class definition: + +Hello::Hello() + : KMainWindow( 0, "Hello" ) +{ + + + + + +Do a global search +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;. + + + +Start a global search from the Edit +Find in Files... menu. +Or + + +Directly make use of the context menu with a right mouse click in the +editor window. + + + +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 hello.cpp source file and have the cursor +positioned on the first Hello occurrence there. Now you wonder, where this one +word Hello 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. + +Now, still keeping the cursor somewhere on this Hello in +the source text, click the right mouse button. The now well known context menu +will pop up, where you should select the Grep: Hello +line. + + + + + + +Initiating a global search from within an editor +window. + + + +This will pop up the following Find in Files dialog +(exactly the same as if you did use the Edit +Find in Files... menu). + + + + + + +A versatile graphical front end to perform global searches in the +project. + + + +As you see, this is a very versatile tool to initiate +find-and-grep 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 Hello be preselected in the +Pattern field. If it is not, just type it in, then press +the Search button at the bottom right. + +Now the Find in Files tool view will open at the +bottom, showing you file names and lines of all literal occurrences of +Hello 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. + +There are two lines of special interest in the tool view window. + + +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. + + + +On bottom the number of occurrences found in these search run will be +listed. In our example this should read *** 11 matches found +***. + + + +&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 Find in Files tool view +window. + + + + + + +Arranging Editor Windows + +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. + +How to remove unneeded +tabs. +How to rearrange the +tabs. +How to view several +files simultaneously in the workspace area. +How to edit +C++ source and header files simultaneously +How to group source +files into development sessions. + + + +Cleaning up the Tabs Row + +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. + + +Closing Several Tabs At Once +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 +Window menu or right click on a tab to either + + + +close the currently selected editor window, + + +close all other open editor windows, or + + +close all editor windows at once (available from the +Window menu only). + + + + +Closing Selected Sets of Tabs +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. + + +Let us illustrate this on a simple example. +In our Hello example project let us assume there were several files open for +edit: hello.cpp, hello.h, +helloui.rc, hello.desktop, and +main.cpp. Now you want to close all of them except +hello.cpp and hello.h. The easiest way +to do so is with the File List 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: + + + +Open File List and, with the Ctrl +key held down, click the files you want to be closed in the list. + + +Then, keeping the mouse pointer on a file name in the list, click the +right mouse button. + + +From the File List popup menu select Close +Selected. + + + + + + + + +How to close selected editor windows in one +step. + + +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. + + + +How to Rearrange Edit Window Tabs + +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: + + +Basic Setup — Where to Position New Tabs + +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. + +You must change a basic user interface setting in &kdevelop; to enable +this behavior. + + +Select Settings Configure +KDevelop... + + +In the left hand icon bar on the dialog popup click the User +Interface icon. The User Interface dialog page +will be now shown. + + +In the left bottom corner there find the section labeled Tabbed +Browsing. Remove the check mark on the Open new tab after +current tab line. + + +Close &kdevelop; and restart it again. Now the new editor window tabs will +open at the far right end of the current tabs row. + + + +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;. + + +How to Rearrange the Tabs +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;. + + +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. + + + +Viewing Several Files Simultaneously + +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. + +There are two split commands which you can reach either through the +Window 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. + +Assume there are two source files open on the tab bar, +hello.cpp and hello.h. Now, while +working on the hello.cpp source, you often need to refer to +the declarations in the hello.h headers file, so you want +to keep both files open simultaneously. + +To get this done, right click on the tab of, say, +hello.h. The following menu will then pop up. + + + + + + +How to split the current workspace area into two +parts. + + + +Select the Split Horizontal entry. This will +split the current workspace area in the middle and move the tabbed editor window +holding the hello.h file into the lower part. + + + + + + +The workspace has been split horizontally. + + + +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. + +There are a few points to note. + + +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. + + + +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. + + + +Also, there is no direct way to close a split area again. +It closes automatically, once the last tabbed window in it was closed. + + + + + +Edit C++ Source and Header Files Simultaneously + +There is a neat application of the above mentioned workspace split +feature built into &kdevelop;. It allows to automatically keep a +.cpp source and its accompanying +.h 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. + +This feature is however deactivated by default. If you want to use it in +your project you need to activate it. + +Select Project +Project Options. The +Project Options dialog will pop up. In the left hand icon +bar there select C++ Support and subsequently the +Navigation tab on the dialog page which will display on +the right side. + + + + + + +Have C++ source and header files be displayed side by +side. + + + +Now check the Enable split of Header/Source files +box. This will enable Automatic Synchronize +and Vertical by default. Keep these settings for now and +press OK. + +To illustrate this feature, now close in our example Hello project +both the hello.cpp and hello.h editor +windows, if necessary. Then select hello.cpp again from the +src subdirectory of the project. The +editor window will open as usual. But if you now open the +hello.h belonging to it, &kdevelop; will automatically +split the workspace and open this header file editor window just beneath the +hello.cpp window. + +There is even more, as we mentioned already. In the +hello.cpp editor find ⪚ this constructor definition +line: + +Hello::Hello() + +and put the cursor there. Then look at the hello.h +window below and note how &kdevelop; did navigate to the corresponding default +constructor declaration line. + + + + + + +&kdevelop; automatically navigated to the constructor +declaration. + + + +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. + + + +Grouping Source Files Into Development Sessions + +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 File List tool view of &kdevelop; allows you +do to just this. + +On top of the File List tool view window there is a +tool bar where you can create, save, select, and remove such sessions. Or +alternatively use the View View +Sessions sub-menu. + +We will illustrate this facility again with our Hello example project. +Assume you want to always open the hello.cpp, +hello.h, and main.cpp 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, +sources. + + + + + + +Use development sessions to remember groups of +files. + + + +This is a multiple step approach as follows. + + +Create a new session + + +Click the New Session icon top left in the +File List tool view window. + + +A dialog will pop up. In the Enter the name of the +session input field give your new session a name, ⪚ +sources. + + +Close the dialog with OK. The new session will now +be listed in the drop down box on the toolbar. + + + + +This new session will initially be empty. You must populate it with the +files you want to be kept there. + + +Open all files you want to be grouped in this development session. In our +example we decided to keep hello.cpp, +hello.h, and main.cpp there as +planned. + + +Once your file list is complete, click the Save Session +icon in the toolbar. Do not skip this step, &kdevelop; will forget the file list +otherwise. + + + + + +That was it. Whenever you select the sources session +from the Open Session drop down box, &kdevelop; will close +all currently open editor windows and open the remembered ones +(hello.cpp, hello.h, and +main.cpp in our example) instead. + +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 Save Session click. And if you +want get rid of a session, select it in the drop down box, then click the +Delete Session icon in the toolbar right. + +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 Projects Project +Options File List project +options configuration page. + + + + + + +Let &kdevelop; open a specific session when the project is +loaded. + + + + + + +Keeping an Eye on Common Problems + +When you open an editor window containing a source file, &kdevelop; will +parse its contents. This allows the built in problem +reporter 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. + +Let us illustrate this facility with our Hello example project. + + + +Open an editor window with the main.cpp source +file. + + + +Make sure it still contains the following line somewhere towards the +end: + + /// @todo do something with the command line args here + +This was inserted by the &appwizard; when you created the Hello project in +the Starting a New Project chapter +above. + + + +Now open the Problems tool view in the bottom tabs +row. If all went right, it will currently report this todo: + + + + + +&kdevelop; is alerting a source code line containing a todo +mark. + + + + + +The format of the /// @todo command is +for special treatment by the Doxygen code documenter, +which we will look at briefly in the Documentation section below. It is not +mandatory that you use this format, the more common +TODO and FIXME +comment marks will be recognized as well. + +If you ⪚ insert the following TODO and +FIXME comment lines in our +hello.cpp example file + +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" ); +} + +you will find them listed in the Problems tool view +as well: + + + + + + +The problem reporter listing lines which require attention in the +currently edited file. + + + +Note the other tabs in the Problem reporter tool view +window, especially Fixme, and Todo. If +you open them, you will find all FIXME and +TODO marked lines, &kdevelop; has found so far +in this session. For example the TODO alerts +will currently look thus: + + + + + + +The problem reporter has collected the +TODO alerts. + + + +The Errors 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. + +You will find the &kdevelop; problem reporter facility a very valuable +tool, so check the Problems tool view regularly in the +development process. + + + + +How to Compile a Project + +Compiling a project in &kdevelop; requires several setup steps and then +building the application. All these are available through the +Build menu. + + + + + + +Building a project requires several steps. + + + +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 Build Project 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. + +For now we will concentrate on several facilities which &kdevelop; +provides for project setup, initializing, building, and running an application. +In general, this includes: + + +Looking briefly at the +basic build cycle. +Looking at some basic +means to configure a project. + + + +The Basic Build Cycle + +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. + +How to initialize the +project for a first build. +How to do the +initial configuration. +How to build the +project. +How to run the +application from within &kdevelop;. + + + +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 +QMake 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. + + + +Initialize the Project for the Build + +When the &appwizard; created our Hello example project, it left it in a +sort of raw, virgin 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 Build Build +Project menu or pressing the F8 +function key, you will get the following warning. + + + + + + +Trying to build a raw automake based project. + + + +You may press the Run Them 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 Do Not run. + + +As mentioned already, compiling and linking the application is done +through the Build menu. Call it up and select +Run automake and friends. + + + + + + +Initiating a basic initialization run. + + + + +&kdevelop; will now open the Messages 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 +*** Success ***. + +If you scroll back to the top, you will find the command line, &kdevelop; +issued to call up the tools beneath the surface: + + +cd '/home/devel/projects/hello' && \ +WANT_AUTOCONF_2_5="1" WANT_AUTOMAKE_1_6="1" gmake -f Makefile.cvs + + +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 autoconf and +automake tool revisions used for this initialization. +And finally it instructed the make tool (&GNU; gmake +in this case) to process the Makefile.cvs make file. + +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 configure skript file necessary to perform the +next setup step. + + + +Initial Hello Configuration + +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. + +You can command a configure sequence once the basic automake +initialization has been successfully finished because only after this +initial run the necessary configure files will be +available. This done, select the Build +Run Configure menu entry to initiate a +configuration sequence. + +&kdevelop; opened the Messages tool view +window again if necessary and listed the messages of the configure run therein. +If all went right, the final messages will be Good - your +configure finished. Start make now (which was issued by +configure) followed by the &kdevelop; *** Success +*** message. + +On top of the +Messages window you will again find +the command line, &kdevelop; used to initiate this configuration run: + + +mkdir '/home/devel/projects/hello/debug' && \ +cd '/home/devel/projects/hello/debug' && \ +CXXFLAGS="-O0 -g3" "/home/devel/projects/hello/configure" --enable-debug=full + + +You can tell several interesting details from these commands. + + + + + + + + + + + + + +First, &kdevelop; uses a dedicated subdirectory in the project directory +tree for the build process. This debug +build directory (shown to the left) mirrors the basic project structure and +contains some set of build related files, such as several +configure based files and additionally a +Makefile in each subdirectory. + + +In the Configuring the +Project +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 debug directory — if necessary — prior +to the configure call and that the configure script did +build the sub structure and all the Makefiles in +there. + + +Next, from within the debug build +directory, &kdevelop; called the configure script in the +root directory of our project using a dedicated environment, where the +CXXFLAGS="-O0 -g3" flags will later signal the +&gcc; compiler that it should not optimize the resulting binaries and include +full debugging information with them. + + +Finally the configure script was called with the +--enable-debug=full option which instructs it +to create each Makefile so that later compilation and +linking will have all necessary debugging information be built in and +usable. + + + + + + +All these settings are configurable on a per project basis. You will learn +more about this in the Project +Management chapter. + + + +Build the Project + +Once you got this far you will be ready to actually build, &ie; +compile and link the application. Looking at the Build menu, +there are three such compile options from which to select. + + + + + + +&kdevelop; commands to build binaries. + + + +Going from bottom to top, there are: + + +Compile File — This will compile the +source file in the currently open editor window. Mostly used for quick error +checks. + + +Build Active Target — This is mainly used +in conjunction with the Automake +Manager which we will briefly look at below. + + +Build Project — Now this is what we +currently are interested in. It will iterate over the whole project, compiling +and linking all files as necessary. + + + +It might be interesting to watch what happens to the +Debug directory created in the former +configure run. So best keep it open with all +subdirectories unfolded just as shown above. Then select +Build Build +Project (or press the F8 key) to +initiate the build sequence. As before, the Messages tool +view window will open at the bottom and list the outcome of this build run. And +additionally some files will appear on the Debug subtree. + +There are not many source +files in our Hello example project, so the Messages window +will contain only a few lines. On top of them again find the command line +&kdevelop; issued to the underlying shell. + + +cd '/home/devel/projects/hello/debug' && \ +WANT_AUTOCONF_2_5="1" WANT_AUTOMAKE_1_6="1" gmake -k + + +Not very surprisingly, &kdevelop; switched to the Debug subtree root in order to run the +Makefile located there. A dedicated sub-environment was +set up again as before in the Initialization step in which +then the gmake tool was called. + +Note the -k option in the +gmake 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 Messages window. If +there are any, use the virtues of an &IDE;: Just click on the error message in +the Messages window and &kdevelop; will take you to +exactly the position where the error occurred in the source file. + +And what did happen inside the Debug subtree? Not very much. A few files showed up +on the doc/en and src branches, most notably the +hello file in /home/devel/projects/hello/debug/src/. 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 +hello. + + + +Run the Application + +There are no extra steps involved to run this new Hello +application. Either select Build +Execute Program or press +Shift F9 or use the +Execute program button on the Build +Toolbar shown below. + + + + + + +Running an application form the Build +Toolbar. + + + + +That was all. &kdevelop; will now start the new application in +the dedicated console window which opens as Application +tool view on the bottom. There the command &kdevelop; issued to execute the +program will be shown in the top line: + + +./hello + + +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 Project +Management chapter. + +The ./hello line will most likely +be followed by a warning message. Ignore this for now. It does not keep +our Hello form running. + + + + + + + +Our initial Hello application. + + + + +Close the Hello application window as +usual. If no errors occurred, &kdevelop; will report this as +*** Exited normally *** +in the Application tool view window. + + + + +Configuring the Project + +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. + + + +Of what use are build +configurations? + +Where to the define +the behavior of the configure script. + +Some considerations +how make should run. + +Where should the +executable be and how should it be called? + + + +Build Configurations + +When we did a first run of the configure script in +the Initial Hello +Configuration section above, we noted that &kdevelop; had set up a +dedicated debug subdirectory for this +purpose. In this section we will briefly consider some consequences of +this feature. + +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. + +To find out which build configurations currently are available, have a +look at the Project Build +Configuration menu. + + + + + + +There are various build configurations available +for this project. + + + +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 +default. + +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. + +Now let us have a brief look at what these build configurations +provide. + + + +debug + +You should use this as the standard build configuration during the +development process. The build occurs separately from the source directories in +the dedicated debug subdirectory, &ie; +all object, auxiliary, and executable files will be put in the subdirectories +there instead of their counterparts in the project root. The +configure script will be given the +--enable-debug=full option and the +CXXFLAGS="-O0 -g3" will signal the &gcc; +compiler to not optimize the code and to insert extensive debug information +into the resulting binaries. + + + + +optimized + +This is used to build a final C++ application. The build occurs +separately from the source directories in the dedicated optimized subdirectory. No specific arguments to +the configure script will be preset, yet the +CXXFLAGS="-O2 -g0" will signal the &gcc; +compiler to optimize the code and to not insert debug information into the +resulting binaries. + + + + +default + +The term default denotes the standard setup when you build +an application from the console using ⪚ the &GNU; +configure and +make/gmake command line +oriented build tools. Other than debug or +optimize 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.). + + +Think twice before you decide to use the +default build environment! + +It cannot be used in parallel to the dedicated +debug or optimized ones. +Any build operation using default will +render both of the other build environments unusable. This is caused +by some peculiarities of the Makefile construction process +using the +automake/autoconf +machinery, which cannot be easily overcome. + + + + + +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. + +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. + +Thus instead of cleaning up and recompile everything from scratch with +alternate options, you need only switch from the +debug to the optimize +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 debug and immediately continue +your work there. + +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. + + + +Project Configure Options + +Configuring the application properly is vital in the &GNU; +autotools building chain. This is usually guided by option definitions to the +configure script and/or specific flags settings in the +environment prior to running configure as ⪚ the +CXXFLAGS in our previous discussions. + +You may set most of the configuring options for a given project from +within &kdevelop; &GUI;. Select +Project +Project Options and then from the +icon bar on the left of the dialog the Configure Options +icon. The Configure Options dialog featuring several tabbed +windows will display on the right handed side. + + + + + + +Most configure options can be defined here. + + + +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 Configuring Projects chapter. If you +want to know more about the meaning of the various flags which can be +set, look up info make from the console (or +info:make from within &konqueror;) and there the +Implicit Rules +Implicit Variables section. + +There are several tabbed dialog setup windows from which the first +one, General, 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. + +You select the build configuration whose configuration settings +have to be defined from the Configuration combo box +on top of the Configure Options dialog. + + + + + + +Select the build configuration whose settings to +define. + + + +Now select another build configuration from this combo box and note how +the contents of ⪚ the Configure arguments and +Build directory text boxes change according to the +settings we mentioned in the build +configurations list above. + + +General Configuration Settings + +On the General dialog page, these +configuration options can be defined: + + + + +Configure arguments +These are the options &kdevelop; assigns to the +configure script call in the build process. See the +example in +the Initial Hello Configuration section above. + + + + + +Build directory +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. + + + + + +Top source directory +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. + + + + + +C/C++ preprocessor flags (CPPFLAGS) +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 example in +the Initial Hello Configuration section above how this is +done. + + + + + +Linker flags (LDFLAGS) +This is extra information for the ld linker +tool where it should look for additional libraries. It is used to build the +temporary build environment as well. + + + + + +Environment Variables +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. + + + + + + +Compiler Specific Settings + +The other tabs on the Configure Options dialog +page are for compiler specific settings. They are similarly structured, +so it suffices to have a brief look at the C++ page. + + + + + + +Select the compiler and its working environment &kdevelop; shall +use here. + + + +This is what you can set up from here: + + + + +C++ compiler +Select the C++ compiler &kdevelop; should regularly use from this +combo box. It however lists only those compilers &kdevelop; really knows +of. + + + + + +Compiler command (CXX) +Only for experts. This is only needed if the C++ compiler is not standard. +Put the name by which it is called here. + + + + + +Compiler flags (CXXFLAGS) +Here you can enter any extra option &kdevelop; shall pass (via the +Makefile) to the compiler. Some option values will be +preset according to the build configuration selected in the +Configuration combo box. + + +Note, that many common compiler options can be selected from a +dialog which will pop up when you press the ... button to +the right of the text box. + + + + + + +Use this dialog to define the &GNU; C++ compiler +behavior. + + + +We deliberately selected the Optimization tab +here. Note how the No Optimization option has been +preselected (according to the -O0 +option preset in the debug build +configuration). + +Unfortunately you cannot currently select all options from this +dialog. The -g3 option ⪚ used by the +debug build +configuration would have to be altered manually if ever needed. + + + + + + +How Make Should Build the Program + +You can as well configure the way &kdevelop; will call the +make tool in the project build. Select +Project +Project Options and then the +Make Options icon from the left dialog window side. The +Make Options dialog page will then be displayed to +the right. + + + + + + +Define how &kdevelop; will call the +make tool. + + + +There is not much to do here for now. The only setting of interest in +most cases will be the Abort on first error switch. +You will find it deactivated in most projects. This corresponds to the +-k option in the +gmake call we found in the initial build of +our example Hello project. + +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 Messages tool +window. Use View +Next Error and +View Previous +Error or respectively the F4 and +Shift F4 keys for this. +&kdevelop; will automatically activate the editor window of the source file in +question and put the cursor on the error line. + +If on the other hand you rather want the build be stopped on whenever an +error occurs, check the Abort on first error option +in this dialog. &kdevelop; will then call gmake +without the -k option. + + + +How to Run the Executable + +Once the build is complete, you can easily run the application from within +&kdevelop;. Use either Build +Execute Program, the +Shift F9 keys, or the +Execute program button in the Build +Toolbar of &kdevelop;. + + + + + + +Run the program from here. + + + +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? + +All this can be solved by configuring some project oriented run options in +&kdevelop;. Select Project +Project Options and then the +Run Options icon from the icon bar on the left dialog window +side. The Run Options dialog page will display to the +right. + + + + + + +Define where and how your program shall be run. + + + +Now, there is quite a lot which can be set up from this dialog. +Basically there are four groups of configuration items. + + + + +Directory +This tells &kdevelop; where it basically shall assume the +executable to be called. There are three possibilities you can select +from. + + +Note however that only root directories are defined here. +&kdevelop; usually looks for the executable in some subdirectory +given in the next configuration group. + + + +Run from the directory, where the executable was build the last +time. This is the default. You can keep this for now. + + + +Run from the build directory according to the currently selected +build configuration. +The name of this directory was set up on the General +Configuration dialog page. + +This is the root where &kdevelop; will find the executable. It +changes automatically with the selection you made in +Project +Build Configurations menu. Try it. + +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 Project +menu. + + + +Run the executable found in a fixed custom directory. Again +this is the root only from where the actual executable is to be +found. + +Use this if you ⪚ want to run the actually installed program instead of +the version located in the project directories. + + + + + + +Program +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. + + + +If leave the Main program text box empty, the +active target 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. + + + + + +Environment Variables +&kdevelop; will set up a dedicated shell environment to run the +program in. Define any extra environment variable in this configuration +group. + + + + + +Miscellaneous +Two more check boxes are located at the bottom of this dialog page. + + + + +Automatically compile before execution 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. + +Uncheck this in case you want to run the program version prior to the +last change. + + + +Start in external terminal 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. + + + + + + + + + +How to Extend a Project — the &automanag; + +(- to be written -) + + +A Short Look at the Automake Machinery + +(- to be written -) + + + +How to Place Icons in a Separate Directory + +(- to be written -) + + + +How to Add New Classes + +(- to be written -) + + +Be careful when you select your class file names. It is extremely difficult to +change them later. + + + +What is in a Subproject? + +(- to be written -) + + +Concentrate on Your Work — the Active Target + +(- to be written -) + + + + +Some Steps to Restructure a Project + +(- to be written -) + + + + + +How to Debug + +(- to be written -) + + + + +A Note on Your Project Documentation + +The &kde; project uses docbook for +generating your project handbook (&ie; the user manual). The user manual is +available through your application menubar by choosing +Help +YourApplication +Handbook 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. + +All &kde; based templates in &kdevelop; have a doc subdir which contains +a index.docbook template in the en folder to get you +started in writing the user manual. You should edit this +index.docbook 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;. +You need to install your project using +Build +Install or Install (as +root user) in &kdevelop; to see the user manual in +&khelpcenter;. +You can find more about the docbook syntax on the &kde; documentation +website. + + + +Last But Not Least, Keyboard Shortcuts + +(- to be written -) + + + +Where to go from here + +(- to be written -) + + +Frequently Encountered Problems + + +The nutshell chapter +FAQ pages +Forum +Mailing lists + + + + +Working With Projects + +(- to be written -) + + +Using Existing &kdevelop; Projects + +(- to be written -) + + + +Importing External Projects + +(- to be written -) + + + + + -- cgit v1.2.3