Building: TinyORM
- Introduction
- Folders structure
- Getting started
- vcpkg
- C preprocessor macros
- Building with CMake
- Building with qmake
- Ccache support
Introduction
The build systems supported out of the box are CMake
and qmake
.
All examples below assume that pwsh
runs on Windows
and bash
runs on Linux
.
Common Prerequisites
Before beginning, install required dependencies.
Windows Prerequisites
Build environment scripts
The Visual Studio
does not provide vcvars
scripts for pwsh
, you can use vcvars64.ps1
provided by TinyORM
in the tools/
folder. Place them on the $env:Path
user/system path and they will be available system-wide.
The same is true for the Qt Framework
, it doesn't provide qtenv
scripts for pwsh
too. You can create your own script, place it on the $env:Path
user/system path and it will be available system-wide.
Here is one simple example for pwsh
.
- qtenv6.ps1
- qtenv5.ps1
Write-Host 'Setting up environment for Qt 6.2.4 usage...' -ForegroundColor Magenta
$env:Path = 'C:\Qt\6.2.4\msvc2019_64\bin;' + $env:Path
. E:\dotfiles\bin\vcvars64.ps1
Write-Host 'Setting up environment for Qt 5.15.2 usage...' -ForegroundColor Magenta
$env:Path = 'C:\Qt\5.15.2\msvc2019_64\bin;' + $env:Path
. E:\dotfiles\bin\vcvars64.ps1
Allow symbolic links unprivileged
Open Local Security Policy
, go to Local Policies - User Rights Assignment
, open Create symbolic links
and add your user account or user group, restart when it doesn't apply immediately.
Folders structure
All tinyorm.org
examples are based on the following folders structure. The tom
folder will contain a migrations console application.
You can set the root and application folder paths in the form below and they will be used across the whole www.tinyorm.org website. 🥳 The pwsh shell is supposed to use on Windows and the bash shell on Linux, but it is not a requirement.
- pwsh
- bash
├──
│ ├── HelloWorld/
│ | ├── HelloWorld/
│ | ├── HelloWorld-builds-cmake/
│ | | └── build-debug/
│ | └── HelloWorld-builds-qmake/
│ | └── build-debug/
│ ├── TinyORM/
│ | ├── TinyORM/
│ | ├── TinyORM-builds-cmake/
│ | │ ├── build-gcc-debug/
│ | │ ├── build-gcc-release/
│ | │ └── build-clang-debug/
│ | └── TinyOrm-builds-qmake/
│ | ├── build-debug/
│ | ├── build-TinyOrm-Desktop_Qt_5_15_2_MSVC2019_64bit-Debug/
│ | └── build-TinyOrm-Desktop_Qt_5_15_2_MSYS2_UCRT64_64bit-Release/
│ └── tom/
│ ├── tom/
│ │ └── database/
│ │ ├── migrations/
│ │ ├── seeders/
│ │ ├── migrations.pri
│ │ └── seeders.pri
│ ├── tom-builds-cmake/
│ │ └── build-TinyOrm-Desktop_Qt_6_3_1_MSVC2019_64bit-Debug/
│ └── tom-builds-qmake/
│ ├── build-TinyOrm-Desktop_Qt_5_15_3_MSYS2_UCRT64_64bit-Release/
│ └── build-TinyOrm-Desktop_Qt_6_3_1_MSVC2019_64bit-Debug/
├── tmp/
└── vcpkg/
├──
│ ├── HelloWorld/
│ | ├── HelloWorld/
│ | ├── HelloWorld-builds-cmake/
│ | | └── build-debug/
│ | └── HelloWorld-builds-qmake/
│ | └── build-debug/
│ ├── TinyORM/
│ | ├── TinyORM/
│ | ├── TinyORM-builds-cmake/
│ | │ ├── build-gcc-debug/
│ | │ ├── build-gcc-release/
│ | │ └── build-clang-debug/
│ | └── TinyOrm-builds-qmake/
│ | ├── build-debug/
│ | ├── build-TinyOrm-Desktop_Qt_5_15_2_GCC_64bit-Debug/
│ | └── build-TinyOrm-Desktop_Qt_5_15_2_clang13_64bit_ccache-Release/
│ └── tom/
│ ├── tom/
│ │ └── database/
│ │ ├── migrations/
│ │ ├── seeders/
│ │ ├── migrations.pri
│ │ └── seeders.pri
│ ├── tom-builds-cmake/
│ │ └── build-TinyOrm-Desktop_Qt_6_3_1_clang14_64bit_ccache-Debug/
│ └── tom-builds-qmake/
│ ├── build-TinyOrm-Desktop_Qt_6_3_1_GCC_64bit-Debug/
│ └── build-TinyOrm-Desktop_Qt_6_3_1_clang14_64bit_ccache-Release/
├── tmp/
└── vcpkg/
Avoid paths with spaces with the qmake
build system, it will not compile.
Getting started
Prepare compilation environment, we need to put the Qt Framework and Visual Studio MSVC compiler on the path on Windows. The Qt Framework and compiler are already on the path on Linux.
- pwsh
- bash
mkdir
cd
$env:Path = 'E:\Qt\5.15.2\msvc2019_64\bin;' + $env:Path
vcvars64.ps1
mkdir -p
cd
vcpkg
Installing the vcpkg
is highly recommended, it simplifies installation of the range-v3
and tabulate
dependencies.
- pwsh
- bash
git clone git@github.com:microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
git clone git@github.com:microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
Add vcpkg
on the system path, add the following to the .bashrc
or .zshrc
on Linux.
export PATH=/vcpkg${PATH:+:}$PATH
On Windows, open the Environment variables
dialog and add vcpkg
on the PATH
.
Or you can export it for the current session only.
- pwsh
- bash
$env:Path = "\vcpkg;" + $env:Path
export PATH=/vcpkg${PATH:+:}$PATH
C preprocessor macros
The following table summarizes all the C preprocessor macros defined in the TinyORM
library. These C macros are configured by CMake
or qmake
build systems. They are not sorted alphabetically, but they are sorted by how significant they are.
In the CMake
build system, all the C macros are auto-detected / auto-configured or controlled by CMake build options
, so you don't have to care too much about them.
In the qmake
build is important whether you are building TinyORM
library or you are building your application and linking against TinyORM
library. When you are building the TinyORM
library, all the C macros are auto-detected / auto-configured or controlled by qmake build options
, so you don't have to care too much about them.
But a special situation is when you are building your application / library and you are linking against TinyORM
library. In this particular case, you must configure all these C macros manually! For this reason, the TinyOrm.pri
has been created, so that's not a big deal. Little more info here.
C Macro Name | Description |
---|---|
TINYORM_LINKING_SHARED | Must be defined when you are linking against TinyORM shared build (dll library), exported classes and functions will be tagged with __declspec(dllimport) on msvc and visibility("default") on GCC >= 4 . |
TINYORM_BUILDING_SHARED | Defined when TinyORM is built as a dll library (shared build). |
TINYORM_DEBUG | Defined in the debug build. |
TINYORM_NO_DEBUG | Defined in the release build. |
TINYORM_DEBUG_SQL | Defined in the debug build. |
TINYORM_NO_DEBUG_SQL | Defined in the release build. |
TINYORM_MYSQL_PING | Enable Orm::MySqlConnection::pingDatabase() method.Defined when mysql_ping (qmake) / MYSQL_PING (cmake) configuration build option is enabled. |
TINYORM_DISABLE_ORM | Controls the compilation of all ORM-related source code, when this macro is defined , then only the query builder without ORM is compiled. Also excludes ORM-related unit tests.Defined when disable_orm (qmake) / ORM (cmake) configuration build option is enabled (qmake) / disabled (cmake). |
TINYORM_EXTERN_CONSTANTS | Defined when extern constants are used. Described at qmake / CMake how it works. |
TINYORM_INLINE_CONSTANTS | Defined when global inline constants are used. Defined when inline_constants (qmake) / INLINE_CONSTANTS (cmake) configuration build option is enabled. |
TINYORM_TESTS_CODE | Enable code needed by unit tests, eg. connection overriding in the Orm::Tiny::Model .Defined when build_tests (qmake) / BUILD_TESTS (cmake) configuration build option is enabled. |
TINYORM_DISABLE_THREAD_LOCAL | Remove all thread_local storage duration specifiers, it disables threading support.Defined when disable_thread_local (qmake) / DISABLE_THREAD_LOCAL (cmake) configuration build option is enabled. |
TINYTOM_MIGRATIONS_DIR | Default migrations path for the make:migration command, can be an absolute or relative path (to the pwd).Default value: database/migrations (relative to the pwd)Defined by TOM_MIGRATIONS_DIR (cmake) configuration build option.(qmake note) You can use DEFINES += TINYTOM_MIGRATIONS_DIR="\"database/migrations\"" on the command-line or set it in the main conf.pri file. |
TINYTOM_MODELS_DIR | Default models path for the make:model command, can be an absolute or relative path (to the pwd).Default value: database/models (relative to the pwd)Defined by TOM_MODELS_DIR (cmake) configuration build option.(qmake note) You can use DEFINES += TINYTOM_MODELS_DIR="\"database/models\"" on the command-line or set it in the main conf.pri file. |
TINYTOM_SEEDERS_DIR | Default seeders path for the make:seeder command, can be an absolute or relative path (to the pwd).Default value: database/seeders (relative to the pwd)Defined by TOM_SEEDERS_DIR (cmake) configuration build option.(qmake note) You can use DEFINES += TINYTOM_SEEDERS_DIR="\"database/seeders\"" on the command-line or set it in the main conf.pri file. |
TINYORM_USING_PCH | Defined if building with precompiled headers. Controlled by qmake / CMake . |
Building with CMake
If something is not clear, you can still look at GitHub Action workflows
how a building is done.
First, create a basic folder structure and then clone the TinyORM
project.
- pwsh
- bash
cd
mkdir /TinyORM/TinyORM-builds-cmake/build-debug
cd /TinyORM
git clone git@github.com:silverqx/TinyORM.git
cd
mkdir -p /TinyORM/TinyORM-builds-cmake/build-debug
cd /TinyORM
git clone git@github.com:silverqx/TinyORM.git
Configure & Build (cmake)
Now you are ready to configure the TinyORM
library.
cd TinyORM-builds-cmake/build-debug
- pwsh
- bash
cmake.exe `
-S "/TinyORM/TinyORM" `
-B "/TinyORM/TinyORM-builds-cmake/build-debug" `
-G 'Ninja' `
-D CMAKE_BUILD_TYPE:STRING='Debug' `
-D CMAKE_TOOLCHAIN_FILE:FILEPATH="/vcpkg/scripts/buildsystems/vcpkg.cmake" `
-D CMAKE_INSTALL_PREFIX:PATH="/tmp/TinyORM" `
-D BUILD_TESTS:BOOL=OFF `
-D MATCH_EQUAL_EXPORTED_BUILDTREE:BOOL=ON `
-D MYSQL_PING:BOOL=OFF `
-D TOM:BOOL=ON `
-D TOM_EXAMPLE:BOOL=OFF `
-D VERBOSE_CONFIGURE:BOOL=ON
cmake \
-S "/TinyORM/TinyORM" \
-B "/TinyORM/TinyORM-builds-cmake/build-debug" \
-G 'Ninja' \
-D CMAKE_BUILD_TYPE:STRING='Debug' \
-D CMAKE_TOOLCHAIN_FILE:FILEPATH="/vcpkg/scripts/buildsystems/vcpkg.cmake" \
-D CMAKE_INSTALL_PREFIX:PATH="/tmp/TinyORM" \
-D VERBOSE_CONFIGURE:BOOL=ON \
-D BUILD_TESTS:BOOL=OFF \
-D MYSQL_PING:BOOL=OFF \
-D TOM:BOOL=ON \
-D TOM_EXAMPLE:BOOL=OFF \
-D MATCH_EQUAL_EXPORTED_BUILDTREE:BOOL=ON
Build TinyORM
And build. You don't have to install it, you can use the build tree directly if you want.
cmake --build . --target all
cmake --install .
Or build and install in one step.
cmake --build . --target install
CMake multi-config generators like Ninja Multi-Config
or Visual Studio 16 2019
are also supported.
CMake build options
Advanced TinyORM
options.
Important CMake
options.
Consume TinyOrm library (cmake)
In your application or library CMakeLists.txt
file add following find_package()
call.
find_package(TinyOrm 0.16.0 CONFIG REQUIRED)
If the TinyORM
build tree is not exported to the CMake's User Package Registry
then also add the TinyORM
build tree or CMAKE_INSTALL_PREFIX
folder to the CMAKE_PREFIX_PATH
, so CMake can find TinyORM's package configuration file during find_package(TinyOrm)
call.
- cmake (pwsh)
- cmake (bash)
# build tree
list(APPEND CMAKE_PREFIX_PATH "/TinyORM/TinyORM-builds-cmake/build-debug")
# installation folder - CMAKE_INSTALL_PREFIX
list(APPEND CMAKE_PREFIX_PATH "/tmp/TinyORM")
# build tree
list(APPEND CMAKE_PREFIX_PATH "/TinyORM/TinyORM-builds-cmake/build-debug")
# installation folder - CMAKE_INSTALL_PREFIX
list(APPEND CMAKE_PREFIX_PATH "/tmp/TinyORM")
Or as an alternative, you can set CMAKE_PREFIX_PATH
environment variable.
As the last thing, do not forget to add TinyOrm0d.dll
on the path on Windows and on the LD_LIBRARY_PATH
on Linux, so your application can find it during execution.
- pwsh
- bash
$env:Path = "\TinyORM\TinyORM-builds-cmake\build-debug;" + $env:Path
export LD_LIBRARY_PATH=/TinyORM/TinyORM-builds-cmake/build-debug${PATH:+:}$PATH
Now you can try the HelloWorld CMake
example.
Building with qmake
First, create a basic folder structure and then clone the TinyORM
project.
- pwsh
- bash
cd
mkdir /TinyORM/TinyOrm-builds-qmake
cd /TinyORM
git clone git@github.com:silverqx/TinyORM.git
cd
mkdir -p /TinyORM/TinyOrm-builds-qmake
cd /TinyORM
git clone git@github.com:silverqx/TinyORM.git
Install dependencies
With the qmake
build system, you have to install TinyORM
dependencies manually. We will use the vcpkg
package manager.
cd ../../vcpkg
vcpkg search range-v3
vcpkg search tabulate
vcpkg install range-v3 tabulate
vcpkg list
On Linux
, you can install the range-v3
library and some other dependencies with the package manager.
Configure & Build (qmake)
Open QtCreator IDE
I recommend creating a new Session
in the QtCreator
, this way you will have all the examples in one place and as a bonus, everything will be in the same place when you close and reopen QtCreator IDE
. You can name it tinyorm.org
or TinyORM examples
, it is up to you.
If you are using sessions, you can use a single clangd
instance for all projects in this session in the QtCreator IDE
. One significant advantage of this method is that the .qtc_clangd/
folder will not be created in the build folder, but will be stored globally in the Roaming profile. You can enable it in the Settings
- C++
- Clangd
- Sessions with a single clangd instance
.
Configure TinyORM
Now you are ready to configure the TinyORM
library. The qmake
does not support auto-configuration of dependencies out of the box, to configure TinyORM's qmake
build dependencies you have to copy the conf.pri.example
file to the conf.pri
and manually edit the INCLUDEPATH
and LIBS
. This way you can override any qmake
build options or variables.
conf.pri
files are nicely commented, so is clearly visible what has to be modified.
- pwsh
- bash
cd /TinyORM/TinyORM
cp conf.pri.example conf.pri
cp tests/conf.pri.example tests/conf.pri
cp examples/tom/conf.pri.example examples/tom/conf.pri
cd /TinyORM/TinyORM
cp conf.pri.example conf.pri
cp tests/conf.pri.example tests/conf.pri
cp examples/tom/conf.pri.example examples/tom/conf.pri
Now you can open the TinyOrm.pro
project in the QtCreator IDE
.
This will open the Configure Project
tab, select some kit and update build folder paths to meet our folders structure or like you want.

