OpenShot Audio Library | OpenShotAudio  0.3.1
INSTALL.md
1 # The OpenShot Audio Library
2 
3 ## Getting Started
4 
5 The best way to get started with libopenshot-audio is to
6 learn about our build system, obtain all the source code,
7 install a development IDE and tools,
8 and better understand our dependencies.
9 So, please read through the following sections and follow the instructions.
10 And keep in mind, every computer system is different.
11 Keep an eye out for subtle file path differences in the commands you type.
12 
13 ## Build Tools
14 
15 CMake is the backbone of our build system.
16 It is a cross-platform build system, which checks for dependencies,
17 locates header files and libraries, generates makefiles,
18 and supports the cross-platform compiling of libopenshot and libopenshot-audio.
19 CMake uses an out-of-source build concept where all temporary build files,
20 such as makefiles, object files, and even the final binaries,
21 are created outside of the source code folder.
22 (A subfolder named `build/` is a common convention, demonstrated here.)
23 This prevents the build process from cluttering up the source code.
24 
25 These instructions have only been tested with
26 the GNU compiler (including MSYS2/MinGW for Windows)
27 and the Clang compiler (including AppleClang).
28 
29 ## Dependencies
30 
31 The following libraries are required to build libopenshot-audio.
32 Instructions on how to install these dependencies vary by operating system.
33 Libraries and Executables have been labeled in the list below,
34 to help distinguish between them.
35 
36 ### Build dependencies
37 
38 #### CMake
39 
40 * <http://www.cmake.org/> (**Executable**)
41 
42 * Used to automate the generation of Makefiles, check for dependencies,
43  and is the backbone of libopenshot-audio’s cross-platform build process.
44 
45 ### Documentation dependencies
46 
47 Only required if you wish to build a local copy of the API documentation.
48 
49 #### Doxygen
50 
51 * <http://doxygen.nl/> (**Executable**)
52 * Used to auto-generate the documentation used by libopenshot-audio.
53 
54 ### OS-specific dependencies
55 
56 #### ALSA - Required, Linux only
57 
58 * `libalsa.so` (**Library**)
59 * Audio hardware interface library, install with OS package manager
60 
61 #### ASIO SDK - Optional, Windows only
62 
63 * <https://new.steinberg.net/developers/> ("ASIO SDK" download link) (**Library**)
64 
65 * Optional audio interface library.
66 
67 * When building, tell CMake where to find the SDK by either:
68 
69  1. Setting the environment variable `ASIO_SDK_DIR`
70  to the full path of the extracted SDK.
71 
72  Example: `ASIO_SDK_DIR="C:\Program Files\asiosdk_2.3.3_2019-06-14"`
73 
74  2. Setting the path on the CMake command line, using `ASIO_ROOT`.
75 
76  Example:
77  `cmake -DASIO_ROOT="C:\Users\Owner\Downloads\asiosdk_2.3.3_2019-06-14"`
78 
79 ## Obtaining Source Code
80 
81 The first step in installing libopenshot-audio is to obtain the source code.
82 The source code is available on
83 [GitHub](https://github.com/OpenShot/libopenshot-audio).
84 Open a terminal and use the following command to obtain the latest source:
85 
86 ```sh
87 git clone https://github.com/OpenShot/libopenshot-audio.git
88 ```
89 
90 ## Linux Build Instructions (libopenshot-audio)
91 
92 Enter the source directory downloaded by git, and configure the `build` directory:
93 
94 ```sh
95 cd libopenshot-audio
96 
97 # Add any other configuration to the next command. Some common options:
98 # -DCMAKE_INSTALL_PREFIX=/usr
99 # -DASIO_ROOT="C:\Program Files\ASIO SDK"
100 cmake -B build -S .
101 ```
102 
103 Once the build is successfully configured, compile the library:
104 
105 ```sh
106 cmake --build build
107 ```
108 
109 If there are no errors, you can test the new build using the demo program.
110 It will list the audio devices detected on your system, then use the
111 default device to play a series of short test tones:
112 
113 ```sh
114 ./build/src/openshot-audio-demo
115 ```
116 
117 If everything is working as expected, you may install the library by running:
118 
119 ```sh
120 # (This installs to the default prefix configured in CMake,
121 # unless you changed CMAKE_INSTALL_PREFIX above)
122 cmake --install build
123 ```
124 
125 If your next step is to build libopenshot, installation is optional here.
126 libopenshot-audio can be used from the build directory by adding
127 `-DOpenShotAudio_ROOT="/path/to/libopenshot-audio/build"`
128 to the `cmake` command line, when configuring libopenshot.