coatisoftware / sourcetrail

Sourcetrail - free and open-source interactive source explorer

Sourcetrail

Important Note: This project was archived by the original autors and maintainers of Sourcetrail by the end of 2021. If you want to know more about this decision, read more on our blog.

Sourcetrail is a free and open-source cross-platform source explorer that helps you get productive on unfamiliar source code.

Windows:

Linux:

Links

• Download
• Quick Start Guide
• Documentation
• Changelog

Sourcetrail is:

• free
• working offline
• operating on Windows, macOS and Linux
• supporting C, C++, Java and Python
• offering an SDK (SourcetrailDB) to write custom language extensions

Sourcetrail on Patreon

The open-source development and regular software releases are made possible entirely by the support of these awesome patrons!

Using Sourcetrail

To setup Sourcetrail on your machine, you can either download the respective build for your operating system from our list of Releases and install it on your machine, or use one of the following package managers:

• Use the Chocolatey package with choco install sourcetrail

After your installation is complete, follow our Quick Start Guide to get to know Sourcetrail.

How to Report Issues

You can post all your feature requests and bug reports on our issue tracker.

Reporting

Use the following template:

• platform version:
• Sourcetrail version:
• description of the problem:
• steps to reproduce the problem:

Supporting

If you want to support a certain feature request or you have the same bug that another user already reported, please let us know:

• post a comment with "+1" to the issue
• or send an email to [email protected] with the issue ID

How to Contribute

• Please read and follow the steps in CONTRIBUTING.md file.
• You may want to look out for issues labeled good first issue to find some initial tasks to tackle.
• If you are looking for more information about Sourcetrail software development, please refer to our wiki.

How to Build

Building Sourcetrail requires several dependencies to be in place on your machine. However, our CMake based setup allows to disable indexing support for specific languages which reduces the number of dependencies to a minimum.

Building the Base Application

Required Tools

• CMake v3.12 (required for Windows, Linux and MacOS)

  • Reason: Used to generate a build configuration for your build system
  • Download: https://cmake.org/download

• Git (required for Windows, Linux and MacOS)

  • Reason: Used for version control and to automatically generate the Sourcetrail version number from commits and tags
  • Download: https://git-scm.com/download
  • Remarks: Make sure git is added to your PATH environment variable before running CMake

• Visual Studio (required for Windows)

  • Reason: Used for building Sourcetrail
  • Download: https://visualstudio.microsoft.com/downloads/

• ccache (optional for Linux and MacOS)

  • Reason: Used to speed up rebuilds if found in PATH
  • Download: https://ccache.dev/download.html

Required dependencies

• Boost 1.67

  • Reason: Used for file system access and interprocess communication
  • Prebuilt Download for Windows: https://sourceforge.net/projects/boost/files/boost-binaries/
  • Building for Unix:

    $ ./bootstrap.sh --with-libraries=filesystem,program_options,system,date_time
    $ ./b2 --link=static --variant=release --threading=multi --runtime-link=static --cxxflags=-fPIC
    

• Qt 5.12.3

  • Reason: Used for rendering the GUI and for starting additional (indexer) processes.
  • Prebuilt Download: http://download.qt.io/official_releases/qt/

Building

On Windows

• To set up your build environment run:

  $ git clone https://github.com/CoatiSoftware/Sourcetrail.git
  $ cd Sourcetrail
  $ mkdir -p build/win64
  $ cd build/win64
  $ cmake -G "Visual Studio 15 2017 Win64" -DBOOST_ROOT=<path/to/boost_1_67_0> -DQt5_DIR=<path/to/Qt/version/platform/compiler/lib/cmake/Qt5> ../..
  

  Hint: If you are using the CMake GUI, we recommend that you activate advanced mode. Also you may be required to add some of the defines via the "Add Entry" button.

• After generating the build configuration, just open the Sourcetrail.sln file that was generated by CMake and build the Sourcetrail project.

On Unix

• To set up your build environment run:

  $ cd Sourcetrail
  $ mkdir -p build/Release
  $ cd build/Release
  $ cmake -DCMAKE_BUILD_TYPE="Release" -DBOOST_ROOT=<path/to/boost_1_67_0> -DQt5_DIR=<path/to/Qt/version/platform/compiler/lib/cmake/Qt5> ../..
  

• Now start the build with:

  $ make Sourcetrail
  

Running

• Run Sourcetrail from within the build directory. During execution Sourcetrail needs resources from bin/app/data and bin/app/user. CMake creates symlinks within the build directory that make these directories accessible.

Enable C/C++ Language Support

Required dependencies

• LLVM/Clang 11.0.0
  • Reason: Used for running the preprocessor on the indexed source code, building and traversing an Abstract Syntax Tree and generating error messages.
  • Building: Make sure to check out the correct tag: git checkout llvmorg-11.0.0
  • Building for Windows: Follow these steps to build the project. Run the cmake command exactly as described.
  • Building for Unix: Follow this installation guide to build the project. Make sure to build with -DLLVM_ENABLE_RTTI=ON.

