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 --name src https://chromium.googlesource.com/libyuv/libyuv 15 gclient sync 16 17Then you'll get a .gclient file like: 18 19 solutions = [ 20 { "name" : "src", 21 "url" : "https://chromium.googlesource.com/libyuv/libyuv", 22 "deps_file" : "DEPS", 23 "managed" : True, 24 "custom_deps" : { 25 }, 26 "safesync_url": "", 27 }, 28 ]; 29 30For iOS add `;target_os=['ios'];` to your OSX .gclient and run `gclient sync.` 31 32Browse the Git reprository: https://chromium.googlesource.com/libyuv/libyuv/+/master 33 34### Android 35For Android add `;target_os=['android'];` to your Linux .gclient 36 37 solutions = [ 38 { "name" : "src", 39 "url" : "https://chromium.googlesource.com/libyuv/libyuv", 40 "deps_file" : "DEPS", 41 "managed" : True, 42 "custom_deps" : { 43 }, 44 "safesync_url": "", 45 }, 46 ]; 47 target_os = ["android", "linux"]; 48 49Then run: 50 51 gclient sync 52 53To get just the source (not buildable): 54 55 git clone https://chromium.googlesource.com/libyuv/libyuv 56 57 58## Building the Library and Unittests 59 60### Windows 61 62 call gn gen out\Release "--args=is_debug=false target_cpu=\"x64\"" 63 call gn gen out\Debug "--args=is_debug=true target_cpu=\"x64\"" 64 ninja -v -C out\Release 65 ninja -v -C out\Debug 66 67 call gn gen out\Release "--args=is_debug=false target_cpu=\"x86\"" 68 call gn gen out\Debug "--args=is_debug=true target_cpu=\"x86\"" 69 ninja -v -C out\Release 70 ninja -v -C out\Debug 71 72### macOS and Linux 73 74 gn gen out/Release "--args=is_debug=false" 75 gn gen out/Debug "--args=is_debug=true" 76 ninja -v -C out/Release 77 ninja -v -C out/Debug 78 79### Building Offical with GN 80 81 gn gen out/Official "--args=is_debug=false is_official_build=true is_chrome_branded=true" 82 ninja -C out/Official 83 84### iOS 85http://www.chromium.org/developers/how-tos/build-instructions-ios 86 87Add to .gclient last line: `target_os=['ios'];` 88 89arm64 90 91 gn gen out/Release "--args=is_debug=false target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"arm64\"" 92 gn gen out/Debug "--args=is_debug=true target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"arm64\"" 93 ninja -v -C out/Debug libyuv_unittest 94 ninja -v -C out/Release libyuv_unittest 95 96ios simulator 97 98 gn gen out/Release "--args=is_debug=false target_os=\"ios\" ios_enable_code_signing=false use_xcode_clang=true target_cpu=\"x86\"" 99 gn gen out/Debug "--args=is_debug=true target_os=\"ios\" ios_enable_code_signing=false use_xcode_clang=true target_cpu=\"x86\"" 100 ninja -v -C out/Debug libyuv_unittest 101 ninja -v -C out/Release libyuv_unittest 102 103ios disassembly 104 105 otool -tV ./out/Release/obj/libyuv_neon/row_neon64.o >row_neon64.txt 106 107### Android 108https://code.google.com/p/chromium/wiki/AndroidBuildInstructions 109 110Add to .gclient last line: `target_os=['android'];` 111 112arm64 113 114 gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"arm64\"" 115 gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"arm64\"" 116 ninja -v -C out/Debug libyuv_unittest 117 ninja -v -C out/Release libyuv_unittest 118 119armv7 120 121 gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"arm\"" 122 gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"arm\"" 123 ninja -v -C out/Debug libyuv_unittest 124 ninja -v -C out/Release libyuv_unittest 125 126ia32 127 128 gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"x86\"" 129 gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"x86\"" 130 ninja -v -C out/Debug libyuv_unittest 131 ninja -v -C out/Release libyuv_unittest 132 133mips 134 135 gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"mips64el\" mips_arch_variant=\"r6\" mips_use_msa=true is_component_build=true" 136 gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"mips64el\" mips_arch_variant=\"r6\" mips_use_msa=true is_component_build=true" 137 ninja -v -C out/Debug libyuv_unittest 138 ninja -v -C out/Release libyuv_unittest 139 140arm disassembly: 141 142 llvm-objdump -d ./out/Release/obj/libyuv/row_common.o >row_common.txt 143 144 llvm-objdump -d ./out/Release/obj/libyuv_neon/row_neon.o >row_neon.txt 145 146 llvm-objdump -d ./out/Release/obj/libyuv_neon/row_neon64.o >row_neon64.txt 147 148 Caveat: Disassembly may require optimize_max be disabled in BUILD.gn 149 150Running tests: 151 152 out/Release/bin/run_libyuv_unittest -vv --gtest_filter=* 153 154Running test as benchmark: 155 156 out/Release/bin/run_libyuv_unittest -vv --gtest_filter=* --libyuv_width=1280 --libyuv_height=720 --libyuv_repeat=999 --libyuv_flags=-1 --libyuv_cpu_info=-1 157 158Running test with C code: 159 160 out/Release/bin/run_libyuv_unittest -vv --gtest_filter=* --libyuv_width=1280 --libyuv_height=720 --libyuv_repeat=999 --libyuv_flags=1 --libyuv_cpu_info=1 161 162### Build targets 163 164 ninja -C out/Debug libyuv 165 ninja -C out/Debug libyuv_unittest 166 ninja -C out/Debug compare 167 ninja -C out/Debug yuvconvert 168 ninja -C out/Debug yuvconstants 169 ninja -C out/Debug psnr 170 ninja -C out/Debug cpuid 171 172### ARM Linux 173 174 gn gen out/Release "--args=is_debug=false target_cpu=\"arm64\"" 175 gn gen out/Debug "--args=is_debug=true target_cpu=\"arm64\"" 176 ninja -v -C out/Debug libyuv_unittest 177 ninja -v -C out/Release libyuv_unittest 178 179### MIPS Linux 180 181mips 182 183 gn gen out/Release "--args=is_debug=false target_os=\"linux\" target_cpu=\"mips64el\" mips_arch_variant=\"loongson3\" is_component_build=false use_sysroot=false use_gold=false" 184 gn gen out/Debug "--args=is_debug=true target_os=\"linux\" target_cpu=\"mips64el\" mips_arch_variant=\"loongson3\" is_component_build=false use_sysroot=false use_gold=false" 185 ninja -v -C out/Debug libyuv_unittest 186 ninja -v -C out/Release libyuv_unittest 187 188## Building the Library with make 189 190### Linux 191 192 make V=1 -f linux.mk 193 make V=1 -f linux.mk clean 194 make V=1 -f linux.mk CXX=clang++ CC=clang 195 196## Building the library with cmake 197 198Install cmake: http://www.cmake.org/ 199 200### Default debug build: 201 202 mkdir out 203 cd out 204 cmake .. 205 cmake --build . 206 207### Release build/install 208 209 mkdir out 210 cd out 211 cmake -DCMAKE_INSTALL_PREFIX="/usr/lib" -DCMAKE_BUILD_TYPE="Release" .. 212 cmake --build . --config Release 213 sudo cmake --build . --target install --config Release 214 215### Build RPM/DEB packages 216 217 mkdir out 218 cd out 219 cmake -DCMAKE_BUILD_TYPE=Release .. 220 make -j4 221 make package 222 223## Building RISC-V target with cmake 224 225### Prerequisite: build risc-v clang toolchain and qemu 226 227If you don't have prebuilt clang and riscv64 qemu, run the script to download source and build them. 228 229 ./riscv_script/prepare_toolchain_qemu.sh 230 231After running script, clang & qemu are built in `build-toolchain-qemu/riscv-clang/` & `build-toolchain-qemu/riscv-qemu/`. 232 233### Cross-compile for RISC-V target 234 cmake -B out/Release/ -DUNIT_TEST=ON \ 235 -DCMAKE_BUILD_TYPE=Release \ 236 -DCMAKE_TOOLCHAIN_FILE="./riscv_script/riscv-clang.cmake" \ 237 -DTOOLCHAIN_PATH={TOOLCHAIN_PATH} \ 238 -DUSE_RVV=ON . 239 cmake --build out/Release/ 240 241#### Customized Compiler Flags 242 243Customized compiler flags are supported by `-DRISCV_COMPILER_FLAGS="xxx"`. 244If `-DRISCV_COMPILER_FLAGS="xxx"` is manually assigned, other compile flags(e.g disable -march=xxx) will not be appended. 245 246Example: 247 248 cmake -B out/Release/ -DUNIT_TEST=ON \ 249 -DCMAKE_BUILD_TYPE=Release \ 250 -DCMAKE_TOOLCHAIN_FILE="./riscv_script/riscv-clang.cmake" \ 251 -DRISCV_COMPILER_FLAGS="-mcpu=sifive-x280" \ 252 . 253 254### Run on QEMU 255 256#### Run libyuv_unittest on QEMU 257 cd out/Release/ 258 USE_RVV=ON \ 259 TOOLCHAIN_PATH={TOOLCHAIN_PATH} \ 260 QEMU_PREFIX_PATH={QEMU_PREFIX_PATH} \ 261 ../../riscv_script/run_qemu.sh libyuv_unittest 262 263 264## Setup for Arm Cross compile 265 266See also https://www.ccoderun.ca/programming/2015-12-20_CrossCompiling/index.html 267 268 sudo apt-get install ssh dkms build-essential linux-headers-generic 269 sudo apt-get install kdevelop cmake git subversion 270 sudo apt-get install graphviz doxygen doxygen-gui 271 sudo apt-get install manpages manpages-dev manpages-posix manpages-posix-dev 272 sudo apt-get install libboost-all-dev libboost-dev libssl-dev 273 sudo apt-get install rpm terminator fish 274 sudo apt-get install g++-arm-linux-gnueabihf gcc-arm-linux-gnueabihf 275 276### Build psnr tool 277 278 cd util 279 arm-linux-gnueabihf-g++ psnr_main.cc psnr.cc ssim.cc -o psnr 280 arm-linux-gnueabihf-objdump -d psnr 281 282## Running Unittests 283 284### Windows 285 286 out\Release\libyuv_unittest.exe --gtest_catch_exceptions=0 --gtest_filter="*" 287 288### macOS and Linux 289 290 out/Release/libyuv_unittest --gtest_filter="*" 291 292Replace --gtest_filter="*" with specific unittest to run. May include wildcards. 293 out/Release/libyuv_unittest --gtest_filter=*I420ToARGB_Opt 294 295## CPU Emulator tools 296 297### Intel SDE (Software Development Emulator) 298 299Pre-requisite: Install IntelSDE: http://software.intel.com/en-us/articles/intel-software-development-emulator 300 301Then run: 302 303 c:\intelsde\sde -hsw -- out\Release\libyuv_unittest.exe --gtest_filter=* 304 305 ~/intelsde/sde -skx -- out/Release/libyuv_unittest --gtest_filter=**I420ToARGB_Opt 306 307### Intel Architecture Code Analyzer 308 309Inset these 2 macros into assembly code to be analyzed: 310 IACA_ASM_START 311 IACA_ASM_END 312Build the code as usual, then run iaca on the object file. 313 ~/iaca-lin64/bin/iaca.sh -reduceout -arch HSW out/Release/obj/libyuv_internal/compare_gcc.o 314 315## Sanitizers 316 317 gn gen out/Release "--args=is_debug=false is_msan=true" 318 ninja -v -C out/Release 319 320Sanitizers available: asan, msan, tsan, ubsan, lsan, ubsan_vptr 321 322### Running Dr Memory memcheck for Windows 323 324Pre-requisite: Install Dr Memory for Windows and add it to your path: http://www.drmemory.org/docs/page_install_windows.html 325 326 drmemory out\Debug\libyuv_unittest.exe --gtest_catch_exceptions=0 --gtest_filter=* 327