OpenShot Library | libopenshot  0.2.6
/build/libopenshot-qajDji/libopenshot-0.2.6+dfsg2+1045+202108251946+daily~ubuntu18.04.1/doc/INSTALL-MAC.md
Go to the documentation of this file.
1 # Building libopenshot for MacOS
2 
3 ## Getting Started
4 
5 The best way to get started with libopenshot, is to learn about our build system, obtain all the source code,
6 install a development IDE and tools, and better understand our dependencies. So, please read through the
7 following sections, and follow the instructions. And keep in mind, that your computer is likely different
8 than the one used when writing these instructions. Your file paths and versions of applications might be
9 slightly different, so keep an eye out for subtle file path differences in the commands you type.
10 
11 ## Build Tools
12 
13 CMake is the backbone of our build system. It is a cross-platform build system, which checks for
14 dependencies, locates header files and libraries, generates makefiles, and supports the cross-platform
15 compiling of libopenshot and libopenshot-audio. CMake uses an out-of-source build concept, where
16 all temporary build files, such as makefiles, object files, and even the final binaries, are created
17 outside of the source code folder, inside a /build/ sub-folder. This prevents the build process
18 from cluttering up the source code. These instructions have only been tested with the GNU compiler
19 (including MSYS2/MinGW for Windows).
20 
21 ## Dependencies
22 
23 The following libraries are required to build libopenshot. Instructions on how to install these
24 dependencies vary for each operating system. Libraries and Executables have been labeled in the
25 list below to help distinguish between them.
26 
27 ### FFmpeg (libavformat, libavcodec, libavutil, libavdevice, libavresample, libswscale)
28  * http://www.ffmpeg.org/ `(Library)`
29  * 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.
30 
31 ### ImageMagick++ (libMagick++, libMagickWand, libMagickCore)
32  * http://www.imagemagick.org/script/magick++.php `(Library)`
33  * This library is **optional**, and used to decode and encode images.
34 
35 ### OpenShot Audio Library (libopenshot-audio)
36  * https://github.com/OpenShot/libopenshot-audio/ `(Library)`
37  * 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
38 
39 ### Qt 5 (libqt5)
40  * http://www.qt.io/qt5/ `(Library)`
41  * 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...
42 
43 ### CMake (cmake)
44  * http://www.cmake.org/ `(Executable)`
45  * This executable is used to automate the generation of Makefiles, check for dependencies, and is the backbone of libopenshot’s cross-platform build process.
46 
47 ### SWIG (swig)
48  * http://www.swig.org/ `(Executable)`
49  * 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.
50 
51 ### Python 3 (libpython)
52  * http://www.python.org/ `(Executable and Library)`
53  * 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).
54 
55 ### Doxygen (doxygen)
56  * http://www.stack.nl/~dimitri/doxygen/ `(Executable)`
57  * This executable is used to auto-generate the documentation used by libopenshot.
58 
59 ### UnitTest++ (libunittest++)
60  * https://github.com/unittest-cpp/ `(Library)`
61  * 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.
62 
63 ### ZeroMQ (libzmq)
64  * http://zeromq.org/ `(Library)`
65  * This library is used to communicate between libopenshot and other applications (publisher / subscriber). Primarily used to send debug data from libopenshot.
66 
67 ### OpenMP (-fopenmp)
68  * http://openmp.org/wp/ `(Compiler Flag)`
69  * 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.
70 
71 ## CMake Flags (Optional)
72 There are many different build flags that can be passed to cmake to adjust how libopenshot is compiled.
73 Some of these flags might be required when compiling on certain OSes, just depending on how your build
74 environment is setup. To add a build flag, follow this general syntax:
75 `cmake -DMAGICKCORE_HDRI_ENABLE=1 -DENABLE_TESTS=1 ../`
76 
77 * MAGICKCORE_HDRI_ENABLE (default 0)
78 * MAGICKCORE_QUANTUM_DEPTH (default 0)
79 * OPENSHOT_IMAGEMAGICK_COMPATIBILITY (default 0)
80 * DISABLE_TESTS (default 0)
81 * CMAKE_PREFIX_PATH (`/location/to/missing/library/`)
82 * PYTHON_INCLUDE_DIR (`/location/to/python/include/`)
83 * PYTHON_LIBRARY (`/location/to/python/lib.a`)
84 * PYTHON_FRAMEWORKS (`/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/`)
85 * CMAKE_CXX_COMPILER (`/location/to/mingw/g++`)
86 * CMAKE_C_COMPILER (`/location/to/mingw/gcc`)
87 
88 ## Obtaining Source Code
89 
90 The first step in installing libopenshot is to obtain the most recent source code. The source code
91 is available on [GitHub](https://github.com/OpenShot/libopenshot). Use the following command to
92 obtain the latest libopenshot source code.
93 
94 ```
95 git clone https://github.com/OpenShot/libopenshot.git
96 git clone https://github.com/OpenShot/libopenshot-audio.git
97 ```
98 
99 ## Folder Structure (libopenshot)
100 
101 The source code is divided up into the following folders.
102 
103 ### build/
104  * 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).
105 
106 ### cmake/
107  * 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.
108 
109 ### doc/
110  * This folder contains documentation and related files, such as logos and images required by the doxygen auto-generated documentation.
111 
112 ### include/
113  * This folder contains all headers (*.h) used by libopenshot.
114 
115 ### src/
116  * This folder contains all source code (*.cpp) used by libopenshot.
117 
118 ### tests/
119  * 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.
120 
121 ### thirdparty/
122  * This folder contains code not written by the OpenShot team. For example, jsoncpp, an open-source JSON parser.
123 
124 ## Install Dependencies
125 
126 In order to actually compile libopenshot and libopenshot-audio, we need to install some dependencies on
127 your system. Most packages needed by libopenshot can be installed easily with Homebrew. However, first
128 install Xcode with the following options ("UNIX Development", "System Tools", "Command Line Tools", or
129 "Command Line Support"). Be sure to refresh your list of Homebrew packages with the “brew update” command.
130 
131 **NOTE:** Homebrew seems to work much better for most users (compared to MacPorts), so I am going to
132 focus on brew for this guide.
133 
134 Install the following packages using the Homebrew package installer (http://brew.sh/). Pay close attention
135 to any warnings or errors during these brew installs. NOTE: You might have some conflicting libraries in
136 your /usr/local/ folders, so follow the directions from brew if these are detected.
137 
138 ```
139 brew install gcc48 --enable-all-languages
140 brew install ffmpeg
141 brew install librsvg
142 brew install swig
143 brew install doxygen
144 brew install unittest-cpp --cc=gcc-4.8. You must specify the c++ compiler with the --cc flag to be 4.7 or 4.8.
145 brew install qt5
146 brew install cmake
147 brew install zeromq
148 ```
149 
150 ## Mac Build Instructions (libopenshot-audio)
151 Since libopenshot-audio is not available in a Homebrew or MacPorts package, we need to go through a
152 few additional steps to manually build and install it. Launch a terminal and enter:
153 
154 ```
155 cd [libopenshot-audio repo folder]
156 mkdir build
157 cd build
158 cmake -d -G "Unix Makefiles" -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang ../ (CLang must be used due to GNU incompatible Objective-C code in some of the Apple frameworks)
159 make
160 make install
161 ./src/openshot-audio-test-sound (This should play a test sound)
162 ```
163 
164 ## Mac Build Instructions (libopenshot)
165 Run the following commands to build libopenshot:
166 
167 ```
168 $ cd [libopenshot repo folder]
169 $ mkdir build
170 $ cd build
171 $ cmake -G "Unix Makefiles" -DCMAKE_CXX_COMPILER=/usr/local/opt/gcc48/bin/g++-4.8 -DCMAKE_C_COMPILER=/usr/local/opt/gcc48/bin/gcc-4.8 -DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt5/5.4.2/ -DPYTHON_INCLUDE_DIR=/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/Versions/3.3/include/python3.3m/ -DPYTHON_LIBRARY=/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/Versions/3.3/lib/libpython3.3.dylib -DPython_FRAMEWORKS=/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/ ../ -D"CMAKE_BUILD_TYPE:STRING=Debug"
172 ```
173 
174 The extra arguments on the cmake command make sure the compiler will be gcc4.8 and that cmake
175 knows where to look for the Qt header files and Python library. Double check these file paths,
176 as yours will likely be different.
177 
178 ```
179 make
180 ```
181 
182 If you are missing any dependencies for libopenshot, you will receive error messages at this point.
183 Just install the missing dependencies, and run the above commands again. Repeat until no error
184 messages are displayed and the build process completes.
185 
186 Also, if you are having trouble building, please see the CMake Flags section above, as it might
187 provide a solution for finding a missing folder path, missing Python 3 library, etc...
188 
189 To run all unit tests (and verify everything is working correctly), launch a terminal, and enter:
190 
191 ```
192 make test
193 ```
194 
195 To auto-generate the documentation for libopenshot, launch a terminal, and enter:
196 
197 ```
198 make doc
199 ```
200 
201 This will use doxygen to generate a folder of HTML files, with all classes and methods documented.
202 The folder is located at build/doc/html/. Once libopenshot has been successfully built, we need
203 to install it (i.e. copy it to the correct folder, so other libraries can find it).
204 
205 ```
206 make install
207 ```
208 
209 This should copy the binary files to /usr/local/lib/, and the header files to /usr/local/include/openshot/...
210 This is where other projects will look for the libopenshot files when building. Python 3 bindings are
211 also installed at this point. let's verify the python bindings work:
212 
213 ```
214 python3 (or python)
215 >>> import openshot
216 ```
217 
218 If no errors are displayed, you have successfully compiled and installed libopenshot on your
219 system. Congratulations and be sure to read our wiki on [Becoming an OpenShot Developer](https://github.com/OpenShot/openshot-qt/wiki/Become-a-Developer)!
220 Welcome to the OpenShot developer community! We look forward to meeting you!