Building and Installing

Note

Examples in this chapter refer to a version X.Y.Z, please replace this with your current version, for example 1.1.0!

This chapter describes, how you can build and install simulavr.

Attention

The build scripts with cmake aren’t prepared to work with Windows or Mac OS, even if cmake itself is able to create build configuration for this platforms!

Prerequisites

To build simulavr only you need:

  • cmake (at least version 3.5 or newer)

  • make

  • gcc (at least a version, which supports c++11)

  • git

  • python (at least version 3.5 or newer)

If you want to build the python extension, you need also python development files (e.g. in a debian or ubuntu platform you have to install python3-dev package) and swig. (at least version 3.x or newer)

If you want to build tcl extension, you need:

  • tclsh

  • tcl development files

  • swig (at least version 3.x or newer)

To build the verilog extension you have to install iverilog tool. (included vvp)

For running the complete regression test you need also:

  • avr-gcc (on debian it’s package gcc-avr)

  • avr-libc

  • valgrind (optional, check for overwriting memory and memory leaks)

Building the documentation suite needs also:

  • gzip

  • help2man

  • makeinfo

  • doxygen (optional, for api documentation)

  • dot (optional, for api documentation)

  • python module sphinx (at least version 2.2 for web site and manual)

  • python module rst2pdf (at least version 0.94 for web site and manual)

  • python module beautifulsoup4 (short bs4, for web site and manual)

  • python module requests (for web site and manual)

Building debian packages need also:

  • dpkg

  • strip

  • fakeroot

Build

simulavr uses cmake and git. This means that you should be able to use the following steps to build simulavr:

> git clone https://git.savannah.nongnu.org/git/simulavr.git
> cd simulavr
> make build
> make check

This will build simulavr and check, if the main function is ok.

In the root directory of repository you can find a Makefile as wrapper for calling cmake and control configuration. If you call:

> make

you’ll get a help, what targets are available and what the targets will do.

Targets

make cfgclean

Removes the build directory. The make wrapper configures cmake for “out of source” build. E.g. nearly all build artifacts are below build directory. This removes also the complete cmake configuration.

make clean

As usual, it removes all build artifacts but let cmake configuration untouched.

make build

Build simulavr and all extensions as configured.

make check

Run regression test.

make doc

Build documentation, e.g. man page, info page, sphinx documentation (manual and web site).

make doxygen

Build api documentation.

make debian

Build debian packages for simulavr tool and lib and all configured extensions.

To switch on/off configuration options, you have to call make with the configuration target:

> make debug    # build program, libs and extensions with debug information
> make no-debug # build without debug information

Other config targets are:

  • python (build/do not build python module)

  • tcl (build/do not build tcl module)

  • verilog (build/do not build verilog extension)

  • valgrind (run the gtest regression test additional with valgrind for memory check)

With target all and simple you can switch on and off all configuration options together. There is one special target, taken over from old automake build system:

> make keytrans

This create keytrans.h for tcl extension.

Debian packages

To support install on debian systems (e.g. debian and ubuntu and derivates) it’s possible to build debian packages. Go to root directory and call:

> make debian

This will produce the following packages (PLAT represents the build platform):

libsim_X.Y.Z_PLAT.deb

The simulavr lib itself.

simulavr_X.Y.Z_PLAT.deb

The simulavr tool, depends on libsim package.

simulavr-dev_X.Y.Z_PLAT.deb

Contains header and other files, to build applications against libsim, depends on libsim package.

simulavr-vpi_X.Y.Z_PLAT.deb

Verilog extension, depends on libsim package.

python3-simulavr_X.Y.Z_PLAT.deb

Python3 module, static linked, so no other dependencies needed.

simulavr-tcl_X.Y.Z_PLAT.deb

Tcl extension, depends on libsim package.

On a debian system you could install the simulavr tool itself then (you need root permission):

cd <root_of_repo>/build/debian
apt install libsim_X.Y.Z_PLAT.deb # first install lib to fullfil dependencies
apt install simulavr_X.Y.Z_PLAT.deb

After that you can check, if simulavr is ready:

simulavr -h

Install

If you want to make a installation on a system and not use debian packages, (maybe you system doesn’t support debian packages) then you can call the install target from cmake itself after the normal build is finished:

cd <root_of_repo>
cmake --build build --target progdoc
cmake --build build --target install

After that you’ll find the install tree in the build/install directory. Copy this to the destination, as you want. As example (you need root permission):

cd <root_of_repo>/build/install
cp -r usr /

Build using docker

If docker is installed, then you can create docker images to build simulavr in a stable and defined environment and independent from what’s installed on your computer.

Step 1: create a docker image

There are docker scripts and a small script to create a image:

cd <root_of_repo>/docker
./mkimage buildscripts/bionic.build.Dockerfile

This will create a docker image with name “simulavrbuild” and version “bionic”. (e.g. Ubuntu 18:04)You can check it with:

docker images

There you should find the new created image in the list. Attention: because of the installed packages in this image, the resulting image size is about 1G! There is also a docker script for ubuntu 16:04, called “xenial.build.Dockerfile”.

Now, after the image is ready, you can create the build container:

docker run -it -u buildbudy --name <container_name> simulavrbuild:bionic
buildbudy@e1694c8b9f26:/

You stay now in your new created container, the second line is the bash prompt. You have created a container with name “<container_name>” (replace this to a name, which is useful for you!) from the new built image and running with user “buildbudy”. If you omit the “-u” option, then you’ll be root inside your container. Because this could be dangerous in some cases and normally not needed, it’s better to run with a normal user with normal privileges also inside the container!

You can now leave the container on every time with “exit” command and come back with:

docker start -i <container_name>

In this container you can now start the build:

cd # to come to buildbudy's home directory
git clone -b master https://git.savannah.nongnu.org/git/simulavr.git simulavr
cd simulavr
make all # to switch on all config options exept debug option
make build

After that is finished, you’ve build sucessful simulavr and all extensions.

If you don’t want to clone from official repository, as described before, you could also clone from a local repository (maybe where you’ve written some new code). In this case the container have to created with a extra option:

docker run -it -u buildbudy --name <container_name> -v /local/path:/repo simulavrbuild:bionic

Replace (as before) “<container_name> with a useful name and /local/path with a path, where your local repository is hold. For example /home/user/simulavr is the repository, then ypu could give “-v /home/user:/repo”. Inside the container you will find then a new directory /repo, where you see your repository. Then the clone command could be:

cd
git clone -b your_branch /repo/simulavr simulavr_local

To get out your build artefacts, you can user “docker cp” command (and after you leaved the container):

docker cp <container_name>:/home/buildbudy/simulavr/build/app/simulavr .
docker cp <container_name>:/home/buildbudy/simulavr/build/libsim/libsim.so .

This copies the simulavr tool itself and the simulavr library, which is needed, simulavr to run.