Build instructions for FreeMedForms project applications

This documentation describes how to build FreeMedForms applications for Linux, MacOs or Windows.

The FreeMedForms project is written in C++/Qt. In order to build one of the applications, you will need to install and configure the Qt libraries (please refer to the Qt documentation). All code is compatible with latest Qt5 version.

FreeMedForms project applications consist of a very small executable, libs and plugins. When the application starts, the executable is loaded, some libs too The plugin manager then loads all needed plugins and executes them.

Build workflow is similar for each supported OS, but there are slight differences and subtleties for each OS.

We use Git as version control system, and GitHub for code hosting. You can go here and follow the instructions there to fetch a copy of the FreeMedForms source code.

All systems

  • Be sure to install the correct version of Qt, otherwise you will not be able to compile FreeMedForms:
    • Since April 25th 2015 and the release of Debian 8.0, FreeMedForms (0.9.6 or higher) is developed and compiled with Qt5.
    • FreeMedForms is ready for upcoming Qt5.6 LTS release
    • Even though FreeMedForms builds prefectly on the latest official Qt5 release, we keep the source code fully compatible with the Debian Stable Qt5 version (currently Qt 5.3.2)

QtCreator configuration

  • Be sure to uncheck the shadow build checkbox in the projet 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

Debian GNU/Linux packages required for compilation

  • Since the release of Debian 8.0 on April 25th 2015, Qt5 became the standard Qt version for development.
  • For GNU/Linux users, you need to install the following packages before trying anything with the source:
    • build-essential
    • all Qt5 libs and binaries (libqt5*)
    • qtscript5-dev
    • qttools5-dev
    • libxext-dev and libxext6
    • qtxmlpatterns5-dev-tools
  • libqt5sql5-mysql is not required to build FreeMedForms, but it is required to run the app
  • We recommend to use the QtCreator IDE
#in Debian Stable/Ubuntu
sudo apt-get install build-essential libxext-dev libxext6 libqt5* qtscript5-dev zlib1g-dev zlib1g qtxmlpatterns5-dev-tools

MacOs needed applications for compilation

  • Download and install Qt libs
  • We recommend to use the QtCreator IDE
  • See also this page.

Windows needed applications for compilation

  • Download and install Qt SDK
  • For the Webcam plugin:
    • Download OpenCV lib
    • Install OpenCV libs in the contrib sub-dir
  • We recommend to use the QtCreator IDE
  • See also this page.

The Quazip case

  • By default all the FreeMedForms apps are built with the latest quazip library. This lib is included in the source package.
  • Some linux distros do provide specific package of precompiled 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 FreeMedForms 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" ...
  • To build unit-tests set the WITH_TESTS qmake command line param to 1 and start the application with the –test command line param.

Building the optional plugins

  • To build the optional plugins you can use two methods:
  • 1) add to the qmake commande line:
    • CONFIG+=with-plugin
    • where 'plugin' is the name of the plugin
  • 2) Use buildspecs/optionalplugins.pri file
    • Uncomment required plugins
    • This is the prefered way to build optional plugins
  • Find more documentation in the following file: buildspecs/optionalplugins.pri

Building optional features

  • Find documentation in the following file: buildspecs/optionalfeatures.pri

Building the Qt MySQL plugin

  • For MacOs: there is a specific MacOs script in the scripts dir. You need to install MySQL bin and includes.
  • For Windows: to build qsqlmysql4.dll for the latest Qt 4.8 and MySQL 5.6 releases, follow instructions in english on this post (tested with FreeMedForms 0.9.4, Qt 4.8.6 and MySQL 5.6 on Windows 7 32 bit using MinGW-32): Create MySQL driver for Qt on Windows. Another method in french on this useful post.
  • For Linux: No compilation is required, just install the plugin with sudo apt-get install libqt5sql5-mysql. If you want to build it anyway (to be able to use Qt 5.6 QMYSQL Plugin TLS features for instance), see this page: qmysql-plugin
  • 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.

