getting_started.md 8.71 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
# Getting Started

How to get and build the libyuv code.

## Pre-requisites

You'll need to have depot tools installed: https://www.chromium.org/developers/how-tos/install-depot-tools
Refer to chromium instructions for each platform for other prerequisites.

## Getting the Code

Create a working directory, enter it, and run:

14
    gclient config --name src https://chromium.googlesource.com/libyuv/libyuv
15 16 17 18 19
    gclient sync

Then you'll get a .gclient file like:

    solutions = [
20
      { "name"        : "src",
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
        "url"         : "https://chromium.googlesource.com/libyuv/libyuv",
        "deps_file"   : "DEPS",
        "managed"     : True,
        "custom_deps" : {
        },
        "safesync_url": "",
      },
    ];

For iOS add `;target_os=['ios'];` to your OSX .gclient and run `GYP_DEFINES="OS=ios" gclient sync.`

Browse the Git reprository: https://chromium.googlesource.com/libyuv/libyuv/+/master

### Android
For Android add `;target_os=['android'];` to your Linux .gclient

    solutions = [
38
      { "name"        : "src",
39 40 41 42 43 44 45
        "url"         : "https://chromium.googlesource.com/libyuv/libyuv",
        "deps_file"   : "DEPS",
        "managed"     : True,
        "custom_deps" : {
        },
        "safesync_url": "",
      },
46
    ];
Frank Barchard's avatar
Frank Barchard committed
47
    target_os = ["android", "linux"];
48 49 50 51 52 53 54 55 56

Then run:

    export GYP_DEFINES="OS=android"
    gclient sync

