diff --git a/dev-docs/build.md b/dev-docs/build.md index 67282ea5d..949382dd0 100644 --- a/dev-docs/build.md +++ b/dev-docs/build.md @@ -1,165 +1,157 @@ -# Building +# Building Kdenlive -*This page describes how to build Kdenlive with its dependencies.* +## Base procedure +Kdenlive usually requires the latest version of MLT, in which go several API updates, bufixes and optimizations. -## Building Kdenlive +### Get the build dependencies -Building is done in 3 steps: +You can use your distribution packages information (if not too old) to easily get a complete build environment: -1. Install the development dependencies and remove existing installations -2. Clone the repositories -3. Build and install the projects - - -### Get the development dependencies +```bash +# Debian/Ubuntu -- Enable deb-src entries /etc/apt/sources beforehand +sudo apt build-dep mlt kdenlive +# Fedora/CentOS -- Install builddep beforehand +dnf builddep mlt kdenlive +# OpenSUSE +zypper source-install --build-deps-only mlt kdenlive +``` -Kdenlive usually requires the latest versions of MLT. MLT depends on frei0r, -and on Ubuntu frei0r needs to be built as well as there is no -`frei0r-plugins-dev` package. +### Clone the repositories -First, install the requirements. For Ubuntu 20.04 and 19.10, the required packages are: +In your development directory, run: ```bash -# Basic packages -sudo apt install git build-essential cmake cmake-extras pkg-config +git clone https://github.com/mltframework/mlt.git +git clone https://invent.kde.org/multimedia/kdenlive.git +``` -# frei0r -sudo apt install libopencv-dev libcairo-dev libgavl-dev +### Build and install the projects -# MLT -sudo apt install libavformat-dev libsdl2-dev libswscale-dev libavfilter-dev \ - libavdevice-dev libgdk-pixbuf2.0-dev libpango1.0-dev libexif-dev \ - libfftw3-dev libebur128-dev librubberband-dev librtaudio-dev \ - libvidstab-dev libxml2-dev qt5-default libqt5svg5-dev +You should decide where you want to install your builds: -# Kdenlive -sudo apt install libkf5archive-dev libkf5bookmarks-dev libkf5coreaddons-dev \ - libkf5config-dev libkf5configwidgets-dev libkf5dbusaddons-dev \ - libkf5kio-dev libkf5widgetsaddons-dev libkf5notifyconfig-dev \ - libkf5newstuff-dev libkf5xmlgui-dev libkf5declarative-dev \ - libkf5notifications-dev libkf5guiaddons-dev libkf5textwidgets-dev \ - libkf5purpose-dev libkf5iconthemes-dev kdoctools-dev libkf5crash-dev \ - libkf5filemetadata-dev kio kinit qtdeclarative5-dev libqt5svg5-dev \ - qml-module-qtquick-controls qtmultimedia5-dev qtquickcontrols2-5-dev \ - appstream gettext libv4l-dev libqt5webkit5-dev librttr-dev breeze ffmpeg -``` +- by default it goes to `/usr/local` (good option if you are admin of the machine, normally programs there are automatically detected); +- you may use `$HOME/.local` user-writable directory (good option if you don't want to play with admin rights, programs there are also usually found) +- you may want to override the distribution files in `/usr` (then you have to remove MLT & Kdenlive binary & data packages first) +- you can pick any destination you like (eg in `/opt` or anywhere in `$HOME`, then you will have to set several environment variables for programs, libs and data to be found) + +Let's define that destination as `INSTALL_PREFIX` variable; also you can set `JOBS` variable to the number of threads your CPU can offer for builds. -Most development packages will already be installed with the following command: +And build the dependencies (MLT) before the project (Kdenlive): ```bash -# Ubuntu -# Enable deb-src entries /etc/apt/sources beforehand! -sudo apt-get build-dep mlt kdenlive +INSTALL_PREFIX=$HOME/.local # or any other choice +JOBS=4 -# OpenSuse -zypper build-dep +# MLT +cd mlt +./configure --enable-gpl --enable-gpl3 --prefix=/home/soft/kdenlive +make -j$JOBS +make install +# 'sudo make install' if INSTALL_PREFIX is not user-writable -# Fedora -# Install builddep beforehand -dnf builddep +# Kdenlive +cd ../kdenlive +mkdir build +cd build +cmake .. -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX +make -j$JOBS +make install +# 'sudo make install' if INSTALL_PREFIX is not user-writable ``` -**Important:** If you are going to install the projects to your `/usr` after -building them, make sure to remove existing packages of Kdenlive, MLT, and -frei0r beforehand! +Note that `make install` is required for Kdenlive, otherwise the effects will not be installed and cannot be used. -```bash -apt purge kdenlive frei0r-plugins libmlt++3 -``` +### Run Kdenlive -### Clone frei0r, MLT, and Kdenlive +If you didn't build in a system path in which all libs and data are automatically found, you will need to set environment variables to point to them. +This is done by the auto-generated script in `kdenlive/build` that must be sourced (to keep variables set in current shell, unlike just executing the script): ```bash -git clone https://github.com/dyne/frei0r.git -git clone https://github.com/mltframework/mlt.git -git clone https://invent.kde.org/kde/kdenlive.git +. prefix.sh +kdenlive ``` +## Various development tricks -### Build it! +### Debugging -Now you can build and install the projects. As Kdenlive depends on MLT which -depends on frei0r, build and install them in reverse order. +Having debug symbols helps getting much more useful information from crash logs or analyzers outputs; this is enabled at configure stage. +- in MLT, append `--enable-debug` to `./configure` line +- in Kdenlive, append `-DCMAKE_BUILD_TYPE=Debug` to `cmake` line -Note that `make install` is required for Kdenlive, otherwise the effects will -not be installed and cannot be used. +### Running tests -For frei0r, MLT, and Kdenlive (in that order), run the following steps -inside their directory to build, compile, and install it. +Kdenlive test coverage is focused mostly on timeline model code (extending tests to more parts is highly desired). To run those tests, append to `cmake` line: +`-DBUILD_TESTING=ON` -```bash -# Create a build directory – the build files remain in here -mkdir build -cd build +### Fuzzer -# Check dependencies and configure the build process -cmake .. -DCMAKE_INSTALL_PREFIX=/usr +Kdenlive embeds a fuzzing engine that can detect crashes and auto-generate tests. This can be activated in `cmake` line with: +`-DBUILD_FUZZING=ON` -# Compile -make +### Speeding up compilations -# Install the compiled files -sudo make install -``` +Ninja build systems, compared to make, seems faster and better detecting which files are necessary to rebuild. You can enable it appending `-GNinja` to `cmake` line +CCache also helps: `-DCMAKE_CXX_COMPILER_LAUNCHER=ccache` -#### Building on Ubuntu 20.04 +### Analyzers -Ubuntu 20.04 provides OpenCV 4.2 which is not supported by the frei0r plugins yet. Run CMake with +You can configure Kdenlive to embed tooling for runtime analysis, for example appending to cmake line: +`-DCMAKE_CXX_COMPILER=/usr/bin/clang++ -DECM_ENABLE_SANITIZERS='address'` -```bash -cmake .. -DWITHOUT_OPENCV=true -DCMAKE_INSTALL_PREFIX=/usr -``` +This one will report in terminal all memory handling errors found during execution. +### Building OpenCV tracking module -### Install Kdenlive to a local path - -As alternative to installing Kdenlive system wide in `/usr`, it can also be -installed in a custom directory, for example `~/.local`, in order to still have -a global sytem version for comparison. In that case, the `prefix.sh` script in -the build directory has to be executed prior to running Kdenlive from the -installation directory; it sets some environment variables. +MLT/Kdenlive tracking effect relies on a "contrib" a OpenCV module that is not shipped by distributions. +We build it in our AppImage but you may want it on your system (note OpenCV deserves its reputation of being difficult to build!). ```bash -# Configure with a different install directory -cmake .. -DCMAKE_INSTALL_PREFIX=~/.local +wget https://github.com/opencv/opencv/archive/4.3.0.tar.gz -O opencv-4.3.0.tar.gz +wget https://github.com/opencv/opencv_contrib/archive/4.3.0.tar.gz -O opencv_contrib-4.3.0.tar.gz +tar xaf opencv-4.3.0.tar.gz +tar xaf opencv_contrib-4.3.0.tar.gz +cd opencv-4.3.0 +mkdir build +cd build +cmake .. -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX \ + -DOPENCV_GENERATE_PKGCONFIG=ON -DBUILD_LIST=tracking -DOPENCV_BUILD_3RDPARTY_LIBS=OFF +``` -# Compile and install (sudo is not required for ~/.local) -make -make install +### Building frei0r -# Load environment variables -chmod u+x prefix.sh -./prefix.sh +You may be interested in building latest frei0r effects library. So get dependencies, clone repository, and build-install: -# Run Kdenlive -~/.local/bin/kdenlive +```bash +sudo apt build-dep frei0r +git clone https://github.com/dyne/frei0r.git +cd frei0r +mkdir build +cd build +cmake .. -DWITHOUT_OPENCV=true -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX ``` +Note: as of 20.04, frei0r doesn't support recent OpenCV (and effects using it seemed not very stable) ### Building in Docker -For checking if the dependencies are still up-to-date, it is possible to run -all the above commands inside a Docker container with a fresh Ubuntu, for -example. - -Note that Kdenlive cannot be run from inside the Docker container as it is a -GUI application and Docker is console-only. +It is possible to run the above commands inside a container, with a fresh Ubuntu for example. +Note that Kdenlive cannot be easily run from inside the Docker container as it is a GUI application. ```bash # Spin up a Docker container # The --rm flag removes the container after it is stopped. -docker run -it --rm ubuntu:19.10 +docker run -it --rm ubuntu:20.04 # Now install the dependencies etc. # Note that you are root in the container, and sudo neither exists nor works. apt install … # When you are done, exit exit ``` - ## Translating Kdenlive TODO