Skip to content

Mac Build Instructions

Jump to bottom
Jonathan Thomas edited this page Jan 30, 2021 · 17 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.

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

    • http://www.ffmpeg.org/ (Library)
    • This library is 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.

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

  • OpenShot Audio Library (libopenshot-audio)

  • Qt 5 (libqt5)

    • http://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...

  • CMake (cmake)

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

  • SWIG (swig)

    • http://www.swig.org/ (Executable)
    • This executable is 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)

    • http://www.python.org/ (Executable and Library)
    • This library is 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)

  • UnitTest++ (libunittest++)

    • https://github.com/unittest-cpp/ (Library)
    • This library is used to execute unit tests for libopenshot. It contains many macros used to keep our unit testing code very clean and simple.

  • ZeroMQ (libzmq)

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

  • OpenMP (-fopenmp)

    • http://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.

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 ../

  • MAGICKCORE_HDRI_ENABLE (default 0)
  • MAGICKCORE_QUANTUM_DEPTH (default 0)
  • OPENSHOT_IMAGEMAGICK_COMPATIBILITY (default 0)
  • DISABLE_TESTS (default 0)
  • CMAKE_PREFIX_PATH (/location/to/missing/library/)
  • PYTHON_INCLUDE_DIR (/location/to/python/include/)
  • PYTHON_LIBRARY (/location/to/python/lib.a)
  • PYTHON_FRAMEWORKS (/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/)
  • CMAKE_CXX_COMPILER (/location/to/mingw/g++)
  • CMAKE_C_COMPILER (/location/to/mingw/gcc)

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.

  • build/

    • This folder needs to be manually created, and is used by cmake to store the temporary build files, such as makefiles, as well as the final binaries (library and test executables).

  • cmake/

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

  • doc/

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

  • include/

    • This folder contains all headers (*.h) used by libopenshot.

  • src/

    • This folder contains all source code (*.cpp) used by libopenshot.

  • tests/

    • This folder contains all unit test code. Each class has it’s own test file (*.cpp), and uses UnitTest++ macros to keep the test code simple and manageable.

  • thirdparty/

    • This folder contains code not written by the OpenShot team. For example, jsoncpp, an open-source JSON parser.

Install Dependencies

In order to actually compile libopenshot and libopenshot-audio, we need to install some dependencies on your system. Most packages needed by libopenshot can be installed easily with Homebrew. However, first install Xcode with the following options ("UNIX Development", "System Tools", "Command Line Tools", or "Command Line Support"). Be sure to refresh your list of Homebrew packages with the “brew update” command.

NOTE: Homebrew seems to work much better for most users (compared to MacPorts), so I am going to focus on brew for this guide.

