Lines Matching +full:- +full:- +full:build +full:- +full:and +full:- +full:test
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. [License header](#license-header)
34 5. [Submitting patches](#submitting-patches)
35 - [Login cookie](#login-cookie)
36 - [Contributor agreement](#contributor-agreement)
37 - [Testing your code](#testing-your-code)
38 - [Commit message hook](#commit-message-hook)
39 - [Upload your change](#upload-your-change)
40 - [Incorporating Reviewer Comments](#incorporating-reviewer-comments)
41 - [Submitting your change](#submitting-your-change)
42 - [Viewing change status](#viewing-the-status-of-uploaded-changes)
44 7. [Bug reports](#bug-reports)
46 ## Building the library and applications {#building-the-library-and-applications}
52 2. [Git](https://git-scm.com/).
54 the latest version of MinGW-w64 (clang64 or ucrt toolchains) are
55 recommended. A C++ compiler is necessary to build the unit tests and some
59 or later) of [nasm](http://www.nasm.us/). (If both yasm and nasm are
60 present, yasm will be used by default. Pass -DENABLE_NASM=ON to cmake to
62 Studio, please download win32.exe or win64.exe and rename it into yasm.exe.
64 also be used and avoids an issue caused by a missing Visual C++
69 [EMSDK](https://kripken.github.io/emscripten-site/index.html).
71 ### Get the code {#get-the-code}
82 ### Basic build {#basic-build}
85 produce configuration and build files for the currently selected CMake
87 form of a makefile build is the following:
94 The above will generate a makefile build that produces the AV1 library and
97 applies: On systems where cc and c++ are present in $PATH at the time CMake is
98 run the generated build will use cc and c++ by default.
100 ### Configuration options {#configuration-options}
105 1. Build system configuration options. These have the form `ENABLE_FEATURE`.
109 enables ccache and disables the AV1 encoder:
112 $ cmake path/to/aom -DENABLE_CCACHE=1 -DCONFIG_AV1_ENCODER=0
116 The available configuration options are too numerous to list here. Build system
118 in the root of the AV1 repository, and AV1 codec configuration options can
119 currently be found in the file `build/cmake/aom_config_defaults.cmake`.
121 ### Dylib builds {#dylib-builds}
123 A dylib (shared object) build of the AV1 codec library can be enabled via the
127 $ cmake path/to/aom -DBUILD_SHARED_LIBS=1
131 This is currently only supported on non-Windows targets.
140 $ cmake path/to/aom -DCMAKE_BUILD_TYPE=Debug
144 configuration windows deep and must be set for each subproject within the Xcode
148 $ cmake path/to/aom -G Xcode -DCMAKE_CONFIGURATION_TYPES=Debug
151 For Visual Studio the in-IDE configuration controls should be used. Simply set
154 In addition to the above it can sometimes be useful to debug only C and C++
155 code. To disable all assembly code and intrinsics set `AOM_TARGET_CPU` to
159 $ cmake path/to/aom -DAOM_TARGET_CPU=generic
162 ### Cross compiling {#cross-compiling}
164 For the purposes of building the AV1 codec and applications and relative to the
166 architecture will be considered cross compiles. The AV1 CMake build handles
170 - arm64-ios.cmake
171 - arm64-linux-clang.cmake
172 - arm64-linux-gcc.cmake
173 - arm64-mingw-gcc.cmake
174 - armv7-ios.cmake
175 - armv7-linux-gcc.cmake
176 - armv7-mingw-gcc.cmake
177 - armv7s-ios.cmake
178 - ppc-linux-gcc.cmake
179 - riscv-linux-gcc.cmake
180 - x86-ios-simulator.cmake
181 - x86-linux.cmake
182 - x86-macos.cmake
183 - x86-mingw-gcc.cmake
184 - x86\_64-ios-simulator.cmake
185 - x86\_64-mingw-gcc.cmake
187 The following example demonstrates use of the x86-macos.cmake toolchain file on
192 -DCMAKE_TOOLCHAIN_FILE=path/to/aom/build/cmake/toolchains/x86-macos.cmake
196 To build for an unlisted target creation of a new toolchain file is the best
199 as used in the AV1 codec build.
202 and C++ sources can be produced using the following commands:
205 $ cmake path/to/aom -DAOM_TARGET_CPU=generic
215 Sanitizer integration is built-in to the CMake build system. To enable a
216 sanitizer, add `-DSANITIZE=<type>` to the CMake command line. For example, to
220 $ cmake path/to/aom -DSANITIZE=address
224 Sanitizers available vary by platform, target, and compiler. Consult your
227 ### Microsoft Visual Studio builds {#microsoft-visual-studio-builds}
231 generating projects and a solution for the Microsoft IDE:
235 # This assumes the build host is a Windows x64 computer.
238 $ cmake path/to/aom -G "Visual Studio 17 2022"
240 # To create a Visual Studio 2022 solution for the 32-bit x86 target:
241 $ cmake path/to/aom -G "Visual Studio 17 2022" -A Win32
244 $ cmake path/to/aom -G "Visual Studio 16 2019"
246 # To create a Visual Studio 2019 solution for the 32-bit x86 target:
247 $ cmake path/to/aom -G "Visual Studio 16 2019" -A Win32
249 # To build the solution:
250 $ cmake --build .
253 NOTE: The build system targets Windows 7 or later by compiling files with
254 `-D_WIN32_WINNT=0x0601`.
256 ### Xcode builds {#xcode-builds}
262 $ cmake path/to/aom -G Xcode
265 ### Emscripten builds {#emscripten-builds}
272 It is assumed here that you have already downloaded and installed the EMSDK,
273 installed and activated at least one toolchain, and setup your environment
276 1. Build [AOM Analyzer](https://github.com/xiph/aomanalyzer).
278 2. Configure the build:
282 -DENABLE_CCACHE=1 \
283 -DAOM_TARGET_CPU=generic \
284 -DENABLE_DOCS=0 \
285 -DENABLE_TESTS=0 \
286 -DCONFIG_ACCOUNTING=1 \
287 -DCONFIG_INSPECTION=1 \
288 -DCONFIG_MULTITHREAD=0 \
289 -DCONFIG_RUNTIME_CPU_DETECT=0 \
290 -DCONFIG_WEBM_IO=0 \
291 -DCMAKE_TOOLCHAIN_FILE=path/to/emsdk-portable/.../Emscripten.cmake
294 3. Build it: run make if that's your generator of choice:
308 ### Extra build flags {#extra-build-flags}
310 Three variables allow for passing of additional flags to the build system.
312 - AOM\_EXTRA\_C\_FLAGS
313 - AOM\_EXTRA\_CXX\_FLAGS
314 - AOM\_EXTRA\_EXE\_LINKER\_FLAGS
316 The build system attempts to ensure the flags passed through the above variables
318 These flags can be used, for example, to enable asserts in a release build:
322 -DCMAKE_BUILD_TYPE=Release \
323 -DAOM_EXTRA_C_FLAGS=-UNDEBUG \
324 -DAOM_EXTRA_CXX_FLAGS=-UNDEBUG
327 ### Build with VMAF support {#build-with-vmaf}
334 $ cmake path/to/aom -DCONFIG_TUNE_VMAF=1
342 # --vmaf-model-path=path/to/model
345 ## Testing the AV1 codec {#testing-the-av1-codec}
347 ### Testing basics {#testing-basics}
350 the presence of the AV1 source code and a working build of the AV1 library and
353 #### 1. Unit tests: {#unit-tests}
355 The unit tests can be run at build time:
359 # variable should be set to avoid downloading the test files to the
360 # cmake build configuration directory.
362 # Note: The AV1 CMake build creates many test targets. Running make
363 # with multiple jobs will speed up the test run significantly.
367 #### 2. Example tests: {#example-tests}
369 The example tests require a bash shell and can be run in the following manner:
375 # It's best to build the testdata target using many make jobs.
376 # Running it like this will verify and download (if necessary)
379 $ path/to/aom/test/examples.sh --bin-path examples
382 #### 3. Encoder tests: {#encoder-tests}
386 tests the build configuration should be changed to enable internal encoder
390 $ cmake path/to/aom -DCONFIG_INTERNAL_STATS=1
401 $ cd path/to/test/inputs
403 # best_encode.sh, and the aomenc you intend to test are all within a
408 After making your change and creating the baseline clips, you'll need to run
415 $ cd path/to/test/inputs
417 # best_encode.sh, and the aomenc you intend to test are all within a
422 After creating both data sets you can use `test/visual_metrics.py` to generate a
433 ### IDE hosted tests {#ide-hosted-tests}
436 runtests and testdata rules when generating for IDEs like Microsoft Visual
437 Studio and Xcode. This is done to avoid intolerably long build cycles in the
438 IDEs-- IDE behavior is to build all targets when selecting the build project
439 options in MSVS and Xcode. To enable the test rules in IDEs the
444 # available, run cmake with the -G argument missing its
446 $ cmake path/to/aom -DENABLE_IDE_TEST_HOSTING=1 -G Xcode
449 ### Downloading the test data {#downloading-the-test-data}
451 The fastest and easiest way to obtain the test data is to use CMake to generate
452 a build using the Unix Makefiles generator, and then to build only the testdata
453 rule. By default the test files will be downloaded to the current directory. The
458 $ cmake path/to/aom -G "Unix Makefiles"
459 # 28 is used because there are 28 test files as of this writing.
460 $ make -j28 testdata
463 The above make command will only download and verify the test data.
465 ### Adding a new test data file {#adding-a-new-test-data-file}
467 First, add the new test data file to the `aom-test-data` bucket of the
468 `aomedia-testing` project on Google Cloud Platform. You may need to ask someone
471 NOTE: When a new test data file is added to the `aom-test-data` bucket, its
476 $ gsutil acl ch -g all:R gs://aom-test-data/test-data-file-name
479 "test-data-file-name" in the `aom-test-data` bucket.
481 Once the new test data file has been added to `aom-test-data`, create a CL to
482 add the name of the new test data file to `test/test_data_util.cmake` and add
483 the SHA1 checksum of the new test data file to `test/test-data.sha1`. (The SHA1
487 ### Additional test data {#additional-test-data}
489 The test data mentioned above is strictly intended for unit testing.
494 ### Sharded testing {#sharded-testing}
497 test jobs. Sharded test runs can be achieved in a couple of ways.
499 #### 1. Running test\_libaom directly: {#running-test_libaom-directly}
506 $ seq 0 $(( $GTEST_TOTAL_SHARDS - 1 )) \
507 | xargs -n 1 -P 0 -I{} env GTEST_SHARD_INDEX={} ./test_libaom
510 To create a test shard for each CPU core available on the current system set
513 #### 2. Running the tests via the CMake build: {#running-the-tests-via-the-cmake-build}
520 # For make and ninja builds the -j parameter controls the number of shards
521 # at test run time. This example will run the tests using 10 shards via
523 $ make -j10 runtests
526 The maximum number of test targets that can run concurrently is determined by
527 the number of CPUs on the system where the build is configured as detected by
528 CMake. A system with 24 cores can run 24 test shards using a value of 24 with
529 the `-j` parameter. When CMake is unable to detect the number of cores 10 shards
532 ## Coding style {#coding-style}
537 The coding style used by this project is enforced with clang-format using the
539 [.clang-format](https://chromium.googlesource.com/webm/aom/+/main/.clang-format)
542 You can download clang-format using your system's package manager, or directly
545 Output from clang-format varies by clang-format version, for best results your
546 version should match the one used on Jenkins. You can find the clang-format
547 version by reading the comment in the `.clang-format` file linked above.
552 # Apply clang-format to modified .c, .h and .cc files
553 $ clang-format -i --style=file \
554 $(git diff --name-only --diff-filter=ACMR '*.[hc]' '*.cc')
557 Check the .clang-format file for the version used to generate it if there is any
558 difference between your local formatting and the review system.
560 Some Git installations have clang-format integration. Here are some examples:
563 # Apply clang-format to all staged changes:
564 $ git clang-format
566 # Clang format all staged and unstaged changes:
567 $ git clang-format -f
569 # Clang format all staged and unstaged changes interactively:
570 $ git clang-format -f -p
573 ## License header {#license-header}
583 * This source code is subject to the terms of the BSD 2 Clause License and
592 ## Submitting patches {#submitting-patches}
597 all changes get peer reviewed and tested prior to their distribution.
599 ### Login cookie {#login-cookie}
601 Browse to [AOMedia Git index](https://aomedia.googlesource.com/) and login with
607 this visit the [Gerrit review server](https://aomedia-review.googlesource.com)
608 and click "Sign in" (top right).
610 ### Contributor agreement {#contributor-agreement}
619 ### Testing your code {#testing-your-code}
621 The testing basics are covered in the [testing section](#testing-the-av1-codec)
627 ### Commit message hook {#commit-message-hook}
629 Gerrit requires that each submission include a unique Change-Id. You can assign
630 one manually using git commit --amend, but it’s easier to automate it with the
631 commit-msg hook provided by Gerrit.
633 Copy commit-msg to the `.git/hooks` directory of your local repo. Here's an
637 …$ curl -Lo aom/.git/hooks/commit-msg https://chromium-review.googlesource.com/tools/hooks/commit-m…
639 # Next, ensure that the downloaded commit-msg script is executable:
640 $ chmod u+x aom/.git/hooks/commit-msg
644 [documentation](https://gerrit-review.googlesource.com/Documentation/user-changeid.html)
647 ### Upload your change {#upload-your-change}
652 $ git push https://aomedia-review.googlesource.com/aom HEAD:refs/for/main
655 ### Incorporating reviewer comments {#incorporating-reviewer-comments}
657 If you previously uploaded a change to Gerrit and the Approver has asked for
661 2. Recommit your edits using the --amend flag, for example:
664 $ git commit -a --amend
674 ### Submitting your change {#submitting-your-change}
676 Once your change has been Approved and Verified, you can “submit” it through the
691 ### Viewing the status of uploaded changes {#viewing-the-status-of-uploaded-changes}
694 [Gerrit](https://aomedia-review.googlesource.com/), sign in, and click My >
702 ## Bug reports {#bug-reports}