2.1. Getting Started

This explains how to install and use joedb.

2.1.1. Compiling from source

The source code of joedb can be found on joedb’s github page. The master branch can be cloned with git clone https://github.com/Remi-Coulom/joedb.git.

Joedb is written in portable C++ 17, and uses CMake for its build system, and vcpkg for its dependencies. So it should be portable to almost any platform.

Note that joedb can work without any external dependency, as pure standard C++. Each external dependency provides extra optional features.

2.1.1.1. Windows

Visual Studio can open the CMake project located in the compcmake folder. CMakePresets.json contains the vcpkg_release and vcpkg_debug presets that you can use to get all dependencies automatically with vcpkg. You may have to install vcpkg in Visual Studio as explained on that page.

2.1.1.2. Linux

Linux can use vcpkg, but cmake should be able to find installed system packages as well. Full development prerequisites in Ubuntu can be installed with this command:

sudo apt install git g++ clang clang-tidy cmake make ninja-build libssh-dev libbrotli-dev libcurl4-openssl-dev libgtest-dev 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:

cd joedb/compcmake/
cmake --preset gcc_release -G Ninja
cd gcc_release/
cmake --build .

These commands will install joedb system-wide:

sudo cmake --build . install
sudo ldconfig

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.5)
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 source stored in the <dir>/<name> directory
#     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...): shortcut to add an executable
#     that uses joedb in a single command
#
#  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("src" tutorial)
joedbc_build("src" settings)

joedb_add_executable(tutorial
 src/tutorial_main.cpp
 src/tutorial/writable.cpp
)

joedb_add_executable(tutorial_interpreter
 src/tutorial_interpreter.cpp
 src/tutorial/writable.cpp
)

joedb_add_executable(local_concurrency
 src/local_concurrency.cpp
 src/tutorial/writable.cpp
)

joedb_add_executable(file_tutorial
 src/file_tutorial.cpp
 src/tutorial/writable.cpp
)

joedb_add_executable(concurrency_tutorial
 src/concurrency_tutorial.cpp
 src/tutorial/writable.cpp
)

joedb_add_executable(index_tutorial
 src/index_tutorial.cpp
 src/tutorial/writable.cpp
)

joedb_add_executable(settings
 src/settings_main.cpp
 src/settings/writable.cpp
)

joedb_add_executable(write_server_blob
 src/write_server_blob.cpp
)

joedb_add_executable(client_lock
 src/client_lock.cpp
 src/tutorial/writable.cpp
)

joedb_add_executable(step_by_step_replay
 src/step_by_step_replay.cpp
 src/tutorial/readonly.cpp
)

joedb_add_executable(server_file_tutorial
 src/server_file_tutorial.cpp
)