Install the following packages using the Homebrew package installer (http://brew.sh/). Pay close attention to any warnings or errors during these brew installs. NOTE: You might have some conflicting libraries in your /usr/local/ folders, so follow the directions from brew if these are detected.

# Download packages using Homebrew
$ brew install ffmpeg librsvg swig doxygen unittest-cpp qt5 cmake zeromq libomp python@3.7 librsvg mktorrent

# Download ZMQ C++ header file manually
$ curl https://raw.githubusercontent.com/zeromq/cppzmq/master/zmq.hpp --output /usr/local/include/zmq.hpp

Mac Build Instructions (libopenshot-audio)

Since libopenshot-audio is not available in a Homebrew or MacPorts package, we need to go through a few additional steps to manually build and install it. Launch a terminal and enter:

$ cd [libopenshot-audio repo folder]
$ mkdir build
$ cd build
$ cmake -d -G "Unix Makefiles" -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -DCMAKE_EXE_LINKER_FLAGS="-stdlib=libc++" -DCMAKE_SHARED_LINKER_FLAGS="-stdlib=libc++" -D"CMAKE_BUILD_TYPE:STRING=Release" ../
$ make
$ make install
$ ./src/openshot-audio-test-sound  (This should play a test sound)

Mac Build Instructions (libopenshot)

Run the following commands to build libopenshot:

Note: These path names are out of date and should be updated to match currently-available versions of the dependencies.

$ cd [libopenshot repo folder]
$ mkdir build
$ cd build
$ cmake -d -G "Unix Makefiles" -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -DCMAKE_PREFIX_PATH=/usr/local/opt/qt/ -DCMAKE_EXE_LINKER_FLAGS="-stdlib=libc++" -DCMAKE_SHARED_LINKER_FLAGS="-stdlib=libc++" -D"CMAKE_INSTALL_RPATH_USE_LINK_PATH=1" -D"ENABLE_RUBY=0" -D"CMAKE_BUILD_TYPE:STRING=Release" ../
$ make

If you are missing any dependencies for libopenshot, you will receive error messages at this point. Just install the missing dependencies, and run the above commands again. Repeat until no error messages are displayed and the build process completes.

Also, if you are having trouble building, please see the CMake Flags section above, as it might provide a solution for finding a missing folder path, missing Python 3 library, etc...

To run all unit tests (and verify everything is working correctly), launch a terminal, and enter:

make test

To auto-generate the documentation for libopenshot, launch a terminal, and enter:

make 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/. Once libopenshot has been successfully built, we need to install it (i.e. copy it to the correct folder, so other libraries can find it).

make install

This should copy the binary files to /usr/local/lib/, and the header files to /usr/local/include/openshot/... This is where other projects will look for the libopenshot files when building. Python 3 bindings are also installed at this point. let's verify the python bindings work:

python3 (or python)
>>> import openshot

If no errors are displayed, you 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!

Mac Build Instructions (OPTIONAL openshot-qt)

WORK IN PROGRESS

If you also plan on building the openshot-qt repo (our Qt5-based user interface), it requires a few deviations from the above plans. Primarily, we need a recent version of Qt5 and PyQt5 (plus QtWebEngine module). And since Homebrew does not support QtWebEngine with their version of PyQt, we must build it ourselves.

The following versions are used on the official Mac build server (newer versions will also work, but the commands below might not work without modifications).

  • Qt: 5.15.0
  • Sip: 4.19.23
  • PyQt: 5.15.1.dev2007111314
  • PyQtWebEngine:5.15.1.dev2006110847
$ mkdir /usr/local/qt5.15.x/
$ cd /usr/local/qt5.15.x/
# Extract the Qt, Sip, PyQt, and PyQtWebEngine folders to this location.

# Update Mac Deployment Target
# sudo nano qt5.15/clang_64/mkspecs/macx-clang/qmake.conf
# sudo nano qt5.15/clang_64/mkspecs/macx-g++/qmake.conf
QMAKE_MACOSX_DEPLOYMENT_TARGET = 10.13
QMAKE_MAC_SDK = macosx10.13
load(qt_config)

# Compile SIP with PyQt5 support (and specific deployment target)
# SIP 4.19.23 required
python3 configure.py --deployment-target 10.13 -p macx-g++ --sip-module PyQt5.sip
make
make install

# Compile PyQt5 (with custom SIP and custom Qt install locations)
QMAKESPEC="macx-g++" ARCHFLAGS="-arch x86_64" MACOSX_DEPLOYMENT_TARGET=10.13 python3 configure.py -q /usr/local/qt5.15.x/qt5.15/5.15.0/clang_64/bin/qmake --disable "QtWebKitWidgets QtWebKit QtPositioning QtTest EngionIo" --sip "/usr/local/Cellar/python@3.7/3.7.9_2/Frameworks/Python.framework/Versions/3.7/bin/sip"

make 
make install

# Compile PyQtWebEngine (separate download)
QMAKESPEC="macx-g++" ARCHFLAGS="-arch x86_64" MACOSX_DEPLOYMENT_TARGET=10.13 python3 configure.py -q /usr/local/qt5.15.x/qt5.15/5.15.0/clang_64/bin/qmake --sip "/usr/local/Cellar/python@3.7/3.7.9_2/Frameworks/Python.framework/Versions/3.7/bin/sip"

# Remove port_v2/__init__.py
rm /usr/local/lib/python3.7/site-packages/PyQt5/uic/port_v2/__init__.py

# Fix RPath for installed PyQt5 libraries
# by creating symlinks inside the /site-packages/PyQt5/lib/ folder
cd [openshot-qt repo folder]
python3 installer/fix_qt5_rpath.py

Next, we need to install opencv from source.

git clone https://github.com/opencv/opencv
cd opencv/
git checkout '4.3.0'
cd ..
git clone https://github.com/opencv/opencv_contrib
cd opencv_contrib/
git checkout '4.3.0'
cd ..
cd opencv
mkdir build
cd build/   # NOTE: If re-building DELETE THE CONTENTS OF THIS FOLDER

# Install Python build server dependencies
python3 -m pip install numpy zmq tinys3 github3.py cx_Freeze

# Install opencv
cmake -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON -DCMAKE_CXX_FLAGS=-I\ /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/usr/include -DCMAKE_PREFIX_PATH=/usr/local/qt5.15.X/qt5.15/5.15.0/clang_64/ -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local -D INSTALL_C_EXAMPLES=ON -D INSTALL_PYTHON_EXAMPLES=ON -D WITH_TBB=OFF -D WITH_V4L=ON -D OPENCV_PYTHON3_INSTALL_PATH=/usr/local/lib/python3.7/site-packages/ -D WITH_QT=ON -D WITH_CUDA=ON -D WITH_OPENGL=ON -D -DENABLE_PRECOMPILED_HEADERS=OFF -DBUILD_opencv_text=OFF OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules -D OPENCV_GENERATE_PKGCONFIG=ON -D BUILD_EXAMPLES=ON -D"CMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk" -D"CMAKE_OSX_DEPLOYMENT_TARGET=10.9" ..

# New Improved
cmake -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON -DCMAKE_CXX_FLAGS=-I\ /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/usr/include -DCMAKE_PREFIX_PATH=/usr/local/qt5.15.X/qt5.15/5.15.0/clang_64/ -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local -D INSTALL_C_EXAMPLES=ON -D INSTALL_PYTHON_EXAMPLES=ON -D WITH_TBB=OFF -D WITH_V4L=ON -D OPENCV_PYTHON3_INSTALL_PATH=/usr/local/lib/python3.7/site-packages/ -D WITH_QT=ON -D WITH_CUDA=ON -D WITH_OPENGL=ON -D  OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules -D OPENCV_GENERATE_PKGCONFIG=ON -DENABLE_PRECOMPILED_HEADERS=OFF -DBUILD_opencv_text=OFF -D"CMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk" -D"CMAKE_OSX_DEPLOYMENT_TARGET=10.9" ..

# Verify OpenCV modules to be built...
# Sometimes I had to run the cmake command twice for 
# all the modules to show up.
--   OpenCV modules:
--     To be built:                 aruco bgsegm bioinspired calib3d ccalib core cvv datasets dnn dnn_objdetect dnn_superres dpm face features2d flann freetype fuzzy gapi hfs highgui img_hash imgcodecs imgproc intensity_transform line_descriptor ml objdetect optflow phase_unwrapping photo plot python2 python3 quality rapid reg rgbd saliency shape stereo stitching structured_light superres surface_matching tracking ts video videoio videostab xfeatures2d ximgproc xobjdetect xphoto
--     Disabled:                    text world

make -j9
make install

# Install custom version of ffmpeg (if you are attempting to package and distribute a Mac version of OpenShot)
# libavdevice has a dependency on tesseract, which depends on a conflicting libgif.dylib file which 
# makes packaging impossible
brew uninstall ffmpeg
brew edit ffmpeg        # remove lines related to tesseract
brew install ffmpeg -s  # install ffmpeg from source (with no tesseract dependency)

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