Skip to content

Linux Build Instructions

Jump to bottom
Frank Dana edited this page May 26, 2022 · 16 revisions

Getting Started

The best way to get started with libopenshot, is to learn about our build system, obtain all the source code, install a development IDE and tools, and better understand our dependencies. So, please read through the following sections, and follow the instructions. And keep in mind, that your computer is likely different than the one used when writing these instructions. Your file paths and versions of applications might be slightly different, so keep an eye out for subtle file path differences in the commands you type.

Build Tools

CMake is the backbone of our build system. It is a cross-platform build system, which checks for dependencies, locates header files and libraries, generates makefiles, and supports the cross-platform compiling of libopenshot and libopenshot-audio. CMake uses an out-of-source build concept, where all temporary build files, such as makefiles, object files, and even the final binaries, are created outside of the source code folder, inside a /build/ sub-folder. This prevents the build process from cluttering up the source code. These instructions have only been tested with the GNU compiler (including MSYS2/MinGW for Windows).

Dependencies

The following libraries are required to build libopenshot. Instructions on how to install these dependencies vary for each operating system. Libraries and Executables have been labeled in the list below to help distinguish between them.

OpenShot Audio Library (libopenshot-audio)

CMake (cmake)

  • https://www.cmake.org/ (Executable)
  • Used to automate the generation of Makefiles, check for dependencies, and is the backbone of libopenshot’s cross-platform build process.

FFmpeg (libavformat, libavcodec, libavutil, libavdevice, libavresample, libswscale)

  • https://www.ffmpeg.org/ (Library)
  • Used to decode and encode video, audio, and image files. It is also used to obtain information about media files, such as frame rate, sample rate, aspect ratio, and other common attributes.

Qt 5 (libqt5)

  • https://www.qt.io/qt5/ (Library)
  • Qt5 is used to display video, store image data, composite images, apply image effects, and many other utility functions, such as file system manipulation, high resolution timers, etc...

ZeroMQ (libzmq)

  • https://zeromq.org/ (Library)
  • Used to communicate between libopenshot and other applications (publisher / subscriber). Primarily used to send debug data from libopenshot.

OpenCV (libopencv)

  • https://opencv.org/ (Library)
  • Open source computer vision and machine learning software library. Used to add optional intelligent effects (Stabilization, Tracking, and Object Detection). Also requires Protocol Buffers.

Protocol Buffers (protobuf)

  • https://developers.google.com/protocol-buffers (Library+Executable)
  • Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data. Used to manage the large data streams produced by OpenCV-based intelligent effects.
  • Required only if OpenCV is enabled, otherwise not used.

Babl (libbabl)

  • https://gegl.org/babl/ (Library)
  • Colorspace conversion library. Enables advanced blending modes in the ChromaKey effect.

OpenMP (-fopenmp)

  • https://openmp.org/wp/ (Compiler Flag)
  • If your compiler supports this flag (GCC, Clang, and most other compilers), it provides libopenshot with easy methods of using parallel programming techniques to improve performance and take advantage of multi-core processors.

SWIG (swig)

  • https://www.swig.org/ (Executable)
  • Used to generate the Python and Ruby bindings for libopenshot. It is a simple and powerful wrapper for C++ libraries, and supports many languages.

Python 3 (libpython)

  • https://www.python.org/ (Executable and Library)
  • Used by SWIG to create the Python (version 3+) bindings for libopenshot. This is also the official language used by OpenShot Video Editor (a graphical interface to libopenshot).

Doxygen (doxygen)

ImageMagick++ (libMagick++, libMagickWand, libMagickCore)

Catch2

CMake Flags (Optional)

There are many different build flags that can be passed to cmake to adjust how libopenshot is compiled. Some of these flags might be required when compiling on certain OSes, just depending on how your build environment is setup. To add a build flag, follow this general syntax: cmake -DMAGICKCORE_HDRI_ENABLE=1 -DENABLE_TESTS=1 ../

If you want to change what dependencies are used in the build:

  • ENABLE_TESTS=0 (default 1)
  • ENABLE_PYTHON=0 (default: autodetect)
  • ENABLE_RUBY=0 (default: autodetect)

