CodeCharta consists of two separate parts: analysis that generates a .cc.json file and visualization that consumes said file.

Please note that CodeCharta only runs on your client. No .cc.json that you analyze or visualize will ever leave your computer unless you distribute it yourself.

You can try the web visualization immediately and explore CodeCharta Code in CodeCharta. No downloads necessary, though we do provide a desktop client for your convenience. The visualization interface is explained here and if you want to explore another code base from the default one, you can use one of the files from the showcase.

However, if you want to generate your own .cc.json, you should read this guide first.

Prerequisites

Please make sure that you have:

  • Java installed
  • Node and npm installed
  • CodeCharta installed

There are several ways to install CodeCharta. For this tutorial we’ll assume you installed it globally via npm:

npm i -g codecharta-analysis
npm i -g codecharta-visualization

5 min Java Metrics Quickstart

You are free to use your own java code base if you want. In this example we’ll assume you picked the Junit4 code base because it’s fast to analyze.

# Download code base of your choice
git clone https://github.com/junit-team/junit4
# parse sources
ccsh sourcecodeparser junit4 -o junit4.source.cc.json
# done :)

The generated file can be opened in the web or the desktop client:

# start visualization and open the generated file
# might require sudo, depending on where you install global npm modules
codecharta-visualization

5 min Generic Metrics Quickstart

Please make sure you have Tokei installed.

# Download code base of your choice
git clone https://github.com/apache/httpd.git
# Parse code with Tokei
cd httpd; tokei -o json . > ../httpd.tokei.json; cd ..
# Parse sources
ccsh tokeiimporter httpd.tokei.json -o httpd.tokei.cc.json
# Done :)

The generated file can be opened in the web or the desktop client:

# start visualization and open the generated file
# might require sudo, depending on where you install global npm modules
codecharta-visualization

10 min SonarQube Quickstart

  1. Install SonarQube and analyze your project as described here.
  2. Parse analyzed project to the sonar importer to generate cc.json file.
ccsh sonarimport [options] [file] [url] [project-id]

5+2 min Combine Metrics Quickstart

Please make sure you have Git installed and that you have completed one of the previous quickstarts. Otherwise, you won’t have a .cc.json to combine with git metrics.

# Generate and parse a <project>.git.log
cd junit4; ccsh gitlogparser repo-scan -o junit4.git.cc.json -nc

We can now merge the files.

ccsh merge junit4.source.cc.json junit4.git.cc.json -o junit4.cc.json

With the merge done you can now open it in the visualization again.

Depending on what importer you use there might be a structural problem though. ccsh merge actually creates a union of all files you give it and only merges the metrics for which the path matches. That’s great if one file only contains metrics for .java files and the other file has metrics for all files, but it can create problems.

For example the path for a file Foo.java should be the same in both files. If the structures don’t match, the metrics you got from different sources won’t be merged into the same entity but stay separate. In the visualization you’ll see one building root/Foo.java that has all source metrics and one root/src/main/java/Foo.java that has all the git metrics. That’s not what you want.

A simple comparison you can do is to check that the <project>.source.cc.json has a folder src directly under root (root/src) and the git.cc.json has the same folder also under root.

# Print the first level of the <project>.source.cc.json
ccsh modify junit4.source.cc.json -p 1
# Print the first level of the <project>.git.cc.json
ccsh modify junit4.git.cc.json -p 1
# Use (--move-from and --move-to) or --set-root to correct wrong structure

10 min Docker Quickstart

To get started quickly, you can also use CodeCharta in a Docker container. For this you need to have Docker and Docker compose installed.

# Assuming you have the docker-compose.yml on hand
docker compose pull && docker compose up --detach

Now that all containers are running, we can connect to the analysis container.

# You can see the name of all running containers with 'docker ps'
docker exec -it codecharta-analysis bash

You are now connected into the container, and are able to run ccsh by simply typing ccsh. You can try any of the other quickstart guides to create a .cc.json file. Once you have a .cc.json file, we can copy it to our hard drive.

docker cp codecharta-analysis:path/to/ccjson/ docker-sample.cc.json

You can also check the docs of the docker cp command to learn more. To move files between containers (for example to and from sonar) you can use the shared volume, which you can access under /mnt/data in each container.

Now you’re almost done! Simply navigate to localhost:9001 in your browser to open the visualization and upload your file.

CodeCharta in a Tweet Quickstart

ccsh merge is a powerful tool to merge multiple .cc.json files. Sometimes though you do not need the intermediate .cc.json files though and just want a combined file as fast as possible. For this purpose the most popular ccsh importers allow piping the .cc.json contents (see ccsh docs). This allows us to generate a combine .cc.json in less than 280 characters :)

npm i -g codecharta-analysis
ccsh sourcecodeparser junit4 \
  | ccsh gitlogparser repo-scan --repo-path junit4 \
  > junit4.cc.json

Next Steps

CodeCharta is not limited to the importers mentioned here. The analysis docs show the way. They are also worth checking out if you need some custom metrics. Furthermore, you should read the visualization docs to find out more about the available features.

Updated: