Bug 1885565 - Part 2: Fix up parameter ordering and kDoc descriptions in NavigationBa...
[gecko.git] / third_party / aom / README.md
blob4e2eb2756c9daa04ca1261c37540eb6cc5b15238
1 README.md                {#LREADME}
2 =========
3 # AV1 Codec Library
5 ## Contents
6 1. [Building the lib and applications](#building-the-library-and-applications)
7     - [Prerequisites](#prerequisites)
8     - [Get the code](#get-the-code)
9     - [Basics](#basic-build)
10     - [Configuration options](#configuration-options)
11     - [Dylib builds](#dylib-builds)
12     - [Debugging](#debugging)
13     - [Cross compiling](#cross-compiling)
14     - [Sanitizer support](#sanitizers)
15     - [MSVC builds](#microsoft-visual-studio-builds)
16     - [Xcode builds](#xcode-builds)
17     - [Emscripten builds](#emscripten-builds)
18     - [Extra Build Flags](#extra-build-flags)
19     - [Build with VMAF support](#build-with-vmaf)
20 2. [Testing the library](#testing-the-av1-codec)
21     - [Basics](#testing-basics)
22         - [Unit tests](#unit-tests)
23         - [Example tests](#example-tests)
24         - [Encoder tests](#encoder-tests)
25     - [IDE hosted tests](#ide-hosted-tests)
26     - [Downloading test data](#downloading-the-test-data)
27     - [Adding a new test data file](#adding-a-new-test-data-file)
28     - [Additional test data](#additional-test-data)
29     - [Sharded testing](#sharded-testing)
30         - [Running tests directly](#running-test_libaom-directly)
31         - [Running tests via CMake](#running-the-tests-via-the-cmake-build)
32 3. [Coding style](#coding-style)
33 4. [Submitting patches](#submitting-patches)
34     - [Login cookie](#login-cookie)
35     - [Contributor agreement](#contributor-agreement)
36     - [Testing your code](#testing-your-code)
37     - [Commit message hook](#commit-message-hook)
38     - [Upload your change](#upload-your-change)
39     - [Incorporating Reviewer Comments](#incorporating-reviewer-comments)
40     - [Submitting your change](#submitting-your-change)
41     - [Viewing change status](#viewing-the-status-of-uploaded-changes)
42 5. [Support](#support)
43 6. [Bug reports](#bug-reports)
45 ## Building the library and applications {#building-the-library-and-applications}
47 ### Prerequisites {#prerequisites}
49  1. [CMake](https://cmake.org). See CMakeLists.txt for the minimum version
50     required.
51  2. [Git](https://git-scm.com/).
52  3. [Perl](https://www.perl.org/).
53  4. For x86 targets, [yasm](http://yasm.tortall.net/), which is preferred, or a
54     recent version of [nasm](http://www.nasm.us/). If you download yasm with
55     the intention to work with Visual Studio, please download win32.exe or
56     win64.exe and rename it into yasm.exe. DO NOT download or use vsyasm.exe.
57  5. Building the documentation requires
58    [doxygen version 1.8.10 or newer](http://doxygen.org).
59  6. Emscripten builds require the portable
60    [EMSDK](https://kripken.github.io/emscripten-site/index.html).
62 ### Get the code {#get-the-code}
64 The AV1 library source code is stored in the Alliance for Open Media Git
65 repository:
67 ~~~
68     $ git clone https://aomedia.googlesource.com/aom
69     # By default, the above command stores the source in the aom directory:
70     $ cd aom
71 ~~~
73 ### Basic build {#basic-build}
75 CMake replaces the configure step typical of many projects. Running CMake will
76 produce configuration and build files for the currently selected CMake
77 generator. For most systems the default generator is Unix Makefiles. The basic
78 form of a makefile build is the following:
80 ~~~
81     $ cmake path/to/aom
82     $ make
83 ~~~
85 The above will generate a makefile build that produces the AV1 library and
86 applications for the current host system after the make step completes
87 successfully. The compiler chosen varies by host platform, but a general rule
88 applies: On systems where cc and c++ are present in $PATH at the time CMake is
89 run the generated build will use cc and c++ by default.
91 ### Configuration options {#configuration-options}
93 The AV1 codec library has a great many configuration options. These come in two
94 varieties:
96  1. Build system configuration options. These have the form `ENABLE_FEATURE`.
97  2. AV1 codec configuration options. These have the form `CONFIG_FEATURE`.
99 Both types of options are set at the time CMake is run. The following example
100 enables ccache and disables the AV1 encoder:
103     $ cmake path/to/aom -DENABLE_CCACHE=1 -DCONFIG_AV1_ENCODER=0
104     $ make
107 The available configuration options are too numerous to list here. Build system
108 configuration options can be found at the top of the CMakeLists.txt file found
109 in the root of the AV1 repository, and AV1 codec configuration options can
110 currently be found in the file `build/cmake/aom_config_defaults.cmake`.
112 ### Dylib builds {#dylib-builds}
114 A dylib (shared object) build of the AV1 codec library can be enabled via the
115 CMake built in variable `BUILD_SHARED_LIBS`:
118     $ cmake path/to/aom -DBUILD_SHARED_LIBS=1
119     $ make
122 This is currently only supported on non-Windows targets.
124 ### Debugging {#debugging}
126 Depending on the generator used there are multiple ways of going about
127 debugging AV1 components. For single configuration generators like the Unix
128 Makefiles generator, setting `CMAKE_BUILD_TYPE` to Debug is sufficient:
131     $ cmake path/to/aom -DCMAKE_BUILD_TYPE=Debug
134 For Xcode, mainly because configuration controls for Xcode builds are buried two
135 configuration windows deep and must be set for each subproject within the Xcode
136 IDE individually, `CMAKE_CONFIGURATION_TYPES` should be set to Debug:
139     $ cmake path/to/aom -G Xcode -DCMAKE_CONFIGURATION_TYPES=Debug
142 For Visual Studio the in-IDE configuration controls should be used. Simply set
143 the IDE project configuration to Debug to allow for stepping through the code.
145 In addition to the above it can sometimes be useful to debug only C and C++
146 code. To disable all assembly code and intrinsics set `AOM_TARGET_CPU` to
147 generic at generation time:
150     $ cmake path/to/aom -DAOM_TARGET_CPU=generic
153 ### Cross compiling {#cross-compiling}
155 For the purposes of building the AV1 codec and applications and relative to the
156 scope of this guide, all builds for architectures differing from the native host
157 architecture will be considered cross compiles. The AV1 CMake build handles
158 cross compiling via the use of toolchain files included in the AV1 repository.
159 The toolchain files available at the time of this writing are:
161  - arm64-ios.cmake
162  - arm64-linux-clang.cmake
163  - arm64-linux-gcc.cmake
164  - arm64-mingw-gcc.cmake
165  - armv7-ios.cmake
166  - armv7-linux-gcc.cmake
167  - armv7-mingw-gcc.cmake
168  - armv7s-ios.cmake
169  - ppc-linux-gcc.cmake
170  - riscv-linux-gcc.cmake
171  - x86-ios-simulator.cmake
172  - x86-linux.cmake
173  - x86-macos.cmake
174  - x86-mingw-gcc.cmake
175  - x86\_64-ios-simulator.cmake
176  - x86\_64-mingw-gcc.cmake
178 The following example demonstrates use of the x86-macos.cmake toolchain file on
179 a x86\_64 MacOS host:
182     $ cmake path/to/aom \
183       -DCMAKE_TOOLCHAIN_FILE=path/to/aom/build/cmake/toolchains/x86-macos.cmake
184     $ make
187 To build for an unlisted target creation of a new toolchain file is the best
188 solution. The existing toolchain files can be used a starting point for a new
189 toolchain file since each one exposes the basic requirements for toolchain files
190 as used in the AV1 codec build.
192 As a temporary work around an unoptimized AV1 configuration that builds only C
193 and C++ sources can be produced using the following commands:
196     $ cmake path/to/aom -DAOM_TARGET_CPU=generic
197     $ make
200 In addition to the above it's important to note that the toolchain files
201 suffixed with gcc behave differently than the others. These toolchain files
202 attempt to obey the $CROSS environment variable.
204 ### Sanitizers {#sanitizers}
206 Sanitizer integration is built-in to the CMake build system. To enable a
207 sanitizer, add `-DSANITIZE=<type>` to the CMake command line. For example, to
208 enable address sanitizer:
211     $ cmake path/to/aom -DSANITIZE=address
212     $ make
215 Sanitizers available vary by platform, target, and compiler. Consult your
216 compiler documentation to determine which, if any, are available.
218 ### Microsoft Visual Studio builds {#microsoft-visual-studio-builds}
220 Building the AV1 codec library in Microsoft Visual Studio is supported. Visual
221 Studio 2019 (16.0) or later is required. The following example demonstrates
222 generating projects and a solution for the Microsoft IDE:
225     # This does not require a bash shell; Command Prompt (cmd.exe) is fine.
226     # This assumes the build host is a Windows x64 computer.
228     # To create a Visual Studio 2022 solution for the x64 target:
229     $ cmake path/to/aom -G "Visual Studio 17 2022"
231     # To create a Visual Studio 2022 solution for the 32-bit x86 target:
232     $ cmake path/to/aom -G "Visual Studio 17 2022" -A Win32
234     # To create a Visual Studio 2019 solution for the x64 target:
235     $ cmake path/to/aom -G "Visual Studio 16 2019"
237     # To create a Visual Studio 2019 solution for the 32-bit x86 target:
238     $ cmake path/to/aom -G "Visual Studio 16 2019" -A Win32
240     # To build the solution:
241     $ cmake --build .
244 NOTE: The build system targets Windows 7 or later by compiling files with
245 `-D_WIN32_WINNT=0x0601`.
247 ### Xcode builds {#xcode-builds}
249 Building the AV1 codec library in Xcode is supported. The following example
250 demonstrates generating an Xcode project:
253     $ cmake path/to/aom -G Xcode
256 ### Emscripten builds {#emscripten-builds}
258 Building the AV1 codec library with Emscripten is supported. Typically this is
259 used to hook into the AOMAnalyzer GUI application. These instructions focus on
260 using the inspector with AOMAnalyzer, but all tools can be built with
261 Emscripten.
263 It is assumed here that you have already downloaded and installed the EMSDK,
264 installed and activated at least one toolchain, and setup your environment
265 appropriately using the emsdk\_env script.
267 1. Build [AOM Analyzer](https://github.com/xiph/aomanalyzer).
269 2. Configure the build:
272     $ cmake path/to/aom \
273         -DENABLE_CCACHE=1 \
274         -DAOM_TARGET_CPU=generic \
275         -DENABLE_DOCS=0 \
276         -DENABLE_TESTS=0 \
277         -DCONFIG_ACCOUNTING=1 \
278         -DCONFIG_INSPECTION=1 \
279         -DCONFIG_MULTITHREAD=0 \
280         -DCONFIG_RUNTIME_CPU_DETECT=0 \
281         -DCONFIG_WEBM_IO=0 \
282         -DCMAKE_TOOLCHAIN_FILE=path/to/emsdk-portable/.../Emscripten.cmake
285 3. Build it: run make if that's your generator of choice:
288     $ make inspect
291 4. Run the analyzer:
294     # inspect.js is in the examples sub directory of the directory in which you
295     # executed cmake.
296     $ path/to/AOMAnalyzer path/to/examples/inspect.js path/to/av1/input/file
299 ### Extra build flags {#extra-build-flags}
301 Three variables allow for passing of additional flags to the build system.
303 - AOM\_EXTRA\_C\_FLAGS
304 - AOM\_EXTRA\_CXX\_FLAGS
305 - AOM\_EXTRA\_EXE\_LINKER\_FLAGS
307 The build system attempts to ensure the flags passed through the above variables
308 are passed to tools last in order to allow for override of default behavior.
309 These flags can be used, for example, to enable asserts in a release build:
312     $ cmake path/to/aom \
313         -DCMAKE_BUILD_TYPE=Release \
314         -DAOM_EXTRA_C_FLAGS=-UNDEBUG \
315         -DAOM_EXTRA_CXX_FLAGS=-UNDEBUG
318 ### Build with VMAF support {#build-with-vmaf}
320 After installing
321 [libvmaf.a](https://github.com/Netflix/vmaf/tree/master/libvmaf),
322 you can use it with the encoder:
325     $ cmake path/to/aom -DCONFIG_TUNE_VMAF=1
328 Please note that the default VMAF model
329 ("/usr/local/share/model/vmaf_v0.6.1.json")
330 will be used unless you set the following flag when running the encoder:
333     # --vmaf-model-path=path/to/model
336 ## Testing the AV1 codec {#testing-the-av1-codec}
338 ### Testing basics {#testing-basics}
340 There are several methods of testing the AV1 codec. All of these methods require
341 the presence of the AV1 source code and a working build of the AV1 library and
342 applications.
344 #### 1. Unit tests: {#unit-tests}
346 The unit tests can be run at build time:
349     # Before running the make command the LIBAOM_TEST_DATA_PATH environment
350     # variable should be set to avoid downloading the test files to the
351     # cmake build configuration directory.
352     $ cmake path/to/aom
353     # Note: The AV1 CMake build creates many test targets. Running make
354     # with multiple jobs will speed up the test run significantly.
355     $ make runtests
358 #### 2. Example tests: {#example-tests}
360 The example tests require a bash shell and can be run in the following manner:
363     # See the note above about LIBAOM_TEST_DATA_PATH above.
364     $ cmake path/to/aom
365     $ make
366     # It's best to build the testdata target using many make jobs.
367     # Running it like this will verify and download (if necessary)
368     # one at a time, which takes a while.
369     $ make testdata
370     $ path/to/aom/test/examples.sh --bin-path examples
373 #### 3. Encoder tests: {#encoder-tests}
375 When making a change to the encoder run encoder tests to confirm that your
376 change has a positive or negligible impact on encode quality. When running these
377 tests the build configuration should be changed to enable internal encoder
378 statistics:
381     $ cmake path/to/aom -DCONFIG_INTERNAL_STATS=1
382     $ make
385 The repository contains scripts intended to make running these tests as simple
386 as possible. The following example demonstrates creating a set of baseline clips
387 for comparison to results produced after making your change to libaom:
390     # This will encode all Y4M files in the current directory using the
391     # settings specified to create the encoder baseline statistical data:
392     $ cd path/to/test/inputs
393     # This command line assumes that run_encodes.sh, its helper script
394     # best_encode.sh, and the aomenc you intend to test are all within a
395     # directory in your PATH.
396     $ run_encodes.sh 200 500 50 baseline
399 After making your change and creating the baseline clips, you'll need to run
400 encodes that include your change(s) to confirm that things are working as
401 intended:
404     # This will encode all Y4M files in the current directory using the
405     # settings specified to create the statistical data for your change:
406     $ cd path/to/test/inputs
407     # This command line assumes that run_encodes.sh, its helper script
408     # best_encode.sh, and the aomenc you intend to test are all within a
409     # directory in your PATH.
410     $ run_encodes.sh 200 500 50 mytweak
413 After creating both data sets you can use `test/visual_metrics.py` to generate a
414 report that can be viewed in a web browser:
417     $ visual_metrics.py metrics_template.html "*stt" baseline mytweak \
418       > mytweak.html
421 You can view the report by opening mytweak.html in a web browser.
424 ### IDE hosted tests {#ide-hosted-tests}
426 By default the generated projects files created by CMake will not include the
427 runtests and testdata rules when generating for IDEs like Microsoft Visual
428 Studio and Xcode. This is done to avoid intolerably long build cycles in the
429 IDEs-- IDE behavior is to build all targets when selecting the build project
430 options in MSVS and Xcode. To enable the test rules in IDEs the
431 `ENABLE_IDE_TEST_HOSTING` variable must be enabled at CMake generation time:
434     # This example uses Xcode. To get a list of the generators
435     # available, run cmake with the -G argument missing its
436     # value.
437     $ cmake path/to/aom -DENABLE_IDE_TEST_HOSTING=1 -G Xcode
440 ### Downloading the test data {#downloading-the-test-data}
442 The fastest and easiest way to obtain the test data is to use CMake to generate
443 a build using the Unix Makefiles generator, and then to build only the testdata
444 rule. By default the test files will be downloaded to the current directory. The
445 `LIBAOM_TEST_DATA_PATH` environment variable can be used to set a
446 custom one.
449     $ cmake path/to/aom -G "Unix Makefiles"
450     # 28 is used because there are 28 test files as of this writing.
451     $ make -j28 testdata
454 The above make command will only download and verify the test data.
456 ### Adding a new test data file {#adding-a-new-test-data-file}
458 First, add the new test data file to the `aom-test-data` bucket of the
459 `aomedia-testing` project on Google Cloud Platform. You may need to ask someone
460 with the necessary access permissions to do this for you.
462 NOTE: When a new test data file is added to the `aom-test-data` bucket, its
463 "Public access" is initially "Not public". We need to change its
464 "Public access" to "Public" by using the following
465 [`gsutil`](https://cloud.google.com/storage/docs/gsutil_install) command:
467     $ gsutil acl ch -g all:R gs://aom-test-data/test-data-file-name
469 This command grants the `AllUsers` group READ access to the file named
470 "test-data-file-name" in the `aom-test-data` bucket.
472 Once the new test data file has been added to `aom-test-data`, create a CL to
473 add the name of the new test data file to `test/test_data_util.cmake` and add
474 the SHA1 checksum of the new test data file to `test/test-data.sha1`. (The SHA1
475 checksum of a file can be calculated by running the `sha1sum` command on the
476 file.)
478 ### Additional test data {#additional-test-data}
480 The test data mentioned above is strictly intended for unit testing.
482 Additional input data for testing the encoder can be obtained from:
483 https://media.xiph.org/video/derf/
485 ### Sharded testing {#sharded-testing}
487 The AV1 codec library unit tests are built upon gtest which supports sharding of
488 test jobs. Sharded test runs can be achieved in a couple of ways.
490 #### 1. Running test\_libaom directly: {#running-test_libaom-directly}
493    # Set the environment variable GTEST_TOTAL_SHARDS to control the number of
494    # shards.
495    $ export GTEST_TOTAL_SHARDS=10
496    # (GTEST shard indexing is 0 based).
497    $ seq 0 $(( $GTEST_TOTAL_SHARDS - 1 )) \
498        | xargs -n 1 -P 0 -I{} env GTEST_SHARD_INDEX={} ./test_libaom
501 To create a test shard for each CPU core available on the current system set
502 `GTEST_TOTAL_SHARDS` to the number of CPU cores on your system minus one.
504 #### 2. Running the tests via the CMake build: {#running-the-tests-via-the-cmake-build}
507     # For IDE based builds, ENABLE_IDE_TEST_HOSTING must be enabled. See
508     # the IDE hosted tests section above for more information. If the IDE
509     # supports building targets concurrently tests will be sharded by default.
511     # For make and ninja builds the -j parameter controls the number of shards
512     # at test run time. This example will run the tests using 10 shards via
513     # make.
514     $ make -j10 runtests
517 The maximum number of test targets that can run concurrently is determined by
518 the number of CPUs on the system where the build is configured as detected by
519 CMake. A system with 24 cores can run 24 test shards using a value of 24 with
520 the `-j` parameter. When CMake is unable to detect the number of cores 10 shards
521 is the default maximum value.
523 ## Coding style {#coding-style}
525 We are using the Google C Coding Style defined by the
526 [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
528 The coding style used by this project is enforced with clang-format using the
529 configuration contained in the
530 [.clang-format](https://chromium.googlesource.com/webm/aom/+/main/.clang-format)
531 file in the root of the repository.
533 You can download clang-format using your system's package manager, or directly
534 from [llvm.org](http://llvm.org/releases/download.html). You can also view the
535 [documentation](https://clang.llvm.org/docs/ClangFormat.html) on llvm.org.
536 Output from clang-format varies by clang-format version, for best results your
537 version should match the one used on Jenkins. You can find the clang-format
538 version by reading the comment in the `.clang-format` file linked above.
540 Before pushing changes for review you can format your code with:
543     # Apply clang-format to modified .c, .h and .cc files
544     $ clang-format -i --style=file \
545       $(git diff --name-only --diff-filter=ACMR '*.[hc]' '*.cc')
548 Check the .clang-format file for the version used to generate it if there is any
549 difference between your local formatting and the review system.
551 Some Git installations have clang-format integration. Here are some examples:
554     # Apply clang-format to all staged changes:
555     $ git clang-format
557     # Clang format all staged and unstaged changes:
558     $ git clang-format -f
560     # Clang format all staged and unstaged changes interactively:
561     $ git clang-format -f -p
564 ## Submitting patches {#submitting-patches}
566 We manage the submission of patches using the
567 [Gerrit](https://www.gerritcodereview.com/) code review tool. This tool
568 implements a workflow on top of the Git version control system to ensure that
569 all changes get peer reviewed and tested prior to their distribution.
571 ### Login cookie {#login-cookie}
573 Browse to [AOMedia Git index](https://aomedia.googlesource.com/) and login with
574 your account (Gmail credentials, for example). Next, follow the
575 `Generate Password` Password link at the top of the page. You’ll be given
576 instructions for creating a cookie to use with our Git repos.
578 You must also have a Gerrit account associated with your Google account. To do
579 this visit the [Gerrit review server](https://aomedia-review.googlesource.com)
580 and click "Sign in" (top right).
582 ### Contributor agreement {#contributor-agreement}
584 You will be required to execute a
585 [contributor agreement](http://aomedia.org/license) to ensure that the AOMedia
586 Project has the right to distribute your changes.
588 Note: If you are pushing changes on behalf of an Alliance for Open Media member
589 organization this step is not necessary.
591 ### Testing your code {#testing-your-code}
593 The testing basics are covered in the [testing section](#testing-the-av1-codec)
594 above.
596 In addition to the local tests, many more (e.g. asan, tsan, valgrind) will run
597 through Jenkins instances upon upload to gerrit.
599 ### Commit message hook {#commit-message-hook}
601 Gerrit requires that each submission include a unique Change-Id. You can assign
602 one manually using git commit --amend, but it’s easier to automate it with the
603 commit-msg hook provided by Gerrit.
605 Copy commit-msg to the `.git/hooks` directory of your local repo. Here's an
606 example:
609     $ curl -Lo aom/.git/hooks/commit-msg https://chromium-review.googlesource.com/tools/hooks/commit-msg
611     # Next, ensure that the downloaded commit-msg script is executable:
612     $ chmod u+x aom/.git/hooks/commit-msg
615 See the Gerrit
616 [documentation](https://gerrit-review.googlesource.com/Documentation/user-changeid.html)
617 for more information.
619 ### Upload your change {#upload-your-change}
621 The command line to upload your patch looks like this:
624     $ git push https://aomedia-review.googlesource.com/aom HEAD:refs/for/main
627 ### Incorporating reviewer comments {#incorporating-reviewer-comments}
629 If you previously uploaded a change to Gerrit and the Approver has asked for
630 changes, follow these steps:
632 1. Edit the files to make the changes the reviewer has requested.
633 2. Recommit your edits using the --amend flag, for example:
636    $ git commit -a --amend
639 3. Use the same git push command as above to upload to Gerrit again for another
640    review cycle.
642 In general, you should not rebase your changes when doing updates in response to
643 review. Doing so can make it harder to follow the evolution of your change in
644 the diff view.
646 ### Submitting your change {#submitting-your-change}
648 Once your change has been Approved and Verified, you can “submit” it through the
649 Gerrit UI. This will usually automatically rebase your change onto the branch
650 specified.
652 Sometimes this can’t be done automatically. If you run into this problem, you
653 must rebase your changes manually:
656     $ git fetch
657     $ git rebase origin/branchname
660 If there are any conflicts, resolve them as you normally would with Git. When
661 you’re done, reupload your change.
663 ### Viewing the status of uploaded changes {#viewing-the-status-of-uploaded-changes}
665 To check the status of a change that you uploaded, open
666 [Gerrit](https://aomedia-review.googlesource.com/), sign in, and click My >
667 Changes.
669 ## Support {#support}
671 This library is an open source project supported by its community. Please
672 please email aomediacodec@jointdevelopment.kavi.com for help.
674 ## Bug reports {#bug-reports}
676 Bug reports can be filed in the Alliance for Open Media
677 [issue tracker](https://bugs.chromium.org/p/aomedia/issues/list).