If you want to change how CMake builds libopenshot:

  • CMAKE_CXX_COMPILER (example: /msys64/mingw64/usr/bin/g++)
  • CMAKE_C_COMPILER (example: /msys64/mingw64/usr/bin/gcc)
  • CMAKE_PREFIX_PATH (example: /opt/ffmpeg/)
  • PYTHON_INCLUDE_DIR (example: /usr/local/include/python3.8/)
  • PYTHON_LIBRARY (example: /usr/local/lib64/libpython3.8.so)
  • PYTHON_FRAMEWORKS (example: /usr/local/Cellar/python3/3.8.5/Frameworks/Python.framework/)

If you're using an ImageMagick build with HDRI enabled, or a quantum depth other than 16:

  • MAGICKCORE_HDRI_ENABLE (default: 0)
  • MAGICKCORE_QUANTUM_DEPTH (default: 16)

Obtaining Source Code

The first step in installing libopenshot is to obtain the most recent source code. The source code is available on GitHub. Use the following command to obtain the latest libopenshot source code.

git clone https://github.com/OpenShot/libopenshot.git
git clone https://github.com/OpenShot/libopenshot-audio.git

Folder Structure (libopenshot)

The source code is divided up into the following folders.

bindings/

  • SWIG definition files for both the Ruby and Python language bindings, used to build the shared library extensions to interface with those languages.

cmake/

  • Custom modules not included by default in cmake, used to find dependency libraries and headers and determine if these libraries are installed.

doc/

  • Documentation and related files, such as logos and images required by the doxygen auto-generated documentation.

examples/

  • Sample code using the library (including the source to openshot-player), as well as test media files used by both the unit tests and the example code.

src/

  • All source code (*.cpp) and headers (*.h) for libopenshot.

tests/

  • Unit test code. Tests are organized by class, so for example the unit tests for src/Frame.cpp are in tests/Frame.cpp. (Not all classes have tests.)

thirdparty/

  • Bundled source code not written by the OpenShot team. For example, jsoncpp, an open-source JSON parser, is included here for use on systems where it is not available. (A system install will take priority if found.)

Install Dependencies

In order to actually compile libopenshot, we need to install some dependencies on your system. The easiest way to accomplish this is with our Daily PPA. A PPA is an unofficial Ubuntu repository, which has our software packages available to download and install.

sudo add-apt-repository ppa:openshot.developers/libopenshot-daily
sudo apt-get update
sudo apt-get install \
cmake \
pkg-config \
libopenshot-audio-dev \
libx11-dev \
libfreetype6-dev \
libasound2-dev \
libavcodec-dev \
libavformat-dev \
libavutil-dev \
libswresample-dev \
libswscale-dev \
libpostproc-dev \
libfdk-aac-dev \
libjsoncpp-dev \
libzmq3-dev \
qtbase5-dev \
libqt5svg5-dev \
libbabl-dev \
libopencv-dev \
libprotobuf-dev \
protobuf-compiler \
python3-dev \
swig \
libmagick++-dev

The last item, libmagick++-dev, is completely optional. Libopenshot will build fine without it. The two items before that, swig and python3-dev, are only required if you need to build libopenshot's Python bindings. If not, you can skip them and add -DENABLE_PYTHON=0 to the CMake command line.

If you're building the library for use with OpenShot then you will need both SWIG and the Python development package. There are also a few more things you should install — but none of these are required if you're only building libopenshot itself, for use from your own C++ or Python code.

sudo apt-get install \
openshot-qt \
python3-zmq \
python3-pyqt5.qtwebengine

If you want to build and run the unit tests, you'll need the Catch2 framework.

  • Ubuntu 22.04 — Catch2 is in the standard repos. Run: 
    sudo apt install catch2
  • Ubuntu 20.04 (and earlier) ­— Only Catch version 1 is officially packaged. You'll need to manually install a build of Catch2: 
    wget https://launchpad.net/ubuntu/+archive/primary/+files/catch2_2.13.0-1_all.deb
