BerndPol &appwizard; In &kdevelop; software development work is organized in projects. Such a project keeps everything together which belongs to a complete programming task: source files, additional data files, any actually needed management facilities as the make system as well as access to all components and any additional tools needed to get the application up and running. Organizing all development work in projects allows you to easily switch between the global tasks at hand. This is quite handy if you ⪚ work on several applications at the same time as is often the case. Tell &kdevelop; to open the project you want to work at and you may proceed in the environment just where you left. project new Whenever you want to initiate a new programming project quite a lot of formal setup procedures need to be done. An initial directory structure has to be set up, initial header and source files must be provided, the make system has to be initialized, &etc; &kdevelop; provides an easy way to initiate a new programming project—the &appwizard;. You will find the &appwizard; at menu entry Project New Project. Only a short series of steps is necessary to start a new programming project, using the &appwizard;: Select the programming language you want to use and the type of the application you want to build from a set of predefined templates. Supply some general information as application name, directory where the application shall be built, &etc; Decide whether you want to use a version control system, like ⪚ CVS, and supply the necessary data if needed. Set up some templates for initial header and source files (if applicable). Finally tell &appwizard; to set up all initial stuff, directory structure, starting header/source file templates, and management tools, like ⪚ an initial make skeleton, &etc; Voilà—that's all. &appwizard; will have provided you with a primary functional set of programming files, where you can readily start working. Let's look at all this in more detail now ... dialog create new project project create new project dialog project templates templates project To create a new project in &kdevelop;, select New Project from the Project menu. The Create New Project dialog will pop up showing an initial General page: Initial dialog to set up a new project As you see, this dialog is divided into an upper and a lower part. In the upper part you can decide on the programming language and application type, the lower part holds some general information. project application type project programming language project language language programming language application type The left hand side of the upper part in this dialog is where you do the selection work. When it shows up, you'll find there a list of folders each labeled with a programming language, as there are: Ada Ada new project C C new project C++ C++ new project Database (SQL Projects) SQL new project Database new project Fortran Fortran new project Haskell Haskell new project Java Java new project PHP PHP new project Pascal Pascal new project Perl Perl new project Python Python new project Ruby Ruby new project Shell (Scripts for the Bash Shell) Bash new project shell new project To be precise, these folders do not contain real programming tools actually. They do lead to pre-defined templates you can use as a starting point for development in that language. To get an idea of what is provided, just open the folders one after the other. There will be a series of subfolders on some, one or more simple entries only on others. The subfolders you see organize the available templates according to some tasks, the simple entries name the templates you may select. We cannot go into detail here on which tasks each template provides, but it's easy to find out. Whenever you select a template entry some information is displayed in the fields to the right. In the lower field you will find a short description on what the template is supposed to do. In the field above that a picture will be shown, if available, about the outcome of the application this template produces if you compile and run it unmodified. Usually this is a screenshot of the main window the application will display. Select the template which best fits your application's goals as a starting point. Then enter the general properties information in the lower field as shown in the next chapter. Each template is bound to a specific Project Management System. Currently there is no direct means to freely select such a Project Management System. You have to find a template which suits your needs or alter your project accordingly after creation. project properties properties application name name application project directory directory project path new project project author project email author email project main.cpp main.cpp project license license The lower part of the Create New Project dialog General page is a framed field labeled Properties. You must provide some general information about your project here so that the &appwizard; knows how to build the initial structure. Your application needs a name of course. Enter this in the uppermost Properties field, called Application Name. We use MyApp as an example. When you do so, you will notice that the &appwizard; refuses to accept special characters of any kind. The only characters accepted are: upper and lower case characters numbers the underline character One prominent cause of this restriction is that the &appwizard; will use this application name as the basis of some class names it will construct when it sets up an initial project. Thus the name of the application must stick to the rules of the programming language you use. The other prominent cause of this restriction you can see at the bottom line of the Properties area. It is labeled Final location and shows the directory where the &appwizard; will create the application. As you type the application name you will notice that the &appwizard; repeats your input at the end of the Final location line, using lower case only characters. Thus you must select the name of your new application with care. If you end up with an already used directory the &appwizard; will not allow you to continue to the next step, keeping the Next > button deactivated (grayed). Yet, it will warn you in this case by appending (dir/file already exist) to the Final location line. There are two ways to select another path for your new application. One is to select another name. Yet, this is not always feasible (you might ⪚ set up for another version of an already existing application). As an alternative you may select another path to the application directory. This is done in the second row input field of the Properties, named Location. What you enter here is the starting path of the new application development directory. The &appwizard; appends the application name to this path when it initializes the new project. The result is shown in the Final location line to give you better control on what is going on. &appwizard; will copy an initial value to the Location field on start-up. This is taken from what you have chosen in the Default projects directory field during the general configuration steps. In our case we have &kdevelop; set up to use /home/devel/projects/ as initial path for new projects. Alter the Location field contents so that the application development directory shown in the Final location line will be unique. Take care that the path you enter in the Location field already exists. Otherwise you will not be able to continue to the next step. The &appwizard; will warn you about non-existing paths by appending (invalid) to the Final location line. Set new project up for CVS The fields following this are not so critical. Just supply your name (&ie; the name of the person who is responsible for the application) in the Author field, and a valid e-mail address in the Email field, so that users can give you feedback on the application. The &appwizard; fills these fields with some default values, taken from the Email presets in the &kcontrolcenter;. If these defaults in the Create New Project Author and Email fields do not suit, you may want to have a look at your mail configuration in the &kcontrolcenter;. The &appwizard; will integrate this information into the starting program templates if applicable. In &kde; C++ programs for instance you will find it near the beginning of the main.cpp source file. Of all fields, the Email is optional, reflecting the fact that not every developer may have access to the internet. You may keep this field empty if you wish and proceed nevertheless. Finally enter a starting version number for your new application in the Version field, and select the license under which you want your application be put from the License tab. If you select an application type for which the &appwizard; provides common source template texts (⪚ C/C++), you may view the license notification text on the third page of this Create New Project dialog (see the Supply header/source templates chapter below). If you selected Custom from the License tab you must provide a license text on your own. Both version and license information will as well be integrated into the starting templates in a suiting format the application type you selected does provide. Once you have correctly entered all this information stuff, press the Next > button to proceed as shown in the following chapters. CVS new project project CVS database CVS version database version CVS In a second step the &appwizard; will lead you to the Version Control System page where you can decide which version control system you want to use. This discussion concentrates on the needs for project creation only. For more information on &CVS; see the Using &CVS; chapter below. Initially there is None selected in the Version control system tab, and the page will be empty otherwise. If you don't want to use a version control system, just click the Next > button and go on. Otherwise you must reselect the version control system you want to use from the Version control system tab. We use &cvs; for our example. If you select this, the &appwizard; will redisplay the page, now showing a series of fields you must fill in. Set new project up for CVS A version control system such as &CVS; (which means Concurrent Versions System) stores copies of selected project files in some sort of a database. If you use &CVS; you can amongst others upload (commit) those files or load them back into your project directory (checkout, or update). The special thing about this is that the files in the versioning database are stored in a structured way which allows you to always revert to an earlier development state if you need so. And &CVS; allows multiple designers to fairly easily collaborate on a big project (such as &kdevelop;) without disturbing each others work. CVS root root CVS CVS local CVS remote local CVS :local: CVS :local: &CVS; needs to manage the versioning database it keeps from your project files. To accomplish this it keeps some special database information in an own directory, called the &CVS; root. The first step on setting up &CVS; for your new project thus is to tell &kdevelop; where this root is located. Local &CVS; root. There are two basic possibilities. Either you want to use a local &CVS; database or you use a database which is held on a remote server. If you develop for your own, you may want use the &CVS; database as some sort of a backup system on your own computer. Usually this is set up in your home directory root and given the name cvsroot. This may look as follows: /home/devel/cvsroot (where devel simply denotes the developing user, just for example) In fact, this is a short form. Exactly, the local &CVS; root should be addressed using the :local: prefix. The short form is only allowed in cases where the filename starts with a slash (/). The full name for our example local &CVS; root would exactly look like: :local:/home/devel/cvsroot Enter the name of the &CVS; root directory your system has been set up for in the CVS root field. In principle you can select any name, even use multiple &CVS; databases, but it is advisable that you stick to the &CVS; root once set up. Initialize a new &CVS; root. If there does not exist a &CVS; root yet, &kdevelop; can command the &CVS; system to create one for you in the given directory. Just check the Init root checkbox below the CVS root field. As said, &kdevelop; only commands the &CVS; system to initialize a new &CVS; root. It does nothing by itself to this directory. Fortunately &CVS; is clever enough to check whether the &CVS; root directory already exists. Hence it does no harm if you should have inadvertently checked Init root on an already existing &CVS; root directory. Remote &CVS; root. There are occasions where the &CVS; database is to be kept on a remote server, especially when several developers work at the same project. Then you must enter the &CVS; root &URL; of this server in the CVS root field. For example, if you want access to the &kde; &CVS; server: :pserver:mylogin@cvs.kde.org:/home/kde (where mylogin denotes the login name set up in your &kde; &CVS; account) remote CVS :pserver: :ext: CVS :local: CVS :pserver: CVS :ext: Basically there are two widely used remote &CVS; server types, the pserver which uses a password-secured non-encrypted protocol, and the ext server which uses an rsh or ssh encrypted data transfer. They are distinguished by the &URL; prefix they use: :pserver: for the password protected server non-encrypted type, and :ext: for an rsh or ssh encrypted server type. For example :ext:mylogin@cvs.cervisia.sourceforge.net:/cvsroot/cervisia accesses the &CVS; root of the widely used Cervisia &CVS; management tool on the SourceForge server. If you want to use an rsh or ssh encrypted server for &CVS; access you must tell &kdevelop; the encryption protocol to be used. Just enter rsh or ssh in the CVS_RSH field of the Create New Project Version Control System page. There is a caveat if you use an encrypted server for &CVS; from within &kdevelop;. See the Using &CVS; chapter for details. CVS repository repository CVS So far you have told &kdevelop; where the &CVS; root resides which manages the versioning database and how to access it. Now you need to tell &kdevelop; under which name you want &CVS; save your project files in that database. Such a place your project files will be held in &CVS; is called a repository. In principle you can use any name for the &CVS; repository of your project files as long as it adheres to the specifications of naming a file. Yet, most developers simply use the name of the application itself. &CVS; will build a directory with this name in the &CVS; root, hence it is more easily found if you keep the application name for it. Just enter the repository name you want to use in the CVS repository field of the Create New Project Version Control System page. In our example this is: MyApp Take care not to use a repository which already exists! The &CVS; system does not warn about duplicate files but will shovel everything in which does not produce a formal conflict. You will mess up everything! There is not much work left to do. &appwizard; has already set up the remaining fields for you. In detail: The Vendor field is used for compatibility reasons only. You can stick to the vendor default the &appwizard; puts in here. The Message field allows you to comment the initial &CVS; contents. Use any text you like or just stick to the new project default the &appwizard; did put in. The Release tag holds the name which tags the initial state of your project. Such a tag names a certain point within the &CVS; repository by which you can later access this state of your development. (See more in the Using &CVS; chapter.) The &appwizard; has put a default start tag in here which is a worthy proposal. Just stick to it. When any information of all these is wrong &kdevelop; usually will not know about until project construction time. It is the &CVS; system which will figure out those errors when it tries to build the repository. Hence you must keep an eye to the Messages window of &kdevelop; when the project is created in the final setup step. If anything was in error with &CVS; you will in most cases see an error message like this: * cd '/home/devel/test' && cvs -d '/home/devel/mycvsroot' \ import -m 'new project' '' 'vendor' 'start' &&\ sh /opt/kde3/share/apps/kdevcvs/buildcvs.sh . '' \ '/home/devel/mycvsroot' * cvs [import aborted]: /home/devel/mycvsroot/CVSROOT: No such file or directory * *** Exited with status: 1 *** If this happens you will have to either manually set up &CVS; (&kdevelop; should have successfully initialized your project files at this time) or delete the project directory and start over again with New Project from the Project menu. After you have entered all &CVS; related information, click the Next > to go on. If you want to correct an error on the previous Create New Project page, just press the < Back button. The &appwizard; will remember your settings on the current page, so you can easily proceed when you come back. The next step brings you to a series of pages where you can set up common information you want to include in your source and header files, if the task at hand allows. Both header and source templates are provided for C and C++ applications, each on its own page. For other languages there may be source templates only. And in some cases you will even find this template page empty. If the page is used, &appwizard; will fill in some common header comment which for a C++ based application might look like: /*************************************************************************** * Copyright (C) 2003 by Your Name * * you@you.com * * * * This program is free software; you can redistribute it and/or modify * * it under the terms of the GNU General Public License as published by * * the Free Software Foundation; either version 2 of the License, or * * (at your option) any later version. * * * * This program is distributed in the hope that it will be useful, * * but WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * * GNU General Public License for more details. * * * * You should have received a copy of the GNU General Public License * * along with this program; if not, write to the * * Free Software Foundation, Inc., * * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ Other templates will provide similar information in a format according to the definitions of the programming language you want to use. As you might have noticed, the applications manager did readily fill in some information you provided on the first General page of the Create New Project dialog, namely the contents of the Author and Email fields. Also proper license information will have been inserted according to your selection in the License tab. templates project edit project templates edit The templates you set up in the Create New Project dialog will later be processed whenever you command &kdevelop; to set up a new source and/or header file. The information you provided here will be included at top as a documentation header, before the code parts begin. You are not restricted to plain text however. &kdevelop; knows of several variables which allow you to include actual information in the file. The &appwizard; did in fact use some such variables to insert the Author, Email, and License informations into the initial template text. Include &doxygen; File Information If, for example, you want the &doxygen;-built &API; documentation to display some further information about the file's contents in its filenames list, you may include the following lines in the source file template: /** * \file $MODULE$.cpp * \brief (put some short descripion here). **/ Whenever you create a new source file, &kdevelop; will replace the $MODULE$ variable by the name body of the newly created file. For example, if you created a new C++ class named ASimpleTest you will see the following lines in the asimpletest.cpp file: /** * \file asimpletest.cpp * \brief (put some short descripion here). **/ You will still have to provide the short description after the \brief keyword, but part of the job is automatically done for you. The License Text File As another example you could include an explicit hint to the license text you want to use into the template. Use the $LICENSEFILE$ variable for this and add for example this line: // See $LICENSEFILE$ for the full license text. The &appwizard; will replace the $LICENSEFILE$ with the name of the file where the full license text is to be found, namely: // See COPYING for the full license text. for the GPL license, or // See LICENSE.BSD for the full license text. if you decided to put your application under the BSD license. Thee are of course more variables &kdevelop; knows of. See the Editing the templates section in the Editing tools chapter for what is possible. The templates you define here will come in effect only after the &appwizard; has created the new project. You will find this information on top of the files you created yourself in the development process. When creating the initial files the &appwizard; will use some predefined standard templates. You will have to manually adapt those initial files to your needs. project new build project initial build Almost everything is done now. On the last templates page the Next > button will have changed to read Finish now. Think twice before you click on it! You still have the option to revise everything by repeatedly using the < Back button. As the &appwizard; remembers all information you did input so far, it may be advisable for you to take the time and look back once again. In case you use local &CVS;, do not forget to double-check the &CVS; repository name (there should be no subdirectory with that name in the &CVS; root directory already—if it does, try another repository name). If ever you don't want the new project be built, abort the Create New Project dialog by the Cancel button. Otherwise click Finish and watch in the Messages window how the &appwizard; initiates the project. If you want to use a versioning system (&CVS;) there will be two runs actually. &appwizard; will first build the project directories and files and then call up the &CVS; program which restarts the Messages window with its own contents. If any error occurs in either of these runs, the process will stop showing you an according error message in the window. In many cases when your new project has been set up this way, &kdevelop; will automatically load the source file(s) of one or more basically important modules so you can readily start work. (Which source modules will be displayed—if any at all—however depends on the template initially selected in the &appwizard;.) Do not forget to initially check what the &appwizard; has provided. For example you may want to change the initial heading informations according to your own templates. Usually you will find these in a templates subdirectory in your project directory. Some simple copy operations will mostly suffice. Then it is advisable that you compile the initial project before you attempt to change any code. In most cases this initial compilation should be possible. Thus you can make up whether the project really was set up according to your needs. If it was not, simply remove the project directory (in your local &CVS; root as well if you use one) and start over again. default build configuration warning build configurations default build warning warning default build configuration Before you compile your new project the first time, have a look at Project Build Configuration. If there are three selections displayed: default, optimized, and debug, with debug selected, by all means stick to this, or use optimized instead. Due to some limitations in the current autoconf/automake setup you should by no means build in the default configuration. This will corrupt some internal directory settings, thus making configure complain when you try to use it in the optimized, or debug build configuration afterwards. (This applies to these multiselection capabilities only. If the application type you selected provides a default build configuration only, you should of course use this one.) (... to be written ...)