2154 lines
110 KiB
HTML
2154 lines
110 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<title>Sourcetrail - Documentation</title>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="description" content="">
|
||
<meta name="author" content="">
|
||
|
||
<!-- styles -->
|
||
<link type="text/css" rel="stylesheet" href="css/sourcetrail.css" />
|
||
<link type="text/css" rel="stylesheet" href="css/bootstrap.css" />
|
||
<link type="text/css" rel="stylesheet" href="css/jquery.tocify.css" />
|
||
<link type="text/css" rel="stylesheet" href="css/jquery-ui.min.css" />
|
||
|
||
<!-- Google Analytics -->
|
||
<!-- <script>
|
||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
||
|
||
ga('create', 'UA-64108586-2', 'auto');
|
||
ga('send', 'pageview');
|
||
|
||
</script> -->
|
||
<!-- End Google Analytics -->
|
||
|
||
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
|
||
<!--[if lt IE 9]>
|
||
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
|
||
<![endif]-->
|
||
|
||
<!-- icons -->
|
||
<link rel="shortcut icon" href="favicon.ico">
|
||
<style>
|
||
body {
|
||
padding-top: 20px;
|
||
}
|
||
|
||
#nav {
|
||
position:fixed;
|
||
width: 20%;
|
||
margin-left: 2%;
|
||
}
|
||
|
||
.tocify {
|
||
position:static;
|
||
width: 100%;
|
||
margin-left: 0px;
|
||
}
|
||
|
||
@media (max-width: 767px) {
|
||
#nav {
|
||
position: relative;
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
</head>
|
||
|
||
<body>
|
||
<div class="container-fluid">
|
||
<div class="row-fluid">
|
||
|
||
<div class="col-xs-12 col-sm-3">
|
||
<div id="nav">
|
||
<div class="row">
|
||
<div class="col-xs-12">
|
||
<p><span class="glyphicon glyphicon-arrow-left"></span> <a href="http://www.sourcetrail.com/">back to sourcetrail.com</a></p>
|
||
</div>
|
||
</div>
|
||
<div class="row" style="height:10px;"></div>
|
||
<div class="row">
|
||
<div class="col-xs-12">
|
||
<div id="toc"></div><!-- Our table of contents will be here !-->
|
||
</div>
|
||
</div>
|
||
<div class="row" style="height:40px;"></div>
|
||
</div>
|
||
</div>
|
||
<div class="col-xs-12 col-sm-9 col-md-6">
|
||
<div class="row">
|
||
<div class="col-xs-6 col-xs-offset-3">
|
||
<img src="img/logo.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<div class="row" style="text-align:center; margin-top: 10px;">
|
||
<p>Documentation for version 0.11</p>
|
||
</div>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h1>QUICK START GUIDE</h1>
|
||
<p>This short introduction will briefly guide you through the project setup and the user interface of Sourcetrail. The bullet point lists will tell you what to do:</p>
|
||
<div class="callout callout-info">
|
||
<strong>Tasks:</strong>
|
||
<ul>
|
||
<li>Keep on reading</li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
<h2>Short description</h2>
|
||
<p>Sourcetrail is an interactive source explorer that simplifies navigation in existing source code. Sourcetrail's aim is to give answers to all your questions about your source code. Sourcetrail first indexes your code and gathers data about its structure and then provides you a simple interface consisting of three interactive views, each playing a key role in getting information:</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/concept.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<ul>
|
||
<li><strong>Search:</strong> Use the search field to quickly find and select indexed symbols in your source code. The autocompletion box will instantly provide an overview of all matching results throughout your codebase.</li>
|
||
<li><strong>Graph:</strong> The graph displays the structure of your source code. It focuses on the currently selected symbol and directly shows all incoming and outgoing dependencies to other symbols.</li>
|
||
<li><strong>Code:</strong> The Code view displays all source locations of the currently selected symbol in a list of code snippets. Clicking on a different source location allows you to change the selection and dig deeper.</li>
|
||
</ul>
|
||
<p>Sourcetrail currently supports the languages C/C++ and Java. 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 <a href="#SupportedLanguages">supported languages</a>.</p>
|
||
|
||
|
||
<h2>Starting up Sourcetrail</h2>
|
||
<p>Once you <a href="#INSTALLATION">installed</a> Sourcetrail successfully you are ready to run the application.</p>
|
||
<div class="callout callout-info">
|
||
<strong>Tasks:</strong>
|
||
<ul>
|
||
<li>Run Sourcetrail</li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
<h4>Start Window</h4>
|
||
<p>On every start of Sourcetrail you are shown the <a href="#StartWindow">Start Window</a>. It allows for creating new projects or opening existing ones. As long as you haven't unlocked Sourcetrail with a valid license key it is running in Trial mode.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/start_window_trial.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<div class="callout callout-info">
|
||
<strong>Tasks:</strong>
|
||
<ul>
|
||
<li>If you want to create your own project press <var>Unlock</var> to enter a license key.</li>
|
||
<li>or select the recent project <var>TicTacToe</var> and continue with the <a href="#UIIntro">UI Intro</a>.</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h4>License Key Window</h4>
|
||
<p>The <a href="#EnterLicenseWindow">Enter License Window</a> allows you to enter enter the license key you received via e-mail after purchasing your Sourcetrail license.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/license_key_window.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<div class="callout callout-info">
|
||
<strong>Tasks:</strong>
|
||
<ul>
|
||
<li>Open up the e-mail you received when purchasing your Sourcetrail license.</li>
|
||
<li>Copy & paste your license key into the text box and click <var>Activate</var>. The license key should follow the format shown by the placeholder text.</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h4>Start Window</h4>
|
||
<p>After entering the license key you are redirected to the <a href="#StartWindow">Start Window</a> again. Now you can create your own project.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/start_window.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<div class="callout callout-info">
|
||
<strong>Tasks:</strong>
|
||
<ul>
|
||
<li>Press <var>New Project</var> to continue creating a new project.</li>
|
||
<li>or select the included recent project <var>TicTacToe</var> and continue with the <a href="#UIIntro">UI Intro</a>.</li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
<h2>Creating a Project</h2>
|
||
<p>When creating a new Sourcetrail project you will use the <a href="#ProjectSetupWizard">project setup wizard</a>. This wizard splits the setup process into several subsequent steps. Depending on your projects structure and the used build system there are different types for project setup. Choosing the right setup method is important and can make the setup process a lot easier.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/project_setup_wizard_start.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<h3>Choosing the right project setup</h3>
|
||
There are different types of setup for each supported programming language. It is currently not possible to create a mixed language project, except for mixed C & C++ projects via a <a href="#CreateAProjectFromCompilationDatabase">Compilation Database</a>. We will extend to multi-language projects in the future.
|
||
|
||
<div class="row" style="height:10px;"></div>
|
||
|
||
<h4>Project setup for C/C++</h4>
|
||
<p>The project setup types for C & C++ are the same.</p>
|
||
|
||
<strong>Are you using CMake or Make?</strong>
|
||
<p>If you are using <a href="https://cmake.org/">CMake</a> or <a href="https://www.gnu.org/software/make/">Make</a> as build environment you can export a <a href="https://clang.llvm.org/docs/JSONCompilationDatabase.html">clang JSON Compilaton Database</a> as <code>compile_commands.json</code> file. A Compilation Database holds all information necessary for building the project, such as source files, include paths and compiler flags. Having a Compilation Database makes project setup within Sourcetrail a lot easier. We recommend using this approach if possible.</p>
|
||
|
||
<p>Exporting a Compilation Database:</p>
|
||
<ul>
|
||
<li>From <strong>CMake</strong> by defining the <code>CMAKE_EXPORT_COMPILE_COMMANDS</code> flag. (not supported on for Visual Studio CMake generators)</li>
|
||
<li>For <strong>Make</strong> projects use <a href="https://github.com/rizsotto/Bear">Bear</a>. Bear generates a <code>compile_commands.json</code> file during a simulated build process. Bear has been tested on FreeBSD, GNU/Linux and OS X.</li>
|
||
</ul>
|
||
|
||
<p>If you managed to export a <code>compile_commands.json</code> file, then please continue at <a href="#CreateAProjectFromCompilationDatabase">Create a project from Compilation Database</a> and come back after you finished creating the project.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/project_setup_wizard_start_cdb.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<strong>Are you using Visual Studio?</strong>
|
||
|
||
<p>If you are using Visual Studio you can continue at <a href="#CreateAProjectFromVisualStudio">Project creation from Visual Studio</a> and export a Compilation Database with our <a href="#VisualStudio">Visual Studio Plugin</a>.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/project_setup_wizard_start_vs.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<strong>Create empty</strong>
|
||
|
||
<p>If none of the above options apply to your project then please continue at <a href="#CreateAnEmptyCXXProject">Create an Empty C/C++ Project</a> and come back here as soon as the project is created.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/project_setup_wizard_start.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<div class="row" style="height:10px;"></div>
|
||
|
||
<h4>Project setup for Java</h4>
|
||
Java projects can currently only be created as Empty Projects. Please follow the descriptions at <a href="#CreateAnEmptyJavaProject">Create an Empty Java Project</a>.
|
||
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/project_setup_wizard_start_java.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<div class="callout callout-info">
|
||
<strong>Tasks:</strong>
|
||
<ul>
|
||
<li>Continue at with your chosen project setup and come back here as soon as the project is created.</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<h2>Source Indexing</h2>
|
||
<p>After the project is created, Sourcetrail will ask you whether you want to start indexing. Click <var>Start</var> and wait for the indexing to finish, which might take a little while. The <a href="#IndexingDialogs">Indexing Dialog</a> and the <a href="#Statusbar">status bar</a> will give you information about the progress. Otherwise the UI will be empty. Sourcetrail indexes all named symbols and their relationships throughout the provided source files.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/indexing.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<div class="callout callout-info">
|
||
<strong>Tasks:</strong>
|
||
<ul>
|
||
<li>Click <var>Start</var> when asked whether to start indexing.</li>
|
||
<li>Wait until the indexing of your source files has finished.</li>
|
||
<li>or Click <var>Stop</var> or press ESC to stop indexing (Sourcetrail will provide all information gathered so far and the indexing can be continued later by <a href="#Refresh">refreshing</a>).</li>
|
||
</ul>
|
||
</div>
|
||
<p>After indexing has finished, Sourcetrail will show an overview of all indexed symbols in the <a href="#GraphView">graph view</a> and some statistics in the <a href="#CodeView">code view</a>.</p>
|
||
|
||
<p>If the indexing yielded errors, the status view will be shown with a list of errors. You can click on the errors label on the right side of the status bar or on one of the errors in the table to see their location.</p>
|
||
<div class="row">
|
||
<div class="col-sm-12">
|
||
<img src="img/error_view.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<div class="callout callout-info">
|
||
<strong>Tasks:</strong>
|
||
<ul>
|
||
<li>Fix your errors and <a href="#Refresh">refresh</a> to reindex the files with errors (Open Issue: As long as there was no change in the specific file, Sourcetrail won't reindex it, use the <strong>Force Refresh</strong> option from the <a href="#Edit">Edit Menu</a>).</li>
|
||
<li>or ignore them and continue with an incomplete index.</li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
<h2>UI Intro</h2>
|
||
<p>As already mentioned Sourcetrail'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 <a href="#WidgetWindows">Window Widgets</a>).</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/main_screen.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<p>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.</p>
|
||
|
||
<h3>Search Field</h3>
|
||
<p>The <a href="#Searchbar">search field</a> allows for easy access to all indexed 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 <a href="#Back&Forward">back & forward</a> as well as <a href="#Refresh">refreshing</a>.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/search_view.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<p>When entering a search query the <a href="#AutocompletionPopup">autocompletion popup</a> will provide you with a concise list of all matching symbols. Note that Sourcetrail uses a fuzzy matching algorithm, that allows you to skip characters while entering a query.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/search_view_completion.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<h3>Graph Visualization</h3>
|
||
<p>The <a href="#GraphView">graph visualization</a> 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.</p>
|
||
<ul>
|
||
<li><strong>Nodes:</strong> All named symbols in your source code will be displayed as different <a href="#Nodes">nodes</a>, such as <var>functions</var>, <var>classes</var> or <var>files</var>. Nodes with members (like <var>classes</var>) can be expanded to show all their contents, the number at the expansion arrow shows how many members are hidden. Clicking a node will activate it and update all the views to the new selection. Dragging a node can be used to change its position.</li>
|
||
<li><strong>Edges:</strong> The relationships between the symbols are displayed as different <a href="#Edges">edges</a>, such as <var>type use</var>, <var>function call</var> or <var>file include</var>. Sometimes edges get bundled together and are displayed as an <var>aggregation</var> edge that shows a number of how many edges it contains. Clicking an edge will highlight its source location in the code view.</li>
|
||
</ul>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/graph_view_graph.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<h4>Colors:</h4>
|
||
<p>The different node and edge types are also displayed using different colors. The default color scheme uses this convention:</p>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Color</th> <th>Node</th> <th>Edge</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">gray</th> <td>types and classes</td> <td>type use</td> </tr>
|
||
<tr class="warning"> <th scope="row">yellow</th> <td>functions and methods</td> <td>calls</td> </tr>
|
||
<tr class="info"> <th scope="row">blue</th> <td>variables and fields</td> <td>variable access</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h4>Hatching:</h4>
|
||
<p>Nodes displayed with a striped hatching, are nodes that were used within your indexed source files, but were not defined. Clicking them shows all locations where they are used, without providing their declaration.</p>
|
||
<div class="row">
|
||
<div class="col-xs-4 col-sm-2 col-xs-offset-4 col-sm-offset-5">
|
||
<img src="img/node_non_indexed.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<h3>Code View</h3>
|
||
<p>The <a href="#CodeView">code view</a> displays all locations of the currently active symbol within the indexed 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.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/code_view.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<p>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.</p>
|
||
<p><strong>Note:</strong> 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:</p>
|
||
<ul>
|
||
<li>
|
||
<strong>Minimized:</strong> The file does not show any content
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/snippet_minimized.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<strong>Snippets:</strong> The file displays the snippets containing active locations separated by lines.
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/snippet_snippets.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<strong>Maximized:</strong> The whole content of the file is visible.
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/snippet_maximized.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>For more information please have a look at <a href="#Files">Code View Files</a>.</p>
|
||
|
||
|
||
<h2>Start exploring!</h2>
|
||
<p>After reading this quick guide, you know the basics of Sourcetrail's user interface and you are able to start exploring your codebase. Sourcetrail 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.</p>
|
||
<p>For more detailed information please have a look at the much more extensive instruction manual below.</p>
|
||
<p>If you have feedback for us, please don't hesitate and let us know by writing to <a href="mailto:support@sourcetrail.com" target="_top">support@sourcetrail.com</a>, we'd be glad to hear from you.</p>
|
||
<p>The Sourcetrail team wishes you a good start with our product, lots of saved time, increased productivity and much cleaner code.</p>
|
||
<div class="callout callout-info">
|
||
<strong>Tasks:</strong>
|
||
<ul>
|
||
<li>Start exploring & have fun!</li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
<div class="row" style="height:80px;"></div>
|
||
|
||
<h1>INTRODUCTION</h1>
|
||
|
||
<h2>About this document</h2>
|
||
<p>This document is the official documentation of Sourcetrail and explains everything you need to know about working with it.</p>
|
||
<p>If you have questions not answered by this document, please write us an e-mail to <a href="mailto:support@sourcetrail.com" target="_top">support@sourcetrail.com</a>.</p>
|
||
|
||
|
||
<h2>Supported Languages</h2>
|
||
<h3>C</h3>
|
||
<p>C support is powered by <a href="http://clang.llvm.org/" target="_blank">Clang 3.9</a>. If you have a problem loading C code, please have a look at <a href="http://clang.llvm.org/compatibility.html" target="_blank">Clang language compatibility</a> or report a bug at our <a href="https://github.com/CoatiSoftware/SourcetrailBugTracker">bug tracker</a>.</p>
|
||
|
||
<h3>C++</h3>
|
||
<p>C++ support is powered by <a href="http://clang.llvm.org/" target="_blank">Clang 3.9</a>. For more Information please visit <a href="http://clang.llvm.org/cxx_status.html" target="_blank">Clang C++ Status</a>. If you have a problem loading C++ code, please have a look at <a href="http://clang.llvm.org/compatibility.html" target="_blank">Clang language compatibility</a> or report a bug at our <a href="https://github.com/CoatiSoftware/SourcetrailBugTracker">bug tracker</a>.</p>
|
||
|
||
<h3>Java</h3>
|
||
<p>Sourcetrail includes Java 8 support which is powered by <a href="http://javaparser.org/" target="_blank">JavaParser</a> and <a href="https://github.com/ftomassetti/java-symbol-solver" target="_blank">JavaSymbolSolver</a>. Java support still has some minor issues. If you encounter any of these issues, please let us know by providing a minimal example at our <a href="https://github.com/CoatiSoftware/SourcetrailBugTracker">bug tracker</a>.</p>
|
||
|
||
<h2>FAQ</h2>
|
||
|
||
<div class="panel panel-default">
|
||
<div class="panel-heading">
|
||
<h3 class="panel-title">Can I use Sourcetrail on confidental source code?</h3>
|
||
</div>
|
||
<div class="panel-body">
|
||
Yes. Sourcetrail works completely offline and establishes no connection to the internet whatsoever. All data stays on your computer.
|
||
</div>
|
||
</div>
|
||
|
||
<div class="panel panel-default">
|
||
<div class="panel-heading">
|
||
<h3 class="panel-title">What happens to the indexed data?</h3>
|
||
</div>
|
||
<div class="panel-body">
|
||
<p>Sourcetrail does two things with the data collected during indexing:</p>
|
||
<ol>
|
||
<li>The data is stored in the <code>.sourcetraildb</code> file in the same directory as the <code>.sourcetrailproject</code> file. This database file is used by Sourcetrail to serve its purpose of letting you navigate your source code. And it allows Sourcetrail to reopen the project without reindexing the source code every time.</li>
|
||
<li>If logging is enabled, some of the data gets logged into a log file saved in <a href="#Datafolder">data</a>/logs. These logs can be useful to us for fixing bugs. We might ask for log information on bug reports, but you should only provide it, if your source code is not confidental.</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="row" style="height:80px;"></div>
|
||
|
||
<h1>INSTALLATION</h1>
|
||
|
||
<h2>On Windows</h2>
|
||
<p>Download and open the zip file and extract its contents into a temporary folder of your choice. Run the <var><code>setup.exe</code></var> and go through the wizard. You can now launch Sourcetrail from your start menu.</p>
|
||
|
||
<h2>On Mac</h2>
|
||
<p>Download and open the Sourcetrail.dmg file and drag Sourcetrail.app into the applications folder. You can now launch Sourcetrail from your Applications.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/installation_mac.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<h2>On Linux</h2>
|
||
<p>Download Sourcetrail.tar.gz file and extract it. To start Sourcetrail run the <code>Sourcetrail.sh</code> script. Sourcetrail creates a folder <code>~/.config/sourcetrail</code> at the first run, this is the folder for Sourcetrail settings.
|
||
To Install Sourcetrail run the <code>setup/install.sh</code> Script with sudo, it will install Sourcetrail to <code>/opt/sourcetrail</code> and
|
||
create <code>/usr/bin/sourcetrail</code> symlink.</p>
|
||
|
||
<h2>Data folder</h2>
|
||
<p>The data folder holds certain files that are used by Sourcetrail to run the program. After following the <a href="#INSTALLATION">installation instructions</a> the data folder should be located in the following locations on your platform.</p>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Platform</th> <th>Location</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Windows</th> <td>C:/Users/You/AppData/Local/Coati Software/Sourcetrail <small>(used for dynamic data and settings)</small><br />install_directory/Coati Software/Sourcetrail/data <small>(used for static app data)</small></td> </tr>
|
||
<tr> <th scope="row">Mac</th> <td>~/Library/Application Support/Sourcetrail</td> </tr>
|
||
<tr> <th scope="row">Linux</th> <td>~/.config/sourcetrail</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h2>Finding System Header Locations</h2>
|
||
|
||
<h3>On Windows</h3>
|
||
<p>These files usually ship with your compiler. For the Visual Studio IDE the system headers can be found at:</p>
|
||
<pre><path_to_visual_studio>/VC/include/</pre>
|
||
<p>If you don't use the Visual Studio IDE you can also try to find your system headers in a subdirectory of:</p>
|
||
<pre>C:/Program Files (x86)/Windows Kits/</pre>
|
||
|
||
<h3>On Mac</h3>
|
||
<p>Run this command in your terminal:</p>
|
||
<pre>gcc -x c++ -v -E /dev/null</pre>
|
||
<p>You will find the header search paths your compiler uses in the output between these two lines:</p>
|
||
<pre>#include <...> search starts here:<br />.<br />.<br />.<br />End of search list.</pre>
|
||
|
||
<h3>On Linux</h3>
|
||
<pre>gcc -x c++ -v -E /dev/null</pre>
|
||
or
|
||
<pre>clang -x c++ -v -E /dev/null</pre>
|
||
<p>You will find the header search paths your compiler uses in the output between these two lines:</p>
|
||
<pre>#include <...> search starts here:<br />.<br />.<br />.<br />End of search list.</pre>
|
||
|
||
|
||
<h2>Finding Java Runtime Library Location</h2>
|
||
|
||
<p>The current version of Sourcetrail requires an installation of the Java 8 runtime environment to index any Java project. Make sure that Sourcetrail and your JRE share the same kind or architecture (a 32 bit Sourcetrail requires a 32 bit JRE). To locate the required library file, please refer to the applicable description below.</p>
|
||
|
||
<h3>On Windows</h3>
|
||
<p>The Java Runtime Library (called <code>jvm.dll</code>) can be found inside of your JRE install folder and looks like this:</p>
|
||
<pre><path_to_jre>/bin/client/jvm.dll</pre>
|
||
|
||
<h3>On Mac</h3>
|
||
<p>The Java Runtime Library (called <code>libjli.dylib</code>) can be found inside of your JRE install folder. Run the following command in your terminal to find the location of your default Java installation:</p>
|
||
<pre>/usr/libexec/java_home</pre>
|
||
|
||
<p>This should give you a path looking like this:</p>
|
||
<pre>/Library/Java/JavaVirtualMachines/<jdk_version>/Contents/Home</pre>
|
||
|
||
The <code>"libjli.dylib"</code> should be available at:
|
||
<pre>/Library/Java/JavaVirtualMachines/<jdk_version>/Contents/Home/jre/lib/jli/libjvm.dylib</pre>
|
||
|
||
<p>Insert the full path to <code>libjli.dylib</code> into the <strong>Java Path</strong> setting in the <a href="#PreferencesWindow">Preferences Window</a>.</p>
|
||
|
||
<h3>On Linux</h3>
|
||
<p>The Java Runtime Library (called <code>libjvm.so</code>) can be found inside of your JRE install folder and looks like this:</p>
|
||
<pre><path_to_jre>/lib/<arch>/server/libjvm.so</pre>
|
||
|
||
<div class="row" style="height:80px;"></div>
|
||
|
||
<h1>USER INTERFACE</h1>
|
||
|
||
<h2>Main Window</h2>
|
||
|
||
<h3>Widget Windows</h3>
|
||
<p>Sourcetrail'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.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/main_window.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Drag the Widget Window at the title bar to rearrange it within the Main Window, detach it or attach it again.</li>
|
||
<li>Press the "x" icon to close the Widget Window. They can be reopened from the <a href="#View">View Menu</a>.</li>
|
||
<li>Press the "□" icon to detach the Widget Window from the Main Window.</li>
|
||
</ul>
|
||
|
||
<h3>Statusbar</h3>
|
||
<p>The Statusbar is located on the bottom of the <a href="#MainWindow">Main Window</a> and is used to convey information about Sourcetrail's status and currently running processes to the user.</p>
|
||
<p>If indexing yielded errors the status bar will display their count on the right side.
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/status_bar.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<p>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Click on the error count to display the error locations in the <a href="#CodeView">Code View</a>.</li>
|
||
</ul>
|
||
</p>
|
||
|
||
<h2>Windows</h2>
|
||
<h3>Start Window</h3>
|
||
<p>On every start of Sourcetrail you are shown the start window. It allows for creating new projects or opening existing ones.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/start_window.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>New Project</var> will lead you to <a href="#ProjectSetupWizard">Project Setup</a>.</li>
|
||
<li>Clicking <var>Open Project</var> will let you open an existing Sourcetrail project by choosing from a file dialog.</li>
|
||
<li>Clicking on one of the <var>Recent Projects</var> will open this project. The list shows a maximum of 7 items ordered by recent first.</li>
|
||
<li>Pressing <var>ESC</var> will close the window.</li>
|
||
</ul>
|
||
|
||
<h3>Path List Box</h3>
|
||
<p>The Path List Box is a user interface element that is used within the <a href="#PreferencesWindow">Preferences Window</a> and the <a href="#ProjectSetupWizard">Project Setup Wizard</a>. It allows for entering a list of file and directory paths.</p>
|
||
<p>If you want to use environment variables you can use either of the following notations.</p>
|
||
<pre>${VARIABLE_NAME} or %VARIABLE_NAME%</pre>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/path_list_box.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Click the "+" icon to add a new path line.</li>
|
||
<li>Click the "-" icon to remove a selected path line.</li>
|
||
<li>Click a path line to select it.</li>
|
||
<li>Enter the path by typing on your keyboard</li>
|
||
<li>Click "..." within the path line to open a file dialog for choosing a file or directory path.</li>
|
||
<li>Directly add multiple paths into the box by dropping elements from your filesystem.</li>
|
||
<li>Click the pen icon in the bottom right corner to edit the list as plain text.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h4>Plain Text Editing</h4>
|
||
<p>By pressing the pen icon in the bottom right corner you can open the plain text edition dialog. It allows you to edit the whole list within a text field. Each line will be one list item.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/path_list_box_edit.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Add and remove list items through keyboard interaction.</li>
|
||
<li>Click <var>Cancel</var> to cancel plain text editing.</li>
|
||
<li>Click <var>Save</var> to save your changes to the list.</li>
|
||
</ul>
|
||
|
||
|
||
|
||
<h3>Preferences Window</h3>
|
||
<p>The Preferences window lets you define settings for all projects. You can open the Preferences from the menu via <a href="#Edit">Edit/Preferences</a>.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/preferences_screen.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<th scope="row">Font face</th>
|
||
<td>Define the font face used throughout the UI</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Font size</th>
|
||
<td>Set the font size used throughout the UI. It can also be changed with the actions in the <a href="#View">View Menu</a></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Tab width</th>
|
||
<td>Define the space width of tabs in the code view.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Color scheme</th>
|
||
<td>Choose which color scheme Sourcetrail should display. The color schemes are located in <a href="#Datafolder">data</a>/color_schemes/</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Animations</th>
|
||
<td>Define if animations are used within the user interface.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Logging</th>
|
||
<td>Ticking this box enables logging to console and to a log file. This option is disabled by default to speed up Sourcetrail. If you encounter problems while running Sourcetrail, we recommend to enable this option so you have somewhere to start looking for a cause.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Indexer Logging</th>
|
||
<td>When enabled Sourcetrail will log detailed information during indexing. This log data can help us fix issues.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Scroll Speed</th>
|
||
<td>Define a multiplyer for the default scroll speed. Values smaller than 1 slow down scrolling while values greater than 1 increase the scroll speed.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Graph Zoom</th>
|
||
<td>Switch the default mouse wheel behavior in the graph between scrolling and zooming.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Indexer threads</th>
|
||
<td>Define how many parallel threads are used during indexing.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Sourcetrail Port</th>
|
||
<td>Port number that Sourcetrail uses to listen for incoming messages from plugins.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Plugin Port</th>
|
||
<td>Port number that Sourcetrail sends outgoing messages to.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Java Path</th>
|
||
<td>If you want to use Sourcetrail on Java source code, please specify a path to your Java 8 runtime library. Please keep in mind that a 32 bit Sourcetrail requires a 32 bit version of Java while a 64 bit Sourcetrail requires a 64 bit Java to be working correctly. You can either use the button below for automatic detection or add the path manually. For instructions on how to find your Java runtime path see <a href="#FindingJavaRuntimeLibraryLocation">Finding Java Runtime Library Location</a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">JVM Maximum Memory</th>
|
||
<td>Specify the maximum amount of memory that should be allocated by the indexer's JVM. A value of <code>-1</code> ignores this setting.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Global Include Paths</th>
|
||
<td>Set header search paths that are used for <strong>all</strong> of your projects (e.g. std headers). An option for automatic detection of these paths is available for Clang, GCC and the Visual Studio compiler. For instructions on how to add paths manually see <a href="#PathListBox">Path List Box</a>. For instructions on how to find the system header paths see <a href="#FindingSystemHeaderLocations">Finding System Header Locations</a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Global Framework Search Paths</th>
|
||
<td>Mac only. Define the search paths for <code>.framework</code> files for all of your projects. An option for automatic detection of these paths is available for Clang and GCC. For instructions on how to add paths see <a href="#PathListBox">Path List Box</a>.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
|
||
<h3>Project Setup Wizard</h3>
|
||
<p>The Project Setup Wizard consists of a sequence of windows that let you create a new Sourcetrail project. After selecting the programming language for your project Sourcetrail offers several ways for you to provide all the required information.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/project_setup_wizard_start.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Select the language used in code project.</li>
|
||
<li>Selecting a project type will determine how you enter all the required information.</li>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h4 id="CreateAnEmptyCXXProject">Create an Empty C/C++ Project</h4>
|
||
<p>This is the way to go if you just have some source files you want to index. In case you have a build instructions file, you might want to check out one of the other options for project setup described below.</p>
|
||
|
||
<strong>Project Meta Data</strong>
|
||
<p>In the first step you need to enter meta information about the project.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/project_setup_wizard_empty_meta.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Sourcetrail Project Name</th> <td>The name of the project. This will also be the name of the <code>.sourcetrailproject</code> file generated by Sourcetrail.</td> </tr>
|
||
<tr> <th scope="row">Sourcetrail Project Location</th> <td>Choose the location of the project file from the dialog.</td> </tr>
|
||
<tr> <th scope="row">Standard</th> <td>Select the language standard that should be used for indexing your project. Usually the most recent language standard is preselected here. (See <a href="#SupportedLanguages">Language Support</a>)</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process. All the information you entered will be saved.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<strong>Indexed Paths</strong>
|
||
<p>Provide the paths that contain your project's files. Sourcetrail will index all the source and header files in the specified paths, including subdirectories.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/project_setup_wizard_empty_project_paths.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Indexed Paths</th> <td>Specify one or multiple locations that contain all the source and header files that you want to index with Sourcetrail. (For instructions on how to add paths see <a href="#PathListBox">Path List Box</a>.)</td> </tr>
|
||
</tbody>
|
||
<tbody>
|
||
<tr> <th scope="row">Source File Extensions</th> <td>Define the valid extensions for source files including the dot e.g. <code>.cpp</code></td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>show files</var> will display a list of all the files Sourcetrail will index with the current settings.</li>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process. All the information you entered will be saved.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<strong>Include Paths</strong>
|
||
<p>Sourcetrail needs you to specify all the include paths the indexed source and header files rely on. The include paths are those paths your project's <code>#include</code> directives are relative to. If your project requires additional includes to compile (e.g. Boost for C++, etc.), please specify their location here.</p>
|
||
<p>Additionally you can also specify Global Include Paths, which will be used by all your projects. These are usually the paths to system headers, which can also be auto detected by choosing a compiler below and pressing <var>detect</var>.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/project_setup_wizard_empty_include_paths.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Include Paths</th> <td>These paths are used to find the files specified by <code>#include</code> directives. (For instructions on how to add paths see <a href="#PathListBox">Path List Box</a>.)</td> </tr>
|
||
<tr> <th scope="row">Lazy Include Search (deprecated)</th> <td>(Only visible in projects created before Sourcetrail 0.11) When checked Sourcetrail also looks for included files within the project paths and all their subdirectories. Use this option if you are not familiar with the project to save yourself from figuring the projects include paths. <strong>Warning:</strong> When activated indexing speed is slower.</td> </tr>
|
||
<tr> <th scope="row">Global Include Paths</th> <td>These Header Search Paths will be used in all your projects. (For instructions on how to add paths see <a href="#PathListBox">Path List Box</a>. For instructions on how to find the system header paths see <a href="#FindingSystemHeaderLocations">Finding System Header Locations</a>)</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Selecting a compiler from the dropdown list below and pressing <var>detect</var> will automatically detect system include search paths used by this compiler and add them to the Global Include Paths.</li>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process. All the information you entered will be saved.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<strong>Framework Search Paths (Mac only)</strong>
|
||
<p>Sourcetrail needs you to specify the locations of <code>.framework</code> files, your indexed source and header files rely on.</p>
|
||
<p>Additionally you can also specify Global Framework Search Paths, which will be used by all your projects. They can also be auto detected by choosing a compiler below and pressing <var>detect</var>.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/project_setup_wizard_empty_framework_paths.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Framework Search Paths</th> <td>These paths are used to find <code>.framework</code> files used by your project. (For instructions on how to add paths see <a href="#PathListBox">Path List Box</a>.)</td> </tr>
|
||
<tr> <th scope="row">Global Framework Search Paths</th> <td>These Framework Search Paths will be used in all your projects. (For instructions on how to add paths see <a href="#PathListBox">Path List Box</a>. For instructions on how to find the system header paths see <a href="#FindingSystemHeaderLocations">Finding System Header Locations</a>)</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Selecting a compiler from the dropdown list below and pressing <var>detect</var> will automatically detect system header search paths used by this compiler and add them to the Global Header Search Paths.</li>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process. All the information you entered will be saved.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<strong id="AdvancedSettings">Advanced Settings</strong>
|
||
<p>In this dialog you can enter additional settings. You can add compiler flags or defines that will be used when indexing and you can exclude certain paths or files from indexing.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/project_setup_wizard_advanced.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Compiler Flags</th> <td>Define compiler flags used during indexing including the dash (e.g. use <code>-D RELEASE</code> to add a <code>#define</code> for <code>RELEASE</code>). (For instructions on how to add paths see <a href="#PathListBox">Path List Box</a>.)</td> </tr>
|
||
<tr> <th scope="row">Exclude Paths</th> <td>Exclude Paths define the files and directories that will be left out from indexing. (For instructions on how to add paths see <a href="#PathListBox">Path List Box</a>.)</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process. All the information you entered will be saved.</li>
|
||
</ul>
|
||
|
||
<div class="callout callout-info">
|
||
<p>After this step the <a href="#NewProjectSummary">New Project Summary</a> will appear as last step in the project creation proccess.</p>
|
||
</div>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h4 id="CreateAProjectFromCompilationDatabase">Create a C/C++ Project from Compilation Database</h4>
|
||
<p>If you are using <a href="https://cmake.org/">CMake</a> you can export compile commands by defining the <code>CMAKE_EXPORT_COMPILE_COMMANDS</code> flag and then use the exportet <code>.json</code> file for Sourcetrail project setup.</p>
|
||
<p>For non-CMake projects you can use <a href="https://github.com/rizsotto/Bear">Bear</a>. Bear generates a <code>.json</code> file during the simulated build process. Bear has been tested on FreeBSD, GNU/Linux and OS X.</p>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<strong>Compilation Database Meta Data</strong>
|
||
<p>In the first step you need to enter meta information about the project and define the compilation database.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/project_setup_wizard_compilation_data.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Sourcetrail Project Name</th> <td>The name of the project. This will also be the name of the <code>.sourcetrailproject</code> file generated by Sourcetrail.</td> </tr>
|
||
<tr> <th scope="row">Sourcetrail Project Location</th> <td>Choose the location of the project file from the dialog.</td> </tr>
|
||
<tr> <th scope="row">Compilation Database</th> <td>Select the compilation database <code>.json</code> for the project. Sourcetrail will index the project based on the compile commands in this file. If the compilation database changes you can <a href="#Refresh">Refresh</a> Sourcetrail to the new files.</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process. All the information you entered will be saved.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<strong>Compilation Database Headers</strong>
|
||
<p>In the next step you can see which source files are in the compilation database and define the locations of the corresponding header files.</p>
|
||
<p>Header files will only be indexed if they are included in one of the source files.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/project_setup_wizard_compilation_header.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Source Files</th> <td>Clicking <strong>show source files</strong> will show you a list of all source files in the compilation database.</td> </tr>
|
||
<tr> <th scope="row">Indexed Header Paths</th> <td>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 <a href="#PathListBox">Path List Box</a>.)</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Select From Include Paths</var> will display a dialog showing a list of all the Include Paths used within the Compilation Database. You can select paths and all headers that are included within these paths will also get indexed.</li>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process.</li>
|
||
</ul>
|
||
|
||
<div class="callout callout-info">
|
||
<p>After this step you will continue at the <a href="#AdvancedSettings">Advanced Settings</a>.</p>
|
||
</div>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h4 id="CreateAProjectFromVisualStudio">Create a C/C++ Project from Visual Studio Solution</h4>
|
||
<p>If you are using Visual Studio you can export a Compilation Database with out <a href="#VisualStudio">Visual Studio Plugin</a> and use it to create a project with Sourcetrail.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/project_setup_wizard_visual_studio.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Create CDB</var> will communicate to the <a href="#VisualStudio">Visual Studio Plugin</a> that a project should be exported as Compilation Database. Please have a look at the <a href="#VisualStudio">Visual Studio Plugin</a> for more details on the steps within Visual Studio.</li>
|
||
</ul>
|
||
|
||
<div class="callout callout-info">
|
||
<p>After finishing the export process within Visual Studio the project setup will continue using the same steps as creating a project directly <a href="#CreateAProjectFromCompilationDatabase">from Compilation Database</a>.</p>
|
||
</div>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h4 id="CreateAnEmptyJavaProject">Create an Empty Java Project</h4>
|
||
<p>Choose this option if you want to use Sourcetrail on a Java code base.</p>
|
||
|
||
<strong>Project Meta Data</strong>
|
||
<p>In the first step you need to enter meta information about the project.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/project_setup_wizard_empty_meta_java.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Sourcetrail Project Name</th> <td>The name of the project. This will also be the name of the <code>.sourcetrailproject</code> file generated by Sourcetrail.</td> </tr>
|
||
<tr> <th scope="row">Sourcetrail Project Location</th> <td>Choose the location of the project file from the dialog.</td> </tr>
|
||
<tr> <th scope="row">Standard</th> <td>Select the language standard that should be used for indexing your project. We currently only support Java 8</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process. All the information you entered will be saved.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<strong>Indexed Paths</strong>
|
||
<p>In this step you provide all the information Sourcetrail needs to know about your code base.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/project_setup_wizard_empty_project_paths_java.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Indexed Paths</th> <td>Provide the root path of your Java project. This is the path where all your package names are relative to. You may provide multiple paths here. For an example this may be required if your project's source code resides in one location but generated source files are kept at a different location.</td> </tr>
|
||
<tr> <th scope="row">Class Path</th> <td>Add one entry per jar file that is required for the project to compile. You can also add the root path of the class files your project depends on, or add a mixture if you have class files for some of the dependencies and jar files for the rest of them.</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<strong>Advanced Settings</strong>
|
||
<p>In this dialog you can enter additional settings. You can define source file extentions and you can exclude certain paths or files from indexing.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/project_setup_wizard_advanced_java.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Setting</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Source File Extensions</th> <td>Define extensions for source files including the dot e.g. <code>.cpp</code> or <code>.java</code></td> </tr>
|
||
<tr> <th scope="row">Exclude Paths</th> <td>Exclude Paths define the files and directories that will be left out from indexing. (For instructions on how to add paths see <a href="#PathListBox">Path List Box</a>.)</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Next</var> will take you to the next step of the setup process.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process. All the information you entered will be saved.</li>
|
||
</ul>
|
||
|
||
<div class="callout callout-info">
|
||
<p>After this step the <a href="#NewProjectSummary">New Project Summary</a> will appear as last step in the project creation proccess.</p>
|
||
</div>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h3>New Project Summary</h3>
|
||
<p>This window appears at the end of the <a href = "ProjectSetupWizard">Project Setup Wizard</a> to summarize all the information entered before. It is the same as the <a href="#EditProjectWindow">Edit Project Window</a>.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/new_project_summary.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the window and abort the setup process.</li>
|
||
<li>Clicking <var>Create</var> will check your inputs, save the new project file and start indexing the source files.</li>
|
||
<li>Clicking <var>Previous</var> will take you to the previous step of the setup process. All the information you entered will be saved.</li>
|
||
</ul>
|
||
|
||
<div class="callout callout-info">
|
||
<p>If you are following the <a href="#QUICKSTARTGUIDE">Quick Start Guide</a> then please continue at <a href="#SourceIndexing">Source Indexing</a> after pressing <var>Create</var>.</p>
|
||
</div>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h3>Edit Project Window</h3>
|
||
<p>This window displays all the information relevant for your Sourcetrail project. Please have a look at the <a href = "ProjectSetupWizard">Project Setup Wizard</a> for descriptions on each setting.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/edit_project_summary.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Cancel</var> or pressing <var>ESC</var> will close the dialog with no changes made.</li>
|
||
<li>Clicking <var>Save</var> will check your inputs, save the new project file and inform you whether you need to re-index your project.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h3>Enter License Window</h3>
|
||
<p>The Enter License Window appears on your first start of Sourcetrail and is used to enter and check your Sourcetrail license key.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/license_key_window.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Copy and Paste your license key from your "Sourcetrail 0 License Key" e-mail into the textfield. The key should be formated as shown by the placeholder text.</li>
|
||
<li>Clicking <var>Activate</var> will check if your license key is valid and close the window. Otherwise an error message will be displayed.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h3>Indexing Dialogs</h3>
|
||
<p>These dialogs will be used while Sourcetrail indexes your project. The whole user interface will be frozen as long as these dialogs are visible.</p>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h4>Start Indexing Dialog</h4>
|
||
<p>This dialog displays the number of files for indexing and clearing before indexing starts.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-6 col-sm-offset-3">
|
||
<img src="img/start_indexing_dialog.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Checking <var>full refresh</var> will re-index the whole projects.</li>
|
||
<li>Clicking <var>Cancel</var> will abort indexing.</li>
|
||
<li>Clicking <var>Start</var> will start the file clearing and indexing.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h4>Progress Dialog</h4>
|
||
<p>This dialog shows that Sourcetrail is currently doing processing that can't be interrupted.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-6 col-sm-offset-3">
|
||
<img src="img/progress_dialog.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h4>Indexing Dialog</h4>
|
||
<p>This dialog shows the indexing progress of your project, by displaying the number of already indexed files, the last file that was started indexing, the number of errors and a progress estimate in percent.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-6 col-sm-offset-3">
|
||
<img src="img/indexing_dialog.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>Stop</var> or pressing ESC will interrupt indexing. Sourcetrail will still wait for the already running indexer threads to finish. You can continue indexing later by <a href="#Refresh">refreshing</a>.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:20px;"></div>
|
||
|
||
<h4>Finished Indexing Dialog</h4>
|
||
<p>This dialog is shown after indexing finished, giving you information about indexed files, duration and errors.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-6 col-sm-offset-3">
|
||
<img src="img/finished_indexing_dialog.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Clicking <var>OK</var> will close the dialog and allow you to interact with the main window again.</li>
|
||
</ul>
|
||
|
||
|
||
<h2>Menu</h2>
|
||
|
||
<h3>Project</h3>
|
||
<ul>
|
||
<li>
|
||
<strong>New Project</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">New Project</a></li>
|
||
<li>Opens the <a href="#ProjectSetupWizard">New Project</a> Dialog to define a new project and loads it after creation.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Open Project</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Open Project</a></li>
|
||
<li>Opens a file dialog to choose an existing Sourcetrail project file from your system's hard drive.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Recent Projects</strong>
|
||
<ul>
|
||
<li>Opens a submenu to choose recent opened Sourcetrail projects.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Edit Project</strong>
|
||
<ul>
|
||
<li>Opens the <a href="#EditProjectWindow">Edit Project Window</a> prefilled with your project settings and allows for changing them.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Exit</strong>
|
||
<ul>
|
||
<li>Quits Sourcetrail.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h3>Edit</h3>
|
||
<ul>
|
||
<li>
|
||
<strong>Back</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Back</a></li>
|
||
<li>Undoes the last navigation action.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Forward</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Forward</a></li>
|
||
<li>Redoes an undone navigation action.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Refresh</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Refresh</a></li>
|
||
<li>Refresh will check all indexed source files for updates and reindex the ones that changed and their depending ones.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Full Refresh</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Full Refresh</a></li>
|
||
<li>Full Refresh will reindex the whole project.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Find Symbol</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Find Symbol</a></li>
|
||
<li>This option will put the focus into the search field, so you can start typing your search query. Alternatively you can click the search field.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Find Text</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Find Text</a></li>
|
||
<li>This option will put the focus into the search field and start a new full text search query</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Code Reference Next</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Code Reference Next</a></li>
|
||
<li>Use this option to iterate to the next source location of the active symbol in the code view.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Code Reference Previous</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Code Reference Previous</a></li>
|
||
<li>Use this option to iterate to the previous source location of the active symbol in the code view.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>To overview</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">To overview</a></li>
|
||
<li>This option will display the overview of the project.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Preferences</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Preferences</a></li>
|
||
<li>Opens the <a href="#PreferencesWindow">Preferences Window</a>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h3>View</h3>
|
||
<ul>
|
||
<li>
|
||
<strong>Show Title Bars</strong>
|
||
<ul>
|
||
<li>Toggle the visibility of the bars above each <a href="#WidgetWindows">Window Widget</a>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Search Window</strong>
|
||
<ul>
|
||
<li>Toggle the visibility of the Search Window. This can also be done by closing the Search Window on clicking the "x" icon in it's title bar. (See <a href="#WidgetWindows">Window Widgets</a>)</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Graph Window</strong>
|
||
<ul>
|
||
<li>Toggle the visibility of the Graph Window. This can also be done by closing the Graph Window on clicking the "x" icon in it's title bar. (See <a href="#WidgetWindows">Window Widgets</a>)</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Code Window</strong>
|
||
<ul>
|
||
<li>Toggle the visibility of the Code Window. This can also be done by closing the Code Window on clicking the "x" icon in it's title bar. (See <a href="#WidgetWindows">Window Widgets</a>)</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Status Window</strong>
|
||
<ul>
|
||
<li>Toggle the visibility of the Status Window. This can also be done by closing the Status Window on clicking the "x" icon in it's title bar. (See <a href="#WidgetWindows">Window Widgets</a>)</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Larger Font</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Larger Font</a></li>
|
||
<li>Increase the font size within the Main Window's user interface.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Smaller Font</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Smaller Font</a></li>
|
||
<li>Decrease the font size within the Main Window's user interface.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Reset font size</strong>
|
||
<ul>
|
||
<li>Shortcut: <a href="#Shortcuts">Reset font size</a></li>
|
||
<li>Decrease the font size to the original size.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h3>Help</h3>
|
||
<ul>
|
||
<li>
|
||
<strong>About</strong>
|
||
<ul>
|
||
<li>Shows copyright information about Sourcetrail.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Keyboard Shortcuts</strong>
|
||
<ul>
|
||
<li>Shows table of keyboard shortcuts for Sourcetrail.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Documentation</strong>
|
||
<ul>
|
||
<li>Opens the documentation of Sourcetrail in your web browser by URL.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Bug Tracker</strong>
|
||
<ul>
|
||
<li>Opens Sourcetrail's bug tracker in your web browser by URL.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>3rd Party Licences</strong>
|
||
<ul>
|
||
<li>Documents which third party licences Sourcetrail is using.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Enter License...</strong>
|
||
<ul>
|
||
<li>Opens the <a href="#EnterLicenseWindow">Enter License Window</a>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Show Data Folder</strong>
|
||
<ul>
|
||
<li>Opens the file explorer showing the <a href="#Datafolder">data folder</a>.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<strong>Show Log Folder</strong>
|
||
<ul>
|
||
<li>Opens the file explorer in the directory <a href="#Datafolder">data</a>/logs where all log files are saved to. You can enable file logging in the <a href="#PreferencesWindow">Preferences Window</a>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
|
||
<h3>Shortcuts</h3>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Shortcut</th> <th>Windows</th> <th>Mac OS X</th> <th>Linux</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<th scope="row">Preferences</th>
|
||
<td><kbd>Ctrl + ,</kbd></td>
|
||
<td><kbd>Cmd + ,</kbd></td>
|
||
<td><kbd>Ctrl + ,</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">New Project</th>
|
||
<td><kbd>Ctrl + N</kbd></td>
|
||
<td><kbd>Cmd + N</kbd></td>
|
||
<td><kbd>Ctrl + N</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Open Project</th>
|
||
<td><kbd>Ctrl + O</kbd></td>
|
||
<td><kbd>Cmd + O</kbd></td>
|
||
<td><kbd>Ctrl + O</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Close Window</th>
|
||
<td><kbd>Alt + F4</kbd></td>
|
||
<td><kbd>Cmd + W</kbd></td>
|
||
<td><kbd>Ctrl + W</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Hide Window</th>
|
||
<td></td>
|
||
<td><kbd>Cmd + H</kbd></td>
|
||
<td></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Refresh</th>
|
||
<td><kbd>F5</kbd></td>
|
||
<td><kbd>Cmd + R</kbd></td>
|
||
<td><kbd>F5</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Full Refresh</th>
|
||
<td><kbd>Shift + F5</kbd></td>
|
||
<td><kbd>Cmd + Shift + R</kbd></td>
|
||
<td><kbd>Shift + F5</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Back</th>
|
||
<td><kbd>Ctrl + Z</kbd> / <kbd>Backspace</kbd></td>
|
||
<td><kbd>Cmd + Z</kbd> / <kbd>Backspace</kbd></td>
|
||
<td><kbd>Ctrl + Z</kbd> / <kbd>Backspace</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Forward</th>
|
||
<td><kbd>Ctrl + Shift + Z</kbd></td>
|
||
<td><kbd>Cmd + Shift + Z</kbd></td>
|
||
<td><kbd>Ctrl + Shift + Z</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Find Symbol</th>
|
||
<td><kbd>Ctrl + F</kbd></td>
|
||
<td><kbd>Cmd + F</kbd></td>
|
||
<td><kbd>Ctrl + F</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Find Text</th>
|
||
<td><kbd>Ctrl + Shift + F</kbd></td>
|
||
<td><kbd>Cmd + Shift + F</kbd></td>
|
||
<td><kbd>Ctrl + Shift + F</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Code Reference Next</th>
|
||
<td><kbd>Ctrl + G</kbd></td>
|
||
<td><kbd>Cmd + G</kbd></td>
|
||
<td><kbd>Ctrl + G</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Code Reference Previous</th>
|
||
<td><kbd>Ctrl + Shift + G</kbd></td>
|
||
<td><kbd>Cmd + Shift + G</kbd></td>
|
||
<td><kbd>Ctrl + Shift + G</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">To overview</th>
|
||
<td><kbd>Ctrl + Home</kbd></td>
|
||
<td><kbd>Cmd + Home</kbd> / <kbd>Cmd + Up</kbd></td>
|
||
<td><kbd>Ctrl + Home</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Larger Font</th>
|
||
<td><kbd>Ctrl + +</kbd></td>
|
||
<td><kbd>Cmd + +</kbd></td>
|
||
<td><kbd>Ctrl + +</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Smaller Font</th>
|
||
<td><kbd>Ctrl + -</kbd></td>
|
||
<td><kbd>Cmd + -</kbd></td>
|
||
<td><kbd>Ctrl + -</kbd></td>
|
||
</tr>
|
||
<tr>
|
||
<th scope="row">Reset Font Size</th>
|
||
<td><kbd>Ctrl + 0</kbd></td>
|
||
<td><kbd>Cmd + 0</kbd></td>
|
||
<td><kbd>Ctrl + 0</kbd></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<div class="row" style="height:40px;"></div>
|
||
|
||
<h2>Graph View</h2>
|
||
<p>The graph view visualizes the currently selected symbol and all its relationships to other symbols as an interactive graph visualization.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/graph_view.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<h4>Interactions:</h4>
|
||
<strong>Panning:</strong>
|
||
<ul>
|
||
<li>Drag the background area with the mouse.</li>
|
||
<li>Scroll left-right and up-down on the mouse pad.</li>
|
||
<li>Use the keys <kbd>W</kbd> <kbd>A</kbd> <kbd>S</kbd> <kbd>D</kbd>.</li>
|
||
</ul>
|
||
<strong>Zooming:</strong>
|
||
<ul>
|
||
<li>Press the <kbd>+</kbd> and <kbd>-</kbd> buttons in the lower left corner.</li>
|
||
<li>Hold <kbd>Shift</kbd> and scroll with mouse wheel or mouse pad.</li>
|
||
<li>Press <kbd>Shift + W</kbd> or <kbd>Shift + S</kbd>.</li>
|
||
<li>Press <kbd>0</kbd> to reset zoom.</li>
|
||
</ul>
|
||
|
||
<h3>Nodes</h3>
|
||
<p>Colors are corresponding to the default color scheme.</p>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Node Type</th> <th>Image</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">File</th> <td><img src="img/node_file.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Macro</th> <td><img src="img/node_macro.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Namespace & Package</th> <td><img src="img/node_namespace.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Class & Struct: <span style="font-weight:normal">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.</span></th> <td><img src="img/node_class.png" style="height:160px;"></td> </tr>
|
||
<tr> <th scope="row">Type & Template Parameter</th> <td><img src="img/node_type.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Typedef</th> <td><img src="img/node_typedef.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Variable & Field</th> <td><img src="img/node_variable.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Function & Method</th> <td><img src="img/node_function.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Enum</th> <td><img src="img/node_enum.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Non-indexed: <span style="font-weight:normal">Nodes that were not defined within the indexed files are shown with hatched background.</span></th> <td><img src="img/node_non_indexed.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Bundle: <span style="font-weight:normal">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.</span></th> <td><img src="img/node_bundle.png" style="height:40px;"></td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Click a node to activate it.</li>
|
||
<li>Drag a node to change its position.</li>
|
||
<li>Click the arrow icon in class nodes to expand and collapse it.</li>
|
||
<li>Click a bundle node to expand it.</li>
|
||
<li>Hover a node to see a tooltip that displays the node’s type.</li>
|
||
</ul>
|
||
|
||
<h3>Edges</h3>
|
||
<p>Colors are corresponding to the default color scheme.</p>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Edge Type</th> <th>Image</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">File Include</th> <td><img src="img/edge_include.png" style="height:60px;"></td> </tr>
|
||
<tr> <th scope="row">Type Use</th> <td><img src="img/edge_type_usage.png" style="height:60px;"></td> </tr>
|
||
<tr> <th scope="row">Variable Use</th> <td><img src="img/edge_variable_use.png" style="height:50px;"></td> </tr>
|
||
<tr> <th scope="row">Function Call</th> <td><img src="img/edge_call.png" style="height:40px;"></td> </tr>
|
||
<tr> <th scope="row">Inheritance</th> <td><img src="img/edge_inheritance.png" style="height:80px;"></td> </tr>
|
||
<tr> <th scope="row">Method Override</th> <td><img src="img/edge_override.png" style="height:100px;"></td> </tr>
|
||
<tr> <th scope="row">Template Parameter Use & Template Argument Use</th> <td><img src="img/edge_template_param.png" style="height:60px;"></td> </tr>
|
||
<tr> <th scope="row">Aggregation: <span style="font-weight:normal">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.</span></th> <td><img src="img/edge_aggregation.png" style="height:50px;"></td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Click an edge to see its location in the <a href="#CodeView">Code View</a>.</li>
|
||
<li>Click an aggregation edge to activate all its corresponding edges.</li>
|
||
<li>Hover an edge to see a tooltip that displays the edge’s type.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:40px;"></div>
|
||
|
||
<h2>Code View</h2>
|
||
<p>The code view displays the corresponding source code of the currently selected symbols. The code view has two modes. In list mode it contains a list of one or more files. In single file mode it shows one full source file at a time.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/code_view.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Look at the different refernces of the currently active symbol with the 2 buttons in the upper left corner.</li>
|
||
<li>Switch between Snippet List and Single File mode with the 2 buttons in the upper right corner.
|
||
<li>Scroll up and down to see the different source files.</li>
|
||
</ul>
|
||
|
||
<h3>Snippet List Mode</h3>
|
||
<p>In this mode the Code View will provide all references of the currently active symbol at once. The top most snippet will show the definition of the symbol if available.</p>
|
||
|
||
<h4>Files</h4>
|
||
<p>Each file has a title bar with the file's name and buttons to change its display state. There are 3 different states:</p>
|
||
<ul>
|
||
<li>
|
||
<strong>Minimized:</strong> The file does not show its content.
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/snippet_minimized.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
</li>
|
||
<li><strong>Snippets:</strong> The file displays the snippets containing active locations separated by lines.
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/snippet_snippets.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
</li>
|
||
<li><strong>Maximized:</strong> The whole content of the file is visible.
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/snippet_maximized.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Hover the title to see the full file path.</li>
|
||
<li>Click the title to activate the file's corresponding node.</li>
|
||
<li>Click one of the three icons on the right to change the display state of the file.</li>
|
||
</ul>
|
||
|
||
<h4>Snippets</h4>
|
||
<p>A code snippet contains the lines of interest for the currently active symbol surrounded by some more lines to provide some context. Other symbols that were indexed by Sourcetrail are framed by a box when hovered. Here Sourcetrail distinguishes between local symbols and symbols that can be related to any other part of the code base. 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).</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/code_view_snippet.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Click the top line to show the whole scope around the snippet.</li>
|
||
<li>Click a boxed symbol to activate it.</li>
|
||
<li>Click a boxed local symbol to highlight all its usages in the visible code.</li>
|
||
</ul>
|
||
|
||
<h3>Single File Mode</h3>
|
||
<p>In single file mode you will only every have one file visible at a time. The first file shown is usually the file containing the definition of the active snippet if available. Other than that the user interface is the same as in <a href="#SnippetListMode">Snippet List Mode</a>.
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/code_view_single.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<div class="row" style="height:40px;"></div>
|
||
|
||
<h2>Search View</h2>
|
||
<p>The Search View contains the search field and some other related user interface elements.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/search_view.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<h3>Back & Forward</h3>
|
||
<p>The left <var>Backward</var> button lets you undo your last navigation actions (see <a href="#Back">Back</a>) and the right <var>Forward</var> button lets you redo your undone navigation actions again (see <a href="#Forward">Forward</a>). Both buttons are only enabled when the respective actions are available at the moment.</p>
|
||
<div class="row">
|
||
<div class="col-xs-2 col-xs-offset-5">
|
||
<img src="img/undo_redo_buttons.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Hover the buttons to see a tool tip.</li>
|
||
<li>Press the buttons to execute the respective action.</li>
|
||
</ul>
|
||
|
||
<h3>Refresh</h3>
|
||
<p>The refresh button allows you to refresh the current project and reindex all updated, added and removed files. To reindex the whole project choose the <strong>Force Refresh</strong> option from the <a href="#Edit">Edit Menu</a>.</p>
|
||
<div class="row">
|
||
<div class="col-xs-2 col-xs-offset-5">
|
||
<img src="img/refresh_button.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Hover the buttons to see a tooltip.</li>
|
||
<li>Press the refresh button to refresh the project.</li>
|
||
</ul>
|
||
|
||
<h3>Overview Button</h3>
|
||
<p>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 <a href="#Shortcuts">To overview</a>.</p>
|
||
<div class="row">
|
||
<div class="col-sm-2 col-sm-offset-5">
|
||
<img src="img/overview_button.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Press the overview button to show the project overview.</li>
|
||
</ul>
|
||
|
||
<h3>Search Bar</h3>
|
||
<p>The search bar allows you to enter search requests to find one of Sourcetrail's indexed 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 <a href="#AutocompletionPopup">Autocompletion Popup</a> will show you search results matching to your entered string.</p>
|
||
<div class="row">
|
||
<div class="col-sm-6 col-sm-offset-3">
|
||
<img src="img/search_bar.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Focus the search field by clicking it or using the <a href="#FindSymbol">Find Symbol</a> action.</li>
|
||
<li>Enter your search request by typing on your keyboard.</li>
|
||
<li>By pressing enter or clicking on the search icon on the right you send your request.</li>
|
||
<li>The search field allows for most interactions known from other text fields such as moving the cursor, copy&paste and text selection.</li>
|
||
</ul>
|
||
|
||
<h3>Autocompletion Popup</h3>
|
||
<p>The Autocompletion Popup displays all <a href="#Nodes">Nodes</a> matching your search request within all indexed 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.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/search_view_completion.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Use the up and down arrow keys to switch between search results.</li>
|
||
<li>Pressing tab or clicking on the search result will insert it into the search field.</li>
|
||
<li>Pressing enter will select the search result and send the search request.</li>
|
||
</ul>
|
||
|
||
<h3>Keywords</h3>
|
||
<p>Additionally the search view provides specific keywords that select a certein group of symbols.</p>
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>keyword</th> <th>effect</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">overview</th> <td>Shows an overview of all indexed symbols in the <a href="#GraphView">graph view</a> and some statistics in the <a href="#CodeView">code view</a>.</td> </tr>
|
||
<tr> <th scope="row">error</th> <td>Shows all errors in the <a href="#CodeView">code view</a>.</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3>Full text search</h3>
|
||
<p>Search for a certain string in all indexed files by putting <code>?</code> at the front of your search query. The default full text search is case-insensitive, use <code>??</code> to search case-sensitive.</p>
|
||
<div class="row">
|
||
<div class="col-sm-12">
|
||
<img src="img/search_view_fulltext.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Start a query with <code>?</code> or use the <a href="#FindText">Find Text</a> action to do a case-insensitive full text serach.</li>
|
||
<li>Start a query with <code>??</code> to do a case-sensitive full text search.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:40px;"></div>
|
||
|
||
<h2>Status View</h2>
|
||
<p>This view provides different tabs with information about your project. This
|
||
view is hidden by default.</p>
|
||
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Click on the titles on top to switch between tabs.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:10px;"></div>
|
||
|
||
<h3>Status Tab</h3>
|
||
<p>This table gives some information about status updates while running Sourcetrail. It can be helpful to figure out why something does not the way it's expected to.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/status_view_status.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Double click on a table cell to select the text for copy&paste.</li>
|
||
<li>Use the checkboxes below to filter the shown messages by type.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:10px;"></div>
|
||
|
||
<h3>Errors Tab</h3>
|
||
<p>This list shows errors occured durring indexing.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/status_view_error.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<p>The following information is provided:</p>
|
||
<ul>
|
||
<li>Error message</li>
|
||
<li>File</li>
|
||
<li>Line number</li>
|
||
<li>Indexed (if the file is within the indexed files)</li>
|
||
</ul>
|
||
|
||
<strong>Interactions:</strong>
|
||
<ul>
|
||
<li>Click on a error line to see the location of the error in the <a href="#CodeView">Code View</a>.</li>
|
||
<li>Double click on a table cell to select the text for copy&paste.</li>
|
||
<li>Use the checkboxes below to filter the shown errors by certain criteria.</li>
|
||
</ul>
|
||
|
||
<div class="row" style="height:40px;"></div>
|
||
|
||
<h1>CODE EDITOR PLUGINS</h1>
|
||
<p>In order to make Sourcetrail the perfect partner for your development workflow you can connect Sourcetrail with different code editors. You can find the plugins in Sourcetrail's download package located in the folder <code>/ide_plugins</code>. Have a look at the following list of supported code editors to find out what editors are currently supported.</p>
|
||
<p>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 <a href="mailto:support@sourcetrail.com" target="_top">support@sourcetrail.com</a>.</p>
|
||
<p>The plugins are Opensource and available on <a href="https://github.com/CoatiSoftware/">github</a>.</p>
|
||
<strong>Supported Editors:</strong>
|
||
<ul>
|
||
<li>Atom</li>
|
||
<li>CLion</li>
|
||
<li>Eclipse</li>
|
||
<li>Emacs</li>
|
||
<li>Sublime Text 2</li>
|
||
<li>Sublime Text 3</li>
|
||
<li>Vim</li>
|
||
<li>Visual Studio 2012</li>
|
||
<li>Visual Studio 2013</li>
|
||
<li>Visual Studio 2015</li>
|
||
</ul>
|
||
<p>The communication between Sourcetrail and the code editor is achieved using a local TCP connection. Sourcetrail uses the port 6667 to listen for incoming messages. Outgoing messages will be sent to the port 6666. The port numbers can be edited in the <a href="#PreferencesWindow">Preferences Window</a>.</p>
|
||
<p>Outgoing messages are in the form:</p>
|
||
<pre>moveCursor>>absolute/file_path>>line_number>>column_number<EOM></pre>
|
||
<p>Incoming messages are in the form:</p>
|
||
<pre>setActiveToken>>absolute/file_path>>line_number>>column_number<EOM></pre>
|
||
|
||
<div class="row" style="height:40px;"></div>
|
||
|
||
<h2>From Sourcetrail</h2>
|
||
<p>If you want your editor to open a file at a specific location from within Sourcetrail, you can achieve this by either selecting the option <var>Set IDE Cursor</var> from the right-click menu in the <a href="#CodeView">Code View</a> or by simply clicking into a line in the <a href="#CodeView">Code View</a> while holding down the <kbd>Ctrl</kbd> or <kbd>Cmd</kbd> key.</p>
|
||
<div class="row">
|
||
<div class="col-sm-6 col-sm-offset-3">
|
||
<img src="img/plugin_use_in_sourcetrail.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<div class="row" style="height:40px;"></div>
|
||
|
||
<h2>To Sourcetrail</h2>
|
||
<p>By using a Sourcetrail plugin for your code editor, you can select a location within a source file and Sourcetrail 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.</p>
|
||
|
||
<h3>Atom</h3>
|
||
<strong>Repo</strong>
|
||
<p><a href="https://github.com/CoatiSoftware/atom-sourcetrail">https://github.com/CoatiSoftware/atom-sourcetrail</a></p>
|
||
|
||
<strong>Installation</strong>
|
||
<p>
|
||
<ol>
|
||
<li>In Atom go to Settings with <code>Edit -> Preferences</code> or <kbd>Ctrl</kbd> + <kbd>,</kbd></li>
|
||
<li>Go to Install and search for sourcetrail</li>
|
||
<li>Install atom-sourcetrail</li>
|
||
</ol>
|
||
</p>
|
||
<strong>Use</strong>
|
||
<p>To start the Tcp Server got <code>Packages -> Sourcetrail -> Start Server</code></p>
|
||
<p>To send a location to Sourcetrail, place the cursor and right-click and select <code>Send location to Sourcetrail</code>
|
||
or <code>Packages -> Sourcetrail -> Send location to Sourcetrail</code></p>
|
||
|
||
<h3>Clion/IntelliJ</h3>
|
||
<strong>Repo</strong>
|
||
<p><a href="https://github.com/CoatiSoftware/idea-sourcetrail">https://github.com/CoatiSoftware/idea-sourcetrail</a></p>
|
||
<strong>Installation</strong>
|
||
<p>
|
||
<ol>
|
||
<li>Go to File -> Settings</li>
|
||
<li>Plugins -> Browser Repositories</li>
|
||
<li>Search for sourcetrail</li>
|
||
<li>Install idea-sourcetrail</li>
|
||
</p>
|
||
<strong>Use</strong>
|
||
<p>If you want IntelliJ/CLion to activate a certain element in Sourcetrail, right-click that element to
|
||
bring up the context menu and choose the “Sent Location” option.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/plugin_use_in_clion.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<h3>Eclipse</h3>
|
||
<strong>Repo</strong>
|
||
<p><a href="https://github.com/CoatiSoftware/eSourcetrail">https://github.com/CoatiSoftware/eSourcetrail</a></p>
|
||
|
||
<strong>Installation</strong>
|
||
<p>
|
||
<ul>
|
||
<li>Updatesite:
|
||
<ol>
|
||
<li>In Eclipse go in the menu to <code>Help -> Install new Software...</code></li>
|
||
<li>Add the Sourcetrail Updatesite</li>
|
||
<ul>
|
||
<li>type <a
|
||
href="https://CoatiSoftware.github.io/eSourcetrail/updatesite">https://CoatiSoftware.github.io/eSourcetrail/updatesite</a>
|
||
into the <code>Work with:</code> field</li>
|
||
<li>or press <code>Add...</code> and add the address above</li>
|
||
</ul>
|
||
<li>Select all and finish the next step.</li>
|
||
<li>Eclipse needs to restart and can now communicate with Eclipse.</li>
|
||
</ol>
|
||
</li>
|
||
<li>Manually:
|
||
<ol>
|
||
<li>Download this <a
|
||
href="https://github.com/CoatiSoftware/eSourcetrail/archive/gh-pages.zip">eSourcetrail-gh-pages.zip</a>
|
||
and unzip it.</li>
|
||
<li>In Eclipse go in the menu to <code>Help -> Install new Software...</code></li>
|
||
<li>Click the <code>Add...</code> Button</li>
|
||
<li>Click the <code>Local...</code> Button select the updatesite folder in the unzipped folder</li>
|
||
<li>Select all and finish the next step.</li>
|
||
<li>Eclipse needs to restart and can now communicate with Eclipse.</li>
|
||
</ol>
|
||
</ul>
|
||
|
||
</p>
|
||
<strong>Use</strong>
|
||
<p>If you want Eclipse to activate a certain element in Sourcetrail, right-click that element to bring up the context menu and choose the “Set active Token” option.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/plugin_use_in_eclipse.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<h3>Emacs</h3>
|
||
<strong>Repo</strong>
|
||
<p><a href="https://github.com/CoatiSoftware/emacs-sourcetrail">https://github.com/CoatiSoftware/emacs-sourcetrail</a></p>
|
||
|
||
<strong>Installation</strong>
|
||
<p><ul>
|
||
<li>Manuelly</li>
|
||
<ol>
|
||
<li>Download the sourcetrail.el from <a href="https://github.com/CoatiSoftware/emacs-sourcetrail">https://github.com/CoatiSoftware/emacs-sourcetrail</a></li>
|
||
<li>In Emacs press <kbd>M</kbd> + <kbd>x</kbd> and type in <code>package-install-file</code></li>
|
||
<li>Type in the path to the downloaded sourcetrail.el file</li>
|
||
</ol>
|
||
<li>Melpa</li>
|
||
<ol>
|
||
<li>Add Melpa to your package-archives</li>
|
||
<li>Press <kbd>M</kbd> + <kbd>x</kbd> and type <code>list-packages</code></li>
|
||
<li>Search for sourcetrail and mark sourcetrail with <kbd>i</kbd> then press <kbd>x</kbd> and the confirm with yes</li>
|
||
</ol>
|
||
</ul></p>
|
||
<strong>Use</strong>
|
||
<p>If you want Emacs to activate a certain element in Sourcetrail, set your cursor to that element and
|
||
<kbd>M</kbd> + <kbd>x</kbd> and type in <code>sourcetrail-send-location</code>.</p>
|
||
<p>To get Location from Sourcetrail the sourcetrail-mode need to be active. To active the sourcetrail-mode
|
||
press <kbd>M</kbd> + <kbd>x</kbd> and type in <code>sourcetrail-mode</code></p>
|
||
|
||
<h3>Qt Creator</h3>
|
||
<strong>Repo</strong>
|
||
<p><a href="https://github.com/CoatiSoftware/qtc-sourcetrail">https://github.com/CoatiSoftware/qtc-sourcetrail</a></p>
|
||
|
||
<strong>Installation</strong>
|
||
<p><ul>
|
||
<ol>
|
||
<li>Download the plugin for your system from <a href="https://github.com/CoatiSoftware/qtc-sourcetrail/releases">here</a>.
|
||
<li>Copy the files into the plugin folder where the QtCreator is installed(eg. /usr/lib/qtcreator/plugins)
|
||
<ul>
|
||
<li>the plugin path can be found at Help -> System Information... -> PluginsPath</li>
|
||
</ul>
|
||
</li>
|
||
</ol>
|
||
</ul></p>
|
||
<strong>Use</strong>
|
||
<p>If you want QtCreator to activate a certain element in Sourcetrail, click a location to place the cursor, right-click to bring up the context menu and choose the “Sourcetrail - Set active Token” option. Please note that the position of the cursor will be sent to Sourcetrail and not the position you opened the context menu at.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/plugin_use_in_sublime_text.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<h3>Sublime Text</h3>
|
||
<strong>Repo</strong>
|
||
<p><a href="https://github.com/CoatiSoftware/sublime-sourcetrail">https://github.com/CoatiSoftware/sublime-sourcetrail</a></p>
|
||
|
||
<strong>Installation</strong>
|
||
<p><ul>
|
||
<li>Manually</li>
|
||
<ol>
|
||
<li>To install the Sourcetrail plugin for Sublime Text copy the SourcetrailPlugin folder located in your
|
||
<code>ide_plugins/sublime_text</code> to your <code>SublimeText/Packages</code> folder
|
||
</li>
|
||
<li>restart Sublime</li>
|
||
</ol>
|
||
<li>Package Controll</li>
|
||
<ol>
|
||
<li>If you dont have Package Controll for Sublime go to https://packagecontrol.io and
|
||
install it</li>
|
||
<li>Open Command Pallete with <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd></li>
|
||
<li>Select <code>Package Controll: Install Package</code></li>
|
||
<li>Install <code>sourcetrail</code></li>
|
||
</ol>
|
||
</ul></p>
|
||
<strong>Use</strong>
|
||
<p>If you want Sublime to activate a certain element in Sourcetrail, click a location to place the cursor, right-click to bring up the context menu and choose the “Sourcetrail - Set active Token” option. Please note that the position of the cursor will be sent to Sourcetrail and not the position you opened the context menu at.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/plugin_use_in_sublime_text.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<h3>Vim</h3>
|
||
<strong>Repo</strong>
|
||
<p><a href="https://github.com/CoatiSoftware/vim-sourcetrail">https://github.com/CoatiSoftware/vim-sourcetrail</a></p>
|
||
|
||
<strong>Installation</strong>
|
||
<p>
|
||
<p>Please visit the <a href="https://github.com/CoatiSoftware/vim-sourcetrail">vim-sourcetrail</a> repository on Github for details.</p>
|
||
</p>
|
||
<strong>Use</strong>
|
||
<p>If you want Vim to activate a certain element in Sourcetrail, go to the code location and use
|
||
<code>:SourcetrailActivateToken</code>, now Sourcetrail should display your the chosen location.</p>
|
||
<p>Use<code>:help sourcetrail.txt</code> get get more information about the plugin</p>
|
||
|
||
<h3>Visual Studio</h3>
|
||
<strong>Installation</strong>
|
||
<p>To install the Sourcetrail plugin for Visual Studio 2012, 2013 or 2015, just execute the corresponding vsix file located in your <code>ide_plugins/visual_studio</code>.</p>
|
||
<strong>Use</strong>
|
||
<p>If you want Visual Studio to activate a certain element in Sourcetrail, right-click that element to bring up the context menu and choose the “Set active Token” option.</p>
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/plugin_use_in_visual_studio.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<strong>Create Compilation Database (Beta)</strong>
|
||
<p>You can create a compilation database (CDB) from your VS solution. Sourcetrail projects can be created from CDBs. This feature will replace solution parsing as implemented in current Sourcetrail versions. The workflow from VS to Sourcetrail will be automated in the future. As of now CDBs have to be <a href="#CreateAProjectFromCompilationDatabase">loaded manually</a> in Sourcetrail.</p>
|
||
<p>The CDB wizard is located in the Sourcetrail section in the VS menu bar. Note that the option is only useable if a solution containing at least one C/C++ project is loaded.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-12">
|
||
<img src="img/vs_plugin_menu.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<p>In the CDB wizard you can select projects you want to include in the CDB as well as the desired build target platform and configuration and a number of other options.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-8 col-sm-offset-2">
|
||
<img src="img/vs_plugin_cdb.png" >
|
||
</div>
|
||
</div>
|
||
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Option</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Select Projects</th> <td>The list of C/C++ projects in your solution. Check all projects you want to be included in the CDB.</td> </tr>
|
||
<tr> <th scope="row">De/Select All</th> <td>Will select all projects if at least one project is not selected. If all projects are selected they will all be unselected.</td> </tr>
|
||
<tr> <th scope="row">Configuration</th> <td>A dropdown list of the available build configurations. The selected configuration determines include paths and compile flags for the CDB.</td> </tr>
|
||
<tr> <th scope="row">Platform</th> <td>A dropdown list of the available target platforms. The selected platform determines include paths and compile flags for the CDB.</td> </tr>
|
||
<tr> <th scope="row">Browse</th> <td>Opens a folder browser to select the directory where the CDB will be created in. By default it is the directory of your solution. Instead of using the folder browser you can also paste a path into the adjacent text field.</td> </tr>
|
||
<tr> <th scope="row">CDB Name</th> <td>This is the name for the CDB file. By default it is the same name as your solution.</td> </tr>
|
||
<tr> <th scope="row">C Standard</th> <td>A dropdown list of all C standards supported by Sourcetrail. If your projects contain C files select the appropriate standard. Note that we aim to automate this selection in the future.</td> </tr>
|
||
<tr> <th scope="row">Cancel</th> <td>Aborts the process and closes the wizard.</td> </tr>
|
||
<tr> <th scope="row">Create</th> <td>Creates the CDB using the specified options. Note that at least one project has to be selected to start creating.</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>Once the CDB was successfully created it can be found in the specified target directory. From this CDB you can create a Sourcetrail project as <a href="#CreateAProjectFromCompilationDatabase">described above</a>.</p>
|
||
|
||
<strong>Settings</strong>
|
||
<p>Network settings and logging options can be changed in the plugin's Tools/Options entry.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-12">
|
||
<img src="img/vs_plugin_ports_0.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<p></p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-12">
|
||
<img src="img/vs_plugin_options.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<p></p>
|
||
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Option</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">Sourcetrail Port</th> <td>The port on which Sourcetrail will receive messages. Note that this must match the port setting in Sourcetrail itself.</td> </tr>
|
||
<tr> <th scope="row">VS Port</th> <td>The port on which Visual Studio will receive messages. Note that this must match the port setting in Sourcetrail itself.</td> </tr>
|
||
<tr> <th scope="row">File Logging</th> <td>Enable log output for the plugin. Additionaly to the output file, log messages will also be displayed in VS' </td> </tr>
|
||
<tr> <th Id="vsPluginOptionObfuscation" scope="row">Log Obfuscation</th> <td>Obfuscate project- and file names as well as directories in the log output. Note that already logged data <b>will not be obfuscated retroactively</b>. A dictionary, mapping obfuscated names to original names, will be created in a seperate file.</td> </tr>
|
||
<tr> <th scope="row">Thread Count</th> <td>The number of threads used during CDB creation</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
<strong>Logging</strong>
|
||
<!-- File logging -->
|
||
<p>The plugin offers optional file logging. Should you ever have problems with the plugin we recommend to turn logging on. This will help to pinpoint and resolve the issue faster.</p>
|
||
<p>Logs will be created in <code>..\AppData\Local\Coati Software\Plugins\VS</code> folder. A new log file will be created every time you restart VS and logging is enabled.</p>
|
||
|
||
<div class="row">
|
||
<div class="col-sm-12">
|
||
<img src="img/vs_log_folder.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Obfuscation -->
|
||
<p>Note that the logs will include project- and file names as well as directories specific to your project. If you wish to keep this informatin secret you can use <a href="#vsPluginOptionObfuscation">log obfuscation</a>.</p>
|
||
<p>Project- and file names as well as directories will be replaced by an alphanumeric sequence. The sequence has the form <code>a0, b0, c0,..., a1, b1, c1,...</code>. Note that after switching on obfuscation, already logged data <b>will not be obfuscated retroactively</b>. No log files will be send to Coati Software automatically. You can check any file you may want to send us for sensible information before sending it.</p>
|
||
<p>A dictionary, mapping obfuscated names to original names, will be created in your log folder if log obfuscation is switched on. When during the support process we refer to project items by their obfuscated name you can still make sense of it. <b>Do not send the dictionary to anybody else</b>.</p>
|
||
|
||
<!-- Console logging -->
|
||
<p>Lastly, log messages are also displayed in the VS output window. This is tied to file logging and is not en- or disabled separately.</p>
|
||
<div class="row">
|
||
<div class="col-sm-10 col-sm-offset-1">
|
||
<img src="img/vs_output_window.png" style="width:100%;">
|
||
</div>
|
||
</div>
|
||
|
||
<div class="row" style="height:40px;"></div>
|
||
|
||
<h2>IDE Communication Protocol</h2>
|
||
<p>Sourcetrail's IDE plugins communicate with Sourcetrail via sockets, using TCP. Sourcetrail implements a number of messages to provide an interface for the plugins.</p>
|
||
<p>This chapter explains the general structure of those messages, followed by a list of possible message types.</p>
|
||
|
||
<h3>Message Structure</h3>
|
||
|
||
<p>The basic structure of the messages used by Sourcetrail plugins consists of a prefix to identify the message type, followed by no, one, or multiple parameters and ends with an 'end-of-message' token. Parameters and tokens are seperated by a 'divider' token.</p>
|
||
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Name</th> <th>Token</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row">messageType</th> <th><a href="#MessageTypes">see below</a></th> <td>A string that determines how the message will be interpreted by Sourcetrail or the plugin</td> </tr>
|
||
<tr> <th scope="row">divider</th> <th><code>>></code></th> <td>Seperates the tokens of the message</td> </tr>
|
||
<tr> <th scope="row">parameter</th> <th><a href="#MessageTypes">see below</a></th> <td>Typically an integer or string</td> </tr>
|
||
<tr> <th scope="row">endOfMessage</th> <th><code><EOM></code></th> <td>Helps to determine the end of a message</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<p>Messages have the following form:</p>
|
||
|
||
<p><code>messageType<<parameter<<...<<parameter<EOM></code></p>
|
||
|
||
<h3>Message Types</h3>
|
||
|
||
<p>Sourcetrail does implement a number of message types that can be used by Sourcetrail plugins. In the following is a list of the messages that Sourcetrail may send to plugins and messages that may be sent by a plugin to Sourcetrail.</p>
|
||
|
||
<p>Note that you can chose which messages you want to implement. Sourcetrail will not make problems if you chose to ignore certain messages.</p>
|
||
|
||
<strong>Incoming messages</strong>
|
||
<p>These messages may be received by a plugin.</p>
|
||
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Message</th> <th>Parameters</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row"><code>moveCursor</code></th> <th>fileLocation: string<br>row: integer<br>column: integer</th> <td>Set the cursor of your editor or IDE to the given file location.<br>Note that fileLocation is the absolute path and name of the target file.</td> </tr>
|
||
<tr> <th scope="row"><code>createCDB</code></th> <th></th> <td>Sourcetrail may send this message to prompt your plugin to create a Compilation Database (CDB). Once the CDB is ready you may want to respond with a <code>createCDBProject</code> message.</td> </tr>
|
||
<tr> <th scope="row"><code>ping</code></th> <th></th> <td>Sourcetrail may send a ping to determine if anybody is listening. Respond with a ping message yourself. Sourcetrail will not respond to this message.</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<strong>Outgoing messages</strong>
|
||
<p>Your plugin may send these messages to Sourcetrail.</p>
|
||
|
||
<table class="table table-hover">
|
||
<thead>
|
||
<tr> <th>Message</th> <th>Parameters</th> <th>Description</th> </tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr> <th scope="row"><code>setActiveToken</code></th> <th>fileLocation: string<br>row: integer<br>column: integer</th> <td>Tells Sourcetrail to shift focus to the token located at the given position. Note that fileLocation is the absolute path and name of the target file.</td> </tr>
|
||
<tr> <th scope="row"><code>createCDBProject</code></th> <th>cdbPath: string<br>headerPaths: string</th> <td>If your plugin can provide a Compilation Database this message can prompt Sourcetrail to import it and display an appropriate dialog for the user. headerPaths is a list of the base project's header include paths. Seperate the single paths using the divider token. You can add as many paths as you need.</td> </tr>
|
||
<tr> <th scope="row"><code>ping</code></th> <th></th> <td>Your plugin may send this message to Sourcetrail to tell it it's listening.</td> </tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<div class="row" style="height:40px;"></div>
|
||
<address>
|
||
<strong>Coati Software OG</strong><br>
|
||
Jakob-Haringer-Straße 1/127<br>
|
||
5020 Salzburg<br>
|
||
Austria<br>
|
||
</address>
|
||
|
||
<address>
|
||
<strong>Contact</strong><br>
|
||
<a href="http://coati.io">coati.io</a><br>
|
||
<a href="mailto:mail@coati.io" target="_top">mail@coati.io</a><br>
|
||
</address>
|
||
|
||
</div> <!-- .span9 !-->
|
||
</div> <!-- .row !-->
|
||
</div> <!-- .container-fluid !-->
|
||
|
||
<script src="js/jquery-1.12.0.min.js"></script>
|
||
<script src="js/jquery-ui.min.js"></script>
|
||
<script src="js/jquery.tocify.js"></script>
|
||
|
||
<script>
|
||
$(function() {
|
||
var toc = $("#toc").tocify({ selectors: "h1, h2, h3", showAndHide: window.innerWidth >= 768 });
|
||
});
|
||
</script>
|
||
</body>
|
||
</html>
|
||
|