Skip to content

Install Instructions

We guide you through the process of preparing, building and running Artery with the following steps. First of all, you will need to clone the Artery repository on your machine. Afterwards, you can either manually build Artery for your Linux machine or create a Linux-based virtual machine using Vagrant.

Cloning the Artery repository

All source code of Artery is stored in a git repository on GitHub. This repository contains compatible versions of INET, SimuLTE, Veins, Vanetza and some other third-party dependencies as git submodules. You can find those submodules in the extern subdirectory.

Please make sure to fetch these submodules when cloning the Artery repository. The command below will clone Artery's master branch along with matching versions of its submodules onto your machine's file system. Your local clone of the repository will be in the artery directory at the location you have invoked the clone command. We refer to the location of your local clone as $ARTERY_PATH in the following.

git clone --recurse-submodule https://github.com/riebl/artery.git

Alternatively, you can also initialise and fetch these submodules after cloning. This command needs to be invoked from $ARTERY_PATH.

git submodule update --init --recursive

Tip

Check if the directories in $ARTERY_PATH/extern are empty. If they are empty, e.g. no extern/inet/Makefile exists, then your working copy is incomplete. Fix your working copy first because the build process will fail otherwise.

Building Artery from sources

Following instructions show you how to build Artery from its sources on a Linux machine step by step. While it is probably not impossible to build Artery on a non-Linux system, this is neither supported nor tested at all. Instead, consider to set up a virtual machine for Artery if you do not have a Linux system at your fingertips. The alternative build instructions at the end of this page show you how to build a virtual machine with Artery installed inside automatically. But let us now continue with the requirements for the manual build process.

Requirements

Artery builds upon the discrete event simulator OMNeT++, which you need to obtain and install beforehand. Instead of opp_makemake usually employed by OMNeT++ models, Artery's build process relies on CMake. This enables us to handle external dependencies beyond OMNeT++ conveniently. Hence, make sure the following requirements are fulfilled:

  • C++ compiler with C++11 support (GNU GCC 4.9 or later or Clang)
  • Boost (1.65.1 or later is recommended)
  • CMake 3.1 or later
  • OMNeT++ 5.5.1 or later
  • Python 3

We have tested Artery with OMNeT++ 5.5.1, GNU GCC 7.3 and Boost 1.65.1 successfully. Please note that these versions are just minimum requirements. You may benefit from bugfixes when using more recent versions. For example, OMNeT++ 5.6 is working great as well.

Danger

OMNeT++ 6.0 (available as Preview 7 at the time of writing) breaks compatibility of models written for 5.x versions. We recommend to stick with a 5.6 release of OMNeT++ when using Artery for now. An upgrade to 6.x will be possible as soon as all dependencies have been ported.

Vanetza is an integral part of Artery because it provides the ITS-G5 network stack. On top of the dependencies listed above, Vanetza requires

You may install the packages libgeographic-dev and libcrypto++-dev on a Debian system for these. The packages libboost-dev, libboost-date-time-dev, and libboost-system-dev provide the required Boost heades and libraries.

Though not required for compiling Artery, you will also need to install SUMO. Ideally, the sumo executable is located in your $PATH. Then, Artery can launch a sumo instance for you when starting a simulation. You will need version 1.0 or later of SUMO because its TraCI protocol of earlier versions is not compatible.

Build 'extern' components

Bundled third-party dependencies in extern subdirectories are built along with Artery. Artery's build process integrates those dependencies seamlessly without manual intervention.

Note

Previously, users needed to build these dependencies before building Artery. A Makefile located in Artery's root directory aided this step. Since July 2020, CMake handles the whole build process alone.

Create build directory

Are you still with us? Congratulations, you are almost done! Invoke following commands from $ARTERY_PATH to create a build directory for Artery, configure the build directory with CMake and finally build Artery there.

mkdir build
cd build
cmake ..
cmake --build .

Note

It is not a strict requirement that Artery's build directory is located at $ARTERY_PATH/build. You can name it in any way you like and also have multiple build directories, e.g. one for release and one for debug builds. A build directory does not need to be a subdirectory of $ARTERY_PATH either, i.e. out-of-source builds are supported as well.

Automated creation of a virtual machine

You can build a virtual machine containing Artery from scratch assisted by Vagrant and our Ansible deployment scripts. For this procedure, you have to install Vagrant and VirtualBox on your host machine. Your host system may use any operating system supported by Vagrant and VirtualBox, including MacOSX and Windows.

Your working copy of Artery at $ARTERY_PATH contains a Vagrantfile. This file tells Vagrant to download a Debian machine image and deploy Artery in this virtual machine according to the Ansible playbook located at ansible/vagrant.yml. Just run vagrant up from Artery's root directory, be patient, and in the end you are rewarded with a ready-to-go environment to work with Artery. Login credentials for this virtual machine, as by convention for any Vagrant box, are "vagrant" with password "vagrant". Of course, you are free to change the password at your discretion.

During the initial provisioning of this virtual machine, when the Ansible deployment is running, an Internet connection is required. Without an Internet connection, it is impossible to download all the dependencies such as OMNeT++, SUMO, and several system tools and libraries. In case of an interrupted deployment, you may restart the provisioning with vagrant up --provision. Also keep in mind that this initial deployment can take quite some time. Afterwards, the virtual machine can be booted much faster.

You can run the example from the artery-build directory located in the box's home directory at /home/vagrant/ by invoking make run_example. Please note that the artery directory mirrors the cloned repository on your host machine.

Running Artery for the first time

When you have finished building Artery, you can give the shipped example a try to see if everything runs smoothly. With current Artery versions, there is no need to start Veins' sumo-launchd script any more. Instead, Artery will start a SUMO instance on its own with appropriate parameters. You can start the example scenario of Artery (located in scenarios/artery) simply by invoking the run_example target from Artery's root directory:

cmake --build build --target run_example

Note

Substitute build with the name of your build directory. If CMake has generated Makefiles in your build directory (it does so by default), you can also invoke make run_example from there.

Please make sure that sumo can be launched in your environment because this is the SUMO executable Artery uses by default. You can, however, specify which SUMO executable shall be used explicitly. If you want Artery to start SUMO with a graphical user interface, you can put the following line in omnetpp.ini:

*.traci.launcher.sumo = "sumo-gui"

Next: Create your own simulation

You are now ready to create your first own simulation scenario. Have a look at our how-to guide for details.

Last update: August 20, 2023