2.1. Getting Started

This explains how to install and use joedb.

2.1.1. Compiling from source

The source code of the most recent stable release can be found on the github Release page. You can also clone the repository to get the most recent development version: git clone https://github.com/Remi-Coulom/joedb.git.

Joedb is written in portable C++ 17, and uses CMake for its build system. So it should be portable to almost any platform. Here are some detailed instructions for the most common situations.

2.1.1.1. Linux

Prerequisites in Ubuntu can be installed with this command (ninja and libssh are optional, but nice to have):

sudo apt install git g++ cmake ninja-build libssh-dev

For test coverage, documentation, and benchmarks, also install:

sudo apt-get install lcov python3-sphinx python3-sphinx-rtd-theme python3-sphinxcontrib.spelling sqlite3 libsqlite3-dev sqlitebrowser

When the necessary packages are installed, the following commands should compile everything:

git submodule update --init --recursive
cd joedb/compcmake/
./generate.sh
cd gcc_release/
cmake --build .

These commands will install joedb system-wide:

sudo cmake --build . install
sudo ldconfig

2.1.1.2. Windows

First, get submodules:

git submodule update --init --recursive

libssh can be installed with vcpkg:

vcpkg install libssh:x64-windows

Visual Studio can open the CMake project located in the compcmake folder.

The install target of this project will produce a directory in joedb/compcmake/out/install. You may have to copy the generated files elsewhere, or adjust your system’s PATH in order to make the tools easily available on the command line.

2.1.2. First Steps

After downloading joedb, you might wish to look at examples located in the doc/source/tutorial directory:

  • tutorial.joedbi contains the interpreter commands that define the database schema,
  • tutorial.joedbc defines compiler options,
  • tutorial_main.cpp is the example presented in the Introduction,
  • index_tutorial.cpp illustrates how to use Indexes,
  • and generate.sh is a bash script that will compile all the code and run the programs.

It might be a good idea to also look at the Tools provided by joedb, and also read the rest of this User’s Guide: it presents the most significant features of joedb in more details than the Introduction.

2.1.3. Using joedb with cmake

If you are using cmake to develop your own project using joedb, you can handle dependencies automatically by including joedb/compcmake/joedbc.cmake in your CMakeLists.txt. The tutorial source contains an example:

cmake_minimum_required(VERSION 3.1)
cmake_policy(SET CMP0069 NEW)

project(tutorial)

set(CMAKE_CXX_STANDARD 17)

include("../../../compcmake/joedbc.cmake")

#
# Including "joedbc.cmake" defines four functions
#
#  * joedbc_build(<dir> <name>): add rules to compile a database with joedbc
#     <dir> is relative to ${CMAKE_CURRENT_SOURCE_DIR}
#     Assumes that <dir>/<name>.joedbi and <dir>/<name>.joedbc contain compiler
#     instructions to generate <dir>/<name>.cpp
#     This function may be invoked multiple times, once for each database
#     contained in the code.
#
#  * joedbc_build_absolute(<dir> <name>): same as above, but <dir> is absolute
#
#  * target_uses_joedb(target): indicate that a target uses joedb. Two effects:
#     1: it adds a dependency, so that joedbc is invoked whenever necessary
#     2: it links the executable to the joedb library
#
#  * joedb_add_executable(target source...): add an executable that uses joedb
#
#  joedbc.cmake will compile joedbc and the joedb library for your project,
#  with the same compiler and compilation options as the rest of your code.
#

joedbc_build("." tutorial)

joedb_add_executable(tutorial tutorial_main.cpp tutorial.cpp)

joedb_add_executable(local_concurrency local_concurrency.cpp tutorial.cpp)

joedb_add_executable(file_tutorial file_tutorial.cpp tutorial.cpp)

joedb_add_executable(concurrency_tutorial concurrency_tutorial.cpp tutorial.cpp)

joedb_add_executable(index_tutorial index_tutorial.cpp tutorial.cpp)