# Technical Documentation: ondrajz/go-callvis

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/ondrajz/go-callvis)

### Overview (`README.md`)

<p align="center"><img src="images/gopher.png" alt="gopher"></p>

<h1 align="center">go-callvis</h1>

<p align="center">
  <a href="https://github.com/ondrajz/go-callvis/releases"><img src="https://img.shields.io/github/release/ondrajz/go-callvis.svg?label=latest%20release&logo=github&sort=semver&color=blue" alt="Github release"></a>
  <a href="https://github.com/ondrajz/go-callvis/actions"><img src="https://github.com/ondrajz/go-callvis/actions/workflows/ci.yml/badge.svg" alt="Build status"></a>
  <a href="https://github.com/nikolaydubina/go-recipes"><img src="https://raw.githubusercontent.com/nikolaydubina/go-recipes/main/badge.svg?raw=true" alt="go-recipes"></a>
  <a href="https://gophers.slack.com/archives/go-callvis"><img src="https://img.shields.io/badge/gophers%20slack-%23go--callvis-ff69b4.svg" alt="Slack channel"></a>
</p>

<p align="center"><b>go-callvis</b> is a development tool to help visualize call graph of a Go program using interactive view.</p>

---

## Introduction

The purpose of this tool is to provide developers with a visual overview of a Go program using data from call graph 
and its relations with packages and types. This is especially useful in larger projects where the complexity of 
the code much higher or when you are just simply trying to understand code of somebody else.

### Features

- click on package to quickly switch the focus using [interactive viewer](#interactive-viewer)
- focus specific package in the program
- group functions by package
- group methods by their receiver type
- filter packages to specific import path prefixes
- ignore calls to/from standard library
- omit various types of function calls

### Output preview

[](images/main.png)

> Check out the [source code](examples/main) for the above image.

### How it works

It runs [pointer analysis](https://godoc.org/golang.org/x/tools/go/pointer) to construct the call graph of the program and 
uses the data to generate output in [dot format](http://www.graphviz.org/content/dot-language), which can be rendered with Graphviz tools.

## Quick start

### Installation

#### Requirements

- [Go](https://golang.org/dl/) 1.19+
- [Graphviz](http://www.graphviz.org/download/) (optional, required only with `-graphviz` flag)

To install go-callvis, run:

```sh
# Latest release
go install github.com/ofabry/go-callvis@latest

# Development version
go install github.com/ofabry/go-callvis@master
```

Alternatively, clone the repository and compile the source code:

```sh
# Clone repository
git clone https://github.com/ofabry/go-callvis.git
cd go-callvis

# Compile and install
make install
```

### Usage

#### Interactive viewer

To use the interactive view provided by a web server that serves SVG images of focused packages, you can simply run:

`go-callvis <target package>` 

HTTP server is listening on [http://localhost:7878/](http://localhost:7878/) by default, use option `-http="ADDR:PORT"` to change HTTP server address.

#### Render static output

To generate a single output file use option `-file=<file path>` to choose output file destination.

The output format defaults to `svg`, use option `-format=<svg|png|jpg|...>` to pick a different output format.

#### Options

```
/* Detailed source-code truncated for AI context efficiency. */
```

Run `go-callvis -h` to list all supported options.

## Reference guide

Here you can find descriptions for various types of output.

### Packages / Types

|Represents  | Style|
|----------: | :-------------|
|`focused`   | **blue** color|
|`stdlib`    | **green** color|
|`other`     | **yellow** color|

### Functions / Methods

|Represents   | Style|
|-----------: | :--------------|
|`exported`   | **bold** border|
|`unexported` | **normal** border|
|`anonymous`  | **dotted** border|

### Calls

|Represents   | Style|
|-----------: | :-------------|
|`internal`   | **black** color|
|`external`   | **brown** color|
|`static`     | **solid** line|
|`dynamic`    | **dashed** line|
|`regular`    | **simple** arrow|
|`concurrent` | arrow with **circle**|
|`deferred`   | arrow with **diamond**|

## Examples

Here is an example for the project [syncthing](https://github.com/syncthing/syncthing).

[](https://raw.githubusercontent.com/ondrajz/go-callvis/master/images/syncthing.png)

> Check out [more examples](examples) and used command options.

## Community

Join [#go-callvis](https://gophers.slack.com/archives/go-callvis) channel at [gophers.slack.com](http://gophers.slack.com). (*not a member yet?* [get invitation](https://gophersinvite.herokuapp.com))

### How to help

Did you find any bugs or have some suggestions?
- Feel free to open [new issue](https://github.com/ondrajz/go-callvis/issues/new) or start discussion in the slack channel.

Do you want to contribute to the project?
- Fork the repository and open a pull request. [Here](https://github.com/ondrajz/go-callvis/projects/1) you can find TODO features.

---

#### Roadmap

##### The *interactive tool* described below has been published as a *separate project* called [goexplorer](https://github.com/ondrajz/goexplorer)!

> Ideal goal of this project is to make web app that would locally store the call graph data and then provide quick access of the call graphs for any package of your dependency tree. At first it would show an interactive map of overall dependencies between packages and then by selecting particular package it would show the call graph and provide various options to alter the output dynamically.

---

### Overview (`examples/README.md`)

# Examples

This document contains examples of various projects from Github.

#### Projects
  - [Syncthing](https://github.com/syncthing/syncthing)
  - [Docker](https://github.com/docker/docker)
  - [Travis CI Worker](https://github.com/travis-ci/worker)


## Syncthing

[](https://raw.githubusercontent.com/ofabry/go-callvis/master/images/syncthing.png)

```sh
go get -u github.com/syncthing/syncthing/
cd $GOPATH/src/github.com/syncthing/syncthing

# Syncthing needs a special build process, so don't forget to call build.sh
./build.sh
```

# Generate graph and launch webserver
```sh
go-callvis -focus upgrade -group pkg,type -limit github.com/syncthing/syncthing -ignore github.com/syncthing/syncthing/lib/logger github.com/syncthing/syncthing/cmd/syncthing
```

---

### Focusing package _upgrade_

[](https://raw.githubusercontent.com/ofabry/go-callvis/master/images/syncthing_focus.png)

```sh
go-callvis -format=png -file=syncthing_focus -focus upgrade -limit github.com/syncthing/syncthing github.com/syncthing/syncthing/cmd/syncthing
```
---

### Grouping by _packages_

[](https://raw.githubusercontent.com/ofabry/go-callvis/master/images/syncthing_group.png)

# Generate graph focused on module 'upgrade', output to PNG file
```sh
go-callvis -format=png -file=syncthing_group -focus upgrade -group pkg -limit github.com/syncthing/syncthing github.com/syncthing/syncthing/cmd/syncthing
```
---

### Ignoring package _logger_

[](https://raw.githubusercontent.com/ofabry/go-callvis/master/images/syncthing_ignore.png)

# Generate graph focused on module 'upgrade' and ignoring 'logger', output to webserver
```sh
go-callvis -focus upgrade -group pkg -ignore github.com/syncthing/syncthing/lib/logger -limit github.com/syncthing/syncthing github.com/syncthing/syncthing/cmd/syncthing
```
---

## Docker

[](https://raw.githubusercontent.com/ofabry/go-callvis/master/images/docker.png)

```sh
go-callvis -format=png -file=docker -limit github.com/docker/docker -ignore github.com/docker/docker/vendor github.com/docker/docker/cmd/docker | dot -Tpng -o docker.png
```
---

## Travis CI Worker

[](https://raw.githubusercontent.com/ofabry/go-callvis/master/images/travis.jpg)

```sh
go-callvis -format=svg -file=travis -minlen 3 -nostd -group type,pkg -focus worker -limit github.com/travis-ci/worker -ignore github.com/travis-ci/worker/vendor github.com/travis-ci/worker/cmd/travis-worker && exo-open travis.svg
```

---

--- METRICS ---
- Files Extracted: 2
- Estimated Token Budget: ~1995 tokens
- Canonical Reference: https://codewiki.google/github.com/ondrajz/go-callvis