Using the automated script for unices builds

  • A generic script is provided to ease the building process under Linux.
  • 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 use our ./ without any commandline params. This step parses all the source files and extracts all translatable strings into *.ts files in global_resources/translations
    • translate use the Qt Linguist to *.ts files, and start translating.
    • compile translations use the Qt tool lrelease.
      cd global_resources/translations
      lrelease *.ts

      or use our script.

The qmake && make processes

  • qmake is a small application from Qt which will translate the Qt project files into Makefile for your preferred compiler. This step requires some attention according to the selected build mode. These requirements are detailed below.
  • You can specify your own spec file to qmake.
  • You can use make in multiple thread compilation
  • make -j4

Debug build

  • The debug mode is suitable for testing purpose. It includes all functionnalities, 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 upper.
  • In the debug mode, all processed binaries are postfixed with “_d” on Win32 platforms or “_debug” on unices platforms. 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 FreeMedForms –> /bin/freemedforms/)
    • plugins and libs are located in /bin/LOWERED_APPNAME/plugins (eg: for FreeMedForms –> /bin/freemedforms/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 of each FreeMedForms and derivatives : –config=“../../path/to/your/config.ini”).
cd freemedforms
qmake -r "CONFIG+=debug debug_without_install"
cd bin/freemedforms

# for Linux
./freemedforms_debug --config=../../global_resources/config.ini

# for Mac --config=../../../../../global_resources/config.ini

# for Windows
freemedforms_d.exe --config=../../global_resources/config.ini

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/FreeMedForms .
# FreeMedForms Sample
# 1. Building a Linux package into a fake root system
cd freemedforms
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 freemedforms
qmake -r -config release "CONFIG+=LINUX_INTEGRATED" "INSTALL_ROOT_PATH=/usr/"
make install

# FreeDiams Sample
# 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

Create a pbuilder base for Debian package creation

Install packages

sudo apt-get install pbuilder

Create a tmpfs for a speedy compilation

  • Add the following line to /etc/fstab
# pbuilder in ram
tmpfs 			/var/cache/pbuilder/build	tmpfs	defaults,auto		0	0
  • mount the dir
mkdir /var/cache/pbuilder/build
sudo mount /var/cache/pbuilder/build

Create the base and populate with usefull packages

sudo pbuilder create --basetgz ./sid.tgz --distribution sid
sudo pbuilder --update --basetgz ./sid.tgz --distribution sid --extrapackages "fakeroot libfakeroot debhelper libqt4-dev qt4-qmake libxext-dev zlib1g-dev qtchooser qt5-qmake qt5-default"

Build your packages

cd <pack-version>
debuild -S -sa --lintian-opts -i -k......
cd ..
sudo pbuilder build *.dsc

Mac OS integration

  • For MacOs, you need to:
    • compile the application
    • link to Qt franmework
    • create a DMG package
  • A script is available for the whole process scripts/mac/ It needs only one arg -b AppToBuild.
cd scripts

# Building FreeDiams in release mode and create the DMG package in one step:
./ -b FreeDiams

# Building FreeMedForms in release mode and create the DMG package in one step:
./ -b FreeMedForms

# Building FreeAccount in release mode and create the DMG package in one step:
./ -b FreeAccount

# Building FreePad in release mode and create the DMG package in one step:
./ -b FreePad

# Building FreeToolBox in release mode and create the DMG package in one step:
./ -b FreeToolBox
  • 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 interaction database
    • ICD10 database
  • You need to prepare and include the documentation of the application. The documentation is written on this wiki website. There is a site exporter plugin to facilitate the extraction of documentation. Please contact the dev team for any informations

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. If you want to make yourself familiar with it, look at the many, many tutorials and help pages available in the internet.

Git is available for Mac OSX, Linux, BSD and Windows (and probably for other OS). As starting point look here.

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 checkout the code as described at the Google Code page (link above).

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/freemedforms./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.