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 `GYP_DEFINES="OS=ios" 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    export GYP_DEFINES="OS=android"
52    gclient sync
53
54The 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`
55
56To get just the source (not buildable):
57
58    git clone https://chromium.googlesource.com/libyuv/libyuv
59
60
61## Building the Library and Unittests
62
63### Windows
64
65    call gn gen out/Release "--args=is_debug=false target_cpu=\"x86\""
66    call gn gen out/Debug "--args=is_debug=true target_cpu=\"x86\""
67    ninja -v -C out/Release
68    ninja -v -C out/Debug
69
70    call gn gen out/Release "--args=is_debug=false target_cpu=\"x64\""
71    call gn gen out/Debug "--args=is_debug=true target_cpu=\"x64\""
72    ninja -v -C out/Release
73    ninja -v -C out/Debug
74
75#### Building with clang-cl
76
77    set GYP_DEFINES=clang=1 target_arch=ia32
78    call python tools\clang\scripts\update.py
79
80    call gn gen out/Release "--args=is_debug=false is_official_build=false is_clang=true target_cpu=\"x86\""
81    call gn gen out/Debug "--args=is_debug=true is_official_build=false is_clang=true target_cpu=\"x86\""
82    ninja -v -C out/Release
83    ninja -v -C out/Debug
84
85    call gn gen out/Release "--args=is_debug=false is_official_build=false is_clang=true target_cpu=\"x64\""
86    call gn gen out/Debug "--args=is_debug=true is_official_build=false is_clang=true target_cpu=\"x64\""
87    ninja -v -C out/Release
88    ninja -v -C out/Debug
89
90### macOS and Linux
91
92    gn gen out/Release "--args=is_debug=false"
93    gn gen out/Debug "--args=is_debug=true"
94    ninja -v -C out/Release
95    ninja -v -C out/Debug
96
97### Building Offical with GN
98
99    gn gen out/Official "--args=is_debug=false is_official_build=true is_chrome_branded=true"
100    ninja -C out/Official
101
102### iOS
103http://www.chromium.org/developers/how-tos/build-instructions-ios
104
105Add to .gclient last line: `target_os=['ios'];`
106
107arm64
108
109    gn gen out/Release "--args=is_debug=false target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"arm64\""
110    gn gen out/Debug "--args=is_debug=true target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"arm64\""
111    ninja -v -C out/Debug libyuv_unittest
112    ninja -v -C out/Release libyuv_unittest
113
114ios simulator
115
116    gn gen out/Release "--args=is_debug=false target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"x86\""
117    gn gen out/Debug "--args=is_debug=true target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"x86\""
118    ninja -v -C out/Debug libyuv_unittest
119    ninja -v -C out/Release libyuv_unittest
120
121### Android
122https://code.google.com/p/chromium/wiki/AndroidBuildInstructions
123
124Add to .gclient last line: `target_os=['android'];`
125
126armv7
127
128    gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"arm\""
129    gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"arm\""
130    ninja -v -C out/Debug libyuv_unittest
131    ninja -v -C out/Release libyuv_unittest
132
133arm64
134
135    gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"arm64\""
136    gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"arm64\""
137    ninja -v -C out/Debug libyuv_unittest
138    ninja -v -C out/Release libyuv_unittest
139
140ia32
141
142    gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"x86\""
143    gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"x86\""
144    ninja -v -C out/Debug libyuv_unittest
145    ninja -v -C out/Release libyuv_unittest
146
147mipsel
148
149    gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"mipsel\" mips_arch_variant=\"r6\" mips_use_msa=true is_component_build=true is_clang=false"
150    gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"mipsel\" mips_arch_variant=\"r6\" mips_use_msa=true is_component_build=true is_clang=false"
151    ninja -v -C out/Debug libyuv_unittest
152    ninja -v -C out/Release libyuv_unittest
153
154    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 is_clang=false"
155    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 is_clang=false"
156    ninja -v -C out/Debug libyuv_unittest
157    ninja -v -C out/Release libyuv_unittest
158
159arm disassembly:
160
161    third_party/android_tools/ndk/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-objdump -d ./out/Release/obj/libyuv/row_common.o >row_common.txt
162
163    third_party/android_tools/ndk/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-objdump -d ./out/Release/obj/libyuv_neon/row_neon.o >row_neon.txt
164
165    third_party/android_tools/ndk/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-objdump -d ./out/Release/obj/libyuv_neon/row_neon64.o >row_neon64.txt
166
167Running tests:
168
169    build/android/test_runner.py gtest -s libyuv_unittest -t 7200 --verbose --release --gtest_filter=*
170
171Running test as benchmark:
172
173    build/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"
174
175Running test with C code:
176
177    build/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"
178
179### Build targets
180
181    ninja -C out/Debug libyuv
182    ninja -C out/Debug libyuv_unittest
183    ninja -C out/Debug compare
184    ninja -C out/Debug convert
185    ninja -C out/Debug psnr
186    ninja -C out/Debug cpuid
187
188### ARM Linux
189
190    gn gen out/Release "--args=is_debug=false target_cpu=\"arm64\""
191    gn gen out/Debug "--args=is_debug=true target_cpu=\"arm64\""
192    ninja -v -C out/Debug libyuv_unittest
193    ninja -v -C out/Release libyuv_unittest
194
195## Building the Library with make
196
197### Linux
198
199    make V=1 -f linux.mk
200    make V=1 -f linux.mk clean
201    make V=1 -f linux.mk CXX=clang++
202
203## Building the library with cmake
204
205Install cmake: http://www.cmake.org/
206
207### Default debug build:
208
209    mkdir out
210    cd out
211    cmake ..
212    cmake --build .
213
214### Release build/install
215
216    mkdir out
217    cd out
218    cmake -DCMAKE_INSTALL_PREFIX="/usr/lib" -DCMAKE_BUILD_TYPE="Release" ..
219    cmake --build . --config Release
220    sudo cmake --build . --target install --config Release
221
222### Build RPM/DEB packages
223
224    mkdir out
225    cd out
226    cmake -DCMAKE_BUILD_TYPE=Release ..
227    make -j4
228    make package
229
230## Setup for Arm Cross compile
231
232See also https://www.ccoderun.ca/programming/2015-12-20_CrossCompiling/index.html
233
234    sudo apt-get install ssh dkms build-essential linux-headers-generic
235    sudo apt-get install kdevelop cmake git subversion
236    sudo apt-get install graphviz doxygen doxygen-gui
237    sudo apt-get install manpages manpages-dev manpages-posix manpages-posix-dev
238    sudo apt-get install libboost-all-dev libboost-dev libssl-dev
239    sudo apt-get install rpm terminator fish
240    sudo apt-get install g++-arm-linux-gnueabihf gcc-arm-linux-gnueabihf
241
242### Build psnr tool
243
244    cd util
245    arm-linux-gnueabihf-g++ psnr_main.cc psnr.cc ssim.cc -o psnr
246    arm-linux-gnueabihf-objdump -d psnr
247
248## Running Unittests
249
250### Windows
251
252    out\Release\libyuv_unittest.exe --gtest_catch_exceptions=0 --gtest_filter="*"
253
254### OSX
255
256    out/Release/libyuv_unittest --gtest_filter="*"
257
258### Linux
259
260    out/Release/libyuv_unittest --gtest_filter="*"
261
262Replace --gtest_filter="*" with specific unittest to run.  May include wildcards. e.g.
263
264    out/Release/libyuv_unittest --gtest_filter=*I420ToARGB_Opt
265
266## CPU Emulator tools
267
268### Intel SDE (Software Development Emulator)
269
270Pre-requisite: Install IntelSDE: http://software.intel.com/en-us/articles/intel-software-development-emulator
271
272Then run:
273
274    c:\intelsde\sde -hsw -- out\Release\libyuv_unittest.exe --gtest_filter=*
275
276    ~/intelsde/sde -skx -- out/Release/libyuv_unittest --gtest_filter=**I420ToARGB_Opt
277
278## Sanitizers
279
280    gn gen out/Debug "--args=is_debug=true is_asan=true"
281    ninja -v -C out/Debug
282
283    Sanitizers available: tsan, msan, asan, ubsan, lsan
284
285### Running Dr Memory memcheck for Windows
286
287Pre-requisite: Install Dr Memory for Windows and add it to your path: http://www.drmemory.org/docs/page_install_windows.html
288
289    drmemory out\Debug\libyuv_unittest.exe --gtest_catch_exceptions=0 --gtest_filter=*
290