OpenShot Library | libopenshot  0.2.8
/home/gitlab-runner/builds/d0022447/0/OpenShot/libopenshot/doc/INSTALL-LINUX.md
Go to the documentation of this file.
1 <!--
2 © OpenShot Studios, LLC
3 
4 SPDX-License-Identifier: LGPL-3.0-or-later
5 -->
6 
7 # Building libopenshot for Linux
8 
9 ## Getting Started
10 
11 The best way to get started with libopenshot, is to learn about our build system, obtain all the source code,
12 install a development IDE and tools, and better understand our dependencies. So, please read through the
13 following sections, and follow the instructions. And keep in mind, that your computer is likely different
14 than the one used when writing these instructions. Your file paths and versions of applications might be
15 slightly different, so keep an eye out for subtle file path differences in the commands you type.
16 
17 ## Build Tools
18 
19 CMake is the backbone of our build system. It is a cross-platform build system, which checks for
20 dependencies, locates header files and libraries, generates makefiles, and supports the cross-platform
21 compiling of libopenshot and libopenshot-audio. CMake uses an out-of-source build concept, where
22 all temporary build files, such as makefiles, object files, and even the final binaries, are created
23 outside of the source code folder, inside a /build/ sub-folder. This prevents the build process
24 from cluttering up the source code. These instructions have only been tested with the GNU compiler
25 (including MSYS2/MinGW for Windows).
26 
27 ## Dependencies
28 
29 The following libraries are required to build libopenshot. Instructions on how to install these
30 dependencies vary for each operating system. Libraries and Executables have been labeled in the
31 list below to help distinguish between them.
32 
33 ### FFmpeg (libavformat, libavcodec, libavutil, libavdevice, libavresample, libswscale)
34  * http://www.ffmpeg.org/ `(Library)`
35  * 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.
36 
37 ### ImageMagick++ (libMagick++, libMagickWand, libMagickCore)
38  * http://www.imagemagick.org/script/magick++.php `(Library)`
39  * This library is **optional**, and used to decode and encode images.
40 
41 ### OpenShot Audio Library (libopenshot-audio)
42  * https://github.com/OpenShot/libopenshot-audio/ `(Library)`
43  * This library is used to mix, resample, host plug-ins, and play audio. It is based on the JUCE project, which is an outstanding audio library used by many different applications
44 
45 ### Qt 5 (libqt5)
46  * http://www.qt.io/qt5/ `(Library)`
47  * 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...
48 
49 ### CMake (cmake)
50  * http://www.cmake.org/ `(Executable)`
51  * This executable is used to automate the generation of Makefiles, check for dependencies, and is the backbone of libopenshot’s cross-platform build process.
52 
53 ### SWIG (swig)
54  * http://www.swig.org/ `(Executable)`
55  * 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.
56 
57 ### Python 3 (libpython)
58  * http://www.python.org/ `(Executable and Library)`
59  * 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).
60 
61 ### Doxygen (doxygen)
62  * http://www.stack.nl/~dimitri/doxygen/ `(Executable)`
63  * This executable is used to auto-generate the documentation used by libopenshot.
64 
65 ### UnitTest++ (libunittest++)
66  * https://github.com/unittest-cpp/ `(Library)`
67  * 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.
68 
69 ### ZeroMQ (libzmq)
70  * http://zeromq.org/ `(Library)`
71  * This library is used to communicate between libopenshot and other applications (publisher / subscriber). Primarily used to send debug data from libopenshot.
72 
73 ### OpenMP (-fopenmp)
74  * http://openmp.org/wp/ `(Compiler Flag)`
75  * 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.
76 
77 
78 ## CMake Flags (Optional)
79 There are many different build flags that can be passed to cmake to adjust how libopenshot is
80 compiled. Some of these flags might be required when compiling on certain OSes, just depending
81 on how your build environment is setup. To add a build flag, follow this general syntax:
82 `cmake -DMAGICKCORE_HDRI_ENABLE=1 -DENABLE_TESTS=1 ../`
83 
84 * MAGICKCORE_HDRI_ENABLE (default 0)
85 * MAGICKCORE_QUANTUM_DEPTH (default 0)
86 * OPENSHOT_IMAGEMAGICK_COMPATIBILITY (default 0)
87 * DISABLE_TESTS (default 0)
88 * CMAKE_PREFIX_PATH (`/location/to/missing/library/`)
89 * PYTHON_INCLUDE_DIR (`/location/to/python/include/`)
90 * PYTHON_LIBRARY (`/location/to/python/lib.a`)
91 * PYTHON_FRAMEWORKS (`/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/`)
92 * CMAKE_CXX_COMPILER (`/location/to/mingw/g++`)
93 * CMAKE_C_COMPILER (`/location/to/mingw/gcc`)
94 
95 ## Obtaining Source Code
96 
97 The first step in installing libopenshot is to obtain the most recent source code. The source code is
98 available on [GitHub](https://github.com/OpenShot/libopenshot). Use the following command
99 to obtain the latest libopenshot source code.
100 
101 ```
102 git clone https://github.com/OpenShot/libopenshot.git
103 git clone https://github.com/OpenShot/libopenshot-audio.git
104 ```
105 
106 ## Folder Structure (libopenshot)
107 
108 The source code is divided up into the following folders.
109 
110 ### build/
111  * 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).
112 
113 ### cmake/
114  * 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.
115 
116 ### doc/
117  * This folder contains documentation and related files, such as logos and images required by the doxygen auto-generated documentation.
118 
119 ### include/
120  * This folder contains all headers (*.h) used by libopenshot.
121 
122 ### src/
123  * This folder contains all source code (*.cpp) used by libopenshot.
124 
125 ### tests/
126  * 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.
127 
128 ### thirdparty/
129  * This folder contains code not written by the OpenShot team. For example, jsoncpp, an open-source JSON parser.
130 
131 ## Install Dependencies
132 
133 In order to actually compile libopenshot, we need to install some dependencies on your system. The easiest
134 way to accomplish this is with our Daily PPA. A PPA is an unofficial Ubuntu repository, which has our
135 software packages available to download and install.
136 
137 ```
138  sudo add-apt-repository ppa:openshot.developers/libopenshot-daily
139  sudo apt-get update
140  sudo apt-get install openshot-qt \
141  cmake \
142  libx11-dev \
143  libasound2-dev \
144  libavcodec-dev \
145  libavdevice-dev \
146  libavfilter-dev \
147  libavformat-dev \
148  libavresample-dev \
149  libavutil-dev \
150  libbabl-dev \
151  libfdk-aac-dev \
152  libfreetype6-dev \
153  libjsoncpp-dev \
154  libmagick++-dev \
155  libopenshot-audio-dev \
156  libswscale-dev \
157  libunittest++-dev \
158  libxcursor-dev \
159  libxinerama-dev \
160  libxrandr-dev \
161  libzmq3-dev \
162  pkg-config \
163  python3-dev \
164  qtbase5-dev \
165  qtmultimedia5-dev \
166  swig
167 ```
168 
169 ## Linux Build Instructions (libopenshot-audio)
170 To compile libopenshot-audio, we need to go through a few additional steps to manually build and
171 install it. Launch a terminal and enter:
172 
173 ```
174 cd [libopenshot-audio repo folder]
175 mkdir build
176 cd build
177 cmake ../
178 make
179 make install
180 ./src/openshot-audio-test-sound (This should play a test sound)
181 ```
182 
183 ## Linux Build Instructions (libopenshot)
184 Run the following commands to compile libopenshot:
185 
186 ```
187 cd [libopenshot repo directory]
188 mkdir -p build
189 cd build
190 cmake ../
191 make
192 ```
193 
194 If you are missing any dependencies for libopenshot, you might receive error messages at this point.
195 Just install the missing packages (usually with a -dev suffix), and run the above commands again.
196 Repeat until no error messages are displayed, and the build process completes. Also, if you manually
197 install Qt 5, you might need to specify the location for cmake:
198 
199 ```
200 cmake -DCMAKE_PREFIX_PATH=/qt5_path/qt5/5.2.0/ ../
201 ```
202 
203 To run all unit tests (and verify everything is working correctly), launch a terminal, and enter:
204 
205 ```
206 make test
207 ```
208 
209 To auto-generate documentation for libopenshot, launch a terminal, and enter:
210 
211 ```
212 make doc
213 ```
214 
215 This will use doxygen to generate a folder of HTML files, with all classes and methods documented. The
216 folder is located at **build/doc/html/**. Once libopenshot has been successfully built, we need to
217 install it (i.e. copy it to the correct folder, so other libraries can find it).
218 
219 ```
220 make install
221 ```
222 
223 This will copy the binary files to /usr/local/lib/, and the header files to /usr/local/include/openshot/...
224 This is where other projects will look for the libopenshot files when building. Python 3 bindings are
225 also installed at this point. let's verify the python bindings work:
226 
227 ```
228 python3
229 >>> import openshot
230 ```
231 
232 If no errors are displayed, you have successfully compiled and installed libopenshot on your system.
233 Congratulations and be sure to read our wiki on [Becoming an OpenShot Developer](https://github.com/OpenShot/openshot-qt/wiki/Become-a-Developer)!
234 Welcome to the OpenShot developer community! We look forward to meeting you!