Prev Tutorial: Cross compilation for ARM based Linux systems
Next Tutorial: Building OpenCV for Tegra with CUDA
| |
| Original author | Kumataro |
| Compatibility | Ubuntu >=23.04 |
| OpenCV >=4.8.0 |
- Warning
- This tutorial may contain obsolete information.
What is "MultiArch"
OpenCV may use a lot of 3rdparty libraries for video and image decoding, rendering, acceleration and complex math algorithms. The 3rd party components are found by CMake on the build host cross-compilation allows to build OpenCV for foreign architecture or OS, but we loose that large world of components and have to cross-compile each dependency separately and point to it during OpenCV build.
Debian/Ubuntu MultiArch helps to fix this. It allows to install several foreign architecture libraries on host system and use them during OpenCV dependencies resolution.
- Warning
- Following these steps will make your Linux environment a little dirty. If possible, it is better to use VMs or Container(e.g. Docker).
- This tutorial expects host and target uses same Ubuntu version. Do not use/mix different versions for external library dependency.
- Good: Host and Target are 23.04.
- Good: Host and Target are 23.10.
- Not Good: Host is 23.04, and Target is 23.10.
- Not Good: Host is 23.10, and Target is 23.04.
- This tutorial may be used for Debian and its derivatives like Raspberry Pi OS. Please make any necessary changes.
Download tools
Install necessary tools and toolchains for cross-compilation.
- git, cmake, pkgconf and build-essential are required basically.
- ninja-build is to reduce compilation time(option).
- crossbuild-essential-armhf is toolchain package for armv7 target.
- crossbuild-essential-arm64 is toolchain package for aarch64 target.
sudo apt update -y
sudo apt install -y \
git \
cmake \
pkgconf \
build-essential \
ninja-build \
crossbuild-essential-armhf \
crossbuild-essential-arm64
If you want to enable Python 3 wrapper, install these packages too.
sudo apt install -y \
python3-minimal \
python3-numpy
Working folder structure
In this tutorial, following working folder structure are used.
/home
+ kmtr - please replace your account name.
+ work
+ opencv - source, cloned from github
+ opencv_contrib - source, cloned from github
+ build4-full_arm64 - artifact(for aarch64 target), created by cmake
+ build4-full_armhf - artifact(for armhf target), created by cmake
- Create working folder under your home directory.
- Clone OpenCV and OpenCV Contrib from repository to work directory.
cd ~
mkdir work
cd work
git clone --depth=1 https://github.com/opencv/opencv.git
git clone --depth=1 https://github.com/opencv/opencv_contrib.git
Update apt and dpkg settings
These steps are on host.
apt and dpkg are package management systems used in Ubuntu and Debian.
Following are setup steps to use MultiArch.
Step 1. Add apt source for arm64 and armhf
Execute sudo apt edit-sources to add foreign arch libraries at end of file.
Example 1: arm64 and armv7 for Ubuntu 23.04
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-updates main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-updates universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-updates multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-backports main restricted universe multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-security main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-security universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports lunar-security multiverse
Example 2: arm64 and armv7 for Ubuntu 23.10
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-updates main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-updates universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-updates multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-backports main restricted universe multiverse
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-security main restricted
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-security universe
deb [arch=arm64,armhf] http://ports.ubuntu.com/ubuntu-ports mantic-security multiverse
Step 2. Update apt database
Update apt database to apply new apt sources.
Execute sudo apt update.
Step 3. Update dpkg settings
Update dpkg settings to support foreign architectures.
Execute sudo dpkg --add-architecture arm64 and/or sudo dpkg --add-architecture armhf.
sudo dpkg --add-architecture arm64
sudo dpkg --add-architecture armhf
sudo dpkg --print-architecture shows what is host architecture.
sudo dpkg --print-architecture
amd64
And sudo dpkg --print-foreign-architectures shows what foreign architectures are supported.
sudo dpkg --print-foreign-architectures
arm64
armhf
Confirm working pkg-config
With MultiArch, several shared libraries and pkg-config information for each architectures are stored into /usr/lib.
/usr
+ lib
+ aarch64-linux-gnu - shared libraries for arm64
+ pkgconfig - pkg-config files for arm64 libraries
+ arm-linux-gnueabihf - shared libraries for armhf
+ pkgconfig - pkg-config files for armhf libraries
+ share
+ pkgconfig - pkg-config files(for header files)
Confirm to work pkg-config using PKG_CONFIG_PATH, PKG_CONFIG_LIBDIR and PKG_CONFIG_SYSROOT_DIR options.
for aarch64:
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
pkg-config --list-all
for armv7:
PKG_CONFIG_PATH=/usr/lib/arm-linux-gnueabihf/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/arm-linux-gnueabihf \
PKG_CONFIG_SYSROOT_DIR=/ \
pkg-config --list-all
Cross-compile for aarch64
Following is to compile for target (aarch64) at host (x86-64).
Step 1. Install external libraries for target into host
This step is on host.
Install libfreetype-dev, libharfbuzz-dev and FFmpeg packages for target (arm64) into host (x86-64).
sudo apt install -y \
libavcodec-dev:arm64 \
libavformat-dev:arm64 \
libavutil-dev:arm64 \
libswscale-dev:arm64 \
libfreetype-dev:arm64 \
libharfbuzz-dev:arm64
If you want to enable Python 3 wrapper, install these packages too.
sudo apt install -y \
libpython3-dev:arm64
If succeed, pkg-config can show information about these packages.
For Freetype2 and Harfbuzz:
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
pkg-config freetype2 harfbuzz --cflags --libs
-I/usr/include/freetype2 -I/usr/include/libpng16 -I/usr/include/harfbuzz -I/usr/include/glib-2.0 -I/usr/lib/aarch64-linux-gnu/glib-2.0/include -L/usr/lib/aarch64-linux-gnu -lfreetype -lharfbuzz
For FFmpeg:
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
pkg-config libavcodec libavformat libavutil libswscale --cflags --libs
-I/usr/include/aarch64-linux-gnu -L/usr/lib/aarch64-linux-gnu -lavcodec -lavformat -lavutil -lswscale
Step 2. Configure OpenCV Settings
This step is on host.
Execute cmake to make cross-compile configuration for aarch64.
- Note
-DCMAKE_TOOLCHAIN_FILE should be absolute/real file path, not relative path.
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
cmake -S opencv \
-B build4-full_arm64 \
-DCMAKE_TOOLCHAIN_FILE=/home/kmtr/work/opencv/platforms/linux/aarch64-gnu.toolchain.cmake \
-DOPENCV_EXTRA_MODULES_PATH=opencv_contrib/modules \
-GNinja
If you want to enable Python 3 wrapper, extra options are needed.
PYTHON3_REALPATH=`realpath /usr/bin/python3`
PYTHON3_BASENAME=`basename ${PYTHON3_REALPATH}`
PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu \
PKG_CONFIG_SYSROOT_DIR=/ \
cmake -S opencv \
-B build4-full_arm64 \
-DCMAKE_TOOLCHAIN_FILE=/home/kmtr/work/opencv/platforms/linux/aarch64-gnu.toolchain.cmake \
-DOPENCV_EXTRA_MODULES_PATH=opencv_contrib/modules \
-DPYTHON3_NUMPY_INCLUDE_DIRS="/usr/local/lib/${PYTHON3_BASENAME}/dist-packages/numpy/core/include/" \
-DPYTHON3_INCLUDE_PATH="/usr/include/${PYTHON3_BASENAME};/usr/include/" \
-DPYTHON3_LIBRARIES=`find /usr/lib/aarch64-linux-gnu/ -name libpython*.so` \
-DPYTHON3_EXECUTABLE="/usr/bin/${PYTHON3_BASENAME}" \
-DPYTHON3_CVPY_SUFFIX=".so" \
-GNinja
- Note
- Lastly, "python3.XX" string is needed. So this script generate it.
- Get real path from "/usr/bin/python3" to "/usr/bin/python3.xx".
- Get base name from "/usr/bin/python3.xx" to "pyhton3.xx".
Following is cmake outputs.
Host is Linux x86_64.Target is Linux aarch64.- FFmpeg is available.
-- General configuration for OpenCV 4.8.0-dev =====================================
-- Version control: 408730b
--
-- Extra modules:
-- Location (extra): /home/kmtr/work/opencv_contrib/modules
-- Version control (extra): faa5468
--
-- Platform:
-- Timestamp: 2023-12-01T22:02:14Z
-- Host: Linux 6.5.0-13-generic x86_64
-- Target: Linux 1 aarch64
-- CMake: 3.27.4
-- CMake generator: Ninja
-- CMake build tool: /usr/bin/ninja
-- Configuration: Release
--
-- CPU/HW features:
-- Baseline: NEON FP16
-- required: NEON
-- disabled: VFPV3
-- Dispatched code generation: NEON_DOTPROD NEON_FP16 NEON_BF16
-- requested: NEON_FP16 NEON_BF16 NEON_DOTPROD
-- NEON_DOTPROD (1 files): + NEON_DOTPROD
-- NEON_FP16 (2 files): + NEON_FP16
-- NEON_BF16 (0 files): + NEON_BF16
--
-- C/C++:
-- Built as dynamic libs?: YES
-- C++ standard: 11
-- C++ Compiler: /usr/bin/aarch64-linux-gnu-g++ (ver 13.2.0)
:
:
--
-- Video I/O:
-- DC1394: NO
-- FFMPEG: YES
-- avcodec: YES (60.3.100)
-- avformat: YES (60.3.100)
-- avutil: YES (58.2.100)
-- swscale: YES (7.1.100)
-- avresample: NO
-- GStreamer: NO
-- v4l/v4l2: YES (linux/videodev2.h)
--
If enabling Python 3 wrapper is succeeded, Python 3: section shows more.
--
-- Python 3:
-- Interpreter: /usr/bin/python3.11 (ver 3.11.6)
-- Libraries: /usr/lib/aarch64-linux-gnu/libpython3.11.so
-- numpy: /usr/local/lib/python3.11/dist-packages/numpy/core/include/ (ver undefined - cannot be probed because of the cross-compilation)
-- install path: lib/python3.11/dist-packages/cv2/python-3.11
--
-- Python (for build): /usr/bin/python3.11
--
Step 3. Build and archive OpenCV libraries and headers
This step in in host.
Build and install. (This install means only that copying artifacts to install folder.)
cmake --build build4-full_arm64
sudo cmake --install build4-full_arm64
Archive artifacts(built libraries and headers) to opencv_arm64.tgz with tar command.
tar czvf opencv_arm64.tgz -C build4-full_arm64/install .
And send opencv_arm64.tgz to target.
Step 4. Install dependency libraries at target
This step is executed on the target system.
Install dependency run-time libraries for OpenCV/OpenCV contrib libraries at target.
sudo apt install -y \
libavcodec60 \
libavformat60 \
libavutil58 \
libswscale7 \
libfreetype6 \
libharfbuzz0b
sudo ldconfig
If you want to enable Python 3 wrapper, install these packages too.
sudo apt install -y \
python3-minimal \
python3-numpy
- Warning
- If version of runtime libraries and/or programs are incremented, apt package names may be changed (e.g.
libswscale6 is used for Ubuntu 23.04, but libswscale7 is used for Ubuntu 23.10). Looking for it with apt search command or https://packages.ubuntu.com/ .
- Warning
External library version between host and target should be same. Please update to the latest version libraries at the same time as possible.
Even if the OS versions are the same between the Host and Target, the versions may differ due to additional updates to the libraries. This will cause unexpected problems.
For example)
- On Host, OpenCV has been build with external libA (v1.0) for target.
- libA (v1.1) may be updated.
- On Target, libA (v1.1) is installed to use OpenCV.
- In this case, versions of libA is difference between compiling and running.
- Warning
If you forget/mismatch to install some necessary libraries, OpenCV will not works well.
ldd command can detect dependency. If there are any "not found", please install necessary libraries.
ldd /usr/local/lib/libopencv_freetype.so
(Not Good) freetype module requires libharfbuzz.so.0, but it has not been installed.
linux-vdso.so.1 (0xABCDEFG01234567)
libopencv_imgproc.so.408 => /usr/local/lib/libopencv_imgproc.so.408 (0xABCDEF001234567)
libfreetype.so.6 => /lib/aarch64-linux-gnu/libfreetype.so.6 (0xABCDEF001234567)
libharfbuzz.so.0 => not found
libopencv_core.so.408 => /usr/local/lib/libopencv_core.so.408 (0xABCDEF001234567)
:
(Good) All libraries which are required from freetype modules are installed.
linux-vdso.so.1 (0xABCDEFG01234567)
libopencv_imgproc.so.408 => /usr/local/lib/libopencv_imgproc.so.408 (0xABCDEF001234567)
libfreetype.so.6 => /lib/aarch64-linux-gnu/libfreetype.so.6 (0xABCDEF001234567)
libharfbuzz.so.0 => /lib/aarch64-linux-gnu/libharfbuzz.so.0 (0xABCDEF001234567)
libopencv_core.so.408 => /usr/local/lib/libopencv_core.so.408 (0xABCDEF001234567)
:
Step 5. Install OpenCV libraries to target
This step is on target.
Receive opencv_arm64.tgz from host (generated at Step3), and extract to /usr/local.
sudo tar zxvf opencv_arm64.tgz -C /usr/local
sudo ldconfig
You can use OpenCV libraries same as self-compiling. Following is OpenCV sample code. Compile and run it on target.
Makefile
a.out : main.cpp
g++ main.cpp -o a.out \
-I/usr/local/include/opencv4 \
-lopencv_core
main.cpp
#include <iostream>
{
return 0;
}
const String & getBuildInformation()
Returns full configuration time cmake output.
int main(int argc, char *argv[])
Definition highgui_qt.cpp:3
Execute make and run it.
If you want to enable Python 3 wrapper, execute following command to confirm.
python3 -c "import cv2; print(cv2.getBuildInformation())"
Cross-compile for armv7
Following is to compile for target (armhf) at host (x86-64).
- To resolve dependencies,
linux-libc-dev:armhf is required.
- To optimize with neon,
-DENABLE_NEON=ON is needed.
sudo apt install -y \
linux-libc-dev:armhf \
libavcodec-dev:armhf \
libavformat-dev:armhf \
libavutil-dev:armhf \
libswscale-dev:armhf \
libfreetype-dev:armhf \
libharfbuzz-dev:armhf
PKG_CONFIG_PATH=/usr/lib/arm-linux-gnueabihf/pkgconfig:/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=/usr/lib/arm-linux-gnueabihf \
PKG_CONFIG_SYSROOT_DIR=/ \
cmake -S opencv \
-B build4-full_armhf \
-DENABLE_NEON=ON \
-DCMAKE_TOOLCHAIN_FILE=/home/kmtr/work/opencv/platforms/linux/arm-gnueabi.toolchain.cmake \
-DOPENCV_EXTRA_MODULES_PATH=opencv_contrib/modules \
-GNinja
cmake --build build4-full_armhf
sudo cmake --install build4-full_armhf
tar czvf opencv_armhf.tgz -C build4-full_armhf/install .
Following is cmake outputs.
Host is Linux x86_64.Target is Linux arm.- FFmpeg is available.
-- General configuration for OpenCV 4.8.0-dev =====================================
-- Version control: 408730b
--
-- Extra modules:
-- Location (extra): /home/kmtr/work/opencv_contrib/modules
-- Version control (extra): faa5468
--
-- Platform:
-- Timestamp: 2023-12-02T03:39:58Z
-- Host: Linux 6.5.0-13-generic x86_64
-- Target: Linux 1 arm
-- CMake: 3.27.4
-- CMake generator: Ninja
-- CMake build tool: /usr/bin/ninja
-- Configuration: Release
--
-- CPU/HW features:
-- Baseline: NEON
-- requested: DETECT
-- required: NEON
-- disabled: VFPV3
--
-- C/C++:
-- Built as dynamic libs?: YES
-- C++ standard: 11
-- C++ Compiler: /usr/bin/arm-linux-gnueabihf-g++ (ver 13.2.0)
:
:
--
-- Video I/O:
-- DC1394: NO
-- FFMPEG: YES
-- avcodec: YES (60.3.100)
-- avformat: YES (60.3.100)
-- avutil: YES (58.2.100)
-- swscale: YES (7.1.100)
-- avresample: NO
-- GStreamer: NO
-- v4l/v4l2: YES (linux/videodev2.h)
--
1.12.0