You are here: Start » Using Library on Linux
Using Library on Linux
Requirements
Aurora Vision Library Lite is designed to be used with GCC compiler on Linux x86_64, embedded ARMv7-A and ARMv8-A systems.
Currently gcc
in version 5.4 is supported,
and corresponding toolchains for embedded linux: arm-linux-gnueabihf-
, aarch64-linux-gnu-
.
Custom build can be prepared upon the earlier contact with Aurora Vision team.
The Aurora Vision Library Lite is distributed as .tar.gz
or .tar.xz
archive.
The library is compatible with Debian-like system, including - but not limited to - Ubuntu distributions.
Common prerequisites
Properly set locale on target computer is important.
Non-existing locale will cause bugs and bad behavior.
To list locale that exists on your computer use: locale -a
,
and currently set: locale
.
Remember that running your application as daemon (e.g. from systemd
) may set different locale,
than the one in your user terminal.
Refer to your Linux distribution documentation.
To build example in simple manner, GNU Make tool and CMake is needed.
- Ubuntu 18.04/Debian 9 or newer:
- Runtime:
- package libc6 ≥ 2.23
- package libudev1 ≥ 229
- Development:
- package g++ version ≥ 5.4
- package make
- package cmake version ≥ 3.10
sudo apt-get install cmake make g++
- Examples:
sudo apt-get install libgtk-3-dev libsdl-dev qtbase5-dev
- Runtime:
- CentOS 8/Fedora 29/OpenSUSE 15.0 or newer:
- Runtime:
- package glibc ≥ 2.23
- package systemd ≥ 229
- Development:
- package gcc-c++ version ≥ 5.4
- package make
- package cmake version ≥ 3.5
- CentOS/Fedora:
dnf install gcc-c++ make cmake
- OpenSUSE:
zypper install gcc-c++ make cmake
- Examples:
- CentOS/Fedora:
dnf install SDL2-devel qt5-qtbase-devel gtk3-devel
- OpenSUSE:
zypper install libSDL2-devel libqt5-qtbase-devel gtk3-devel
- CentOS/Fedora:
- Runtime:
- Generic:
- Runtime:
- libraries libc.so.6, libpthread.so.0, libm.so.6, libdl.so.2, librt.so.1, libgcc_s.so.1 from glibc version ≥ 2.23 or compatible (i.e. musl libc)
- library libudev.so.1 from systemd version ≥ 229
- Runtime:
Supported input devices
Vendor | x86_64 | armv7-a | armv8 |
ximea | ✔ | ✔ | ✔ |
Allied Vision Vimba | ✔ | ✔ | ✔ |
Basler Pylon | ✔ | ✔ | ✔ |
LMI Gocator | ✔ | ✔ | ✔ |
Installation instructions
In unpacked directory call the install
script.
In example: sudo ./install
This command will install the library to a proper directory in opt.
It will also make the library visible to CMake find_package
command.
Compilation instructions
Directory structure
Unpacked directory consists of following entries:
examples/
- directory contains source files of example programs written with Aurora Vision Library Liteinclude/
- this directory contains library header fileslib/
- here the .so file with library is stored, along with any kitsbin/
- directory for additional binaries, like Licensing tool./README
- instruction of library usage/sha512sum
- checksums for all files in archive, check withsha512sum --quiet -c sha512sum
/metadata.json
- file containing information about the optimal target system, and library version/install
- installation script/uninstall
- uninstall script, will be copied to installation directory, where it can be safely used
Compilation
Using CMake
CMake is the recommended way to compile on linux, see documentation Using Library with CMake
Using Makefile or your custom build system
For compiling with Aurora Vision Library Lite please remember to:
- add the
include/
subdirectory to the compiler include directories:-I
switch - add the
lib/
subdirectory to the linker directories:-L
switch - link with Aurora Vision Library Lite:
-lAVL
- use
-rpath
in linker options,LD_LIBRARY_PATH
orLD_PRELOAD
oflibAVL.so
file. - link with dependencies:
-lpthread -lrt -ldl
One can consult makefile in the examples/ directory to see how to compile and link with Aurora Vision Library Lite.
Known compilation bugs
In case of the following linker errors: (or similar)
/usr/bin/ld: warning: libiconv.so, needed by lib/libAVL.so, not found (try using -rpath or -rpath-link) lib/libAVL.so: undefined reference to `libiconv' lib/build/libAVL.so: undefined reference to `libiconv_close' lib/build/libAVL.so: undefined reference to `libiconv_open'
It is a known gnu linker bug, affecting versions older than 2.28 (e.g. in Ubuntu 16.04).
To solve the problem you can:
- Try a different linker (add for linking
-fuse-ld=gold
for gold or-fuse-ld=lld
, consult your linux distribution manual) - Link with the missing library (for example add
-liconv
) - Update the linker (
binutils
2.28 or newer)
Licensing and distribution
Licensing
File based licenses are supported on all Linux platforms. Dongle licenses depend on CodeMeter runtime. Currently Codemeter runtime is available for x86_64 and ARMV7-A. To develop and debug programs written with Aurora Vision Library Lite, Library license has to be present. To run compiled binaries linked with Aurora Vision Library Lite, LibraryRuntime license has to be present.
One can use license_manager
from bin/
directory to list currently installed file or dongle
licenses: license_manager list
Red marked licenses are invalid, for example past the license date or installed license for the wrong machine (bad ID)
File License
To obtain license:
- In a terminal, on the target machine run
license_manager --id
frombin/
directory - Copy the printed Computer ID
- Use that Computer ID to get a
.avkey
file from User Area on www.adaptive-vision.com website. - Download the key to the target machine
- Install the license by one of the following methods:
- Run in terminal
license_manager install downloaded_file.avkey
(Recommended) - Copy the
.avkey
file next to executable, that is using Aurora Vision Library Lite
- Run in terminal
Dongle License
Installed CodeMeter Runtime is required, as well as proper license available on plugged in dongle.
Download runtime package from WIBU
website,
section "CodeMeter User Runtime for Linux".
"Driver Only" (lite) version recommended for headless (no desktop GUI) installations.
ARMV7-A is available under "CodeMeter User Additional Downloads" as "Raspberry PI" version
Distribution
To distribute program with Aurora Vision Library Lite, one have to provide license (file or dongle - depending on system used) and
the libavl.so
.
To provide the .so
file, one can install SDK on target machine, but this will provide headers etc.,
which may be unwanted.
In such case, the library file, with any used kits should be copied to suitable system directory,
or the program has to be compiled with -rpath
and relative path to the .so file.
Third option is to provide a boot script,
which will set LD_LIBRARY_PATH
or LD_PRELOAD
with libavl.so
location.
Program development - general advise
The most convenient way to make programs with Aurora Vision Library Lite for Linux is to develop vision algorithm using Aurora Vision Studio on Windows and then generating C++ code. This code can be further changed or interfaced with rest of the system and tested on Windows. Then, cross-compiler can be used to prepare Linux build, which will be provided to target machine. It is easy to organize work this way, because:
- developing vision algorithm using plain C++ is hard, troublesome and error prone, but Aurora Vision Studio makes it easy,
- programs written with Aurora Vision Library Lite on Windows can be easily debugged using Microsoft Visual Studio thanks to provided debug visualizers and the Image Watch extensions to Microsoft Visual Studio,
- cross compilation using virtualization solution, like Vagrant, is easy and fast, and does not force developer to use two systems simultaneously.
Of course, the programs can be also developed on Linux machine directly.
Then a dose of work should be put into writing good Makefile
.
Debugging can be done by GDB, but we do not provide debug symbols for Aurora Vision Library Lite.
Runtime considerations
Some architectures might impose restrictions on libavl code. In this section we present pitfalls the user should be aware of.
Homogeneous Multiprocessor/SMP
There are many identical cores. One might have a problem when cores span across multiple physical CPUs, frequent on servers. The CPU's don't share CPU cache, so when execution of thread from CPUx/COREa is moved to CPUy/COREb, cache needs to be updated. It imposes time penalty. A workaround would be to pin threads to specific cores, (set affinity) or limit execution of libavl to specific number of cores on one physical CPU.
- use
taskset
linux command to limit execution on specific cores - use
OMP_PROC_BIND=TRUE
environment variable to bind threads to cores they started on
Heterogeneous Multiprocessor
There are different kinds of processors the code runs on. Some examples are ARM big.LITTLE architecture, (where the cores mainly differ in maximum speed), or Tegra TX2 (where the cores serve different purpose). This kind of architecture might also suffer from Homogeneous Multiprocessor problems, but might suffer from different set of problems. One have to consider the cores are designed for low power and high performance, single threaded multithreaded optimized. Use the same solutions as in previous point, just take into account what type of algorithm will be executed.
Tegra TX2
This CPU is an example of Heterogeneous Multiprocessor architecture. It comprises of 6 cores: 2 Denver2 4 Cortex-A57. Denver2 core is designed for single thread performance, while Cortex-A57 for multithreaded. One can use both, but with thread binding, so threads are executed on the cores they started on. Limiting to one type of core might be beneficial when power consumption is a factor. Remember that thread binding might bind your application to core you did not want to use. Core 0 is Cortex-A57, core 1 and 2: Denver2, and cores 3-5: Cortex-A57. Core 0 is always active.
Previous: Project Configuration | Next: Technical Issues |