From 5fbf99bcc4d03f3001f42905d1217758c4aeac13 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Wed, 16 Nov 2011 16:06:07 -0600 Subject: Finish rename from prior commit --- doc/kdevelop/getting-started.docbook | 3221 ---------------------------------- 1 file changed, 3221 deletions(-) delete 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 deleted file mode 100644 index 33bfee94..00000000 --- a/doc/kdevelop/getting-started.docbook +++ /dev/null @@ -1,3221 +0,0 @@ - - - - - - - -BerndPol - - - - -Getting Started with &tdevelop; — a Guided Tour - -Now that you have got your new &tdevelop; &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 &tdevelop; &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, &tdevelop; is an Integrated Development -Environment. That means in essence that &tdevelop; 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 &tdevelop; 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 &tdevelop; &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 &tdevelop; 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 &tdevelop; -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 &tdevelop; currently uses, check with the -Settings Configure -KDevelop... User Interface -dialog. - - - -A Very First Look at &tdevelop; - -This is all about what you will see when you first started &tdevelop;. -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 &tdevelop; for the first time you will get a display -similar to this one: - - - - - - - -The &tdevelop; initial layout -(Actually the initial &tdevelop; window will be larger, but the elements -you see are the same.) - - - - - -Workspace Area and Tool View Tabs -In this initial case &tdevelop; 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 &tdevelop; 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 &tdevelop; 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 -&tdevelop; 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 - -&tdevelop; 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 -&tdevelop;'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 &tdevelop;. 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 -&tdevelop;. - - - -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 -&tdevelop;, 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 &tdevelop;. 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 -&tdevelop; 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 -&tdevelop; 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 &tdevelop; configuration, have a look at -the Configuring KDevelop chapter. - - - -Some General Settings - -To configure &tdevelop;, 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 &tdevelop; 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 &tdevelop; 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. - - -&tdevelop; 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 &tdevelop; 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, &tdevelop; has some means of shortening those messages built -in. - - -Depending on the &tdevelop; 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. &tdevelop; -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 &tdevelop; work. - -Open the Documentation tool view at the right side of -the &tdevelop; 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, &tdevelop; 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. - - - - - - -&tdevelop; 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 &tdevelop; 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 -&tdevelop; 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 &tdevelop;. 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, -&tdevelop; organizes software development tasks in -projects. Thus the first practical step to develop software -in &tdevelop; usually is to create a new project. - -Fortunately this is fairly easily accomplished. &tdevelop; 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 &tdevelop; 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, &tdevelop; 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 &tdevelop; (provided you use the proper built in tools for file -creation). &tdevelop; 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 -&tdevelop; to maintain and start the application. - - - -hi16-app-hello.png, and -hi32-app-hello.png contain some initial default icons, -&tdevelop; 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, &tdevelop; 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. - - - - -&tdevelop; Control Files -&tdevelop; needs some control and administration data on its own. These -are located in the project root directory, in our example -hello.tdevelop, hello.tdevelop.pcs, -and hello.kdevses. - - -Of particular importance in each project is the -xxx.tdevelop (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 &tdevelop; -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 &tdevelop;. 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. &tdevelop; 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 -&tdevelop;. 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 -&tdevelop; 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 &tdevelop; 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 - -&tdevelop; 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. &tdevelop; 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, &tdevelop; 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, -&tdevelop; 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 &tdevelop; were -properly installed, &tdevelop; 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. &tdevelop; 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. &tdevelop; 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. &tdevelop; 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, &tdevelop; 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 &tdevelop; 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 -&tdevelop;. - - - -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 &tdevelop;'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, -&tdevelop; 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 &tdevelop; 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 -***. - - - -&tdevelop; 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. &tdevelop; 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. -&tdevelop; 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 &tdevelop; 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. -&tdevelop; 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. &tdevelop; 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 &tdevelop; 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 &tdevelop; 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 -&tdevelop;. - - -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 -&tdevelop;. - - -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, -&tdevelop; 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 &tdevelop;. 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 &tdevelop; 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, &tdevelop; 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 &tdevelop; did navigate to the corresponding default -constructor declaration line. - - - - - - -&tdevelop; 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, &tdevelop; 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 &tdevelop; 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, &tdevelop; will forget the file list -otherwise. - - - - - -That was it. Whenever you select the sources session -from the Open Session drop down box, &tdevelop; 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 &tdevelop; 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 &tdevelop; 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, &tdevelop; 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: - - - - - -&tdevelop; 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, &tdevelop; 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 &tdevelop; 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 &tdevelop; 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 &tdevelop; -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 &tdevelop;. - - - -This discussion implies that your project is based on the &GNU; autotools, -which enabled the &automanag; tool in &tdevelop; 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 -&tdevelop; 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. - - - - -&tdevelop; 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, &tdevelop; -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 &tdevelop; 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. - -&tdevelop; 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 &tdevelop; *** Success -*** message. - -On top of the -Messages window you will again find -the command line, &tdevelop; 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, &tdevelop; 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 -&tdevelop; uses separate build directories in cases like this one. For the -moment it is enough to know that &tdevelop; 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, &tdevelop; 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. - - - - - - -&tdevelop; 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 -&tdevelop; 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, &tdevelop; 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 &tdevelop; -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 &tdevelop; 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. &tdevelop; will now start the new application in -the dedicated console window which opens as Application -tool view on the bottom. There the command &tdevelop; 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, &tdevelop; will report this as -*** Exited normally *** -in the Application tool view window. - - - - -Configuring the Project - -In &tdevelop; 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 &tdevelop; 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, &tdevelop; 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 &tdevelop; 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 &tdevelop; &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 &tdevelop; 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 &tdevelop; -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. &tdevelop; 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, &tdevelop; 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 &tdevelop; shall -use here. - - - -This is what you can set up from here: - - - - -C++ compiler -Select the C++ compiler &tdevelop; should regularly use from this -combo box. It however lists only those compilers &tdevelop; 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 &tdevelop; 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 &tdevelop; 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 &tdevelop; 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 &tdevelop; 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. -&tdevelop; 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. &tdevelop; 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 -&tdevelop;. Use either Build -Execute Program, the -Shift F9 keys, or the -Execute program button in the Build -Toolbar of &tdevelop;. - - - - - - -Run the program from here. - - - -But where is the executable located which should be run? How does -one have &tdevelop; 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 -&tdevelop;. 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 &tdevelop; 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. -&tdevelop; 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 &tdevelop; 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 &tdevelop; 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 &tdevelop; 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 &tdevelop; -appears not to call the executable you wanted. - - - - - -Environment Variables -&tdevelop; 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. &tdevelop; 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 &tdevelop; 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 &tdevelop; 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 &tdevelop; 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 &tdevelop; 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 &tdevelop; Projects - -(- to be written -) - - - -Importing External Projects - -(- to be written -) - - - - - -- cgit v1.2.3