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 version: git clone https://github.com/Remi-Coulom/joedb.git. The dev branch is tested before being merged into master, so the master branch should be rather safe to use.

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 dependencies, as pure standard C++. Each external dependencies provides extra optional features.

2.1.1.1. Windows

Visual Studio can open the CMake project located in the compcmake folder. It comes with a vcpkg.json that should get all dependencies automatically. You may have to install vcpkg in Visual Studio as explained on that page.

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.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/
./generate.sh gcc_release
cd gcc_release/
cmake --build .

These commands will install joedb system-wide:

sudo cmake --build . install
sudo ldconfig

If you wish to use vcpkg instead of OS-provided libraries, you can invoke the generate script this way instead (the VCPKGROOT environment variable must have been set):

./generate.sh --vcpkg gcc_release

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 <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)
joedbc_build("." settings)

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

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

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

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

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

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