OpenShot Library | libopenshot  0.2.6
/build/libopenshot-qajDji/libopenshot-0.2.6+dfsg2+1045+202108251946+daily~ubuntu18.04.1/doc/INSTALL-WINDOWS.md
Go to the documentation of this file.
1 # Building libopenshot for Windows
2 
3 ## Getting Started
4 
5 The best way to get started with libopenshot, is to learn about our build system, obtain all the
6 source code, install a development IDE and tools, and better understand our dependencies. So,
7 please read through the following sections, and follow the instructions. And keep in mind,
8 that your computer is likely different than the one used when writing these instructions.
9 Your file paths and versions of applications might be slightly different, so keep an eye out
10 for subtle file path differences in the commands you type.
11 
12 ## Build Tools
13 
14 CMake is the backbone of our build system. It is a cross-platform build system, which
15 checks for dependencies, locates header files and libraries, generates makefiles, and
16 supports the cross-platform compiling of libopenshot and libopenshot-audio. CMake uses
17 an out-of-source build concept, where all temporary build files, such as makefiles,
18 object files, and even the final binaries, are created outside of the source code
19 folder, inside a /build/ sub-folder. This prevents the build process from cluttering
20 up the source code. These instructions have only been tested with the GNU compiler
21 (including MSYS2/MinGW for Windows).
22 
23 ## Dependencies
24 
25 The following libraries are required to build libopenshot. Instructions on how to
26 install these dependencies vary for each operating system. Libraries and Executables
27 have been labeled in the list below to help distinguish between them.
28 
29 ### FFmpeg (libavformat, libavcodec, libavutil, libavdevice, libavresample, libswscale)
30  * http://www.ffmpeg.org/ `(Library)`
31  * 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.
32 
33 ### ImageMagick++ (libMagick++, libMagickWand, libMagickCore)
34  * http://www.imagemagick.org/script/magick++.php `(Library)`
35  * This library is **optional**, and used to decode and encode images.
36 
37 ### OpenShot Audio Library (libopenshot-audio)
38  * https://github.com/OpenShot/libopenshot-audio/ `(Library)`
39  * 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
40 
41 ### Qt 5 (libqt5)
42  * http://www.qt.io/qt5/ `(Library)`
43  * 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...
44 
45 ### CMake (cmake)
46  * http://www.cmake.org/ `(Executable)`
47  * This executable is used to automate the generation of Makefiles, check for dependencies, and is the backbone of libopenshot’s cross-platform build process.
48 
49 ### SWIG (swig)
50  * http://www.swig.org/ `(Executable)`
51  * 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.
52 
53 ### Python 3 (libpython)
54  * http://www.python.org/ `(Executable and Library)`
55  * 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).
56 
57 ### Doxygen (doxygen)
58  * http://www.stack.nl/~dimitri/doxygen/ `(Executable)`
59  * This executable is used to auto-generate the documentation used by libopenshot.
60 
61 ### UnitTest++ (libunittest++)
62  * https://github.com/unittest-cpp/ `(Library)`
63  * 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.
64 
65 ### ZeroMQ (libzmq)
66  * http://zeromq.org/ `(Library)`
67  * This library is used to communicate between libopenshot and other applications (publisher / subscriber). Primarily used to send debug data from libopenshot.
68 
69 ### OpenMP (-fopenmp)
70  * http://openmp.org/wp/ `(Compiler Flag)`
71  * 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.
72 
73 ## CMake Flags (Optional)
74 There are many different build flags that can be passed to cmake to adjust how libopenshot
75 is compiled. Some of these flags might be required when compiling on certain OSes, just
76 depending on how your build environment is setup. To add a build flag, follow this general
77 syntax: `cmake -DMAGICKCORE_HDRI_ENABLE=1 -DENABLE_TESTS=1 ../`
78 
79 * MAGICKCORE_HDRI_ENABLE (default 0)
80 * MAGICKCORE_QUANTUM_DEPTH (default 0)
81 * OPENSHOT_IMAGEMAGICK_COMPATIBILITY (default 0)
82 * DISABLE_TESTS (default 0)
83 * CMAKE_PREFIX_PATH (`/location/to/missing/library/`)
84 * PYTHON_INCLUDE_DIR (`/location/to/python/include/`)
85 * PYTHON_LIBRARY (`/location/to/python/lib.a`)
86 * PYTHON_FRAMEWORKS (`/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/`)
87 * CMAKE_CXX_COMPILER (`/location/to/mingw/g++`)
88 * CMAKE_C_COMPILER (`/location/to/mingw/gcc`)
89 
90 ## Environment Variables
91 
92 Many environment variables will need to be set during this Windows installation guide.
93 The command line will need to be closed and re-launched after any changes to your environment
94 variables. Also, dependency libraries will not be found during linking or execution without
95 being found in the PATH environment variable. So, if you get errors related to missing
96 commands or libraries, double check the PATH variable.
97 
98 The following environment variables need to be added to your “System Variables”. Be sure to
99 check each folder path for accuracy, as your paths will likely be different than this list.
100 
101 ### Example Variables
102 
103 * DL_DIR (`C:\libdl`)
104 * DXSDK_DIR (`C:\Program Files\Microsoft DirectX SDK (June 2010)\`)
105 * FFMPEGDIR (`C:\ffmpeg-git-95f163b-win32-dev`)
106 * FREETYPE_DIR (`C:\Program Files\GnuWin32`)
107 * HOME (`C:\msys\1.0\home`)
108 * LIBOPENSHOT_AUDIO_DIR (`C:\Program Files\libopenshot-audio`)
109 * QTDIR (`C:\qt5`)
110 * SNDFILE_DIR (`C:\Program Files\libsndfile`)
111 * UNITTEST_DIR (`C:\UnitTest++`)
112 * ZMQDIR (`C:\msys2\usr\local\`)
113 * PATH (`The following paths are an example`)
114  * `C:\Qt5\bin; C:\Qt5\MinGW\bin\; C:\msys\1.0\local\lib; C:\Program Files\CMake 2.8\bin; C:\UnitTest++\build; C:\libopenshot\build\src; C:\Program Files\doxygen\bin; C:\ffmpeg-git-95f163b-win32-dev\lib; C:\swigwin-2.0.4; C:\Python33; C:\Program Files\Project\lib; C:\msys2\usr\local\`
115 
116 
117 
118 
119 
120 ## Obtaining Source Code
121 
122 The first step in installing libopenshot is to obtain the most recent source code. The source code
123 is available on [GitHub](https://github.com/OpenShot/libopenshot). Use the following command to
124 obtain the latest libopenshot source code.
125 
126 ```
127 git clone https://github.com/OpenShot/libopenshot.git
128 git clone https://github.com/OpenShot/libopenshot-audio.git
129 ```
130 
131 ## Folder Structure (libopenshot)
132 
133 The source code is divided up into the following folders.
134 
135 ### build/
136  * This folder needs to be manually created, and is used by cmake to store the temporary
137  build files, such as makefiles, as well as the final binaries (library and test executables).
138 
139 ### cmake/
140  * This folder contains custom modules not included by default in cmake, used to find
141  dependency libraries and headers and determine if these libraries are installed.
142 
143 ### doc/
144  * This folder contains documentation and related files, such as logos and images
145  required by the doxygen auto-generated documentation.
146 
147 ### include/
148  * This folder contains all headers (*.h) used by libopenshot.
149 
150 ### src/
151  * This folder contains all source code (*.cpp) used by libopenshot.
152 
153 ### tests/
154  * This folder contains all unit test code. Each class has it’s own test file (*.cpp), and
155  uses UnitTest++ macros to keep the test code simple and manageable.
156 
157 ### thirdparty/
158  * This folder contains code not written by the OpenShot team. For example, jsoncpp, an
159  open-source JSON parser.
160 
161 ## Install MSYS2 Dependencies
162 
163 Most Windows dependencies needed for libopenshot-audio, libopenshot, and openshot-qt
164 can be installed easily with MSYS2 and the pacman package manager. Follow these
165 directions to setup a Windows build environment for OpenShot.
166 
167 1) Install MSYS2: http://www.msys2.org/
168 
169 2) Run MSYS2 command prompt (for example: `C:\msys64\msys2_shell.cmd`)
170 
171 3) Append PATH (so MSYS2 can find executables and libraries):
172 
173 ```
174 PATH=$PATH:/c/msys64/mingw64/bin:/c/msys64/mingw64/lib (64-bit PATH)
175  or
176 PATH=$PATH:/c/msys32/mingw32/bin:/c/msys32/mingw32/lib (32-bit PATH)
177 ```
178 
179 4) Update and upgrade all packages
180 
181 ```
182 pacman -Syu
183 ```
184 
185 5a) Install the following packages (**64-Bit**)
186 
187 ```
188 pacman -S --needed base-devel mingw-w64-x86_64-toolchain
189 pacman -S mingw64/mingw-w64-x86_64-ffmpeg
190 pacman -S mingw64/mingw-w64-x86_64-python3-pyqt5
191 pacman -S mingw64/mingw-w64-x86_64-swig
192 pacman -S mingw64/mingw-w64-x86_64-cmake
193 pacman -S mingw64/mingw-w64-x86_64-doxygen
194 pacman -S mingw64/mingw-w64-x86_64-python3-pip
195 pacman -S mingw32/mingw-w64-i686-zeromq
196 pacman -S mingw64/mingw-w64-x86_64-python3-pyzmq
197 pacman -S mingw64/mingw-w64-x86_64-python3-cx_Freeze
198 pacman -S git
199 
200 # Install ImageMagick if needed (OPTIONAL and NOT NEEDED)
201 pacman -S mingw64/mingw-w64-x86_64-imagemagick
202 ```
203 
204 5b) **Or** Install the following packages (**32-Bit**)
205 
206 ```
207 pacman -S --needed base-devel mingw32/mingw-w64-i686-toolchain
208 pacman -S mingw32/mingw-w64-i686-ffmpeg
209 pacman -S mingw32/mingw-w64-i686-python3-pyqt5
210 pacman -S mingw32/mingw-w64-i686-swig
211 pacman -S mingw32/mingw-w64-i686-cmake
212 pacman -S mingw32/mingw-w64-i686-doxygen
213 pacman -S mingw32/mingw-w64-i686-python3-pip
214 pacman -S mingw32/mingw-w64-i686-zeromq
215 pacman -S mingw32/mingw-w64-i686-python3-pyzmq
216 pacman -S mingw32/mingw-w64-i686-python3-cx_Freeze
217 pacman -S git
218 
219 # Install ImageMagick if needed (OPTIONAL and NOT NEEDED)
220 pacman -S mingw32/mingw-w32-x86_32-imagemagick
221 ```
222 
223 6) Install Python PIP Dependencies
224 
225 ```
226 pip3 install httplib2
227 pip3 install slacker
228 pip3 install tinys3
229 pip3 install github3.py
230 pip3 install requests
231 ```
232 
233 7) Download Unittest++ (https://github.com/unittest-cpp/unittest-cpp) into /MSYS2/[USER]/unittest-cpp-master/
234 
235 ```
236 cmake -G "MSYS Makefiles" ../ -DCMAKE_MAKE_PROGRAM=mingw32-make -DCMAKE_INSTALL_PREFIX:PATH=/usr
237 mingw32-make install
238 ```
239 
240 8) ZMQ++ Header (This might not be needed anymore)
241  NOTE: Download and copy zmq.hpp into the /c/msys64/mingw64/include/ folder
242 
243 ## Manual Dependencies
244 
245 ### DLfcn
246  * https://github.com/dlfcn-win32/dlfcn-win32
247  * Download and Extract the Win32 Static (.tar.bz2) archive to a local folder: `C:\libdl\`
248  * Create an environment variable called DL_DIR and set the value to `C:\libdl\`. This environment variable will be used by CMake to find the binary and header file.
249 
250 ### DirectX SDK / Windows SDK
251  * Windows 7: (DirectX SDK) http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=6812
252  * Windows 8: (Windows SDK)
253  * https://msdn.microsoft.com/en-us/windows/desktop/aa904949
254  * Download and Install the SDK Setup program. This is needed for the JUCE library to play audio on Windows.
255 Create an environment variable called DXSDK_DIR and set the value to `C:\Program Files\Microsoft DirectX SDK (June 2010)\` (your path might be different). This environment variable will be used by CMake to find the binaries and header files.
256 
257 ### libSndFile
258  * http://www.mega-nerd.com/libsndfile/#Download
259  * Download and Install the Win32 Setup program.
260  * Create an environment variable called SNDFILE_DIR and set the value to `C:\Program Files\libsndfile`. This environment variable will be used by CMake to find the binary and header files.
261 
262 ### libzmq
263  * http://zeromq.org/intro:get-the-software
264  * Download source code (zip)
265  * Follow their instructions, and build with mingw
266  * Create an environment variable called ZMQDIR and set the value to `C:\libzmq\build\` (the location of the compiled version). This environment variable will be used by CMake to find the binary and header files.
267 
268 ## Windows Build Instructions (libopenshot-audio)
269 In order to compile libopenshot-audio, launch a command prompt and enter the following commands. This does not require the MSYS2 prompt, but it should work in both the Windows command prompt and the MSYS2 prompt.
270 
271 ```
272 cd [libopenshot-audio repo folder]
273 mkdir build
274 cd build
275 cmake -G “MinGW Makefiles” ../
276 mingw32-make
277 mingw32-make install
278 openshot-audio-test-sound (This should play a test sound)
279 ```
280 
281 ## Windows Build Instructions (libopenshot)
282 Run the following commands to build libopenshot:
283 
284 ```
285 cd [libopenshot repo folder]
286 mkdir build
287 cd build
288 cmake -G "MinGW Makefiles" -DPYTHON_INCLUDE_DIR="C:/Python34/include/" -DPYTHON_LIBRARY="C:/Python34/libs/libpython34.a" ../
289 mingw32-make
290 ```
291 
292 If you are missing any dependencies for libopenshot, you will receive error messages at this point.
293 Just install the missing dependencies, and run the above commands again. Repeat until no error
294 messages are displayed and the build process completes.
295 
296 Also, if you are having trouble building, please see the CMake Flags section above, as
297 it might provide a solution for finding a missing folder path, missing Python 3 library, etc...
298 
299 To run all unit tests (and verify everything is working correctly), launch a terminal, and enter:
300 
301 ```
302 mingw32-make test
303 ```
304 
305 To auto-generate the documentation for libopenshot, launch a terminal, and enter:
306 
307 ```
308 mingw32-make doc
309 ```
310 
311 This will use doxygen to generate a folder of HTML files, with all classes and methods
312 documented. The folder is located at build/doc/html/. Once libopenshot has been successfully
313 built, we need to install it (i.e. copy it to the correct folder, so other libraries can find it).
314 
315 ```
316 mingw32-make install
317 ```
318 
319 This should copy the binary files to `C:\Program Files\openshot\lib\`, and the header
320 files to `C:\Program Files\openshot\include\...` This is where other projects will
321 look for the libopenshot files when building.. Python 3 bindings are also installed
322 at this point. let's verify the python bindings work:
323 
324 ```
325 python3
326 >>> import openshot
327 ```
328 
329 If no errors are displayed, you have successfully compiled and installed libopenshot on
330 your system. Congratulations and be sure to read our wiki on [Becoming an OpenShot Developer](https://github.com/OpenShot/openshot-qt/wiki/Become-a-Developer)!
331 Welcome to the OpenShot developer community! We look forward to meeting you!