sudo dpkg -i catch2_2.13.0-1_all.deb

Linux Build Instructions (libopenshot-audio)

To compile libopenshot-audio, we need to go through a few additional steps to manually build and install it. Launch a terminal to run the build commands. If you're using a recent CMake (3.13+), you can run all of the build steps through it. This tends to be easier, as it will automatically select the correct make and other tools.

Except for the initial cd command, feel free to copy/paste these commands to a terminal window. The shell will ignore the comment lines.

cd /path/to/cloned/libopenshot-audio

# Tell CMake to examine the source tree in the current directory (./)
# and write a configuration for it in a build subdirectory (build/)
cmake -B build -S .

# This has cmake compile all of the default build targets in build/
cmake --build build

# This should play a test sound
./build/src/openshot-audio-demo

# This tells CMake to install everything that was compiled in build/
cmake --install build

The last command will install the library, headers, and other files to /usr/local/ by default, and libopenshot will find them there during its own build. If you install to some other location, you'll need to tell the next steps where to find your library. For example

# Install to an /opt subdirectory
cmake --install build --prefix /opt/libopenshot-audio

# When configuring libopenshot in the next section, give it that location:
cmake -B build -S . -DOpenShotAudio_ROOT=/opt/libopenshot-audio

Linux Build Instructions (libopenshot)

If you manually install Qt 5, you might need to specify that location as well, for CMake to find it. (Make sure you point it to the directory containing bin, lib, etc. directories. One level higher or lower, and it won't detect your Qt install. Then either libopenshot will be linked with your system /usr/lib/.../qt5, or the build will fail.)

cmake -B build -S . -DCMAKE_PREFIX_PATH=$HOME/Qt/5.15.0/gcc_64/

Run the following commands to compile libopenshot:

cd /path/to/cloned/libopenshot

# Just like before, configure...
cmake -B build -S .

# Build...
cmake --build build

# Test...
cmake --build build --target test

If you are missing any dependencies for libopenshot, either cmake command might result in an error message, which hopefully will give an indication of what's missing. Just install the packages that provide the missing components. (In particular, make sure you have the necessary -dev or -devel package, which contains the build components necessary to compile other software with the library or tool. On a Debian distro, libavcodec58 will let you run software that uses FFmpeg, but you need libavcodec-dev to compile software that uses it. Similarly, you need ffmpeg-devel when using RPMFusion on Fedora/CentOS, not just ffmpeg-libs.)

When you have the problem corrected, run the build commands again. Repeat until no error messages are displayed, and the build process completes.

API documentation

To produce documentation for libopenshot (requires Doxygen and graphviz installed), after building and testing you can generate the API documentation

cmake --build build --target doc

This will use doxygen to generate a folder of HTML files, with all classes and methods documented. The folder is located at build/doc/html/.

Before installing everything, if you built the Python bindings you can verify that they work correctly right from the build dir. The build tree shared library components are linked directly with each other, so it's easy to run tests there. Once they've been installed, if any of the dependencies you built with was in a non-default location you'll need to make sure that the installed libopenshot can still find everything.

For now, run the following command with your system's default Python 3 interpreter:

PYTHONPATH=/path/to/your/libopenshot/build/bindings/python python3
>>> import openshot
>>> print(openshot.Version)
0.2.5

If the output matches the version of libopenshot you just built and no errors are displayed, you're ready to install the libopenshot components.

cmake --install build

By default this will copy the binary files to /usr/local/lib/, and the header files to /usr/local/include/libopenshot/. This is where other projects will look for the libopenshot files when building. If you need to use a different install path, you can set it with CMake, for example:

cmake --install build --prefix /opt/libopenshot

If everything goes as planned, you will now have successfully compiled and installed libopenshot on your system. Congratulations and be sure to read our wiki on Becoming an OpenShot Developer! Welcome to the OpenShot developer community! We look forward to meeting you!

Want to make some OpenShot friends and join our open-source team? Please send me an email (hello@openshot.org) and introduce yourself! All volunteers are welcome, regardless of skills and/or skill level. Let's build something amazing!

Clone this wiki locally