The 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`

To get just the source (not buildable):
57

58 59 60 61 62 63 64
    git clone https://chromium.googlesource.com/libyuv/libyuv


## Building the Library and Unittests

### Windows

65 66 67 68
    call gn gen out\Release "--args=is_debug=false target_cpu=\"x64\""
    call gn gen out\Debug "--args=is_debug=true target_cpu=\"x64\""
    ninja -v -C out\Release
    ninja -v -C out\Debug
69

70 71 72 73
    call gn gen out\Release "--args=is_debug=false target_cpu=\"x86\""
    call gn gen out\Debug "--args=is_debug=true target_cpu=\"x86\""
    ninja -v -C out\Release
    ninja -v -C out\Debug
74

75
### macOS and Linux
76

77 78
    gn gen out/Release "--args=is_debug=false"
    gn gen out/Debug "--args=is_debug=true"
Frank Barchard's avatar
Frank Barchard committed
79 80
    ninja -v -C out/Release
    ninja -v -C out/Debug
81

82 83 84 85
### Building Offical with GN

    gn gen out/Official "--args=is_debug=false is_official_build=true is_chrome_branded=true"
    ninja -C out/Official
86 87 88 89 90 91 92 93

### iOS
http://www.chromium.org/developers/how-tos/build-instructions-ios

Add to .gclient last line: `target_os=['ios'];`

arm64

Frank Barchard's avatar
Frank Barchard committed
94 95 96 97
    gn gen out/Release "--args=is_debug=false target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"arm64\""
    gn gen out/Debug "--args=is_debug=true target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"arm64\""
    ninja -v -C out/Debug libyuv_unittest
    ninja -v -C out/Release libyuv_unittest
98

Frank Barchard's avatar
Frank Barchard committed
99
ios simulator
100

Frank Barchard's avatar
Frank Barchard committed
101 102 103 104
    gn gen out/Release "--args=is_debug=false target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"x86\""
    gn gen out/Debug "--args=is_debug=true target_os=\"ios\" ios_enable_code_signing=false target_cpu=\"x86\""
    ninja -v -C out/Debug libyuv_unittest
    ninja -v -C out/Release libyuv_unittest
105 106 107 108 109 110

### Android
https://code.google.com/p/chromium/wiki/AndroidBuildInstructions

Add to .gclient last line: `target_os=['android'];`

111
arm64
112

113 114
    gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"arm64\""
    gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"arm64\""
Frank Barchard's avatar
Frank Barchard committed
115 116
    ninja -v -C out/Debug libyuv_unittest
    ninja -v -C out/Release libyuv_unittest
117

118
armv7
119

120 121
    gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"arm\""
    gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"arm\""
Frank Barchard's avatar
Frank Barchard committed
122 123
    ninja -v -C out/Debug libyuv_unittest
    ninja -v -C out/Release libyuv_unittest
124 125 126

ia32

127 128
    gn gen out/Release "--args=is_debug=false target_os=\"android\" target_cpu=\"x86\""
    gn gen out/Debug "--args=is_debug=true target_os=\"android\" target_cpu=\"x86\""
Frank Barchard's avatar
Frank Barchard committed
129 130
    ninja -v -C out/Debug libyuv_unittest
    ninja -v -C out/Release libyuv_unittest
131

132
mips
133

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 is_clang=true"
    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=true"
Frank Barchard's avatar
Frank Barchard committed
136 137
    ninja -v -C out/Debug libyuv_unittest
    ninja -v -C out/Release libyuv_unittest
138

139
arm disassembly:
140

141
    third_party/android_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
142

143
    third_party/android_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
144

145
    third_party/android_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
146 147 148

Running tests:

149
    build/android/test_runner.py gtest -s libyuv_unittest -t 7200 --verbose --release --gtest_filter=*
150 151 152

Running test as benchmark:

153
    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"
154 155 156

Running test with C code:

157
    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"
158 159 160 161 162 163

### Build targets

    ninja -C out/Debug libyuv
    ninja -C out/Debug libyuv_unittest
    ninja -C out/Debug compare
164
    ninja -C out/Debug yuvconvert
165 166 167
    ninja -C out/Debug psnr
    ninja -C out/Debug cpuid

168 169 170 171
### ARM Linux

    gn gen out/Release "--args=is_debug=false target_cpu=\"arm64\""
    gn gen out/Debug "--args=is_debug=true target_cpu=\"arm64\""
Frank Barchard's avatar
Frank Barchard committed
172 173
    ninja -v -C out/Debug libyuv_unittest
    ninja -v -C out/Release libyuv_unittest
174 175 176 177 178

## Building the Library with make

### Linux

Frank Barchard's avatar
Frank Barchard committed
179 180 181
    make V=1 -f linux.mk
    make V=1 -f linux.mk clean
    make V=1 -f linux.mk CXX=clang++
182

Frank Barchard's avatar
Frank Barchard committed
183
## Building the library with cmake
184 185 186

Install cmake: http://www.cmake.org/

187
### Default debug build:
188 189 190 191 192 193

    mkdir out
    cd out
    cmake ..
    cmake --build .

194
### Release build/install
195 196 197 198 199 200 201

    mkdir out
    cd out
    cmake -DCMAKE_INSTALL_PREFIX="/usr/lib" -DCMAKE_BUILD_TYPE="Release" ..
    cmake --build . --config Release
    sudo cmake --build . --target install --config Release

Frank Barchard's avatar
Frank Barchard committed
202
### Build RPM/DEB packages
203 204 205 206 207 208 209

    mkdir out
    cd out
    cmake -DCMAKE_BUILD_TYPE=Release ..
    make -j4
    make package

210 211
## Setup for Arm Cross compile

Frank Barchard's avatar
Frank Barchard committed
212
See also https://www.ccoderun.ca/programming/2015-12-20_CrossCompiling/index.html
213 214 215 216 217 218 219 220 221 222 223 224 225 226 227

    sudo apt-get install ssh dkms build-essential linux-headers-generic
    sudo apt-get install kdevelop cmake git subversion
    sudo apt-get install graphviz doxygen doxygen-gui
    sudo apt-get install manpages manpages-dev manpages-posix manpages-posix-dev
    sudo apt-get install libboost-all-dev libboost-dev libssl-dev
    sudo apt-get install rpm terminator fish
    sudo apt-get install g++-arm-linux-gnueabihf gcc-arm-linux-gnueabihf

### Build psnr tool

    cd util
    arm-linux-gnueabihf-g++ psnr_main.cc psnr.cc ssim.cc -o psnr
    arm-linux-gnueabihf-objdump -d psnr

228 229 230 231 232 233
## Running Unittests

### Windows

    out\Release\libyuv_unittest.exe --gtest_catch_exceptions=0 --gtest_filter="*"

234
### macOS and Linux
235 236 237

    out/Release/libyuv_unittest --gtest_filter="*"

238
Replace --gtest_filter="*" with specific unittest to run.  May include wildcards.
239
    out/Release/libyuv_unittest --gtest_filter=*I420ToARGB_Opt
240 241 242 243 244

## CPU Emulator tools

### Intel SDE (Software Development Emulator)

245
Pre-requisite: Install IntelSDE: http://software.intel.com/en-us/articles/intel-software-development-emulator
246 247 248

Then run:

249 250 251
    c:\intelsde\sde -hsw -- out\Release\libyuv_unittest.exe --gtest_filter=*

    ~/intelsde/sde -skx -- out/Release/libyuv_unittest --gtest_filter=**I420ToARGB_Opt
252

253 254 255 256 257 258 259 260
### Intel Architecture Code Analyzer

Inset these 2 macros into assembly code to be analyzed:
    IACA_ASM_START
    IACA_ASM_END
Build the code as usual, then run iaca on the object file.
    ~/iaca-lin64/bin/iaca.sh -reduceout -arch HSW out/Release/obj/libyuv_internal/compare_gcc.o

261
## Sanitizers
262

263 264
    gn gen out/Release "--args=is_debug=false is_msan=true"
    ninja -v -C out/Release
265

266
Sanitizers available: asan, msan, tsan, ubsan, lsan, ubsan_vptr
267 268 269 270 271 272

### Running Dr Memory memcheck for Windows

Pre-requisite: Install Dr Memory for Windows and add it to your path: http://www.drmemory.org/docs/page_install_windows.html

    drmemory out\Debug\libyuv_unittest.exe --gtest_catch_exceptions=0 --gtest_filter=*