Skip to content

Latest commit

 

History

History
209 lines (164 loc) · 7.9 KB

usage.md

File metadata and controls

209 lines (164 loc) · 7.9 KB

CodeCompass usage

Setup database (one time only)

CodeCompass uses relational database system for data storage. Currently SQLite and PostgreSQL are supported. The first one is for trial purposes and for smaller projects only, as SQLite can slow down considerably on large project. PostgreSQL is recommender for any production operation on medium-size or larger projects. The database backend used is decided when compiling CodeCompass, via the -DDATABASE CMake flag (see chapter Build CodeCompass).

Using SQLite

The usage of SQLite is automatic, the embedded library will take care of creating and using the database file.

Using PostgreSQL from package manager

PostgreSQL can be installed from the package manager, using sudo apt-get install postgresql-<version> (e.g. postgresql-9.5). This will set up an automatically starting local server on the default port 5432.

This server, by default, is only accessible for an automatically created system user named postgres. However, CodeCompass' database layer only supports password-based authentication. First, you have to create a user to access the database:

sudo su postgres
psql

In the PostgreSQL command-line shell, type:

CREATE USER compass WITH SUPERUSER LOGIN PASSWORD 'mypassword';

You can exit this shell by typing \q and pressing the ENTER key. A user with the given name and credentials is now created.

This was the most basic way to set up access to the database. In case of a live, production, public server, certain other measures need to be taken to ensure secure access. For full documentation, see:

In case you want to manually create the database and not through a SUPERUSER via CodeCompass, you need to ensure the database is created with the right locale, otherwise CodeCompass_parser will crash when trying to store your files. Please use the following command to create databases:

CREATE DATABASE mydatabase
  WITH ENCODING 'SQL_ASCII' LC_CTYPE 'C' LC_COLLATE 'C'
  TEMPLATE template0;

Using self-compiled PostgreSQL

Alternatively, you may compile PostgreSQL by yourself. Using this method, you'll need to manually initialise a server and start your own instance:

mkdir -p ~/cc/database
initdb -D ~/cc/database -E SQL_ASCII

# Start PostgreSQL server on port 6250.
postgres -D ~/cc/database -p 6250

A manually started PostgreSQL server is automatically configured to your user, and your user only. No extra user creation or configuration needs to take place.

For full documentation see:

1. Generate compilation database

If you want to parse a C++ project, you have to create a compilation database file.

Get compilation database from CMake

If the project uses CMake build system then you can create the compilation database by CMake with the option CMAKE_EXPORT_COMPILE_COMMANDS:

cmake .. -DCMAKE_EXPORT_COMPILE_COMMANDS=1

This command creates the compile_commands.json file, this is the compilation database.

Create compilation database via build instrumentation

CodeCompass can also be used for generating compilation database. This is a more general solution because it works for non-CMake projects. Suppose you have hello.cpp in the current working directory.

CodeCompass_logger ~/myproject/compilation_commands.json "g++ hello.cpp"

The CodeCompass_logger is provided in the bin directory in the CodeCompass installation. The first command line argument is the output file name and the second argument is the build command which compiles your project. This can be a simple compiler invocation or starting a build system.

2. Parse the project

For parsing a project with CodeCompass, the following command has to be emitted:

keepalive CodeCompass_parser -w <workspace> -n <name> -i <input1> -i <input2> -d <connection_string>
  • Workspace: This is a directory where the some parse results, and different configuration and log files are located. Please ensure that this directory is not located under any input folder, or under your project's source file tree.
  • Input: Several inputs can be given with -i flags. An input can be a directory or a compilation database. The plugins iterate these inputs and decide if they can use it. For example the C++ parser will consume the given compilation databases and the text search parser will consume the files under the given directories. It is entirely up to the parser what it does with the input parameters.
  • Database: The plugins can use an SQL database as storage. By the connection string the user can give the location of a running database system. If the database name is not given in the connection string then the project name will be used.

For full documentation see CodeCompass_parser -h.

❗ The keepalive is a script in the bin directory of CodeCompass installation. This is used to keep CodeCompass alive if it crashes for some reason. This way a long parsing session restarts if an error happens. CodeCompass plugins are expected to individually handle what to do when a parsing is stopped and restarted with an existing database, so the parsing can continue from where it stopped.

Usage example

In these examples, the parser is given two inputs. The compile_commands.json file tells the C/C++ parser which source files to parse. Giving the project's directory will allow the text search parser to index words in your project.

Parse and store the results of the project in a PostgreSQL database:

keepalive CodeCompass_parser \
  -d "pgsql:host=localhost;port=5432;user=compass;password=mypassword;database=mydatabase" \
  -w ~/cc/workdir \
  -n myproject \
  -i ~/myproject/compile_commands.json \
  -i ~/myproject \
  -j 4

Or use SQLite (not recommended for large projects):

keepalive CodeCompass_parser \
  -d "sqlite:database=~/cc/mydatabase.sqlite" \
  -w ~/cc/workdir \
  -n myproject \
  -i ~/myproject/compile_commands.json \
  -i ~/myproject \
  -j 4

3. Start the web server

You can start the CodeCompass webserver with CodeCompass_webserver binary in the CodeCompass installation directory.

keepalive CodeCompass_webserver -w <workdir> -p <port> -d <connection_string>
  • Workspace: This is a directory where the some parse results, and different configuration and log files are located. This should be the same as what was provided to the CodeCompass_parser binary in Step 2.
  • Port: Port number of the web server to listen on.
  • Database: The plugins can use an SQL database as storage. By the connection string the user can give the location of a running database system. In the parsing session the database name could have been provided. This database name is written in a config file in the workspace directory, so it is useless to provide it at server start.

For full documentation see CodeCompass_webserver -h.

❗ The keepalive is a script in the bin directory of CodeCompass installation. This is used to keep CodeCompass alive if it crashes for some reason.

Usage example

# Start the server listening on port 6251.
keepalive CodeCompass_webserver \
  -w ~/cc/workdir \
  -p 6251 \
  -d "pgsql:host=localhost;port=5432;user=compass;password=mypassword"

# Or if SQLite database is used:
keepalive CodeCompass_webserver \
  -w ~/cc/workdir \
  -p 6251 \
  -d "sqlite"

The server will be available in a browser on http://localhost:6251.