User Tools

Site Tools


Build instructions


FreeHealth EHR is written in C++/Qt5. In order to build one of the applications, you need to install and configure the Qt libraries.

FreeHealth requires Qt 5.7 or higher.

FreeHealth applications consist of a very small executable and various libraries and plugins. When the application starts, the executable is loaded, along with some libraries. The plugin manager then loads all needed plugins and executes them. The basic structure of FreeHealth EHR and its plugins system are derived from the code of Qt Creator.

Build workflow is similar for each supported OS, but there are slight differences and subtleties for each OS. This page concentrates on GNU/Linux. Read this page first. Then, have a look at these other pages with specific instructions and tips for other operating systems:

Getting the source

We use Git as version control system, and GitHub for code hosting.

Latest source package release is available on the download page. You must build from source package to make usable binaries. You can also create a source package yourself with script/

Build dependencies

All systems

  • FreeHealth is developed with Qt5.x latest release
  • For now, FreeHealth is backward compatible with Qt 5.6.x LTS. This will not forever be true, as we will soon start using features from Qt WebEngine module that exist only in the latest releases.
  • FreeHealth is tested with Qt5.6.x latest LTS release and Qt 5.X latest release
  • FreeHealth is developed mainly on free and open source GNU/Linux operating systems: Debian 9 Stretch, Ubuntu 16.04 LTS
  • You can develop, build and contribute to FreeHealth with any OS able to run Qt (macOS, Windows) but we will not always be able to help you as much as if you were working with a GNU/Linux OS

All code is compatible with the latest Qt 5.8 release.

Qt Creator configuration

  • Be sure to uncheck the shadow build checkbox in the project mode

Remove cached files

  • If you have any strange behavior during the build process, try to start the build from scratch:
    • remove all Makefile:
      find . -type f -name Makefile -exec rm -vrf {} \;
    • remove all qmake cache:
      find . -type f -name .qmake.cache -exec rm -vrf {} \;
    • remove the build dir:
      rm -vrf ./build
    • remove the bin output dir:
      rm -vrf ./bin

Get Qt SDK (Software Development Kit)

We strongly suggest that you use the packages from you GNU/Linux distribution to build FreeHealth EHR.

FreeHealth devs are developing and building on Debian 9 Stretch (Stable) with Qt version 5.7.1 packages.


Tell your system to use Qt5 version of qmake (qt5-qmake) as the default:

sudo apt-get install qt5-default

In any case, use Qt version 5.7 or higher. Here is a list of Debian GNU/Linux packages required for compilation This should work on Debian 9, Debian 10, Ubuntu 17.04, Ubuntu 17.10 and other derivatives of Debian, make sure they ship with a Qt version superior or equal to 5.7

  • build-essential
  • libgl1-mesa-dev
  • all Qt5 libs and binaries (libqt5*)
  • qtscript5-dev
  • qttools5-dev
  • libxext-dev
  • libxext6
  • qtxmlpatterns5-dev-tools
  • libqt5sql5-mysql (not required to build the app, but required to run it)
#Debian 9 Stable or higher & Ubuntu 16.04 or higher
sudo apt-get install build-essential libgl1-mesa-dev libxext-dev libxext6 qttools5-dev libqt5svg5 libqt5svg5-dev qtscript5-dev qt5-qmake zlib1g-dev qtxmlpatterns5-dev-tools

The Quazip case

  • By default all apps are built with the quazip 0.5.1 library. This lib is included in the source package.
  • Some Linux distros do provide specific package for libquazip.
  • You can get rid of the bundled QuaZip source by adding

    to the qmake command line or by editing the buildspecs/optionalfeatures.pri file.

  • Using the dontbuildquazip config tag will force the compiler to link FreeHealth code to the system QuaZip library and will only create a freemedforms-quazip-wrapper lib.

Unit tests

To avoid building unit tests, add “WITH_TESTS=0” to your qmake command

 qmake ...  "WITH_TESTS=0" ...

