Compile UltraGrid (Source)

For source distribution, you have to compile UltraGrid by yourself. Prior to compiling UltraGrid, you need to setup a build environment and satisfy dependencies for those modules, that you want to compile with UltraGrid.

If you want to use UltraGrid only locally, after the Compilation step you may be able to directly run UltraGrid. If you want to distribute UltraGrid (or run on another computer), you should follow the Bundling instructions (this is recommended for macOS in any case).

There is also a extra section dedicated GUI compilation.

Table of Contents

• Table of Contents
• Prerequisites
  • Windows prerequisites
    • Build environment
    • Building libraries
    • CUDA
  • macOS prerequisites
  • Linux prerequisites
• Modules
• Compiling UltraGrid
  • Cross-compile (for Windows on Linux)
  • Cross-compile 64-bit ARM macOS
• Bundling
  • Bundling in Linux
  • Bundling in macOS
    • Bundling macOS GUI
  • Bundling in Windows
    • Bundling Windows GUI
• GUI
  • QT
    • macOS GUI
      • Dynamic Linking
      • Static Linking
    • Linux GUI

Prerequisites

In general, a working build environment including a C and C++ compiler is requested. POSIX shell is also required to run the configure script. Also autotools (autoconf, automake) are strongly recommended to be able to generate the configure script if not present (only in releases). C99 C compiler and C++17-capable C++ compiler is required (currently at least with the feature set offered by GCC 6). Pthread library is also needed.

Windows prerequisites

For compilation under Windows, you will need to use MinGW-w64. Visual Studio with MSVC will not run out-of-box. Strongly recommended is the use of MSYS2 environment (although not necessary). Winpthreads is also needed (already included in MinGW-w64).

Build environment

If you do not have pregenerated “configure” script in you sources (eg. in a release), you will need to have autoconf and automake.

Following command is recommended to install needed dependencies inside MSYS2:

pacman -Sy autoconf automake make $MINGW_PACKAGE_PREFIX-toolchain pkgconf

Note: The whole toolchain is not necessary, you may come along with only mingw-w64-clang-x86_64-clang and mingw-w64-clang-x86_64-winpthreads-git for clang64 environment.

Only MSYS2 environments using UCRT are supported, clang64 is recommended because it seems to be more recent.

Building libraries

In following sections, we assume that you install libraries into /ucrt64. This is fine because the preprocessor/compiler/linker can find it easily there. On the other hand, you slightly contaminate your MinGW installation. There is one alternative - to install custom packages into /usr/local (or even better to /ucrt64/local) as it is on Unix-based systems. MSYS maps this somewhere to its directory tree and takes care of translation to native path when invoking a non-MSYS command (eg. compiler). Then you can use –prefix=/usr/local when building packages. You may also need some (or all) of these environment variables adjusted:

export PATH=/usr/local/bin${PATH:-:$PATH}
export CPATH=/usr/local/include${CPATH:-:$CPATH}
export LIBRARY_PATH=/usr/local/lib${LIBRARY_PATH:-:$LIBRARY_PATH}

CUDA

For CUDA, you will also need to have Microsoft Visual Studio installed and to have the MSVC compiler (cl.exe) in path, eg. something like the following (VS 2019):