You are ready to configure build options, hit Ctrl+5 to open Project Settings
tab and select Build
in the left sidebar to open the Build Settings
, it should look similar to the following picture.
Disable QML debugging and profiling
and Qt Quick Compiler
, they are not used.

If you want to change some TinyORM
build options, you can pass them to the Build Steps
- qmake TinyOrm.pro
- Additional arguments
input field. It can look like this.
Build TinyORM
Everything is ready for build, you can press Ctrl+b to build the project.
qmake build options
Advanced TinyORM
options.
Important qmake
options.
Consume TinyOrm library (qmake)
The TinyOrm.pri
file is available to simplify the integration of the TinyORM
library into your application. This file sets up all the qmake variables that are needed by TinyORM
. You can use it to configure the TinyORM
library.
TINY_MAIN_DIR = $$clean_path(<your_path>)
# Name of this qmake variable is crucial
TINYORM_BUILD_TREE = $$quote($$TINY_MAIN_DIR/TinyOrm-builds-qmake/build-TinyOrm-Desktop_Qt_6_3_1_MSVC2019_64bit-Debug)
include($$TINY_MAIN_DIR/TinyORM/qmake/TinyOrm.pri)
You will have to link against the TinyORM
library manually if you don't set the TINYORM_BUILD_TREE
qmake variable before the inclusion of the TinyOrm.pri
file. The INCLUDEPATH
is autodetected every time.
- pwsh
- bash
# Link against TinyORM library
# ---
TINY_MAIN_DIR = $$clean_path(<your_path>)
TINY_TINYORM_BUILDS_DIR = $$quote($$TINY_MAIN_DIR/TinyOrm-builds-qmake)
# Configure TinyORM library
include($$TINY_MAIN_DIR/TinyORM/qmake/TinyOrm.pri)
# TinyORM library path
LIBS += $$quote(-L$$TINY_TINYORM_BUILDS_DIR/build-TinyOrm-Desktop_Qt_5_15_2_MSVC2019_64bit-Debug/src/debug/)
LIBS += -lTinyOrm
# Link against TinyORM library
# ---
TINY_MAIN_DIR = $$clean_path(<your_path>)
TINY_TINYORM_BUILDS_DIR = $$quote($$TINY_MAIN_DIR/TinyOrm-builds-qmake)
# Configure TinyORM library
include($$TINY_MAIN_DIR/TinyORM/qmake/TinyOrm.pri)
# TinyORM library path
LIBS += $$quote(-L$$TINY_TINYORM_BUILDS_DIR/build-TinyOrm-Desktop_Qt_5_15_2_GCC_64bit-Debug/src/debug/)
LIBS += -lTinyOrm
The last thing is to set up the INCLUDEPATH
for the vcpkg
that provides the range-v3
and tabulate
header files.
- pwsh
- bash
# vcpkg - range-v3 and tabulate
# ---
INCLUDEPATH += $$quote(<your_path>/vcpkg/installed/x64-windows/include/)
# vcpkg - range-v3 and tabulate
# ---
QMAKE_CXXFLAGS += -isystem $$shell_quote(<your_path>/vcpkg/installed/x64-linux/include/)
Do not forget to add TinyOrm0d.dll
on the path on Windows and on the LD_LIBRARY_PATH
on Linux, so your application can find it during execution.
- pwsh
- bash
$env:Path = "\TinyORM\TinyORM-builds-qmake\build-debug;" + $env:Path
export LD_LIBRARY_PATH=/TinyORM/TinyORM-builds-qmake/build-debug${PATH:+:}$PATH
On Linux -isystem
marks the directory as a system directory, it prevents warnings.
On Windows you can use QMAKE_CXXFLAGS_WARN_ON = -external:anglebrackets -external:W0
, it applies a warning level 0 to the angel bracket includes, #include <file>
.
Ccache support
The TinyORM supports the ccache
out of the box for all supported compilers. For qmake you can enable it using the CONFIG+=ccache
on Linux or CONFIG+=tiny_ccache
on Windows. For CMake you can set the CMAKE_CXX_COMPILER_LAUNCHER=ccache
.
On Linux it's clear, the ccache is fully supported and works also with the precompiled headers. But was necessary to add some workarounds to the qmake/CMake build systems to make out of the box support on Windows. When you enable the ccache on Windows then the build system disables precompiled headers and replaces the -Zi
compiler option with the -Z7
(link to the issue).
You can install the ccache using the scoop install ccache
command on Windows.