Quick-Start Guide
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
- Install SonarQube and analyze your project as described here.
- 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.