Examples

Generate Metrics from Java code

To analyze Java projects, the ccsh provides the Source Code Parser, which uses the sonar-java library for metric generation.

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 :)

After this, 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

Basic metrics with Tokei

The ccsh provides the Tokei Importer, which allows import of metrics generate by Tokei. Tokei supports over 200 languages but only computes basic metrics.

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 :)

After this, 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

Importing metrics generated by SonarQube

SonarQube is a popular platform to analyze code in a variety of metrics. To use it with CodeCharta, you first need to install SonarQube. After, you can analyze your project as described here.

Once the analysis is complete, you can parse analyzed project to the sonar importer to generate a cc.json file using:

ccsh sonarimport [options] [file] [url] [project-id]

Combining metrics

This part requires you to have Git installed and to already have a cc.json file, e.g. from one of the previous sections of this guide. Now, in case the code you analyzed used git, the previously generated metrics will be combined with data from git logs. If you analyzed the code of JUnit4, executing the Git Log Parser would look like this:

# 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. We can now merge this with the previously generated file by using the Merge Filter.

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 used there might be a structural problem though. ccsh merge actually creates a union of all files given to 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

Using CodeCharta in Docker

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 run -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 previous sections 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.