Building

• Run CMake with these additional options:

  -DClang_DIR=<path/to/llvm_build>/lib/cmake/clang
  -DBUILD_CXX_LANGUAGE_PACKAGE=ON
  

• Build Sourcetrail as described above.

Enable Java Language Support

Required dependencies

• JDK 1.8

  • Reason: Used to build the Java indexer and make it callable from the C++ code via JNI.
  • Remarks: Make sure that <jdk_root>/bin is available in your PATH environment variable and that the JAVA_HOME environment variable is set:

    JAVA_HOME=<path/to/Java>/jdk1.x.x_xxx
    

• Maven

  • REASON: Used within Sourcetrail's automated tests.
  • Remarks: Make sure .../apache-maven-x.x.x/bin is available in your PATH environment variable and that both M2_HOME and MAVEN_HOME environment variables are set:

    M2_HOME=.../apache-maven-x.x.x
    MAVEN_HOME=.../apache-maven-x.x.x
    

Building

• Run CMake with these additional options:

  -DBUILD_JAVA_LANGUAGE_PACKAGE=ON
  

• Build Sourcetrail as described above.

Enable Python Language Support

Required Tools

• 7z (required for Windows)
  • REASON: Used to extract the prebuilt SourcetrailPythonIndexer which is downloaded automatically during build execution.

Building

• Run CMake with these additional options:

  -DBUILD_PYTHON_LANGUAGE_PACKAGE=ON
  

• Build Sourcetrail as described above.

Creating the deployment Package

Windows

Required Tools

• Visual Studio (required for Windows)

  • Reason: Used for building the Sourcetrail Windows installer.
  • Remarks: Make sure to install the .Net desktop development workload.
  • Download: https://visualstudio.microsoft.com/downloads/

• Wix 3.11

  • Reason: Used to build the sourcetrail.msi Windows installer.
  • Remarks: Make sure to add <path/to>/WiX Toolset v3.11/bin to your PATH environment variable.
  • Download: https://wixtoolset.org/releases/

• Wix extension for Visual Studio

  • Reason: Used to run Wix from the Visual Studio build environment.
  • Download: https://marketplace.visualstudio.com/items?itemName=WixToolset.WixToolsetVisualStudio2017Extension

• JRE

  • Reason: Used for indexing the java sample project that ships with the package.

• WinRAR

  • Reason: Used for creating the final zip files for the installer and the portable package.
  • Remarks: Make sure to add <path/to>/WinRAR to your PATH environment variable.

Building

• Run ./script/deploy_windows.sh from your Developer Command Prompt for Visual Studio. The script which will generate a 64bit build and packages it into a portable .zip file and a Wix-based Windows installer, each.

macOS

After building, run the bundle_install.sh script within the build directory which will create a Sourcetrail.app bundle and generate a Sourcetrail_<version>.dmg container.

Linux

Run ./setup/Linux/createPackages.sh from the main directory, which creates both a .tar.gz and a .AppImage package in the main directory. Packaging depends on linuxdeployqt.

How to Run the Tests

The automated test suite of Sourcetrail is powered by Catch2. To run the tests, simply execute the Sourcetrail_test binary. Before executing, please make sure to set the working directory to ./bin/test.

License

Sourcetrail is licensed under the GNU General Public License Version 3.

Trademark

The "Sourcetrail" name is a trademark owned by Coati Software and is not included within the assets licensed under the GNU GPLv3.

sourcetrail's Issues

Allow additional extensions for c++ source files

A reasonably common practice for template classes is to place the class declaration in an h/hpp file, and then place the class definition in an ipp file and include the ipp file from the hpp file. For example, the boost libraries do this.

It seems as though the ipp files are not being considered c++ code by Coati. Consider the following files:

foo.hpp

#ifndef __FOO_HPP__
#define __FOO_HPP__

template <typename T>
struct foo
{
    void go();
};

#include "foo.ipp"

#endif /* __FOO_HPP__ */

foo.ipp

#include <iostream>
#include "foo.hpp"

template <typename T>
void foo<T>::go()
{
    std::cout << "Hello World!" << std::endl;
}

main.cpp

#include "foo.hpp"

int main()
{
    foo<int> my_foo;
    my_foo.go();
}

Makefile

all:
    clang++ -std=c++11 main.cpp

ipp-test.coatiproject

<?xml version="1.0" encoding="utf-8" ?>
<config>
    <language_settings>
        <language>C++</language>
        <standard>11</standard>
    </language_settings>
    <source>
        <header_search_paths>
            <header_search_path>/usr/lib64/../include/c++/5.3.0</header_search_path>
            <header_search_path>/usr/lib64/../include/c++/5.3.0/x86_64-unknown-linux-gnu</header_search_path>
            <header_search_path>/usr/lib64/../include/c++/5.3.0/backward</header_search_path>
            <header_search_path>/usr/local/include</header_search_path>
            <header_search_path>/usr/lib/clang/3.7.1/include</header_search_path>
            <header_search_path>/usr/include</header_search_path>
        </header_search_paths>
        <source_paths>
            <source_path>/home/aaronj/sandbox/ipp-test</source_path>
        </source_paths>
        <use_source_paths_for_header_search>0</use_source_paths_for_header_search>
    </source>
</config>

When Coati attempts analysis I get the following output 12:36:43 | Storage.cpp:1188 addSourceLocation() | ERROR: Can't create source location, file node does not exist for: /home/aaronj/sandbox/ipp-test/foo.ipp

Coati reports no errors were encountered:

However, the source of the go function can't be retrieved:

If I put the code in foo.ipp directly into foo.hpp and rerun the analysis things work as expected and the go function is no longer undefined.

It would be good to allow users to specify custom extensions that should be parsed by Coati as C/C++ code.

Crash on Arch Linux 64bit, kernel 4.2.5

output:
$ ./Coati.sh
/path-to-coati/coati
QPixmap::scaleHeight: Pixmap is a null pixmap
QPixmap::scaleHeight: Pixmap is a null pixmap
: CommandLine Error: Option 'help-list' registered more than once!
LLVM ERROR: inconsistency in registered CommandLine options

Support Mac multitouch gestures for back and forward

When edit Path open Folder Picker at current Path

When opening the Folder Picker when editing a path (e.g. when editing a project), open it at the current path.

Filter by read/write access to fields/variables

Could potentially be done by checking if the variable in an l-value in a statement.

Use active path in file dialogs

Currently file dialogs show the working directory of Coati's executable when being opened.

Highlight code locations next to scroll bar in expanded code view

When a code snippet is expanded, highlight the location of the active token next to scroll bar (like e.g. VS displays search results)

Support Objective-C

New project/setup type dialog too small on Windows10

The dialog for creating a new project and selecting type of setup (simple or too small) is too small. Not all elements are visible. It is possible to scroll down to the advanced radio button but not to show all text.

See attached screen shot

Allow view windows that are disconnected from the main window to go into fullscreen.

Select code in Code view and copy it to clipboard

Currently collides with the panning feature in the code view -> You can click and drag the code view to scroll it.

Global header search paths not saved to AppSettings

antergos linux, with gcc 5.3.0

Add home-button to return to overview

Currently this can by done by using the keyword 'overview' in the search bar.
A button would be more straight forward, but also clutters the UI.
Opinions?

Vote with +1 or -1

Debian Wheezy - Startup not possible

Dear Coati team,

I'm using Debian Oldstable Wheezy. There is no startup possible, in cause of some dependencies. I use an actual Linux kernel version, see "uname -an" output below.

Here the startup output:

---

coati$ ./Coati.sh
/home/tim/Coati/Coati-0.3.0-Linux/coati
/home/tim/Coati/Coati-0.3.0-Linux/coati/Coati: relocation error: /home/tim/Coati/Coati-0.3.0-Linux/coati/lib/libc.so.6: symbol _dl_find_dso_for_object, version GLIBC_PRIVATE not defined in file ld-linux-x86-64.so.2 with link time reference

coati$ ./Coati
./Coati: error while loading shared libraries: libQt5Widgets.so.5: cannot open shared object file: No such file or directory

coati$ cat /etc/debian_version
7.9

coati$ uname -an
Linux p1hee002 4.0.4 #1 SMP Tue Jun 2 13:51:48 CEST 2015 x86_64 GNU/Linux

---

I think I need some newer libraries to startup Coati successfully.

Best regards,
Tim

Reset size of File List Box in New Project Window

After having created a project with many files, when creating yet a new project the file list boxes are still very big, please reset size to fit window

Support CMake files for project setup

Feature request: creating a project using a CMake file.

Display basic datatypes differently

Datatypes such as 'int' or 'char' are currently shown as undefined nodes in the graph, because they don't have a declaration in any source file.

Should they be displayed as defined nodes? Or have a different node style for basic datatypes?

Create Coati project from command line by passing directory or file paths as arguments

Set compiler flags via GUI

Even though Coati already supports compiler flags this feature is quite hard to find. To specify such a flag the user needs to open the *.coatiproject file in a text editor and add them manually as child nodes of the <source> node in the following way.

<source>
    <compiler_flags>
        <compiler_flag>...</compiler_flag>
    </compiler_flags>
<source>

For the future it should be possible to view and enter these flags in the project setup wizard and in the project settings.

Rename "undo & redo" to "back & forward"