Building optional plugins

You can choose between two methods:

  1. add to the qmake commande line:
    • CONFIG+=with-plugin
    • where 'plugin' is the config name of the plugin
  2. Use buildspecs/optionalplugins.pri file
    • Uncomment required plugins

Agenda plugin

  • Since v0.8.4, the agenda plugin is now an optional plugin
  • Manages multi-user agenda
  • By default, the Agenda plugin is not built. If you want to build it, you need to add
    • with-agenda tag to the config qmake command.
      qmake ... "CONFIG+=with-agenda" ...

Alert plugin

  • v0.7.6 or upper
  • Manages alerts for user, patient and application
  • By default, the Alert plugin is not built. If you want to build it, you need to add
    • with-alerts tag to the config qmake command.
      qmake ... "CONFIG+=with-alerts" ...

Feedback plugin

  • v0.8.4 or upper
  • Manages user feedback to the dev team
  • By default, the Feedback plugin is not built. If you want to build it, you need
    • to add with-feedback tag to the config qmake command.
      qmake ... "CONFIG+=with-feedback" ...

PMHx plugin

  • v0.8.4 or upper
  • Manages patient personal & family PMHx
  • By default, the PMHx plugin is not built. If you want to build it, you need
    • to add with-pmh tag to the config qmake command.
      qmake ... "CONFIG+=with-pmh" ...

WebCam plugin

  • v0.8.0 or upper
  • Manages webcam access (patient identity photo for eg)
  • By default, the WebCam plugin is not built. If you want to build it, you need
    • to install the libopencv-dev on your computer
    • to add with-webcam tag to the config qmake command.
      qmake ... "CONFIG+=with-webcam" ...

Building Qt MySQL & Qt SQLite plugins

Build process

  • You can build applications in two modes:
    • debug to test, two type of compilation are available here:
      • “non-install”: allow you to debug the application without the need of installing it
      • “install-exclusive”: allow you to debug the application after its installation
      • the CONFIG flag debug_without_install can be used in the qmake command line to switch to the non-install debugging mode
    • release to use the applications. In this case, you must install it.


  • A generic script is provided to ease the building process (Linux only)
  • Please read the help page of the script.
  • Command:
    # get help
    ./ -h
    # On Linux, you can use the GUI (you need to have zenity installed on your system)

Creating translations

  • Translations are provided as sources. We provide some scripts to help you in that process.
  • Translations must be compiled before starting the make install step.
  • If you want to:
    • update the translations source file: ./ without any command line parameter. This script parses source files and extracts translatable strings into *.ts files in global_resources/translations
The script will only work for sure with Qt5.8 version of lupdate. The script will not update .ts files if you use Debian 8 version of lupdate. Debian 9 version is not tested, it might work. You can get the
lupdate -version
  • translate: read our translation instructions
  • compile translations use the Qt tool lrelease.
    cd global_resources/translations
    lrelease *.ts

    or use our script.

The qmake && make processes


qmake is a utility that automates the generation of Makefiles.


You can use make in multiple thread (make -j X).

make -j4

Debug build

  • The debug mode is suitable for testing purpose. It includes all functionalities, even those which are not stable or very buggy. All logged messages and errors are printed to the console.
  • There are two debug mode: a “non-install” and an “install” debug mode. See above.
  • In debug mode, all processed binaries are postfixed with “_d” on Win32 platforms or “_debug” on Linux. You can inhibit this behavior with the CONFIG flag dont_postfixe_binaries on the qmake command line.
  • Here are some paths descriptions :
    • binaries are located in /bin/LOWERED_APPNAME (eg: for FreeHealth EHR –> /bin/freehealth/)
    • plugins and libs are located in /bin/LOWERED_APPNAME/plugins (eg: for FreeHealth EHR –> /bin/freehealth/plugins)
    • applications resources (pixmaps, sql files etc.) are located in /global_resources
    • users resources are located in your home path (you can modify this behavior using the command line (for EHR and derivatives): –config=“../../path/to/your/config.ini”).
