Installing MADS

configuration
setup
how-to
easy
Author
Affiliation

Paolo Bosetti

University of Trento

Published

August 27, 2025

Abstract

A brief how to for installing MADS on different operating systems.

Installing pre-compiled binaries

Getting the installers

The installers are provided for:

  • MacOS, as a universal binary (Intel and Apple Silicon)
  • Linux, two different deb packages for X86 and aarm64 architectures; the latter also works for Raspberry Pi OS (Raspbian)
  • Windows, as an exe installer (tested on Windows 10 and 11)
Important

Always get the latest MADS installer on: git.new/MADS

A note on versions

MADS follows Semantic Versioning. The version number is in the form MAJOR.MINOR.PATCH, where:

  • MAJOR is incremented when there are incompatible API changes
  • MINOR is incremented when functionality is added in a backwards-compatible manner
  • PATCH is incremented when backwards-compatible bug fixes or minor new functions are made

In addition, some internal bug fixes are published as MAJOR.MINOR.PATCH-<number>-g<hash>, where <number> is the number of commits since the last official release and <hash> is the short git hash of the commit.

That said, agents and broker must have the same MAJOR.MINOR version to be able to communicate. An agent trying to connect to a broker with different MAJOR.MINOR versions refuses to start. The PATCH number can be different, but it is recommended to keep it the same and as recent as possible.

Installing on MacOS

Suppose that you downloaded the installer mads-<version>-Darwin-universal.sh (where <version> is the version number, e.g. 1.3.3). The installer takes the following arguments:

./mads-1.3.3-Darwin-universal.sh --help
Usage: packages/mads-1.3.3-Darwin-universal.sh [options]
Options: [defaults in brackets after descriptions]
  --help            print this message
  --version         print cmake installer version
  --prefix=dir      directory in which to install
  --include-subdir  include the mads-1.3.3-Darwin-universal subdirectory
  --exclude-subdir  exclude the mads-1.3.3-Darwin-universal subdirectory
  --skip-license    accept license

If you run it with no arguments, it will install MADS in the /usr/local/ directory (need sudo) and ask for accepting the license. If you (as me) prefer to keep it in your home directory, you can run:

./mads-1.3.3-Darwin-universal.sh --prefix=${HOME} --skip-license

which will install in ${HOME}/usr/local and automatically accept license. Then, you want to add ${HOME}/usr/local/bin to your search path: add the following line to your .zshrc or .bashrc file:

export PATH=${HOME}/usr/local/bin:$PATH

Finally, restart your terminal and check that MADS is correctly installed by running:

mads --version

Requirements

Unless we’re talking of very specific use cases, you probably want to compile your own plugins. For that, you need the Apple Developer Tools installed, together with CMake and Git.

Installing on Linux

On git.new/MADS you find two deb packages:

  • mads-<version>-Linux-x86_64.deb for Intel architectures
  • mads-<version>-Linux-aarch64.deb for ARM architectures (e.g. Raspberry Pi)

Installing is as simple as:

export MV=1.3.3  # or the latest version
wget https://github.com/pbosetti/MADS/releases/download/v${MV}/mads-${MV}-Linux-aarch64.deb
sudo dpkg -i mads-${MV}-Linux-aarch64.deb
rm mads-${MV}-Linux-aarch64.deb
Note

If you run native Linux virtual machines on MacOS with Apple Silicon chips, as for example by using OrbStack, you need to install the aarch64 version of MADS within the VM. In other words, the same binaries work on Raspberry Pi OS (Raspbian) and on a Linux native VM running on Apple Silicon.

Requirements

Unless we’re talking of very specific use cases, you probably want to compile your own plugins. For that, you need the followings:

sudo apt update
sudo apt install build-essential cmake git clang

In addition, install any other library you plan to use in the development.

Installing on Windows

The Windows installer is a standard graphical exe installer. Download it from git.new/MADS and run it.

The installer installs MADS in C:\Program Files\MADS, The installer will also add the MADS bin directory to your search path.

Requirements

Unless we’re talking of very specific use cases, you probably want to compile your own plugins. For that, you need the Visual Studio 17 (Community Edition is fine) with the C++ development tools, together with CMake and Git.

Building from source

Building from source is discouraged and on some architectures can be quite a long process (10s of minutes). However, it is the only way to get MADS on architectures for which no pre-compiled binaries are available.

If you want to build MADS from source, you need to have the following tools installed:

  • A C++17 compliant compiler: clang on MacOS and Linux, MSVC17 on Windows
  • CMake 3.16 or higher; ccmake comes handy on MacOS and Linux to safely configure build options
  • Git

Get the source code from the MADS repository:

git clone -d1 https://github.com/pbosetti/MADS.git
cd MADS

Building MADS takes three steps:

  1. Configuration

This is where you configure the various build options. You can specify build options either on the cmake command line or interactively with ccmake (on MacOS and Linux, CMake GUI on Windows). For example, to configure MADS in the build directory with default options, you can run:

cmake -Bbuild

Options that you might want to customize include:

  • CMAKE_INSTALL_PREFIX: this is where build products will be put by doing cmake --install build after compilation is done
  • CMAKE_OSX_ARCHITECTURES: on MacOS, you can specify x86_64, arm64, or x86_64;arm64 for universal binary. Picking only one architecture will build faster and produce smaller binaries
  • MADS_ENABLE_DOXYGEN: default OFF; if ON, the Doxygen documentation will be built (requires Doxygen installed)
  • MADS_ENABLE_GUI: default OFF; if ON, the MADS GUI will be built (requires Qt installed)
  • MADS_ENABLE_LOGGER: default ON; if OFF, the MADS logger plugin will not be built; since it requires to build the MongoDB libraries, this will speed up the build significantly
  • MADS_MINIMAL: default OFF; if ON, only the core MADS libraries will be built, no plugins, no examples, no tests, no MongoDB interface; this is useful if you want to build MADS just the bare minimum (the broker and the libraries needed for developing plugins).
  1. Building

Make the first build. On Unixes:

cmake --build build -j8

On Windows:

cmake --build build --config Release

If everything goes fine, skip to the next step. If something goes wrong, check the error messages and try to fix the issues. If you need help, open an issue on the MADS GitHub repository.

  1. Installation

Now open the interactive CMake and toggle the following options:

  • FETCHCONTENT_FULLY_DISCONNECTED: set it to ON to avoid CMake to try to check dependencies again
  • MADS_SKIP_EXTERNALS: set it to ON to avoid CMake build dependencies as MongoDB and Snappy; this is also enabling the creation of an installer.

Runn again the compiler and then create the package:

cmake --build build -j8 # On Windows, don't forget to add --config Release
cmake --build build -t package

The installer will be created in the packages directory.

Back to top