3 ## Building the library and applications
7 1. [CMake](https://cmake.org) version 3.5 or higher.
8 2. [Git](https://git-scm.com/).
9 3. [Perl](https://www.perl.org/).
10 4. For x86 targets, [yasm](http://yasm.tortall.net/), which is preferred, or a
11 recent version of [nasm](http://www.nasm.us/).
12 5. Building the documentation requires [doxygen](http://doxygen.org).
13 6. Building the unit tests requires [Python](https://www.python.org/).
14 7. Emscripten builds require the portable
15 [EMSDK](https://kripken.github.io/emscripten-site/index.html).
19 CMake replaces the configure step typical of many projects. Running CMake will
20 produce configuration and build files for the currently selected CMake
21 generator. For most systems the default generator is Unix Makefiles. The basic
22 form of a makefile build is the following:
27 The above will generate a makefile build that produces the AV1 library and
28 applications for the current host system after the make step completes
29 successfully. The compiler chosen varies by host platform, but a general rule
30 applies: On systems where cc and c++ are present in $PATH at the time CMake is
31 run the generated build will use cc and c++ by default.
33 ### Configuration options
35 The AV1 codec library has a great many configuration options. These come in two
38 1. Build system configuration options. These have the form `ENABLE_FEATURE`.
39 2. AV1 codec configuration options. These have the form `CONFIG_FEATURE`.
41 Both types of options are set at the time CMake is run. The following example
42 enables ccache and disables high bit depth:
45 $ cmake path/to/aom -DENABLE_CCACHE=1 -DCONFIG_HIGHBITDEPTH=0
49 The available configuration options are too numerous to list here. Build system
50 configuration options can be found at the top of the CMakeLists.txt file found
51 in the root of the AV1 repository, and AV1 codec configuration options can
52 currently be found in the file `build/cmake/aom_config_defaults.cmake`.
56 A dylib (shared object) build of the AV1 codec library can be enabled via the
57 CMake built in variable `BUILD_SHARED_LIBS`:
60 $ cmake path/to/aom -DBUILD_SHARED_LIBS=1
64 This is currently only supported on non-Windows targets.
68 Depending on the generator used there are multiple ways of going about
69 debugging AV1 components. For single configuration generators like the Unix
70 Makefiles generator, setting `CMAKE_BUILD_TYPE` to Debug is sufficient:
73 $ cmake path/to/aom -DCMAKE_BUILD_TYPE=Debug
76 For Xcode, mainly because configuration controls for Xcode builds are buried two
77 configuration windows deep and must be set for each subproject within the Xcode
78 IDE individually, `CMAKE_CONFIGURATION_TYPES` should be set to Debug:
81 $ cmake path/to/aom -G Xcode -DCMAKE_CONFIGURATION_TYPES=Debug
84 For Visual Studio the in-IDE configuration controls should be used. Simply set
85 the IDE project configuration to Debug to allow for stepping through the code.
87 In addition to the above it can sometimes be useful to debug only C and C++
88 code. To disable all assembly code and intrinsics set `AOM_TARGET_CPU` to
89 generic at generation time:
92 $ cmake path/to/aom -DAOM_TARGET_CPU=generic
97 For the purposes of building the AV1 codec and applications and relative to the
98 scope of this guide, all builds for architectures differing from the native host
99 architecture will be considered cross compiles. The AV1 CMake build handles
100 cross compiling via the use of toolchain files included in the AV1 repository.
101 The toolchain files available at the time of this writing are:
104 - arm64-linux-gcc.cmake
106 - armv7-linux-gcc.cmake
108 - mips32-linux-gcc.cmake
109 - mips64-linux-gcc.cmake
110 - x86-ios-simulator.cmake
113 - x86-mingw-gcc.cmake
114 - x86\_64-ios-simulator.cmake
115 - x86\_64-mingw-gcc.cmake
117 The following example demonstrates use of the x86-macos.cmake toolchain file on
118 a x86\_64 MacOS host:
121 $ cmake path/to/aom \
122 -DCMAKE_TOOLCHAIN_FILE=path/to/aom/build/cmake/toolchains/x86-macos.cmake
126 To build for an unlisted target creation of a new toolchain file is the best
127 solution. The existing toolchain files can be used a starting point for a new
128 toolchain file since each one exposes the basic requirements for toolchain files
129 as used in the AV1 codec build.
131 As a temporary work around an unoptimized AV1 configuration that builds only C
132 and C++ sources can be produced using the following commands:
135 $ cmake path/to/aom -DAOM_TARGET_CPU=generic
139 In addition to the above it's important to note that the toolchain files
140 suffixed with gcc behave differently than the others. These toolchain files
141 attempt to obey the $CROSS environment variable.
145 Sanitizer integration is built-in to the CMake build system. To enable a
146 sanitizer, add `-DSANITIZE=<type>` to the CMake command line. For example, to
147 enable address sanitizer:
150 $ cmake path/to/aom -DSANITIZE=address
154 Sanitizers available vary by platform, target, and compiler. Consult your
155 compiler documentation to determine which, if any, are available.
157 ### Microsoft Visual Studio builds
159 Building the AV1 codec library in Microsoft Visual Studio is supported. The
160 following example demonstrates generating projects and a solution for the
164 # This does not require a bash shell; command.exe is fine.
165 $ cmake path/to/aom -G "Visual Studio 15 2017"
170 Building the AV1 codec library in Xcode is supported. The following example
171 demonstrates generating an Xcode project:
174 $ cmake path/to/aom -G Xcode
177 ### Emscripten builds
179 Building the AV1 codec library with Emscripten is supported. Typically this is
180 used to hook into the AOMAnalyzer GUI application. These instructions focus on
181 using the inspector with AOMAnalyzer, but all tools can be built with
184 It is assumed here that you have already downloaded and installed the EMSDK,
185 installed and activated at least one toolchain, and setup your environment
186 appropriately using the emsdk\_env script.
188 1. Download [AOMAnalyzer](https://people.xiph.org/~mbebenita/analyzer/).
190 2. Configure the build:
193 $ cmake path/to/aom \
195 -DAOM_TARGET_CPU=generic \
197 -DCONFIG_ACCOUNTING=1 \
198 -DCONFIG_INSPECTION=1 \
199 -DCONFIG_MULTITHREAD=0 \
200 -DCONFIG_RUNTIME_CPU_DETECT=0 \
201 -DCONFIG_UNIT_TESTS=0 \
203 -DCMAKE_TOOLCHAIN_FILE=path/to/emsdk-portable/.../Emscripten.cmake
206 3. Build it: run make if that's your generator of choice:
215 # inspect.js is in the examples sub directory of the directory in which you
217 $ path/to/AOMAnalyzer path/to/examples/inspect.js path/to/av1/input/file
221 ## Testing the AV1 codec
225 Currently there are two types of tests in the AV1 codec repository.
229 The unit tests can be run at build time:
232 # Before running the make command the LIBAOM_TEST_DATA_PATH environment
233 # variable should be set to avoid downloading the test files to the
234 # cmake build configuration directory.
236 # Note: The AV1 CMake build creates many test targets. Running make
237 # with multiple jobs will speed up the test run significantly.
241 #### 2. Example tests:
243 The example tests require a bash shell and can be run in the following manner:
246 # See the note above about LIBAOM_TEST_DATA_PATH above.
249 # It's best to build the testdata target using many make jobs.
250 # Running it like this will verify and download (if necessary)
251 # one at a time, which takes a while.
253 $ path/to/aom/test/examples.sh --bin-path examples
258 By default the generated projects files created by CMake will not include the
259 runtests and testdata rules when generating for IDEs like Microsoft Visual
260 Studio and Xcode. This is done to avoid intolerably long build cycles in the
261 IDEs-- IDE behavior is to build all targets when selecting the build project
262 options in MSVS and Xcode. To enable the test rules in IDEs the
263 `ENABLE_IDE_TEST_HOSTING` variable must be enabled at CMake generation time:
266 # This example uses Xcode. To get a list of the generators
267 # available, run cmake with the -G argument missing its
269 $ cmake path/to/aom -DENABLE_IDE_TEST_HOSTING=1 -G Xcode
272 ### Downloading the test data
274 The fastest and easiest way to obtain the test data is to use CMake to generate
275 a build using the Unix Makefiles generator, and then to build only the testdata
279 $ cmake path/to/aom -G "Unix Makefiles"
280 # 28 is used because there are 28 test files as of this writing.
284 The above make command will only download and verify the test data.
288 The AV1 codec library unit tests are built upon gtest which supports sharding of
289 test jobs. Sharded test runs can be achieved in a couple of ways.
291 #### 1. Running test\_libaom directly:
294 # Set the environment variable GTEST_TOTAL_SHARDS to 9 to run 10 test shards
295 # (GTEST shard indexing is 0 based).
296 $ export GTEST_TOTAL_SHARDS=9
297 $ seq 0 $(( $GTEST_TOTAL_SHARDS - 1 )) \
298 | xargs -n 1 -P 0 -I{} env GTEST_SHARD_INDEX={} ./test_libaom
301 To create a test shard for each CPU core available on the current system set
302 `GTEST_TOTAL_SHARDS` to the number of CPU cores on your system minus one.
304 #### 2. Running the tests via the CMake build:
307 # For IDE based builds, ENABLE_IDE_TEST_HOSTING must be enabled. See
308 # the IDE hosted tests section above for more information. If the IDE
309 # supports building targets concurrently tests will be sharded by default.
311 # For make and ninja builds the -j parameter controls the number of shards
312 # at test run time. This example will run the tests using 10 shards via
317 The maximum number of test targets that can run concurrently is determined by
318 the number of CPUs on the system where the build is configured as detected by
319 CMake. A system with 24 cores can run 24 test shards using a value of 24 with
320 the `-j` parameter. When CMake is unable to detect the number of cores 10 shards
321 is the default maximum value.
325 The coding style used by this project is enforced with clang-format using the
326 configuration contained in the .clang-format file in the root of the repository.
328 Before pushing changes for review you can format your code with:
331 # Apply clang-format to modified .c, .h and .cc files
332 $ clang-format -i --style=file \
333 $(git diff --name-only --diff-filter=ACMR '*.[hc]' '*.cc')
336 Check the .clang-format file for the version used to generate it if there is any
337 difference between your local formatting and the review system.
339 See also: http://clang.llvm.org/docs/ClangFormat.html
343 This library is an open source project supported by its community. Please
344 please email aomediacodec@jointdevelopment.kavi.com for help.
348 Bug reports can be filed in the Alliance for Open Media
349 [issue tracker](https://bugs.chromium.org/p/aomedia/issues/list).