1Welcome to the WebM VP8/VP9 Codec SDK! 2 3COMPILING THE APPLICATIONS/LIBRARIES: 4 The build system used is similar to autotools. Building generally consists of 5 "configuring" with your desired build options, then using GNU make to build 6 the application. 7 8 1. Prerequisites 9 10 * All x86 targets require the Yasm[1] assembler be installed[2]. 11 * All Windows builds require that Cygwin[3] or MSYS2[4] be installed. 12 * Building the documentation requires Doxygen[5]. If you do not 13 have this package, the install-docs option will be disabled. 14 * Downloading the data for the unit tests requires curl[6] and sha1sum. 15 sha1sum is provided via the GNU coreutils, installed by default on 16 many *nix platforms, as well as MinGW and Cygwin. If coreutils is not 17 available, a compatible version of sha1sum can be built from 18 source[7]. These requirements are optional if not running the unit 19 tests. 20 21 [1]: http://www.tortall.net/projects/yasm 22 [2]: For Visual Studio the base yasm binary (not vsyasm) should be in the 23 PATH for Visual Studio. For VS2017 it is sufficient to rename 24 yasm-<version>-<arch>.exe to yasm.exe and place it in: 25 Program Files (x86)/Microsoft Visual Studio/2017/<level>/Common7/Tools/ 26 [3]: http://www.cygwin.com 27 [4]: http://www.msys2.org/ 28 [5]: http://www.doxygen.org 29 [6]: http://curl.haxx.se 30 [7]: http://www.microbrew.org/tools/md5sha1sum/ 31 32 2. Out-of-tree builds 33 Out of tree builds are a supported method of building the application. For 34 an out of tree build, the source tree is kept separate from the object 35 files produced during compilation. For instance: 36 37 $ mkdir build 38 $ cd build 39 $ ../libvpx/configure <options> 40 $ make 41 42 3. Configuration options 43 The 'configure' script supports a number of options. The --help option can be 44 used to get a list of supported options: 45 $ ../libvpx/configure --help 46 47 4. Compiler analyzers 48 Compilers have added sanitizers which instrument binaries with information 49 about address calculation, memory usage, threading, undefined behavior, and 50 other common errors. To simplify building libvpx with some of these features 51 use tools/set_analyzer_env.sh before running configure. It will set the 52 compiler and necessary flags for building as well as environment variables 53 read by the analyzer when testing the binaries. 54 $ source ../libvpx/tools/set_analyzer_env.sh address 55 56 5. Cross development 57 For cross development, the most notable option is the --target option. The 58 most up-to-date list of supported targets can be found at the bottom of the 59 --help output of the configure script. As of this writing, the list of 60 available targets is: 61 62 arm64-android-gcc 63 arm64-darwin-gcc 64 arm64-darwin20-gcc 65 arm64-darwin21-gcc 66 arm64-darwin22-gcc 67 arm64-darwin23-gcc 68 arm64-linux-gcc 69 arm64-win64-gcc 70 arm64-win64-vs15 71 arm64-win64-vs16 72 arm64-win64-vs16-clangcl 73 arm64-win64-vs17 74 arm64-win64-vs17-clangcl 75 armv7-android-gcc 76 armv7-darwin-gcc 77 armv7-linux-rvct 78 armv7-linux-gcc 79 armv7-none-rvct 80 armv7-win32-gcc 81 armv7-win32-vs14 82 armv7-win32-vs15 83 armv7-win32-vs16 84 armv7-win32-vs17 85 armv7s-darwin-gcc 86 armv8-linux-gcc 87 loongarch32-linux-gcc 88 loongarch64-linux-gcc 89 mips32-linux-gcc 90 mips64-linux-gcc 91 ppc64le-linux-gcc 92 sparc-solaris-gcc 93 x86-android-gcc 94 x86-darwin8-gcc 95 x86-darwin8-icc 96 x86-darwin9-gcc 97 x86-darwin9-icc 98 x86-darwin10-gcc 99 x86-darwin11-gcc 100 x86-darwin12-gcc 101 x86-darwin13-gcc 102 x86-darwin14-gcc 103 x86-darwin15-gcc 104 x86-darwin16-gcc 105 x86-darwin17-gcc 106 x86-iphonesimulator-gcc 107 x86-linux-gcc 108 x86-linux-icc 109 x86-os2-gcc 110 x86-solaris-gcc 111 x86-win32-gcc 112 x86-win32-vs14 113 x86-win32-vs15 114 x86-win32-vs16 115 x86-win32-vs17 116 x86_64-android-gcc 117 x86_64-darwin9-gcc 118 x86_64-darwin10-gcc 119 x86_64-darwin11-gcc 120 x86_64-darwin12-gcc 121 x86_64-darwin13-gcc 122 x86_64-darwin14-gcc 123 x86_64-darwin15-gcc 124 x86_64-darwin16-gcc 125 x86_64-darwin17-gcc 126 x86_64-darwin18-gcc 127 x86_64-darwin19-gcc 128 x86_64-darwin20-gcc 129 x86_64-darwin21-gcc 130 x86_64-darwin22-gcc 131 x86_64-darwin23-gcc 132 x86_64-iphonesimulator-gcc 133 x86_64-linux-gcc 134 x86_64-linux-icc 135 x86_64-solaris-gcc 136 x86_64-win64-gcc 137 x86_64-win64-vs14 138 x86_64-win64-vs15 139 x86_64-win64-vs16 140 x86_64-win64-vs17 141 generic-gnu 142 143 The generic-gnu target, in conjunction with the CROSS environment variable, 144 can be used to cross compile architectures that aren't explicitly listed, if 145 the toolchain is a cross GNU (gcc/binutils) toolchain. Other POSIX toolchains 146 will likely work as well. For instance, to build using the mipsel-linux-uclibc 147 toolchain, the following command could be used (note, POSIX SH syntax, adapt 148 to your shell as necessary): 149 150 $ CROSS=mipsel-linux-uclibc- ../libvpx/configure 151 152 In addition, the executables to be invoked can be overridden by specifying the 153 environment variables: AR, AS, CC, CXX, LD, STRIP. Additional flags can be 154 passed to these executables with ASFLAGS, CFLAGS, CXXFLAGS, and LDFLAGS. 155 156 6. Configuration errors 157 If the configuration step fails, the first step is to look in the error log. 158 This defaults to config.log. This should give a good indication of what went 159 wrong. If not, contact us for support. 160 161VP8/VP9 TEST VECTORS: 162 The test vectors can be downloaded and verified using the build system after 163 running configure. To specify an alternate directory the 164 LIBVPX_TEST_DATA_PATH environment variable can be used. 165 166 $ ./configure --enable-unit-tests 167 $ LIBVPX_TEST_DATA_PATH=../libvpx-test-data make testdata 168 169CODE STYLE: 170 The coding style used by this project is enforced with clang-format using the 171 configuration contained in the .clang-format file in the root of the 172 repository. 173 174 Before pushing changes for review you can format your code with: 175 # Apply clang-format to modified .c, .h and .cc files 176 $ clang-format -i --style=file \ 177 $(git diff --name-only --diff-filter=ACMR '*.[hc]' '*.cc') 178 179 Check the .clang-format file for the version used to generate it if there is 180 any difference between your local formatting and the review system. 181 182 See also: http://clang.llvm.org/docs/ClangFormat.html 183 184PROFILE GUIDED OPTIMIZATION (PGO) 185 Profile Guided Optimization can be enabled for Clang builds using the 186 commands: 187 188 $ export CC=clang 189 $ export CXX=clang++ 190 $ ../libvpx/configure --enable-profile 191 $ make 192 193 Generate one or multiple PGO profile files by running vpxdec or vpxenc. For 194 example: 195 196 $ ./vpxdec ../vpx/out_ful/vp90-2-sintel_1280x546_tile_1x4_1257kbps.webm \ 197 -o - > /dev/null 198 199 To convert and merge the raw profile files, use the llvm-profdata tool: 200 201 $ llvm-profdata merge -o perf.profdata default_8382761441159425451_0.profraw 202 203 Then, rebuild the project with the new profile file: 204 205 $ make clean 206 $ ../libvpx/configure --use-profile=perf.profdata 207 $ make 208 209 Note: Always use the llvm-profdata from the toolchain that is used for 210 compiling the PGO-enabled binary. 211 212 To observe the improvements from a PGO-enabled build, enable and compare the 213 list of failed optimizations by using the -Rpass-missed compiler flag. For 214 example, to list the failed loop vectorizations: 215 216 $ ../libvpx/configure --use-profile=perf.profdata \ 217 --extra-cflags=-Rpass-missed=loop-vectorize 218 219 For guidance on utilizing PGO files to identify potential optimization 220 opportunities, see: tools/README.pgo.md 221 222SUPPORT 223 This library is an open source project supported by its community. Please 224 email [email protected] for help. 225 226BUG REPORTS 227 Bug reports can be filed in the libvpx issue tracker: 228 https://issues.webmproject.org/. 229 For security reports, select 'Security report' from the Template dropdown. 230