Before any significant work can be done with &kapp;, the user needs to define a project. A &kapp; project is a set of source files, which Cscope uses to create its cross-reference database. Unlike many other project-based environments, &kapp; is not intrusive: it only uses three files to define the project (with additional two files if the inverted index option is used). These files reside on a user-specified folder that does not have to be related to the location of the source files. Thus, &kapp; does not require any source files to be moved, and does not affect the structure of the source tree. The files used by a &kapp; project are: cscope.proj The project's configuration file cscope.files A list of all source files included in the project cscope.out Cscope's cross-reference database cscope.in.out An inverted index file (optional) cscope.po.out An inverted index file (optional) The only limitation imposed by &kapp; is that these files have to reside in the same directory, referred to as the project's directory. The project's directory has the same name as the project (which means that project names should conform to the file-system conventions), and can be placed by the user under any directory. Normally, a user will create a projects sub-directory under his or her home directory, and create all projects there. However, this is only a convention, and, as explained above, the user can choose any other method he or she prefers. Furthermore, the project's directory can later be moved to another parent directory, without any risk of data loss. The first step in working with projects is to create a new one. This is done by choosing the ProjectsNew... command from the main menu. Issuing this command opens the New Project dialogue. The dialogue consists of three pages: Details, File Types and Options. Note that this dialogue is intended for creating an empty project only, and has nothing to do with the actual source files of the project. This task is left to the Project Files dialogue. The Project Details page The Project Details page Name The name of the project. Note that this name will be given to the project's directory, and should therefore comply with the file-system convention for directory names (e.g., no spaces). Path The full path of the directory under which the new project will be created. &kapp; will create a new directory under this one, and name it after the project. Thus this path does not need to point directly to the project's directory, but rather to the project's parent directory. For example, if a user wants to create a project called "my_project" under his local projects directory, the project's name should be set to "my_project" and the path to /home/my_username/projects. This will set the project's directory to /home/my_username/projects/my_project. Source Root (Optional) The top-level directory that contains the source files to be included in the project. This path only serves as a hint to &kapp;, as files may later be added from different directories as well By default, this value is set to the root directory. The File Types page The File Types page This Project A list of file name patterns that are used to define the type of source files to be included in the project. By default, C source files (.c) and C header files (.h) are included, but other types (including Lex's .l files and Yacc's .y files) can be added. Available Types A list of standard file types that can be included in a project. To add a type, highlight its entry in the list, and click the Add button. Custom types can also be added, by typing in shell-style patterns in the edit-box at the top of the list. Add Adds the currently selected file type to the project. Remove Removes the currently selected file types from the project. The file type is added to the list of available types. The Project Options page The Project Options page Kernel project Mark this check-box if the project is designated to be a kernel-style project. For kernel projects, Cscope ignores the system's include files when building the cross-reference database (i.e., printf will not be found in /usr/include/stdio.h). Build inverted index Cscope can build an inverted index for the project to speed up queries (though at the expense of more time spent on building and refreshing the database). Do not compress the database Builds cross-reference database without compression. This will create a larger, but human-readable database. Slower, but more accurate, function definition detection Applies a huristic that can overcome Cscope's inability to detect function declarations with function pointers as parameters. Requires a patch to Cscope. Refresh database automatically &kapp; can rebuild the cross-reference database automatically, a process which is triggered when a source file is saved. If this option is selected, the user needs to specify the time (in seconds) that should elapse after each file save operation and before the database is rebuilt. Use symbol auto-completion Enables automatic "as-you-type" symbol completion. Note that manual symbol completion is always available, regardless of whether this option is selected. If you choose to enable this option, it is recommended that you also select the inverted index option. Options... Displays the symbol auto-completion configuration dialogue. This button is only enabled if the symbol auto-completion is selected (see Automatic Symbol Completion for a description of this dialogue). Override default tab width (Kate only) Use a per-project tab-width (overriding the editor's settings). Helps when browsing code bases that use different styles than the user's preferred one. OK Accepts the values entered in the dialogue, and creates a new project. If any mandatory values were omitted, or not entered correctly, the user is prompted. Cancel Closes the dialogue without creating a new project. The project's list of source files is maintained by the Project Files dialogue. This dialogue allows the user to add source files to a project, or remove files currently included in it. The dialogue is invoked automatically after a new project has been created, or manually by selecting the ProjectAdd/Remove Files... command from the main menu. The Project Files dialogue The Project Files dialogue File Path Displays a list of all source files included in the project. Note that when adding and removing files, the project itself is not modified until the OK button is clicked. Filter Hides all files whose path names do not include the text entered in the edit-box to the left of the button. This can simplify the task of finding files in the project. The filter text can be any simplified regular expression (as given to file commands in a shell). Show All Reveals any files formerly hidden with the Filter button. Add All buttons in this group add files to the current project. Files... Adds user-selected files to the current project. Directory... Adds all source files in a directory to the current project. Source files are scanned according to the file-types associated with the project. Note that sub-directories are not scanned for files. Tree... Adds all source files in a selected directory and its sub-directories to the current project. Source files are scanned according to the file-types associated with the project. Remove All buttons in this group remove files from the current project. Selected Removes all selected files from the current project. Files can be selected for removal by clicking their path name in the file list. The Ctrl key can be used to select multiple files, and the Shift key can be used to select ranges of files. Directory... Removes all source files in a directory from the current project. Note that sub-directories are not included. Tree... Removes all source files in a directory and any of its sub-directories from the current project. OK Accepts the new list of source files, and updates the project. Cancel Closes the dialogue without modifying the list of project files. Once the list of project files changes (either when files are first added to the project, or upon any subsequent modification), &kapp; informs Cscope to rebuild the cross-reference database. Existing projects can be opened using the ProjectOpen... menu command. Choosing this command invokes the Open Project dialogue, which allows the user to select the project to open. The Open Project dialogue The Open Project dialogue Project Path The full path of the project directory. Use the browser button to locate a project by its configuration file (cscope.proj). Recent Projects Displays a list of recently-opened projects. Clicking a list item copies its path to the Project Path edit-box, while double-clicking an item opens the project. Remove Removes an entry from the list of recently-opened projects. Open Opens the project whose directory is set in the Project Path edit-box. Cancel Closes the dialogue without opening a project. When a project is closed, it saves session information, such as source files being edited and the contents of locked queries. The session is restored when that project is opened again. After the project has been opened, &kapp; will invoke Cscope, which, in turn, will check whether any files have been modified since the last time the project had been closed. If any files have changed, Cscope will rebuild the cross-reference database. The properties of an open project can be changed by choosing the ProjectProperties... menu command. This command invokes the Project Properties dialogue, which is similar to the New Project dialogue, except that the name and path of the project cannot be changed. See the New Project dialogue for a description of the available project options. Temporary projects are created when a user opens a cscope.out file directly. This option is useful for working on projects created by some other Cscope front-end (Cscope's ncurses interface, Vi, >Emacs, etc.), or simply using Cscope's -b command-line parameter. To open a database file, use the ProjectOpen Cscope.out... menu command. If the file is a valid Cscope cross-reference database, &kapp; will invoke Cscope using this file, and will be ready to accept queries on the database. Cscope.out files can also be opened through the command line, which means that you can simply drag a Cscope.out file, and drop it over &kapp;'s programme icon. Note, however, that most project management options provided by &kapp; will not be available for temporary projects: the file list for the project will be empty, users will not be able to add or remove files, and the project properties dialogue will not be available. You will also need to rebuild the database manually when making any changes. &kapp;'s rebuild command assumes the database has been updated, and only re-runs Cscope. While &kapp; was not designed as an IDE with a complete write-build-debug cycle, it does provide a simple GUI for building projects. The command ProjectMake Project displays a dialogue, which can be used to invoke any external tool on a given directory. By default, it runs make on the project's source root. The output of the command will be displayed in the dialogue's Output pane, with any errors or warnings marked-up, similar to links in a browser. Clicking on a link will jump to an editor page showing the source file and line responsible for the message. A list of all abnormal messages also appears in the dialogue's Errors and Warnings pane. The Make Project dialogue The Make Project dialogue Root Directory The directory in which to run the build command. Command The command to execute. Make Executes the build command. Stop Halts an executing build process. Close Closes the dialogue.