Projects
Projects
The most powerful features of Source Insight are designed around projects. A Source Insight project is a collection of source files, plus associated data files that helps you navigate quickly around your source code.
You can add existing source files, or an entire source tree to a project. You can add files as you create the files inside Source Insight. If new files appear in your source directory or subdirectories, they can also be added automatically to your project by running the Project > Synchronize Files command, or by letting Source
Insight synchronize automatically in the background. You can also have Source Insight maintain a Master File
List for a project, which determines what files are in the project.
Project Features
Source Insight projects have several important features:
•
A project logically groups related files.
•
When you want to open a file, you don't have to specify its drive or directory.
•
Source Insight maintains a symbol database, which contains data about all symbols declarations and references in the project. You can use Source Insight to locate symbols and their references very quickly. When source files are saved, the symbol database is automatically updated incrementally so that Source Insight always "knows" where a symbol is. When files are changed externally, for example by a source control system, Source Insight will automatically synchronize those files with the project
symbol database. See “Symbols and Language Parsing” on page 52.
•
Source Insight can show symbol relationships in the project, such as call trees, reference trees, and class hierarchies.
•
Source Insight maintains a reference index, which greatly speeds up project-wide searches for symbol references. The reference index is updated incrementally as you edit and save your files.
•
Each project has its own session workspace. When a project is opened, all the session state is restored.
When a project is closed, all open files are closed and the workspace is saved.
Inside a Project
A project consists of basically two things: Your source files, and the project data files that Source Insight maintains.
Figure 3.1 The components of a Source Insight project.
Each project contains a list file paths that point to your source files. A project also contains a symbol database, which is maintained by Source Insight. Your source files are parsed by Source Insight and symbol declarations and definitions, and references are recorded in the symbol database. All you have to do is add source
38 Source Insight 4 User Guide
Projects
files to your project; you do not have to generate any other "tag" files. Source Insight does that automatically.
Each project has its own session workspace. The workspace contains session information, such as the list of files that are open and window positions.
The Current Project
Each Source Insight instance allows only one project open at a time. You can have multiple instances of
Source Insight running - each of which can have a different project open.
Sometimes Source Insight will open other secondary projects to search for symbol declarations. These are background projects and you will not be aware that they are opened or closed.
Throughout this documentation, most discussions assume that you have a project open, unless otherwise stated. Whenever there is a difference in the way a command works with and without a project open, it will be noted.
Project Directories
When you create a project, you must specify two directories for each project:
•
Project Data Directory
- this is where Source Insight stores its project data files. For example, the
.siproj file is stored here. By default, Source Insight creates a project data directory inside the
Documents\Source Insight 4.0\Projects
folder when you create a new project.
•
Project Source Directory
- this is typically the root of your local source repository tree. By maintaining these two separate folder locations, you can store your Source Insight data separate from your source files. Furthermore, your Source Insight project data files are kept in your own user data area, and other users on the same machine will not be able to access them. If you want, you may use the same location for both folder locations.
Here is an example of a typical project setup:
Project Data Directory:
C:\Users\John\Documents\Source Insight 4.0\Projects\MyProj which contains the file MyProj.siproj - the main project file.
Project Source Directory:
c:\work\proj1\src which contains your source code, possibly including sub-directories of source code.
To edit the project source directory location, use the Project Settings command. See “Project Settings” on page 277.
Project Source Directory
The project source directory is what you consider the main location of your source files. The project source directory is typically the topmost, or root directory of your source repository. You might think of this as the
"home" directory of the project. Source Insight normalizes project file names relative to this directory when it displays file names. You can actually set the source directory to any location on your disk, after the project is created, by using the Project Settings command. This affects how the source file paths are displayed, because they are displayed relative to that directory.
See “Where do you want to store the project data files?” on page 258.
Once a project is created in a given directory, you can add files to it from any directory and any drive, including network drives, and UNC paths.
Source Insight 4 User Guide 39
Projects
As an example, let's say we are creating a project for a game program. The source tree looks like this:
We have source code in the "presentation", "core", and "core" subdirectories. Our Source Insight project will include files from all these directories. We should specify c:\game as the project source directory when we create the project so that all file paths will look relative to that directory.
Normalized File Names
When Source Insight displays a file name and the file is part of a project, it arranges the name and path to make it easier to see and select the base file name without all the directory paths getting in the way. This process is called normalizing the file name. This is an important feature because many projects have files spread out across multiple subdirectories; and "flattening" out the directory tree makes it easy to type and select the most significant part of file names.
A normalized file name always begins with the leaf file name, and it's followed by the directory path in parentheses. Furthermore, the directory path shown is relative to the project's source directory, unless the file is on a different drive. If the file is on a different drive, or not part of the project source directory tree, then the full path is displayed in parentheses.
If you prefer not to see file names normalized in the Project Window, you can turn it off by using the Project
Window Properties
command and checking the File Directory box to add a separate column to the list for the directory name.
Here are some examples using the game project discussed above:
If the file path is:
c:\game\file.c
c:\game\core\file.c
c:\game\core\io\file.c
c:\game\core\enemy\file.c
c:\game\presentation\file.c
c:\SomeDir\file.c
d:\OtherDir\file.c
The file name is displayed as:
file.c
file.c (core) file.c (io) file.c (core\enemy) file.c (presentation) file.c (C:\SomeDir) file.c (D:\OtherDir)
Creating a New Project
Use the Project > New Project command to create a new project. You must give the project a name and specify where you want Source Insight to store the project data.
40 Source Insight 4 User Guide
Projects
You will be asked for a project name, where the files should be stored, and what source files you want to add to the project.
New project name
Enter the name of your project. Source Insight will create several files that start with this name and have different extensions.
Where do you want to store the project data files?
Enter the full path to the folder where you want to save the project data files that are created by Source
Insight. They can either be in the same folder as your source files, or in a separate location. By default, they are created under your Source Insight user directory in the Projects folder.
We recommend that your data directory be on a local, non-networked drive for reliability and best performance.
After you answer these two questions, you will be taken to the Project Settings dialog. See “Project Settings” on page 277.
Where Should You Create A Project?
If you are creating a project for source files that are stored locally on your machine, there should not be any problem creating the project data files in the same directory as your source files.
If you are creating a project that refers to files on a shared server, or any other place that you do not have permission to write to, then you should create the project data somewhere on your local machine. When the
Project Settings dialog box appears, enter the location of the your source files into the project source direc-
tory
field.
The folder you specified as the project data directory will become the default project source directory. In the
Project Settings dialog box, you can specify a different path for the project source directory. The project source directory typically is the path of the topmost directory containing your source files. When Source
Insight displays file names, the files are displayed relative to project source directory. If you point the project source directory to the directory containing most of your source files, then you will not have to look at a lot of redundant path information.
In addition, the "Add new files automatically" feature (in Options > Preferences: General) only will add new files automatically to your project if the files are in the project source directory or a descendant of this directory.
See “Synchronize Files” on page 342., and “Project Settings” on page 277.
Source Insight 4 User Guide 41
Projects
New Project Settings
When you create a project, the New Project Setting dialog opens. See “Project Settings” on page 277.
Setting Index Options for Projects
Name Fragment and Member indexing takes up index space on disk and in memory. It also slows database access a little bit. You can control what is indexed in the Project Settings dialog box.
Two check boxes control indexing:
Quick browsing for member names
Select this to allow member name indexing. When this option is enabled, you can simply type the member names of classes or structures, instead of having the type the class or structure name, followed by a dot (.) and the member name. De-selecting this will save on disk space and memory.
Quick browsing for symbol name fragments
Select this to allow name fragment indexing. When this option is enabled, you can type partial name fragments and find symbols containing those name fragments. Un-checking this will save on disk space and memory. If your project is large, then Source Insight may operate slowly when browsing, or synchronizing files with the symbol database.
If both check boxes are turned off, then the Project Symbol List panel filtering will revert to simple prefix matching. However, the Symbol Window on the left side of each source window, and the Project Window file list will still allow name fragment browsing.
42 Source Insight 4 User Guide
Projects
Adding Files to a Project
After you create a project, you next need to add source files to the project. There are several ways to add files.
If you created a new file in Source Insight and save it for the first time, Source Insight will ask you if you want to add the file to the current project. This will be the most natural way to add a file if you are writing new code and are creating new source files a lot.
If you already have existing source files and you want to add them to the current project, use the Add and
Remove Project Files
command. This command adds any existing files, including whole directory trees, from
anywhere on your disk to the current project. See “Add and Remove Project Files” on page 153., and “Add File
List” on page 156.
You can also add files to the project by dragging files from Windows Explorer and dropping them onto the
Project File List panel. The Project File List panel also allows removing files from the project.
Note:
You can also use Master File List to maintain the files in your project. This is useful for maintaining projects on
separate machines and with other team members. See “Using a Master File List” on page 44.
Adding a file to a project has the following effects:
•
The file name is stored in the file name database for the project. Whenever Source Insight displays a list of files, that file name will be in the list. Therefore, for example, when you use the Open command, the file name will be in the list box.
•
The file is parsed based on its language type. Symbol definitions are added to the project's symbol
database. The language parser used for each file is determined by its file type. See “File Types” on page 70.
•
The file's modification date is recorded in the file name database, so that Source Insight will know to synchronize the project symbol database if the file was modified outside of Source Insight, for example by a source control system.
•
The way the name of the file is displayed is changed. The file name becomes "normalized" to the project's source directory.
•
The file will become part of the project code base, which is searched when showing symbol relations, such as call trees.
What Files Should You Add to a Project?
Source Insight projects should consist of program source files and text files only. It doesn't make any sense to add a binary format file to a Source Insight project. For example, adding an exe or bitmap file to your project would have no benefit.
The file types that are defined by default in Options > File Type Options correspond to the types of source files you probably want to use with Source Insight. Normally, only those types of files should be added to a project.
Use File Type Options to control what types of files are added to projects
The File Type Options dialog box contains the check box: Include when adding to projects. You can use this check box to control what file types Source Insight will automatically add to your project, or what file types will be displayed in the list box in the Add and Remove Project Files dialog box.
Adding Remote Network Files to a Project
For whatever reason, you may want to access your source files directly on a network server, not from local copies of the files. Of course, you are free to open any file on the network directly. However, keep in mind that you may be locking other people out of the file by having it open, or otherwise causing contention over the file. In addition, you won't get the benefit of Source Insight's project features unless the remote file is added to your project.
One way to have a project that refers directly to files on the server is to create a project locally on your workstation and add the files from the remote server to your project using the Add and Remove Project Files com-
Source Insight 4 User Guide 43
Projects
mand. This way, the Source Insight symbol database files are stored locally on your machine, but the source
files still reside on the server. See “Add and Remove Project Files” on page 153.
Using the Project Settings command, you should specify the remote source code directory, on the server, as the project source directory. That way, files will be displayed relative to the main source directory, not rela-
tive to your local project data file directory. See “Project Settings” on page 277.
Project Master File List
Instead of adding and removing files manually through the Add and Remove Project Files command, you can setup a special file called a Master File List and associate that with the current project. For more information,
See “Using a Master File List” on page 44.
Removing Files from a Project
To remove a file from the current project's file list, use the Project > Add and Remove Project Files command.
When a file is removed from a project, all the symbols found in that file are removed from the project's sym-
bol database. Source Insight will not actually delete the file from the disk. See “Add and Remove Project
Files” on page 153.
Note:
You can also use Master File List to maintain the files in your project. This is useful for maintaining projects on
separate machines and with other team members. See “Using a Master File List” on page 44.
Using a Master File List
You can use a Master File List to control what source files are in a project. The Master File List is a text file containing the names of each file or directory in the project. To use it, select Project > Project Settings and enable the Master File List setting.
Although the Master File List (MFL) controls what files are in your project, you can still add or remove files manually by using Project > Add and Remove Files. When you add or remove a file from your project, the change will be saved to the MFL. If the MFL contains a file that is not in your project, then it will get added automatically to your project. If the MFL does not contain a file that is in your project, then it will be removed from your project automatically.
The Master File List can be a part of your source code repository and shared with other people. It is a simple text file that lists all the files (and/or directories) in your project. The MFL is maintained as you add or remove files from your project. If you add or remove files, the changes are saved to the MFL, and when the MFL is pushed out or checked in, your team members will get the additions or deletions automatically as their
Source Insight syncs up with the MFL.
Master File List Format
Each line in the Master File List should contain a path relative to your project's source directory. It can be a simple file name, a wildcard, such as open*.c
, or a directory name.
If a line item is a directory name, then all the files that match known file types in the directory are included in the project. Sub-directories and their contents are not included.
Lines that begin with the semi-colon (;) character are comments.
44 Source Insight 4 User Guide
Projects
Here is an example:
; Source Insight Project File List
; Project Name: WorkTest
; Generated by Source Insight 4.00.0048 at 11/19/2015 1:41:06 PM
; Version=4.00.0048
;
; Each line should contain either a file name, a wildcard, or a sub-directory name.
; File paths are relative to the project source root directory.
;
FM15Output\copycss.bat
FM15Output\custom-table.css
FM15Output\custom.css devices console\get.c
console\put.c
cmd*.c cmd*.h
The example above uses a combination of specific file names, wildcards, and a directory name (devices). All the names are relative to the project source directory root.
Generating a Master File List
If you already have a project built and you would like to use a Master File List, select Project > Export Project
File List
to create a new file list. Select Project > Project Settings and specify the file list in the Master File List
Path section.
Editing the Master File List
You can edit the Master File List directly by selecting Project > Open Project Master File List. Normally you would not need to edit it because Source Insight changes it automatically as you add and remove files from your project. However, you are free to edit it. When you save the file, Source Insight will resynchronize the project with the new version of the Master File List.
Synchronizing with the Master File List
Source Insight periodically checks to see if the Master File List has changed on disk. It resynchronizes with it when a change is detected. This can cause new files to be added to the project, or files to be removed from the project. This is handy if your Master File List is part of your source code repository. For example, if a colleague adds a new file to the project, when you get a new version of the repository, the new source file will be automatically added to your Source Insight project.
Opening and Closing Projects
To open a different project, use the Project > Open Project command (See “Open Project” on page 259.)
Source Insight only allows you to have one project open at a time, so if you already have a project open, it will ask you if you're sure you want to close the current project and save any changes to files. Assuming you do close the current project, the Open Project command will display a list box of existing projects from which to choose.
To close the current project and have no project open, use the Close Project command. Source Insight asks you if you want to save each file you have opened that you've changed, then it closes all files.
Removing a Project
To remove a project, use the Remove Project command. This command removes all the project data files that
Source Insight creates and associates with the project. Your source files are not deleted. See “Remove Project” on page 302.
Source Insight 4 User Guide 45
Projects
Copying a Project
The Project > Copy Project command copies the current project to a new name and location. The new project is created by cloning the current project data files. Your source files will not be copied. The new project will point to the same source files. If you delete the original project after copying it, you have effectively renamed
the project. See “Copy Project” on page 176.
Read-Only Projects
Sometimes it makes sense for a project to be read-only, and Source Insight allows for that. A project should be read-only if it is used only as a import library, or the project only exists on the project symbol path for auto-completion use. Also, a read-only project can be opened simultaneously by multiple instances of
Source Insight.
When Source Insight opens a project in the background to get symbol information for auto-completion or other reference-oriented uses, it opens the project as read-only so that other instances of Source Insight can open the project too.
To make a project always open as read-only, set the read-only file attribute of the project’s
.siproj
file, which is stored in the project’s data directory.
When you open a read-only project, you will not be able to save any files in the project, or add or remove files from it.
Changing Project Settings
The Project Settings command sets various options that govern the current project. If no project is currently open, then the Project Settings command sets the default options inherited by subsequently created projects.
When you create a new project, the Project Settings dialog box appears.
You may specify whether the project has its own private configuration, or if it uses the global configuration file. You can also indicate where the project's source directory is, and what types of symbol information should be indexed.
See “Project Settings” on page 277.
Symbols and Projects
Source Insight parses symbol definitions dynamically out of your source files while you edit. Symbol information is stored on disk in an indexed symbol database, which is integral to the project.
The symbol database is updated incrementally as you open and save files. Files that are changed by other project team members are also automatically synchronized with the symbol database in the background.
You typically do not need to do anything to keep Source Insight’s symbol information current.
Synchronizing Project Files
Source Insight uses a synchronization process to keep files and symbols up to date with respect to its project databases. This is helpful when files are edited without using Source Insight. For example, you may be using a source control system that updates files on your machine, or you may have files that are machine generated by your build process. When that happens, Source Insight has to re-parse those out-of-date files to bring the Source Insight project up to date. Normally, this is done automatically in the background for you, but you can do it manually by using the Project > Synchronize Files command.
The synchronize process ensures that the entire project is up to date. It scans each file in the project and updates the symbol database for each file that has been modified since Source Insight had the file open last.
46 Source Insight 4 User Guide
Projects
The synchronizing process can also optionally add and remove files automatically as new files appear, or dis-
appear from directories. The options are set in Options > Preferences: General Options. See “General
Options” on page 219.
You can also use a Master File List to control what files are in your project. If you use this option, then the syn-
chronization process uses the Master File List to add or remove files as needed. See “Using a Master File List” on page 44.
To synchronize files in a project:
You can synchronize a project in one of two ways:
•
The default: If the "background synchronization" option is enabled in Options > Preferences: General, then synchronizing the project will happen in the background while you continue to edit in Source
Insight. See “General Options” on page 219. You basically don’t need to do anything.
•
You can run the Synchronize Files command, which synchronizes the project on demand. See “Synchronize Files” on page 342.
Normally, if you open a file that has been modified since Source Insight had it open, the symbol database is updated automatically when you open the file. By automatically synchronizing, the update is transparent to you. However, if a symbol is moved from one file to another, you may find that Source Insight loses track of where the symbol is, unless both files are in sync with the project. In addition, if new symbols have been defined, Source Insight won't know about them until the containing file is synchronized.
The Base Project
Source Insight automatically creates a project named Base. When Source Insight cannot find a symbol definition anywhere else, it searches the Base project. It is implicitly at the end of the project symbol path.
Note:
You do not have to add the Base project to the project symbol path. Source Insight automatically searches it as though it were in the list.
This gives you a convenient place to save common symbols. Any symbol stored in the Base project is visible from any other project. The Base project is also a good place to add your favorite Source Insight editor macro files.
Creating a Web Version of Your Project
You can create a snapshot of your project sources as a set of web pages. You can use any web browser to browse your source code. The resulting web pages will have syntax formatting close to what is displayed inside Source Insight.
Use the Project > Export Project to HTML command to save a new set of HTML files. See “Export Project To
HTML” on page 198.
Rebuilding Projects
Sometimes you may need to rebuild a project if you suspect the data files are corrupted or just too far out of date.
If you can still open your project, use the Project > Rebuild Project command to rebuild it. This rebuilds all
the Source Insight data files. See “Rebuild Project” on page 280.
Source Insight automatically detects if a project is corrupted when you open a project. If corruption is detected, it will rebuild the project at that time.
Source Insight 4 User Guide 47