1# Getting Started 2 3How to get and build the libyuv code. 4 5## Pre-requisites 6 7You'll need to have depot tools installed: https://www.chromium.org/developers/how-tos/install-depot-tools 8Refer to chromium instructions for each platform for other prerequisites. 9 10## Getting the Code 11 12Create a working directory, enter it, and run: 13 14 gclient config https://chromium.googlesource.com/libyuv/libyuv 15 gclient sync 16 17 18Then you'll get a .gclient file like: 19 20 solutions = [ 21 { "name" : "libyuv", 22 "url" : "https://chromium.googlesource.com/libyuv/libyuv", 23 "deps_file" : "DEPS", 24 "managed" : True, 25 "custom_deps" : { 26 }, 27 "safesync_url": "", 28 }, 29 ]; 30 31 32For iOS add `;target_os=['ios'];` to your OSX .gclient and run `GYP_DEFINES="OS=ios" gclient sync.` 33 34Browse the Git reprository: https://chromium.googlesource.com/libyuv/libyuv/+/master 35 36### Android 37For Android add `;target_os=['android'];` to your Linux .gclient 38 39 40 solutions = [ 41 { "name" : "libyuv", 42 "url" : "https://chromium.googlesource.com/libyuv/libyuv", 43 "deps_file" : "DEPS", 44 "managed" : True, 45 "custom_deps" : { 46 }, 47 "safesync_url": "", 48 }, 49 ]; 50 target_os = ["android", "unix"]; 51 52Then run: 53 54 export GYP_DEFINES="OS=android" 55 gclient sync 56 57Caveat: Theres an error with Google Play services updates. If you get the error "Your version of the Google Play services library is not up to date", run the following: 58 cd chromium/src 59 ./build/android/play_services/update.py download 60 cd ../.. 61 62For Windows the gclient sync must be done from an Administrator command prompt. 63 64The sync will generate native build files for your environment using gyp (Windows: Visual Studio, OSX: XCode, Linux: make). This generation can also be forced manually: `gclient runhooks` 65 66To get just the source (not buildable): 67 git clone https://chromium.googlesource.com/libyuv/libyuv 68 69 70## Building the Library and Unittests 71 72### Windows 73 74 set GYP_DEFINES=target_arch=ia32 75 call python gyp_libyuv -fninja -G msvs_version=2013 76 ninja -j7 -C out\Release 77 ninja -j7 -C out\Debug 78 79 set GYP_DEFINES=target_arch=x64 80 call python gyp_libyuv -fninja -G msvs_version=2013 81 ninja -C out\Debug_x64 82 ninja -C out\Release_x64 83 84#### Building with clangcl 85 set GYP_DEFINES=clang=1 target_arch=ia32 libyuv_enable_svn=1 86 set LLVM_REPO_URL=svn://svn.chromium.org/llvm-project 87 call python tools\clang\scripts\update.py 88 call python gyp_libyuv -fninja libyuv_test.gyp 89 ninja -C out\Debug 90 ninja -C out\Release 91 92### OSX 93 94Clang 64 bit shown. Remove `clang=1` for GCC and change x64 to ia32 for 32 bit. 95 96 GYP_DEFINES="clang=1 target_arch=x64" ./gyp_libyuv 97 ninja -j7 -C out/Debug 98 ninja -j7 -C out/Release 99 100 GYP_DEFINES="clang=1 target_arch=ia32" ./gyp_libyuv 101 ninja -j7 -C out/Debug 102 ninja -j7 -C out/Release 103 104### iOS 105http://www.chromium.org/developers/how-tos/build-instructions-ios 106 107Add to .gclient last line: `target_os=['ios'];` 108 109armv7 110 111 GYP_DEFINES="OS=ios target_arch=armv7 target_subarch=arm32" GYP_CROSSCOMPILE=1 GYP_GENERATOR_FLAGS="output_dir=out_ios" ./gyp_libyuv 112 ninja -j7 -C out_ios/Debug-iphoneos libyuv_unittest 113 ninja -j7 -C out_ios/Release-iphoneos libyuv_unittest 114 115arm64 116 117 GYP_DEFINES="OS=ios target_arch=arm64 target_subarch=arm64" GYP_CROSSCOMPILE=1 GYP_GENERATOR_FLAGS="output_dir=out_ios" ./gyp_libyuv 118 ninja -j7 -C out_ios/Debug-iphoneos libyuv_unittest 119 ninja -j7 -C out_ios/Release-iphoneos libyuv_unittest 120 121both armv7 and arm64 (fat) 122 123 GYP_DEFINES="OS=ios target_arch=armv7 target_subarch=both" GYP_CROSSCOMPILE=1 GYP_GENERATOR_FLAGS="output_dir=out_ios" ./gyp_libyuv 124 ninja -j7 -C out_ios/Debug-iphoneos libyuv_unittest 125 ninja -j7 -C out_ios/Release-iphoneos libyuv_unittest 126 127simulator 128 129 GYP_DEFINES="OS=ios target_arch=ia32 target_subarch=arm32" GYP_CROSSCOMPILE=1 GYP_GENERATOR_FLAGS="output_dir=out_sim" ./gyp_libyuv 130 ninja -j7 -C out_sim/Debug-iphonesimulator libyuv_unittest 131 ninja -j7 -C out_sim/Release-iphonesimulator libyuv_unittest 132 133### Android 134https://code.google.com/p/chromium/wiki/AndroidBuildInstructions 135 136Add to .gclient last line: `target_os=['android'];` 137 138armv7 139 140 GYP_DEFINES="OS=android" GYP_CROSSCOMPILE=1 ./gyp_libyuv 141 ninja -j7 -C out/Debug libyuv_unittest_apk 142 ninja -j7 -C out/Release libyuv_unittest_apk 143 144arm64 145 146 GYP_DEFINES="OS=android target_arch=arm64 target_subarch=arm64" GYP_CROSSCOMPILE=1 ./gyp_libyuv 147 ninja -j7 -C out/Debug libyuv_unittest_apk 148 ninja -j7 -C out/Release libyuv_unittest_apk 149 150ia32 151 152 GYP_DEFINES="OS=android target_arch=ia32" GYP_CROSSCOMPILE=1 ./gyp_libyuv 153 ninja -j7 -C out/Debug libyuv_unittest_apk 154 ninja -j7 -C out/Release libyuv_unittest_apk 155 156 GYP_DEFINES="OS=android target_arch=ia32 android_full_debug=1" GYP_CROSSCOMPILE=1 ./gyp_libyuv 157 ninja -j7 -C out/Debug libyuv_unittest_apk 158 159mipsel 160 161 GYP_DEFINES="OS=android target_arch=mipsel" GYP_CROSSCOMPILE=1 ./gyp_libyuv 162 ninja -j7 -C out/Debug libyuv_unittest_apk 163 ninja -j7 -C out/Release libyuv_unittest_apk 164 165arm32 disassembly: 166 167 third_party/android_tools/ndk/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin/arm-linux-androideabi-objdump -d out/Release/obj/source/libyuv.row_neon.o 168 169arm64 disassembly: 170 171 third_party/android_tools/ndk/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-objdump -d out/Release/obj/source/libyuv.row_neon64.o 172 173Running tests: 174 175 util/android/test_runner.py gtest -s libyuv_unittest -t 7200 --verbose --release --gtest_filter=* 176 177Running test as benchmark: 178 179 util/android/test_runner.py gtest -s libyuv_unittest -t 7200 --verbose --release --gtest_filter=* -a "--libyuv_width=1280 --libyuv_height=720 --libyuv_repeat=999 --libyuv_flags=-1" 180 181Running test with C code: 182 183 util/android/test_runner.py gtest -s libyuv_unittest -t 7200 --verbose --release --gtest_filter=* -a "--libyuv_width=1280 --libyuv_height=720 --libyuv_repeat=999 --libyuv_flags=1 --libyuv_cpu_info=1" 184 185#### Building with GN 186 187 gn gen out/Release "--args=is_debug=false target_cpu=\"x86\"" 188 gn gen out/Debug "--args=is_debug=true target_cpu=\"x86\"" 189 ninja -C out/Release 190 ninja -C out/Debug 191 192### Building Offical with GN 193 194 gn gen out/Official "--args=is_debug=false is_official_build=true is_chrome_branded=true" 195 ninja -C out/Official 196 197### Linux 198 199 GYP_DEFINES="target_arch=x64" ./gyp_libyuv 200 ninja -j7 -C out/Debug 201 ninja -j7 -C out/Release 202 203 GYP_DEFINES="target_arch=ia32" ./gyp_libyuv 204 ninja -j7 -C out/Debug 205 ninja -j7 -C out/Release 206 207#### CentOS 208 209On CentOS 32 bit the following work around allows a sync: 210 211 export GYP_DEFINES="host_arch=ia32" 212 gclient sync 213 214### Windows Shared Library 215 216Modify libyuv.gyp from 'static_library' to 'shared_library', and add 'LIBYUV_BUILDING_SHARED_LIBRARY' to 'defines'. 217 218 gclient runhooks 219 220After this command follow the building the library instructions above. 221 222If you get a compile error for atlthunk.lib on Windows, read http://www.chromium.org/developers/how-tos/build-instructions-windows 223 224 225### Build targets 226 227 ninja -C out/Debug libyuv 228 ninja -C out/Debug libyuv_unittest 229 ninja -C out/Debug compare 230 ninja -C out/Debug convert 231 ninja -C out/Debug psnr 232 ninja -C out/Debug cpuid 233 234 235## Building the Library with make 236 237### Linux 238 239 make -j7 V=1 -f linux.mk 240 make -j7 V=1 -f linux.mk clean 241 make -j7 V=1 -f linux.mk CXX=clang++ 242 243## Building the Library with cmake 244 245Install cmake: http://www.cmake.org/ 246 247Default debug build: 248 249 mkdir out 250 cd out 251 cmake .. 252 cmake --build . 253 254Release build/install 255 256 mkdir out 257 cd out 258 cmake -DCMAKE_INSTALL_PREFIX="/usr/lib" -DCMAKE_BUILD_TYPE="Release" .. 259 cmake --build . --config Release 260 sudo cmake --build . --target install --config Release 261 262### Windows 8 Phone 263 264Pre-requisite: 265 266* Install Visual Studio 2012 and Arm to your environment.<br> 267 268Then: 269 270 call "c:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\bin\x86_arm\vcvarsx86_arm.bat" 271 272or with Visual Studio 2013: 273 274 call "c:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\x86_arm\vcvarsx86_arm.bat" 275 nmake /f winarm.mk clean 276 nmake /f winarm.mk 277 278### Windows Shared Library 279 280Modify libyuv.gyp from 'static_library' to 'shared_library', and add 'LIBYUV_BUILDING_SHARED_LIBRARY' to 'defines'. Then run this. 281 282 gclient runhooks 283 284After this command follow the building the library instructions above. 285 286If you get a compile error for atlthunk.lib on Windows, read http://www.chromium.org/developers/how-tos/build-instructions-windows 287 288### 64 bit Windows 289 290 set GYP_DEFINES=target_arch=x64 291 gclient runhooks V=1 292 293### ARM Linux 294 295 export GYP_DEFINES="target_arch=arm" 296 export CROSSTOOL=`<path>`/arm-none-linux-gnueabi 297 export CXX=$CROSSTOOL-g++ 298 export CC=$CROSSTOOL-gcc 299 export AR=$CROSSTOOL-ar 300 export AS=$CROSSTOOL-as 301 export RANLIB=$CROSSTOOL-ranlib 302 gclient runhooks 303 304## Running Unittests 305 306### Windows 307 308 out\Release\libyuv_unittest.exe --gtest_catch_exceptions=0 --gtest_filter="*" 309 310### OSX 311 312 out/Release/libyuv_unittest --gtest_filter="*" 313 314### Linux 315 316 out/Release/libyuv_unittest --gtest_filter="*" 317 318Replace --gtest_filter="*" with specific unittest to run. May include wildcards. e.g. 319 320 out/Release/libyuv_unittest --gtest_filter=libyuvTest.I420ToARGB_Opt 321 322## CPU Emulator tools 323 324### Intel SDE (Software Development Emulator) 325 326Pre-requisite: Install IntelSDE for Windows: http://software.intel.com/en-us/articles/intel-software-development-emulator 327 328Then run: 329 330 c:\intelsde\sde -hsw -- out\release\libyuv_unittest.exe --gtest_filter=* 331 332 333## Memory tools 334 335### Running Dr Memory memcheck for Windows 336 337Pre-requisite: Install Dr Memory for Windows and add it to your path: http://www.drmemory.org/docs/page_install_windows.html 338 339 set GYP_DEFINES=build_for_tool=drmemory target_arch=ia32 340 call python gyp_libyuv -fninja -G msvs_version=2013 341 ninja -C out\Debug 342 drmemory out\Debug\libyuv_unittest.exe --gtest_catch_exceptions=0 --gtest_filter=* 343 344### Running UBSan 345 346See Chromium instructions for sanitizers: https://www.chromium.org/developers/testing/undefinedbehaviorsanitizer 347 348Sanitizers available: TSan, MSan, ASan, UBSan, LSan 349 350 GYP_DEFINES='ubsan=1' gclient runhooks 351 ninja -C out/Release 352 353### Running Valgrind memcheck 354 355Memory errors and race conditions can be found by running tests under special memory tools. [Valgrind] [1] is an instrumentation framework for building dynamic analysis tools. Various tests and profilers are built upon it to find memory handling errors and memory leaks, for instance. 356 357[1]: http://valgrind.org 358 359 solutions = [ 360 { "name" : "libyuv", 361 "url" : "https://chromium.googlesource.com/libyuv/libyuv", 362 "deps_file" : "DEPS", 363 "managed" : True, 364 "custom_deps" : { 365 "libyuv/chromium/src/third_party/valgrind": "https://chromium.googlesource.com/chromium/deps/valgrind/binaries", 366 }, 367 "safesync_url": "", 368 }, 369 ] 370 371Then run: 372 373 GYP_DEFINES="clang=0 target_arch=x64 build_for_tool=memcheck" python gyp_libyuv 374 ninja -C out/Debug 375 valgrind out/Debug/libyuv_unittest 376 377 378For more information, see http://www.chromium.org/developers/how-tos/using-valgrind 379 380### Running Thread Sanitizer (TSan) 381 382 GYP_DEFINES="clang=0 target_arch=x64 build_for_tool=tsan" python gyp_libyuv 383 ninja -C out/Debug 384 valgrind out/Debug/libyuv_unittest 385 386For more info, see http://www.chromium.org/developers/how-tos/using-valgrind/threadsanitizer 387 388### Running Address Sanitizer (ASan) 389 390 GYP_DEFINES="clang=0 target_arch=x64 build_for_tool=asan" python gyp_libyuv 391 ninja -C out/Debug 392 valgrind out/Debug/libyuv_unittest 393 394For more info, see http://dev.chromium.org/developers/testing/addresssanitizer 395 396## Benchmarking 397 398The unittests can be used to benchmark. 399 400### Windows 401 402 set LIBYUV_WIDTH=1280 403 set LIBYUV_HEIGHT=720 404 set LIBYUV_REPEAT=999 405 set LIBYUV_FLAGS=-1 406 out\Release\libyuv_unittest.exe --gtest_filter=*I420ToARGB_Opt 407 408 409### Linux and Mac 410 411 LIBYUV_WIDTH=1280 LIBYUV_HEIGHT=720 LIBYUV_REPEAT=1000 out/Release/libyuv_unittest --gtest_filter=*I420ToARGB_Opt 412 413 libyuvTest.I420ToARGB_Opt (547 ms) 414 415Indicates 0.547 ms/frame for 1280 x 720. 416 417## Making a change 418 419 gclient sync 420 git checkout -b mycl -t origin/master 421 git pull 422 <edit files> 423 git add -u 424 git commit -m "my change" 425 git cl lint 426 git cl try 427 git cl upload -r a-reviewer@chomium.org -s 428 <once approved..> 429 git cl land 430