cd freehealth
qmake -r "CONFIG+=debug debug_without_install"
cd bin/freehealth

# start the app

Building in release mode

  • When you build in release mode, all instable functions are inhibited and there is no logging to the console.
  • You MUST install the application (using the make install command), otherwise application will not work.
  • To facilitate the installation process several parameters can be passed through the command line.

Linux OS integration

  • The “CONFIG+=LINUX_INTEGRATED” can be set for a better integration into the operating system. When set, the built application will then use the Qt libraries installed in your OS. The libs are installed in /usr/lib/BuiltApplication and can not be moved. The binary is installed in /usr/bin. The application resources are installed in /usr/share/BuiltApplication. Of course, this is only available for Linux.
  • The “INSTALL_ROOT_PATH=/home/me/test/” used to tell the installation process where to install the application, libs and resources. If you do not specify a path the application is installed in packages/YourOs/AppName. You can combine Linux integration and root path when building a debian package or a rpm package. Actually only valid for Linux.
  • The “LIBRARY_BASENAME=lib64” is used to tell the installation process where to install plugins and libs. This is only valid in the LINUX_INTEGRATED configuration. The lib path will be: /usr/LIBRARY_BASENAME/freehealth .
# EHR sample
# 1. Building a Linux package into a fake root system
cd freehealth
qmake -r -config release "CONFIG+=LINUX_INTEGRATED" "INSTALL_ROOT_PATH=%build__path/usr/"
make install

# 2. Fresh compilation and install without aiming to create a package
cd freehealth
qmake -r -config release "CONFIG+=LINUX_INTEGRATED" "INSTALL_ROOT_PATH=/usr/"
make install

# FreeRx (formerly known as FreeDiams)
# 1. Building a Linux package into a fake root system
cd freediams
qmake -r -config release "CONFIG+=LINUX_INTEGRATED" "INSTALL_ROOT_PATH=%build__path/usr/"
make install

# 2. Fresh compilation and install without aiming to create a package
cd freediams
qmake -r -config release "CONFIG+=LINUX_INTEGRATED" "INSTALL_ROOT_PATH=/usr/"
make install

Building sources packages

  • A specific script is available for the source package creation: scripts/

Source building requirements

  • You need to compile and use FreeToolBox to create and install the databases:
    • drugs database
    • drugs database with DDI (Drug Drug Interation)
    • ICD10 database
  • You need to prepare and include the documentation of the application. The documentation is written on this wiki. There used to be a site exporter plugin to facilitate the extraction of documentation… it's broken.

Creating the source package

  • The source packager script will prepare a complete source archive:
    • Version numbers are defined in pluginspec, libs version, win32 scripts and others
    • To release a new version, update version number in buildspecs/projectversion.pri
    • Give you GPG key long ID (64-bit key ID) to sign the archive
    • Part of mandatory workflow for any source release
cd scripts

# Replace 0x75D4AE85B9520933 with your actual GPG key ID
./ -k 0x75D4AE85B9520933

# find output
cd ../source_package



We use Git as our VCS.

Configuring Git

First tell git who you are - you are advised to use your real name and a valid email addresse, no nicknames please.

git config --global "James T. Kirk"
git config --global ""

Now git clone the code from GitHub

git clone

If you want to contribute some code, register on GitHub, fork the repository and send us a pull request.

Installing git-hooks

We recommend to install our pre-defined git-hooks to simplify your work when pushing to our server. They run some code quality tests at each commit and automatically correct small issues (remove whitespace at the end of lines etc.):

cd /home/kirk/freehealth/.git/hooks
ln -s ../../githooks/*

Contributions & code modifications

You are more than welcome to contribute code to the project! You can sign up on , fork our repository, modify the code and make a pull request. If you want to become a regular contributor to the project, please read Contribute and introduce yourself on the dev mailing list.

en/code/buildsystem.txt · Last modified: 2017/12/24 01:06 by Jérôme Pinguet