Crash on Windows for UrHo3D project

Windows log: https://gist.github.com/ViteFalcon/246edcb3c730224354d9

Tooltips unreadable in dark scheme

Can't parse source code with C++14 standard

Windows tool tips hover

On Windows tool tips of errors in code view disappear when mouse moves a little (even when it is still on the error mark)

Add support for excluding files

Wrong font size in UI on Windows 8.1

Can't resize views when detached from main window on Mac OSX

Is a Qt 5.5 bug: https://bugreports.qt.io/browse/QTBUG-46882

Shortcut after installation always runs some .msi files

(Only tested for Win10) The shortcut that is placed in the start menu calls always some .msi file that is placed in C:\Windows\Installer which starts after some further clicks the program (a dialogue shows up which says something with "please wait while windows configures coati") instead of calling the coati.exe directly.

Generate overview map with all nodes

Visual Studio Solution/Project parsing

loading a coati project based on a .sln or .vcxproj file would be nice

Refreshing a project in the Trial build destroys the project

Automatic std header search path retrieval

Wouldn't it be nice if Coati could detect what the std header search paths are on each system?

Show fatal errors of code analysis

When a fatal error arises during source code analysis the compiler usually stops which results in an incomplete analysis.
Therefore Coati's UI should show if there are any fatals among the errors it generated so that we know whether or not it is really important to fix an error.

Project header file is not found (Unreal Engine 4 project)

All other header files are found except for the "project" header file which is basically included in every source file in an unreal project even though it lies in the same directory as the rest of the files which were found successfully.

Crash if you try to open project without having sufficient access rights

When I try to open a Coati Project from a protected directory (in my case C:\Program Files (x86)\SomeFolder) Coati crashes.

NOTE: All source files referenced in the project are also inside a subfolder of Program Files.

Can't maximize Window with Mac SizeUp

http://www.irradiatedsoftware.com/sizeup/

Global Header Search Paths are not getting saved

What?: Global Header Search Paths does not get saved and disappears upon restarting Coati.

How to reproduce?

1. Open a project that has errors.
2. Go to 'Help' -> 'Preferences...'
3. Add header file locations.
4. Click 'Save'
5. Restart Coati

What is expected?: The paths added to Global Header Search Paths should stay

What happens?: There are no paths listed in Global Header Search Paths.

Add view with project file tree

2 finger swipe sideways for using undo and redo on Mac OS

VS plugin: Menu item "Create Coati Project" not clickable

The Coati menu itself is shown, but the only entry "Create Coati Project" is grayed out and not clickable. VS Version 2015 (Community), Coati Version 0.5.0.4

Create Coatiproject from VS Solution with no license entered

When you try to create coatiproject from Visual Studio, while the "Enter License" window is open, this windows disappears and a disabled "New project form vs solution" windows appears

Pin Graph Nodes and Edges

Pin graph nodes and edges to the screen so they don't disappear when moving on to another node. Would enable creating a specific map of a certain procedure, kinda like the attached image

Highlight both opening and closing bracket in Code view while hovering either one

Visual studio headers cause errors

Visual studio integration aside, some of the not quite standard features that Microsoft is known for seems to be causing errors in the their header files.

I doubt that this is affecting the parsing of my project, however, it is a bit frustrating, and after trying out several of the Visual Studio include paths, it seems that Visual Studio 2013 has the fewest errors. The error that appears is from a file in any of the paths which I have added to the project.

Most strangely of all, I can't figure out where it's found this file from. It's not in the directories I've pointed it at, neither the Visual Studio include files, nor the SFML installation on my system have any references to this file.

I've also gone into the logs and found no mention of where this file is, it reports that the error is present, but does not show the error itself.

Show Qt SIGNAL & SLOT calls

Coati doesn't show a QT SLOT is calling a user provided function

Using CTRL+MouseWheel (unlocked) causes Coati to become unresponsive

I am assuming that CTRL+Wheel changes the font size by one step?!

Using an unlocked mouse wheel I can cause Coati to soft lock into a "refresh loop" because of the thousand "change font size instructions". Even worse: If I try to type into the search bar while Coati is in that state will cause the auto complete result list to be drawn over other applications once Coati reaches the point when it processes these UI inputs.

Support Swift

Avoid project re-parsing when opening project via file association (windows)

Projects get re-parsed when opened directly (double klicked) rather than via open-project dialog in coati

Change analyzed file extensions via GUI

Coati crashes on Debian Jessie

Coati Version 0.3.0 for Linux

OS: Debian 8.2 jessie
Kernel: x86_64 Linux 4.2.0-1-amd64

when executing in the command line, following error occours

./Coati.sh 
Segmentation fault

tried to backtrack the error, but debugsymbols are, certainly, turned off. Could backtrack it to

exec $COATI_PATH/Coati