PATH=$PATH:$(echo /c/Program\ Files/Microsoft\ Visual\ Studio/*/Community/VC/Tools/MSVC/*/bin/Hostx64/x64

(if only one MSVS edition is installed, otherwise replace first asterisk or use eg. find)

Note: You may also use vswhere to locate VS installation (this is the preferred alternative for VS 2017 and newer), see here.

Furthermore, you need to have CUDA_PATH environment variable set to CUDA toolkit root or nvcc in PATH (usually both done by CUDA installator).

macOS prerequisites

On macOS you need to have Xcode with command line tools (need to be installed separately). Recommended is also to install Homebrew (or any of MacPorts, Fink and pkgin).

If you compile from GIT, that doesn't the configure script, you need additional dependencies (can be installed via Homebrew):

brew install autoconf automake pkgconfig libtool

For bundling, a tool called dylibbundler is recommended:

brew install dylibbundler

Linux prerequisites

For Linux build you generally need working build environment, eg. for Debian/Ubuntu:

sudo apt install build-essential

To be able to build from GIT (that doesn't have generated configure script), you also need:

sudo apt install autoconf automake libtool pkgconf # Ubuntu, Debian

and of course if you are cloning from GIT:

sudo apt install git

Modules

This section lists dependencies for optional UltraGrid modules and instructions how to install that dependencies and configure UltraGrid. When content with the selection, continue to Compile section.

It is recommended that whenever you modify an environment variable, you may add the appropriate export command also to your shell initializiton file (eg. .bashrc) to make it persist for further shell sessions.

Module	Required libraries¹	Ubuntu packages	Fedora packages	Notes	Non-free²
AJA	libajantv2				no
ALSA	alsa	libasound-dev	alsa-lib-devel
avfoundation	AV Foundation Kit Framework (preinstalled in OS X)
BitFlow	BitFlow SDK				yes
Bluefish444	bluefish444 SDK				yes
Cineform	Cineform SDK	uuid-dev (dependency)		Requires cmake, ossp-uuid (Mac, Homebrew)	no
Comprimato J2K	UltraJ2K			expects libs/headers in common path⁴	yes
Conference	OpenCV	libopencv-dev	opencl-devel		no
CUDA DXT	CUDA	nvidia-cuda-toolkit
DVS	DVS SDK				yes
DeckLink	none
DELTACAST	VideoMasterHD SDK				yes
GL	glew GLFW gl	libglew-dev libgl1-mesa-dev libglfw3-dev	mesa-libGL-devel glfw-devel glew-devel		no
GPUJPEG	libgpujpeg
JACK audio driver	jack	libjack-jackd2-dev	jack-audio-connection-kit-devel
JACK transport	jack	libjack-jackd2-dev	jack-audio-connection-kit-devel
JPEG to DXT	CUDA libgpujpeg	nvidia-cuda-toolkit (libgpujpeg not available in Ubuntu repositories)
Libavcodec	libavcodec libavutil	libavcodec-dev libavutil-dev	ffmpeg-devel
NDI	NDI SDK headers			expects headers in common path⁴	yes
OpenSSL | wolfSSL	crypto (OpenSSL) | wolfssl	libssl-dev | wolfssl-dev	openssl-devel
Portaudio	portaudio-2.0	portaudio19-dev	portaudio-devel
Qt GUI	Qt5 | Qt6	qtbase5-dev | qt6-base-dev	qt5-qtbase-devel
resize	opencv	libopencv-dev	opencv-devel
RTDXT	gl	libgl1-mesa-dev
RTSP	libcurl	libcurl4-openssl-dev	libcurl-devel
RTSP server	live555 [ up to commit 35c375 ]			old version from 2015 is needed	no
SDP/HTTP transport	EmbeddableWebServer.h
scale	gl	libgl1-mesa-dev
screen	none (macOS,Win) x11 | pipewire (Linux)	libx11-dev | libpipewire-dev
SDL	sdl2	libsdl2-dev	SDL2-devel
Soxr	soxr	libsoxr-dev	soxr-devel	for audio resampling³	no
SpeexDSP	speexdsp	libspeexdsp-dev	speexdsp-devel	-"-	no
SPOUT
Syphon
swmix	gl	libgl1-mesa-dev
UYVY	CUDA	nvidia-cuda-toolkit
Vulkan	vulkan sdl2	libvulkan-dev libsdl2	vulkan-loader-devel SDL2-devel		no
V4L2	(libv4lconvert)	(libv4l-dev)	(libv4l-devel)	libv4lconvert dependency is optional
zfec (Reed-Solomon)	-	python(3)-zfec or src	-	checks python-zfec or /usr[/local]/src/zfec	no
DRM display	libdrm	libdrm-dev	libdrm-devel		no

¹ If applicable, requirements are in pkg-config compatible format.

² For modules marked as a non-free you shall obtain SDK from vendor by yourself.

³ Soxr/SpeexDSP is very recommended if using audio (otherwise resampling won't work)

⁴ eg. libs in /usr/local/lib, headers /usr/local/include (or in /usr/{include,lib} directly). Alternatively the path for libs can be added to environment variable LIBRARY_PATH and headers to CPATH.

AJA

see also the corresponding CI script

Get the libajantv2 source codes, eg.:

git clone --depth 1 https://github.com/aja-video/libajantv2.git

Compile:

export MACOSX_DEPLOYMENT_TARGET=10.13 # needed only for arm64 mac
cmake -DAJANTV2_DISABLE_DEMOS=ON  -DAJANTV2_DISABLE_DRIVER=ON \
        -DAJANTV2_DISABLE_TOOLS=ON  -DAJANTV2_DISABLE_TESTS=ON \
        -DAJANTV2_DISABLE_PLUGINS=ON  -DAJANTV2_BUILD_SHARED=ON \
        -DCMAKE_BUILD_TYPE=Release -Blibajantv2/build -Slibajantv2
cmake --build libajantv2/build --config Release -j "$(nproc)"

Then install it:

• Linux

   sudo cmake --install libajantv2/build
  

• Windows (MSYS2 environment)

    cp libajantv2/build/ajantv2/Release/ajantv2.dll /usr/local/bin/
    cp libajantv2/build/ajantv2/Release/ajantv2.lib /usr/local/lib/
  

  then run the data/scripts/build_aja_lib_win64.sh UltraGrid script to create the AJA wrapper

Then you should be able to configure and compile UltraGrid with AJA support:

./autogen.sh --enable-aja

(--enable-aja is not necessary but ensures that AJA will be either compiled-in or configure script fails)

BitFlow

Following instructions applies currently to Linux only.

You need to have BitFlow SDK. Assuming you installed the SDK into /bitflow, you need also camera file (bfml XML file) for you camera copied to /bitflow/camf. The camera file contains couple of regimes. You need also to set appropriate camera file in configuration file to your grabber file /bitflow/config/<name>. Information about present framegrabbers can be obtained with:/bitflow/src/CIexample -i.

Driver can be compiled from /bitflow/drv. You may also want to copy the compiled bitflow.ko to module tree (directory /lib/modules/$(uname -r)) and run depmod in order the dependencies to be satisfied automatically. You may also needed to run "modprobe bitflow" manually.

In order to bitflow work properly, you need to set paths to (assuming instalation in /bitflow):

export BITFLOW_INSTALL_DIRS=/bitflow\;/bitflow/flash\;/bitlow/camf

UltraGrid needs header files to be present in source directory as bitflow, so you just need to copy them. Libraries should be located somewhere UltraGrid can find them (eg. /usr/local/lib):

cp -r /bitflow/inc <path_with_ug_sources>/bitflow
cp /bitflow/64b/lib/* /usr/local/lib

If all of above is done, you should be able to build and run UltraGrid with bitflow, bitflow support has to be enabled explicitly:

./autogen.sh --enable-bitflow && make
./bin/uv -t bitflow

Bluefish 444

You will need Bluefish 444 SDK for in your system.

Linux

Extract the archive and then execute following command in extracted directory:

cd apis/BlueVelvetC/lin
make install

Then export path to the the SDK directory, eg.:

export BLUE_LATEST_SDK=$HOME/Bluefish_linux_driver_6_0_1_21

After that, UltraGrid configure script should report support for BlueFish cards.

Cineform

First you need to clone Cineform:

git clone https://github.com/gopro/cineform-sdk

Linux & macOS

You may need to install uuid-dev package as a Cineform dependency:

macOS$ brew install ossp-uuid     # or
Ubuntu$ sudo apt install uuid-dev

Then you need to build and install the Cineform library:

cmake -DBUILD_TOOLS=OFF ..
cmake --build . --parallel
sudo cmake --install .

After this, you can compile UltraGrid with

./autogen.sh --enable-cineform && make

Windows

Using either ways below, after that, you'd need to tell UltraGrid configure where to find the built library:

./autogen.sh --enable-cineform --with-cineform=<path_to_CF_src>

Alternativelly, if using MSYS2+pkgconfig, you may also copy the library, headers and pkgconfig-file to a recognized system paths (eg. using /usr/local prefix).

Using GUI

On Windows Cineform needs to be compiled as a dynamic library with MSVC. For this you need to install CMake and Visual Studio (tested on 2017).

The first step is to open CMake select the cineform-sdk as the source and build folders. Then press the Configure button and select Visual Studio 15 2017. After that you need to uncheck the BUILD_STATIC option and press Generate.

You can then press the Open Project button to launch Visual Studio. If you want to build Ultragrid as a 64-bit binary you need to also build Cineform as 64-bit. To do this you need to right-click on CFHDCodecShared in Solution Explorer and select Properties then Configuration Manager -> Active solution platform -> new. Here we select x64 and copy settings from Win32. Then we select Release configuration. Then in Linker -> All options we need to replace /machine:X86 in Additional options with /machine:x64. Finally we can build CFHDCodecShared solution.

This should result in CFHDCodec.lib in cineform-sdk/Release/ and CFHDCodec.dll in cineform-sdk/x64/Release/

After this you can compile Ultragrid with the --enable-cineform option. Keep in mind that you need to have the CFHDCodec.dll in PATH or in the executable directory.

CLI - MSYS2 or cmd/PS

From the MSYS2 environment, the project can be build with following commands. Similarly this commands can be used in a normal Windows command-line shell (Command Prompt or PowerShell) only by substituting path separators.

CMAKE=`/c/Program\ Files\ \(x86\)/Microsoft\ Visual\ Studio/Installer/vswhere.exe -latest -find **\\Bin\\CMake.exe`
$CMAKE -DBUILD_STATIC=false -G 'Visual Studio 16 2019' -A x64 .
$CMAKE --build . --config Release

Conference

For video-conferencing mode you need to have OpenCV installed.

For CUDA-accelerated OpenCV build, follow instructions here:

cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local -D WITH_TBB=ON \
   -D BUILD_NEW_PYTHON_SUPPORT=ON -D WITH_V4L=ON -D INSTALL_C_EXAMPLES=ON -D INSTALL_PYTHON_EXAMPLES=ON \
   -D BUILD_EXAMPLES=ON -D WITH_QT=ON -D WITH_OPENGL=ON -D ENABLE_FAST_MATH=1 -D CUDA_FAST_MATH=1 -D WITH_CUBLAS=1 ..

DELTACAST

Linux and Windows

• download SDK from DELTACAST download center

• extract it to directory of your choice, eg. $HOME/VideoMasterHD

• install libraries:

  for n in $HOME/VideoMasterHD/Library/*; do
      make -C $n/x64 install
  done
  

• install drivers:

  # for HDMI devices and newer SDI devices, or select X400
  make -C $HOME/VideoMasterHD/Drivers/X300/x64
  make -C $HOME/VideoMasterHD/Drivers/X300/x64 install
  

  Note: Drivers for Windows can be freely obtained from here without need of SDK.

• finally, let UltraGrid know where is the SDK, you can do it this way:

  export DELTACAST_DIRECTORY=$HOME/VideoMasterHD
  

• then, you can configure UltraGrid and DELTACAST support should be detected automatically

DKMS

In Linux you may wish to create a DKMS to allow automatical drivers build with new kernels.

OS X

Install VideoMasterHD SDK downloaded from DELTACAST download center. UltraGrid should recognize the framework and add support for DELTACAST automatically.

GPUJPEG

Obtaining CUDA

For GPUJPEG compression you will need to have CUDA-capable NVidia card (a reasonably recent one, GeForce 4XX or better). You will also need NVIDIA drivers and Cuda Toolkit, both can be obtained from NVidia web pages or with distro packages/

Obtaining GPUJPEG library

Easiest way to obtain GPUJPEG for use with UltraGrid is to run a script bootstrap_gpujpeg.sh from within UltraGrid sources:

./bootstrap_gpujpeg.sh [-d|-f|-h|-s|-u]

By default it downloads and compiles GPUJPEG statically and locally so that UltraGrid can find it. Other options for the script can be seen if you enter -h.

Configuring UltraGrid

Issue following command to ensure that GPUJPEG is enabled:

./autogen.sh --enable-gpujpeg

You should verify if GPUJPEG is going to be compiled from the script output. Look for line like this:

Configuration summary:
<--- output omitted -->
GPUJPEG ..................... yes
<--- output omitted -->

If you have supported NVidia Toolkit and have passed its output to the script (if needed) and you still don’t see JPEG support enabled, consider reporting a bug.

Libavcodec

Linux

For standard featured FFMPEG, you can use package from your distribution (including headers, eg. libavcodec-dev in Debian/Ubuntu). If you want to enable NVENC or another optional feature, you will need to build FFMPEG from source.

OS X

Recommended way is to obtain libavcodec from MacPorts:

sudo port install ffmpeg-devel

Or, to have most complete installation, you can better use

sudo port install ffmpeg-devel +universal +gpl2 +gpl3 +nonfree

• adjust PKG_CONFIG_PATH and PKG_CONFIG environment variables, eg. by adding following line to ~/.profile (assuming default MacPorts location):

export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/opt/local/lib/pkgconfig
export PKG_CONFIG=/opt/local/bin/pkg-config

• after these steps, UltraGrid configure script should detect libavcodec and compile support for it.

Windows

FFMPEG

You can use directly a MSYS2 package. If so, you are done, UltraGrid configure script will detect FFMPEG automatically.

Alternatively you can download builds from this page, select Dev and Shared version for Windows 64-bit. The advantage is that this version offers greater deal of encoders, including NVENC- and cuvid-accelerated ones, libdav1d for AV1 etc. Copy directories include and lib from Dev to to appropriate /usr/local directories. From Shared, copy DLL files from bin to path visible to uv.exe binary (that is eg. /usr/local/bin or to a directory where is UltraGrid executable).

From source

See main article.

Build

Then build and install it as usual:

make && sudo make install

PortAudio

General

To use Portaudio, you will need Portaudio library installed inside your system including headers. When recognize with configure script, Portaudio support will be automatically added.

Please note that PortAudio v19 is needed, some Linux distributions still stick with v18 only but they usually provide package for newer version (eg. Ubungu package portaudio19-dev).

Windows

Download PortAudi o, configure it and install (see also here):

cd portaudio
wget https://raw.githubusercontent.com/msys2/MINGW-packages/master/mingw-w64-portaudio/0001-clang-fix.patch
patch -p1 -i 0001-clang-fix.patch 
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .
cmake --install .

Default Windows Portaudio backend is MME but WDM also works. WASAPI looks currently (stable build from 2016) defunct for capture (although it compiles). See also here. DirectSound and ASIO APIs are also available.

Then you can configure and compile UltraGrid as usual. Finally, copy PortAudio dll into location where resides UG binary:

cp /usr/local/bin/libportaudio.dll bin

ASIO

Use these instructions to build PortAudio with ASIO backend. When compiled, the resulting dll can replace the one with different backend. You can also link UltraGrid directly with the dll, in that case (assuming MSYS build environment):

1. copy dll to /usr/local/bin and lib to /usr/local/lib
2. copy contents of include subdirectory to /usr/local/include
3. modify UltraGrid configure.ac not to use pkg-config (or supply appropriate .pc file by yourself)

Configure UltraGrid

To assure PortAudio compilation, run UltraGrid configure script with argument –enable-portaudio:

./configure --enable-portaudio

RTSP client/server

RTSP client (Linux)

On Ubuntu, you need to install libcurl4-dev (or equivalent on other distros).

RTSP server

You will need older version of live555, eg. from https://github.com/xanview/live555/, you will need commit 35c375 (Bump to 2015.08.07). If you install it, you can reconfigure ultragrid with:

--enable-rtsp-server --with-live555=/usr/local

SAGE

Setup SAGE

If you have a working version of SAGE client already present on your computer, you can link it with Ultragrid upon configuration. Otherwise you can download and compile it using the manual below.

Configuring UltraGrid with SAGE suppport

You can configure UltraGrid to use SAGE client library by adding the parameter --with-sage=<path> to the configuration script of ultragrid:

./configure --with-sage=/home/sageuser/sage3.0

Compiling SAGE client

To compile a SAGE client, download it from here and save it to the UltraGrid root directory.

Note: Since UltraGrid has the name pre-set statically, make sure the directory you created is named "sage3.0". The other option is to use --with-sage=<dir>

Enter the directory and compile SAGE library:

cd sage3.0 && make

Running

To be able to use the SAGE display, you need to run from a directory, where is placed SAGE application configuration file. The configuration file must be named “ultragrid.conf”.

Syphon

On OS X, you can compile in support for Syphon by downloading and installing framework (to /Library/Frameworks). UltraGrid should be then configured with following option:

./configure --enable-syphon

SPOUT

For SPOUT you will need SPOUT, ideally from GitHub repo. UltraGrid expects headers to be inside SpoutSDK subdirectory.

Recommended instructions how to build and install SPOUT library for UltraGrid build with MSYS can be found in this UltraGrid GitHub CI script.

NDI

Linux

Obtain the https://ndi.video/for-developers/ndi-sdk/download/ and run the script:

./Install_NDI_SDK_v6_Linux.sh

which creates you directory "NDI SDK for Linux" after agreeing license. Then copy headers to system path:

sudo cp -r NDI\ SDK\ for\ Linux/include/* /usr/local/include/

optionally you can copy libraries as well for a run-time dependency:

cp -a NDI\ SDK\ for\ Linux/lib/x86_64-linux-gnu/lib* /usr/local/lib/

After that, UltraGrid should detect installed NDI.

macOS

You can install the NDI package with GUI installer or by running:

sudo installer -pkg Install_NDI_SDK_v6_Apple.pkg -target /

NDI installes itself usually to "/Library/NDI SDK for Apple/" (may differ in different versions). In order to avoid problems I'd recommend to symlink it to a name without spaces, eg. by replacing them by underscores:

sudo mv "/Library/NDI SDK for Apple" /Library/NDI

Then you need to add headers to search path:

export CPATH=${CPATH:+"$CPATH:"}/Library/NDI/include

UltraGrid then detects NDI automatically.

Windows

Make sure that configure is able to find the library Processing.NDI.Lib.x64 and headers (by default installed to "C:\Program Files\NDI\NDI X SDK"). This is possible by setting environment variables:

NDI_D=$(ls -d /c/Program\ Files/NDI/*SDK | tail -n 1)
export CPATH=${CPATH:+"$CPATH:"}$NDI_D/Include

Note: If the environment variable NDI_SDK_DIR is set, configure will try to add those paths automatically.

Compiling UltraGrid

Once all above is done, based on your preferences, run the configuration script:

cd ultragrid
./autogen.sh           # optional args may follow

Here you can check whether all the features you have selected were detected and are going to be included. If so, compile UltraGrid:

make

If no error has occured, the compilation is complete and UltraGrid is ready to run. If bundling is not needed, you can jump to Running UltraGrid.

Cross-compile (for Windows on Linux)

export CC=/usr/bin/x86_64-w64-mingw32-gcc-posix
export CXX=/usr/bin/x86_64-w64-mingw32-g++-posix
export CPATH=
export LIBRARY_PATH=
export PKG_CONFIG_LIBDIR=
./autogen.sh --host=x86_64-w64-mingw32

Notes:

1. setting CC/CXX explicitly, otherwise Win32 threading model gcc will be used, which disables C++11 thread/mutex
2. CPATH/LIBRARY_PATH is optional to cancel potential incompatible includes/libs from host system
3. PKG_CONFIG_LIBDIR causes host system packages to be ignored

Cross-compile 64-bit ARM macOS

To compile for 64-bit macOS ARM (M1) on x86_64, you can issue this commands:

export ARCH='-arch arm64'
./autogen.sh --host=arm64-apple-macos11

Note: Appropriate Xcode supporting ARM is required (at least version 12).

Bundling

Distributions in macOS, Linux and Windows usually includes adding (non-system) libraries into a bundle (macOS), a running directory (Windows) or a AppImage (Linux). Without that, resulting executable may not be portable because of missing dependencies. For Linux, another option is to use a distribution package, which will, however, not be described here.

Bundling in Linux

Note: further text describes creation of an AppImage. If you do not intend to create that package, you may ignore this part.

First, configure UltraGrid with required configuration. Although not necessary, it is recommended to use plugins:

./autogen.sh --enable-plugins

you may also add Qt GUI:

./autogen.sh --enable-plugins --enable-qt

Then use a script create-appimage.sh to create an AppImage:

./data/scripts/Linux-AppImage/create-appimage.sh

References:

1. https://github.com/AppImage/AppImageKit/wiki/Creating-AppImages
2. https://gitlab.com/probono/platformissues
3. https://github.com/CESNET/UltraGrid/blob/master/data/scripts/Linux-AppImage/create-appimage.sh

Bundling in macOS

On Mac systems, we recommend to create UltraGrid application bundle. UltraGrid itself doesn’t require this, but some drivers (SDL) do. To create a bundle, type

make bundle

You can also use

make bundle-nolib

which doesn’t include libraries in that bundle (in that case the bundle won’t probably run on another Mac).

Note: target bundle command requires dylibbundler (see the prerequisite above) to be installed, bundle-nolib doesn't.

This creates bundle uv.app. To run UltraGrid from bundle via command-line, use this command:

<path_to>/uv.app/Contents/MacOS/uv [params]

Bundling macOS GUI

If you build UltraGrid with GUI, you can use Makefile target gui-bundle (UltraGrid needs to be configured to compile the GUI, see Compile UltraGrid (Source)#QT), which creates an application bundle gui/QT/uv-qt.app:

make gui-bundle

Because this is a normal GUI app, it can be executed normally by clicking in Finder (if moved to Applications), eg.:

mv gui/QT/uv-qt.app /Applications

Furthermore, there exists also a target osx-gui-dmg that creates from the GUI bundle a DMG file.

Note: See also the section GUI if QT was build as a dynamic library (Framework).

Bundling in Windows

For Windows there exists a script get_dll_depends.sh inside source tree that generates dependencies of a executable and prints them on commandline. Please note that it is tailored to MSYS2 environment - it is a BASH script expecting objdump to be present and uses MSYS/cygwin paths. Intended use is something like:

for n in `./get_dll_depends.sh <dir>/uv.exe`; do
    cp "$n" <dir>
done

The above won't work if some path contains spaces. In that case, something more complicated like following will be required ($DIR contains destination directory):

SAVED_IFS=$IFS
IFS="|"; for exe in $DIR/*exe; do for n in `data/scripts/get_dll_depends.sh "$exe" | tr "\n" "|"`; do cp "$n" $DIR; done; done
IFS=$SAVED_IFS

Bundling Windows GUI

Use windeployqt to add QT assets.

GUI

QT

Sources for QT GUI are stored in directory gui/QT. To use it, compile UG with GUI support:

./autogen.sh --enable-qt

and then:

make

The GUI will be created in gui/QT/uv-qt.app.

The GUI itself can be built also alone which is, however, not recommended (preview will be disabled):

gui/QT$ qmake
gui/QT$ make

When started, the GUI tries to find UltraGrid (uv) executable in system path or application bundle (macOS). Custom location can be provided with --with-uv parameter.

macOS GUI

See QT deployment

You have 2 options from the perspective of distribution the bundle - static and dynamic linking. Recommended way is the one in the second paragraph (using aqt tool) of "Dynamic linking".

Dynamic Linking

You may be able to use Qt from Homebrew or MacPorts. Provided that there is a program macdeployqt (distributed with QT) and dylibbundler present, UltraGrid should handle the deployment automatically if make called is called with a gui_bundle target.

However, please note that the Homebrew macdeployqt is sometimes broken and does not produce correct bundle, currently (2023-11-02) on ARM64; also some manual intervention for x64 in Makefile is needed. In case of problems, it is recommended to install Qt with aqt tool (or to use install-qt-action in CI).

Static Linking

To use static QT, it is needed to be compiled from source (see Building static QT):

wget https://download.qt.io/archive/qt/5.15/5.15.2/single/qt-everywhere-src-5.15.2.tar.xz # or use a newer version
tar xJf qt-everywhere-src-*.tar.xz
cd qt-everywhere-src-*/
./configure -static -release -nomake examples -opensource -confirm-license -opengl
make -j 6
sudo make install

UltraGrid needs to add option --enable-qt-static in order to use correct link flags (otherwise eg. libqtpcre2 may be omitted):

./configure --enable-qt --enable-qt-static

Linux GUI

For portable application it is mostly recommended static Qt build (eg. for AppImage) although linuxdeployqt also exists. The procedure is very similar to macOS so see the instructions above. Recommended configure options for Qt are:

./configure -static -release -nomake examples -opensource -confirm-license -opengl -no-fontconfig