Installation

• Quick start
• Environment
• C++ API
• MySQL
• Test the installation
• Distribution specific

Quick start

TL;DR; CCDB API is available for different programming languages. Usually, a user doesn't need every CCDB feature.

The most essential ccdb command is the main tool for CCDB management. To install and run it:

> git clone git@github.com:JeffersonLab/ccdb.git ccdb  # or 
# git clone https://github.com/JeffersonLab/ccdb.git   for https version
> source ccdb/environment.bash

# That's it! Check that it works
> ccdb -i

Here is what environment.bash does:

• CCDB_HOME - sets to where environment.bash is located
• PATH - adds $CCDB_HOME/bin
• LD_LIBRARY_PATH - adds $CCDB_HOME/lib
• PYTHONPATH - adds $CCDB_HOME/python

To build APIs:

• The C++ API is built by standard CMake
• The Python API is ready right away.
• The Java API ready to use without compilation. ccdb.jar is located in $CCDB_HOME/java directory.

The following chapters describe the details.

Environment

One must have the CCDB_HOME variable pointing to the root directory of the CCDB package.

Automatic environment setup

You can run the script located in the root directory of CCDB:

     source environment.bash

The script determines its own path and sets up all path variables to run and link the ccdb.

Manual environment setup

CODE FOR .bashrc:

    #set CCDB environment
    export CCDB_HOME=/path/to/ccdb/home/directory

    export LD_LIBRARY_PATH="$CCDB_HOME/lib":$LD_LIBRARY_PATH
    export PYTHONPATH="$CCDB_HOME/python":$PYTHONPATH
    export PATH="$CCDB_HOME/bin":$PATH

C++ API

The C++ API is provided by the ccdb library.

There two configurations to choose from when building CCDB:

1. With SQLite and MySQL support (default)
2. With SQLite support only.

MySQL, a fully-functional database system, was envisioned in the original design, and MySQL+SQLite is used by default. The SQLite-only version has the advantage that it does not depend on any other software packages with the exception of pthread.

1. To compile CCDB with the default configuration:

    cd $CCDB_HOME
    scons

2. To compile CCDB with SQLite support only (no MySQL dependencies).

    cd $CCDB_HOME
    scons with-mysql=false

MySQL

(!) SKIP this step if you are NOT going to install a MySQL CCDB database on YOUR server. Usually it is not needed for users. Even if one needs to evaluate CCDB package, open for read MySQL JLab servers (e.g. hallddb) and SQLite for write operations may be used instead

If you would like to install a MySQL database on the local machine, you need to create the database first. By default it is called ccdb. Then use ccdb db init command to initialize the database. By default CCDB tries to connect by using 'ccdb_user' user name with no password To create the user and the database:

> mysql -u root -p 
     CREATE USER ccdb_user;
     CREATE SCHEMA IF NOT EXISTS `ccdb`;
     GRANT ALL PRIVILEGES ON ccdb.* TO 'ccdb_user'@'localhost';
     exit;

Now with the database created, you can call ccdb db init to create tables and fill some default values:

ccdb db init
# You will need to add `init-i-am-sure` flag. Just follow the promt

You might need to adjust mysql configuration max_allowed_packet for bigger value i.e 32M in order to be able to get large data tables from CCDB, set
max_allowed_packet=32M
to [mysqld] section of /etc/my.cnf

if you don't have /etc/my.cnf in your system yet, create one and add [mysqld] in the beginning.

More on MySQL database:

• How to make a copy of MySQL database to your local server is in Development section
• A MySQL-Workbench project with the correct MySQL schema: ccdb_eer_diagram.mwb, is located in sql.

Test the installation

To test CCDB installed correctly one might run CCDB unit tests

     . $CCDB_HOME/bin/test_ccdb_lib
     . $CCDB_HOME/bin/test_ccdb_python

You should see ccdb unit test running and successfully complete.

To test python is working you may run ccdbcmd

     ccdb -i

interactive ccdb shell should be started

In order to log changes it is HIGHLY desirable to let CCDB know yout CUE user name. If your CUE user is not the same as $USER variable, please define CCDB_USER environment variable as your CUE username.

INCERT INTO .bashrc:

     export CCDB_USER=<your CUE login>

Instructions of building website is in $CCDB_HOME/web/install.txt

Distribution specific

Fedora

The packages needed to compile CCDB for Fedora: (Tested on Fedora 14, Fedora 15, RHEL 6)

     yum install scons mysql-server mysql-devel python-devel

If you haven't configured mysql server:

     service mysqld start
     mysqladmin -u root -h password 'your-password'

Ubuntu

The packages needed to compile CCDB for Ubuntu: (tested on ubuntu 11.10, mint 12)

RUN CODE:

	 apt-get install mysql-server scons libmysqlclient-dev