Documentation for version 0.5
This short introduction will briefly guide you through the project setup and the user interface of Coati. The bullet point lists will tell you what to do:
Coati is an interactive source explorer that simplifies navigation in existing source code. Coati's aim is to give answers to all your questions about your source code. Coati first analyses your code and gathers data about its structure and then provides you with a simple interface consisting of three linked views, each having a key role in getting information:
Coati currently only supports the language C and C++. Much of the UI design is therefore based on these languages and might change as soon as other languages are supported. For more information have a look at supported languages.
Once you installed Coati successfully you are ready to run the application.
When running the full version of Coati for the first time you are greeted with the enter license window. You need to enter the license key you received via e-mail when you purchased your Coati license.
On every start of Coati you are shown the start window. It allows for creating new projects or opening existing ones.
When creating a new Coati project you will use the project setup wizard. This wizard splits the setup process into several subsequent steps.
The simplest way to set up a Coati project would be the following:
Coati will now start analyzing your source files, which might take a little while. The status bar will give you information about the progress. Otherwise the UI will be empty. Coati analyses all named symbols and their relationships throughout the provided source files. However, it stops the analysis at the level of local variables and symbols that are only valid within a certain function scope.
After analysis has finished, Coati will show an overview of all analysed symbols in the graph view and some statistics in the code view. If the analysis found errors in your code, the code view will display them. You can see the error message by hovering an error's location.
As already mentioned Coati's user interface is split into three main views. Their arrangement can be changed however you wish, you can even detach them from the main window and put them on different screens (see Window Widgets).
The three views show information about the currently selected symbol. The search field provides the name, the graph visualization shows its relationships to other symbols and the code view displays all locations the symbol gets referenced throughout the codebase.
The search field allows for easy access to all analyzed symbols. Use it to find all the classes and functions you wish to investigate. Apart from that is also holds the UI buttons for navigating back & forward as well as refreshing.
When entering a search query the autocompletion popup will provide you with a concise list of all matching symbols. Note that Coati uses a fuzzy matching algorithm, that allows you to skip characters while entering a query.
The graph visualization displays the currently selected symbol in an active state and all other symbols it shares relationships with. The visualization is made up of nodes and edges.
The different node and edge types are also displayed using different colors. The default color scheme uses this convention:
| Color | Node | Edge |
|---|---|---|
| gray | types and classes | type use |
| yellow | functions and methods | calls |
| blue | variables and fields | variable access |
Nodes displayed with a striped hatching, are nodes that were used within your analyzed source files, but were not analyzed themselves. Clicking them shows all locations where they are used, without providing where they got defined.
The code view displays all locations of the currently active symbol within the analyzed source files. It does not allow for editing the source code. Syntax highlighting is used to increase readability. Source locations that are surrounded by a box when hovered can be clicked to activate the respective symbol. Active source locations are highlighted gray.
The source locations are displayed as code snippets, containing the line of interest and extra lines added to the top and bottom to give information about its context. Code snippets are then bundled together into files.
Note: A file can be selected as active symbol by clicking its name in the title bar. By clicking the icons on the right hand side of the title bar, the file can switch between 3 different states:
For more information please have a look at Code View Files.
After reading this quick guide, you know the basics of Coati's user interface and you are able to start exploring your codebase. Coati will allow you to see your source code from a whole new perspective, by giving you a concise overview of its parts and a faster way of drilling down to its internals while always maintaining the connection to the implementation details of the actual source code.
For more detailed information please have a look at the much more extensive instruction manual below.
If you have feedback for us, please don't hesitate and let us know by writing to support@coati.io, we'd be glad to hear from you.
The Coati team wishes you a good start with our product, lots of saved time, increased productivity and much cleaner code.
This document is the official documentation of Coati and explains everything you need to know about working with it.
If you have questions not answered by this document, please write us an e-mail to support@coati.io.
C support is powered by Clang 3.7. If you have a problem loading C code, please have a look at Clang language compatibility or report a bug at our bug tracker.
C++ support is powered by Clang 3.7. For more Information please visit Clang C++ Status. If you have a problem loading C++ code, please have a look at Clang language compatibility or report a bug at our bug tracker.
Coati does two things with the data collected during analysis:
.coatidb file in the same directory as the .coatiproject file. This data file is used by Coati to serve its purpose of letting you navigate your source code. And it allows Coati to reopen the project without reanalysing the source code.Download and open the zip file and extract its contents into a temporary folder of your choice. Run the setup.exe and go through the wizard. You can now launch Coati from your start menu.
Download and open the Coati.dmg file and drag Coati.app into the applications folder. You can now launch Coati from your Applications.
Download Coati.tar.gz file and extract it. To start Coati run the Coati.sh script. Coati creates a folder ~/.config/coati at the first run, this is the folder for Coati settings.
The data folder holds certain files that are used by Coati to run the program. After following the installation instructions the data folder should be located in the following locations on your platform.
| Platform | Location |
|---|---|
| Windows | C:/Users/You/AppData/Local/Coati Software/Coati (used for dynamic data and settings) install_directory/Coati Software/Coati/data (used for static app data) |
| Mac | ~/Library/Application Support/Coati |
| Linux | ~/.config/coati |
These files usually ship with your compiler. For the Visual Studio IDE the system headers can be found at:
path_to_visual_studio/VC/include/
If you don't use the Visual Studio IDE you can also try to find your system headers in a subdirectory of:
C:/Program Files (x86)/Windows Kits/
Run this command in your terminal:
gcc -x c++ -v -E /dev/null
You will find the header search paths your compiler uses in the output between these two lines:
#include <...> search starts here:
.
.
.
End of search list.
gcc -x c++ -v -E /dev/nullor
clang -x c++ -v -E /dev/null
You will find the header search paths your compiler uses in the output between these two lines:
#include <...> search starts here:
.
.
.
End of search list.
Coati's three views are organized into Widgets Windows, which can be freely arranged within the Main Window or detached from it. Each Widget Window has a title bar displaying its name and 2 buttons for closing the Widget Window and for detaching it from the Main Window.
The Statusbar is located on the bottom of the Main Window and is used to convey information about Coati's status and currently running processes to the user.
If your analysis yielded errors the status bar will display their count on the right side.
Interactions:
On every start of Coati you are shown the start window. It allows for creating new projects or opening existing ones.
The Path List Box is a user interface element that is used within the Preferences Window and the Project Setup Wizard. It allows for entering a list of file and directory paths.
The Preferences window lets you define settings for all projects. You can open the Preferences from the menu via Help/Preferences.
| Setting | Description |
|---|---|
| Header Search Paths | Set header search paths that are used for all of your projects (e.g. std headers). (For instructions on how to add paths see Path List Box. For instructions on how to find the system header paths see Finding System Header Locations) |
| Framework Search Paths | Mac only. Define the search paths for .framework files for all of your projects. (For instructions on how to add paths see Path List Box.) |
The Project Setup Wizard consists of a sequence of windows that lets you create a new Coati project. After selecting the programming language for your project Coati offers several ways for you to provide all the required information.
This is the way to go if you just have some source files you want to analyze and you don't have any files that instruct your compiler how to build a binary from those files. In case you actually have such a build instructions file, you might want to check out one of the other options for project setup described below.
Project Meta DataIn this first step Coati needs you to enter some meta information about the project.
| Setting | Description |
|---|---|
| Name | The name of the project. This will also be the name of the *.coatiproject file generated by Coati. |
| Location | Choose the location of the project file from the dialog. |
| Language | Select the language of your project. This setting is preselected according to your choice in the previous screen. (See Language Support) |
| Standard | Select the language standard that should be used for analyzing your project. Usually the most recent language standard is preselected here. (See Language Support) |
In this step you can choose between the simple setup and the advanced method.
In simple setup you just provide the directory of your project and Coati will find all source files and resolve header search paths within. Please note that simple setup slows down the analysis.
In the advanced setup you define analyzed source files and the corresponding header search paths separately.
Provide the paths that contain your project's files. Coati will analyze all the source and header files in the specified paths, including subdirectories.
| Setting | Description |
|---|---|
| Project Paths | Specify one or multiple locations that contain all the source and header files that should be analyzed by Coati. (For instructions on how to add paths see Path List Box.) |
When you selected the simple setup method Coati will automatically search your source folder(s) for included headers. However, if your project requires additional includes to compile (e.g. Boost for C++, etc.), please specify them here.
If you chose the advanced setup method Coati needs you to specify all the project's internal include paths in addition to the external dependencies. Project internal include paths are those paths your project internal #include directives are relative to.
Additionally you can also specify Global Header Search Paths, which will be used by all yout projects. These are usually the paths to system headers, which can also be auto detected by choosing a compiler below and pressing detect.
| Setting | Description |
|---|---|
| Header Search Paths | These paths are used to find the files specified by #include directives. (For instructions on how to add paths see Path List Box.) |
| Global Header Search Paths | These Header Search Paths will be used in all your projects. (For instructions on how to add paths see Path List Box. For instructions on how to find the system header paths see Finding System Header Locations) |
If you already have a Visual Studio solution file, this is the way to go. Just select the solution file in the file picker and Coati will automatically analyze (this may take a second) it to prepopulate the New Project Summary Window.
If you are using CMake you can export compile commands by defining the flag CMAKE_EXPORT_COMPILE_COMMANDS. Just select the exportet .json file in the file picker.
In the next step you can define the locations of the corresponding header files of the source files in the compilation database.
These header files will only be analyzed if they are included in one of the source files.
| Setting | Description |
|---|---|
| Source Files | Clicking show source files will show you a list of all source files in the compilation database |
| Header Paths | Specify one or multiple locations that contain the header files to the source files defined in the compilation database. (For instructions on how to add paths see Path List Box.) Clicking show header files will show you the list of the header files that will be analyzed if included. |
This window appears at the end of the Project Setup Wizard to summarize all the information entered before. It is the same as the Edit Project Window.
This window displays all the information relevant for your Coati project.
| Setting | Description |
|---|---|
| Name | The name of the project. This will also be the name of the *.coatiproject file generated by Coati. |
| Location | Choose the location of the project file from the dialog. |
| Language | Select the language of your project. This setting is preselected according to your choice in the previous screen. (See Language Support) |
| Standard | Select the language standard that should be used for analyzing your project. Usually the most recent language standard is preselected here. (See Language Support) |
| Project Paths | Provide the paths that contain your project's files. Coati will analyze all the source and header files in the specified paths, including subdirectories. |
| Visual Studio Solution | Only when using Setup from Visual Studio Solution. Provide the path to your Visual Studio Solution. Clicking the refresh arrow inside the text box will refresh the Project Paths and the Header Search Paths below. |
| Compilation Database | Only when using Setup from Compilation Database. Provide the path to your Compilation Database. |
| Header Paths | Only when using Setup from Compilation Database. Provide the paths to the corresponding header paths of your Compilation Database. |
| Simple Setup | If this checkbox is checked Coati also looks into the analyzed paths (including subdirectories) when resolving #include directives. |
| Header Search Paths | Specify where Coati should be looking for included headers. |
| Global Header Search Paths | Same as Header Search Paths but these are used application wide for all of your Coati projects. |
| Framework Search Paths | Mac only. Define the search paths for .framework files for your project. (For instructions on how to add paths see Path List Box.) |
| Global Framework Search Paths | Mac only. Same as Framework Search Paths but these are used application wide for all of your Coati projects. |
| Advanced Setting | Description |
|---|---|
| Compiler Flags | Define compiler flags used during analysis e.g. -v |
| Header File Extensions | Define extensions for header files including the dot e.g. .h |
| Source File Extensions | Define extensions for source files including the dot e.g. .cpp |
The Enter License Window appears on your first start of Coati and is used to enter and check your Coati license key.
| Shortcut | Windows | Mac OS X | Linux |
|---|---|---|---|
| Preferences | Cmd + , | ||
| New Project | Ctrl + N | Cmd + N | Ctrl + N |
| Open Project | Ctrl + O | Cmd + O | Ctrl + O |
| Save Project | Ctrl + S | Cmd + S | Ctrl + S |
| Save Project As | Ctrl + Shift + S | Cmd + Shift + S | Ctrl + Shift + S |
| Close Window | Alt + F4 | Cmd + W | Ctrl + W |
| Hide Window | Cmd + H | ||
| Refresh | F5 | Cmd + R | F5 |
| Force Refresh | Shift + F5 | Cmd + Shift + R | Shift + F5 |
| Back | Ctrl + Z | Cmd + Z | Ctrl + Z |
| Forward | Ctrl + Shift + Z | Cmd + Shift + Z | Ctrl + Shift + Z |
| Find | Ctrl + F | Cmd + F | Ctrl + F |
| To overview | Ctrl + HOME | Cmd + HOME | Ctrl + HOME |
| Larger Font | Ctrl + + | Cmd + + | Ctrl + + |
| Smaller Font | Ctrl + - | Cmd + - | Ctrl + - |
| Reset Font Size | Ctrl + 0 | Cmd + 0 | Ctrl + 0 |
The graph view visualizes the currently selected symbol and all its relationships to other symbols as an interactive graph visualization.
Colors are corresponding to the default color scheme.
| Node Type | Image |
|---|---|
| File | ![]() |
| Type & Template Parameter | ![]() |
| Typedef | ![]() |
| Class & Struct: Display their members nested, and separated by access type: public, protected, private. By default only members with edges are shown. The arrow icon allows to expand and collapse them. The number tells how many nodes are hidden. | ![]() |
| Variable & Field | ![]() |
| Function & Method | ![]() |
| Enum | ![]() |
| Undefined: Nodes that were not defined within the analyzed files are shown with hatched background. | ![]() |
| Bundle: A bundle node combines multiple nodes to reduce the size of the graph visualization. The name describes what kind of nodes are bundled. The number tells how many nodes are bundled. | ![]() |
Colors are corresponding to the default color scheme.
| Edge Type | Image |
|---|---|
| File Include | ![]() |
| Type Use | ![]() |
| Variable Use | ![]() |
| Function Call | ![]() |
| Inheritance | ![]() |
| Method Override | ![]() |
| Template Parameter Use & Template Argument Use | ![]() |
| Aggregation: Bundles multiple edges between the child nodes of the 2 nodes. The thickness gives an impression of how many edges are bundled. Hover the edge to get the number of bundled edges. | ![]() |
The code view displays the corresponding source code of the currently selected symbols. The code view contains a list of one or more files.
Each file has a title bar with the file's name and buttons to change its display state. There are 3 different states:
A code snippet contains the line of interest for the currently active symbols. Other symbols that were analyzed by Coati are framed by a box when hovered. In case the snippet is part of a class, function or namespace, an additional line at the top of the snippet provides information about the snippet’s context (e.g. the surrounding scope).
The Search View contains the search field and some other related user interface elements.
The left Backward button lets you undo your last navigation actions (see Back) and the right Forward button lets you redo your undone navigation actions again (see Forward). Both buttons are only enabled when the respective actions are available at the moment.
The left refresh button allows you to refresh the current project and reanalyze all updated files (see Refresh). With the right auto refresh toggle button you can activate automatic refresh, which will reanalyze all updated files whenever you put window focus on Coati's Main Window.
Show the overview screen, which gives a summary of the loaded project. The overview screen is shown after the project was loaded. Alternatively use the shortcut To overview.
The search bar allows you to enter search requests to find one of Coati's analyzed symbols. It doesn't allow for full text searching across all files so far. The search field allows for most text editing interactions common to text fields. When typing your request the Autocompletion Popup will show you search results matching to your entered string.
The Autocompletion Popup displays all Nodes matching your search request within all analyzed symbols. The match results are determined by a fuzzy matching algorithm, that allows you to skip characters. The popup shows which characters in the words are matching and displays their corresponding node color. The node type is displayed on the right.
Additionally the search view provides specific keywords that select a certein group of symbols.
| keyword | effect |
|---|---|
| overview | Shows an overview of all analysed symbols in the graph view and some statistics in the code view. |
| error | Shows all errors in the code view. |
In order to make Coati the perfect partner for your development workflow you can connect Coati with different code editors. You can find the plugins in Coati's download package located in the folder /ide_plugins. Have a look at the following list of supported code editors to find out what editors are currently supported.
We are eager to expand the range of supported editors, so if you can't find a plugin for the code editor you are using, please let us know by writing to support@coati.io.
Supported Editors:The communication between Coati and the code editor is achieved using a local TCP connection. Coati uses the port 6667 to listen for incoming messages. Outgoing messages will be sent to the port 6666.
Outgoing messages are in the form:
moveCursor>>absolute/file_path>>line_number>>column_number<EOM>
Incoming messages are in the form:
setActiveToken>>absolute/file_path>>line_number>>column_number<EOM>
If you want your editor to open a file at a specific location from within Coati, you can achieve this by either selecting the option Set IDE Cursor from the right-click menu in the Code View or by simply clicking into a line in the Code View while holding down the Ctrl or Cmd key.
By using a Coati plugin for your code editor, you can select a location within a source file and Coati will show you all symbols found at this location. Please have look at the list below to see which plugins are currently available and how they are used.
To install the Coati plugin for Sublime Text copy the CoatiPlugin folder located in your ide_plugins/sublime_text to your SublimeText/Packages folder and restart Sublime.
If you want Sublime to activate a certain element in Coati, click a location to place the cursor, right-click to bring up the context menu and choose the “Coati - Set active Token” option. Please note that the position of the cursor will be sent to Coati and not the position you opened the context menu at.
To install the Coati plugin for any version of Visual Studio, just execute the corresponding vsix file located in your ide_plugins/visual_studio.
If you want Visual Studio to activate a certain element in Coati, right-click that element to bring up the context menu and choose the “Set active Token” option.