1# Travis Testing 2 3LDNS 1.7.1 and above leverage Travis CI to increase coverage of compilers and platforms. Compilers include Clang and GCC; while platforms include Android, iOS, Linux, and OS X on AMD64, Aarch64, PowerPC and s390x hardware. 4 5Android is tested on armv7a, aarch64, x86 and x86_64. The Android recipes build and install OpenSSL, and then builds LDNS. The testing is tailored for Android NDK-r19 and above, and includes NDK-r20 and NDK-r21. Mips and Mips64 are not tested because they are no longer supported under current NDKs. 6 7iOS is tested for iPhoneOS, WatchOS, AppleTVOS, iPhoneSimulator, AppleTVSimulator and WatchSimulator. The testing uses Xcode 10 on OS X 10.13. 8 9The LDNS Travis configuration file `.travis.yml` does not use top-level keys like `os:` and `compiler:` so there is no matrix expansion. Instead LDNS specifies the exact job to run under the `jobs:` and `include:` keys. 10 11## Typical recipe 12 13A typical recipe tests Clang and GCC on various hardware. The hardware includes AMD64, Aarch64, PowerPC and s390x. PowerPC is a little-endian platform, and s390x is a big-endian platform. There are pairs of recipes that are similar to the following. 14 15``` 16- os: linux 17 name: GCC on Linux, Aarch64 18 compiler: gcc 19 arch: arm64 20 dist: bionic 21- os: linux 22 name: Clang on Linux, Aarch64 23 compiler: clang 24 arch: arm64 25 dist: bionic 26``` 27 28OS X provides a single recipe to test Clang. GCC is not tested because GCC is an alias for Clang. 29 30## Sanitizer builds 31 32Two sanitizer builds are tested using Clang and GCC, for a total of four builds. The first sanitizer is Undefined Behavior sanitizer (UBsan), and the second is Address sanitizer (Asan). The sanitizers are only run on AMD64 hardware. Note the environment includes `UBSAN=yes` or `ASAN=yes` for the sanitizer builds. 33 34The recipes are similar to the following. 35 36``` 37- os: linux 38 name: UBsan, GCC on Linux, Amd64 39 compiler: gcc 40 arch: amd64 41 dist: bionic 42 env: UBSAN=yes 43- os: linux 44 name: UBsan, Clang on Linux, Amd64 45 compiler: clang 46 arch: amd64 47 dist: bionic 48 env: UBSAN=yes 49``` 50 51When the Travis script encounters a sanitizer it uses different `CFLAGS` and configuration string. 52 53``` 54if [ "$UBSAN" = "yes" ]; then 55 export CFLAGS="-DNDEBUG -g2 -O3 -fsanitize=undefined -fno-sanitize-recover" 56 bash test/test_ci.sh 57elif [ "$ASAN" = "yes" ]; then 58 export CFLAGS="-DNDEBUG -g2 -O3 -fsanitize=address" 59 bash test/test_ci.sh 60... 61``` 62 63## Android builds 64 65Travis tests Android builds for the armv7a, aarch64, x86 and x86_64 architectures. The builds are trickier than other builds for several reasons. The testing requires installation of the Android NDK and SDK, it requires a cross-compile, and requires OpenSSL prerequisites. The Android cross-compiles also require care to set the Autotools triplet, the OpenSSL triplet, the toolchain path, the tool variables, and the sysroot. The discussion below detail the steps of the Android recipes. 66 67### Android job 68 69The first step sets environmental variables for the cross-compile using the Travis job. A typical job with variables is shown below. 70 71``` 72- os: linux 73 name: Android armv7a, Linux, Amd64 74 compiler: clang 75 arch: amd64 76 dist: bionic 77 env: 78 - ANDROID=yes 79 - AUTOTOOLS_HOST=armv7a-linux-androideabi 80 - OPENSSL_HOST=android-arm 81 - ANDROID_CPU=armv7a 82 - ANDROID_API=23 83 - ANDROID_PREFIX="$HOME/android$ANDROID_API-$ANDROID_CPU" 84 - ANDROID_SDK_ROOT="$HOME/android-sdk" 85 - ANDROID_NDK_ROOT="$HOME/android-ndk" 86``` 87 88### ANDROID_NDK_ROOT 89 90The second step for Android is to set the environmental variables `ANDROID_NDK_ROOT` and `ANDROID_SDK_ROOT`. This is an important step because the NDK and SDK use the variables internally to locate their own tools. Also see [Recommended NDK Directory?](https://groups.google.com/forum/#!topic/android-ndk/qZjhOaynHXc) on the android-ndk mailing list. (Many folks miss this step, or use incorrect variables like `ANDROID_NDK_HOME` or `ANDROID_SDK_HOME`). 91 92If you are working from a developer machine you probably already have the necessary tools installed. You should ensure `ANDROID_NDK_ROOT` and `ANDROID_SDK_ROOT` are set properly. 93 94### Tool installation 95 96The second step installs tools needed for OpenSSL, Expat and LDNS. This step is handled in by the script `contrib/android/install_tools.sh`. The tools include curl, tar, zip, unzip and java. 97 98``` 99before_script: 100 - | 101 if [ "$ANDROID" = "yes" ]; then 102 ./contrib/android/install_tools.sh 103 elif [ "$IOS" = "yes" ]; then 104 ./contrib/ios/install_tools.sh 105 fi 106``` 107 108### NDK installation 109 110The third step installs the NDK and SDK. This step is handled in by the script `contrib/android/install_ndk.sh`. The script uses `ANDROID_NDK_ROOT` and `ANDROID_SDK_ROOT` to place the NDK and SDK in the `$HOME` directory. 111 112If you are working from a developer machine you probably already have a NDK and SDK installed. 113 114### Android environment 115 116The fourth step sets the Android cross-compile environment using the script `contrib/android/setenv_android.sh`. The script is `sourced` so the variables in the script are available to the calling shell. The script sets variables like `CC`, `CXX`, `AS` and `AR`; sets `CFLAGS` and `CXXFLAGS`; sets a `sysroot` so Android headers and libraries are found; and adds the path to the toolchain to `PATH`. 117 118`contrib/android/setenv_android.sh` knows which toolchain and architecture to select by inspecting environmental variables set by Travis for the job. In particular, the variables `ANDROID_CPU` and `ANDROID_API` tell `contrib/android/setenv_android.sh` which tools and libraries to select. 119 120The `contrib/android/setenv_android.sh` script specifies the tools in a `case` statement like the following. There is a case for each of the architectures armv7a, aarch64, x86 and x86_64. 121 122``` 123armv8a|aarch64|arm64|arm64-v8a) 124 CC="aarch64-linux-android$ANDROID_API-clang" 125 CXX="aarch64-linux-android$ANDROID_API-clang++" 126 LD="aarch64-linux-android-ld" 127 AS="aarch64-linux-android-as" 128 AR="aarch64-linux-android-ar" 129 RANLIB="aarch64-linux-android-ranlib" 130 STRIP="aarch64-linux-android-strip" 131 132 CFLAGS="-funwind-tables -fexceptions" 133 CXXFLAGS="-funwind-tables -fexceptions -frtti" 134``` 135 136### OpenSSL 137 138The fifth step builds OpenSSL. OpenSSL is built for iOS using the scripts `contrib/android/install_openssl.sh`. The script downloads, configures and installs the latest release version of the OpenSSL libraries. OpenSSL is configured with `--prefix="$ANDROID_PREFIX"` so the headers are placed in `$ANDROID_PREFIX/include` directory, and the libraries are placed in the `$ANDROID_PREFIX/lib` directory. 139 140`ANDROID_PREFIX` is the value `$HOME/android$ANDROID_API-$ANDROID_CPU`. The libraries will be installed in `$HOME/android23-armv7a`, `$HOME/android23-aarch64`, etc. For Autotools projects, the appropriate `PKG_CONFIG_PATH` is exported. 141 142`PKG_CONFIG_PATH` is an important variable. It is the userland equivalent to sysroot, and allows Autotools to find non-system headers and libraries for an architecture. Typical `PKG_CONFIG_PATH` are `$HOME/android23-armv7a/lib/pkgconfig` and `$HOME/android23-aarch64/lib/pkgconfig`. 143 144OpenSSL also uses a custom configuration file called `15-android.conf`. It is a copy of the OpenSSL's project file and located at `contrib/android/15-android.conf`. The LDNS version is copied to the OpenSSL source files after unpacking the OpenSSL distribution. The LDNS version has legacy NDK support removed and some other fixes, like `ANDROID_NDK_ROOT` awareness. The changes mean LDNS's `15-android.conf` will only work with LDNS, with NDK-r19 and above, and a properly set environment. 145 146OpenSSL is configured with `no-engine`. If you want to include OpenSSL engines then edit `contrib/android/install_openssl.sh` and remove the config option. 147 148### Android build 149 150Finally, once OpenSSL are built, then the Travis script configures and builds LDNS. The recipe looks as follows. 151 152``` 153elif [ "$ANDROID" = "yes" ]; then 154 export AUTOTOOLS_BUILD="$(./config.guess)" 155 export PKG_CONFIG_PATH="$ANDROID_PREFIX/lib/pkgconfig" 156 ./contrib/android/install_ndk.sh 157 source ./contrib/android/setenv_android.sh 158 ./contrib/android/install_openssl.sh 159 ./contrib/android/bootstrap_ldns.sh 160 ./configure \ 161 --build="$AUTOTOOLS_BUILD" \ 162 --host="$AUTOTOOLS_HOST" \ 163 --prefix="$ANDROID_PREFIX" \ 164 --with-ssl="$ANDROID_PREFIX" \ 165 --disable-gost \ 166 --with-drill --with-examples 167 make -j 2 168 make install 169``` 170 171Travis only smoke tests an Android build using a compile, link and install. The self tests are not run. TODO: figure out how to fire up an emulator, push the tests to the device and run them. 172 173### Android flags 174 175`contrib/android/setenv_android.sh` uses specific flags for `CFLAGS` and `CXXFLAGS`. They are taken from `ndk-build`, so we consider them the official flag set. It is important to use the same flags across projects to avoid subtle problems due to mixing and matching different flags. 176 177`CXXFLAGS` includes `-fexceptions` and `-frtti` because exceptions and runtime type info are disabled by default. `CFLAGS` include `-funwind-tables` and `-fexceptions` to ensure C++ exceptions pass through C code, if needed. Also see `docs/CPLUSPLUS-SUPPORT.html` in the NDK docs. 178 179To inspect the flags used by `ndk-build` for a platform clone ASOP's [ndk-samples](https://github.com/android/ndk-samples/tree/master/hello-jni) and build the `hello-jni` project. Use the `V=1` flag to see the full compiler output from `ndk-build`. 180 181## iOS builds 182 183Travis tests iOS builds for the armv7a, armv7s and aarch64 architectures for iPhoneOS, AppleTVOS and WatchOS. iPhoneOS is tested using both 32-bit builds (iPhones) and 64-bit builds (iPads). Travis also tests compiles against the simulators. The builds are trickier than other builds for several reasons. The testing requires a cross-compile, and requires OpenSSL prerequisites. The iOS cross-compiles also require care to set the Autotools triplet, the OpenSSL triplet, the toolchain path, the tool variables, and the sysroot. The discussion below detail the steps of the iOS recipes. 184 185### iOS job 186 187The first step sets environmental variables for the cross-compile using the Travis job. A typical job with variables is shown below. 188 189``` 190- os: osx 191 osx_image: xcode10 192 name: Apple iPhone on iOS, armv7 193 compiler: clang 194 env: 195 - IOS=yes 196 - AUTOTOOLS_HOST=armv7-apple-ios 197 - OPENSSL_HOST=ios-cross 198 - IOS_SDK=iPhoneOS 199 - IOS_CPU=armv7s 200 - IOS_PREFIX="$HOME/$IOS_SDK-$IOS_CPU" 201``` 202 203### Tool installation 204 205The second step installs tools needed for OpenSSL, Expat and LDNS. This step is handled in by the script `contrib/ios/install_tools.sh`. The tools include autotools, curl and perl. The installation happens at the `before_script:` stage of Travis. 206 207``` 208before_script: 209 - | 210 if [ "$ANDROID" = "yes" ]; then 211 ./contrib/android/install_tools.sh 212 elif [ "$IOS" = "yes" ]; then 213 ./contrib/ios/install_tools.sh 214 fi 215``` 216 217### iOS environment 218 219The third step sets the iOS cross-compile environment using the script `contrib/ios/setenv_ios.sh`. The script is `sourced` so the variables in the script are available to the calling shell. The script sets variables like `CC`, `CXX`, `AS` and `AR`; sets `CFLAGS` and `CXXFLAGS`; sets a `sysroot` so iOS headers and libraries are found; and adds the path to the toolchain to `PATH`. 220 221`contrib/ios/setenv_ios.sh` knows which toolchain and architecture to select by inspecting environmental variables set by Travis for the job. In particular, the variables `IOS_SDK` and `IOS_CPU` tell `contrib/ios/setenv_ios.sh` which tools and libraries to select. 222 223The `contrib/ios/setenv_ios.sh` script specifies the tools to use during the cross-compile. For Apple SDKs, the tool names are the same as a desktop. There are no special prefixes for the mobile tools. 224 225``` 226CPP=cpp 227CC=clang 228CXX=clang++ 229LD=ld 230AS=as 231AR=ar 232RANLIB=ranlib 233STRIP=strip 234``` 235 236If you are working from a developer machine you probably already have the necessary tools installed. 237 238### OpenSSL 239 240The fourth step builds OpenSSL. OpenSSL is built for iOS using the scripts `contrib/ios/install_openssl.sh`. The script downloads, configures and installs the latest release version of the OpenSSL libraries. OpenSSL is configured with `--prefix="$IOS_PREFIX"` so the headers are placed in `$IOS_PREFIX/include` directory, and the libraries are placed in the `$IOS_PREFIX/lib` directory. 241 242`IOS_PREFIX` is the value `$HOME/$IOS_SDK-$IOS_CPU`. The scheme handles both iOS SDKs and cpu architectures so the pair receives a unique installation directory. The libraries will be installed in `$HOME/iPhoneOS-armv7s`, `$HOME/iPhoneOS-arm64`, `$HOME/iPhoneSimulator-i386`, etc. For Autotools projects, the appropriate `PKG_CONFIG_PATH` is exported. 243 244`PKG_CONFIG_PATH` is an important variable. It is the userland equivalent to sysroot, and allows Autotools to find non-system headers and libraries for an architecture. Typical `PKG_CONFIG_PATH` are `$HOME/iPhoneOS-armv7s/lib/pkgconfig` and `$HOME/iPhoneOS-arm64/lib/pkgconfig`. 245 246OpenSSL also uses a custom configuration file called `15-ios.conf`. It is a copy of the OpenSSL's project file and located at `contrib/ios/15-ios.conf`. The LDNS version is copied to the OpenSSL source files after unpacking the OpenSSL distribution. The changes mean LDNS's `15-ios.conf` will only work with LDNS and a properly set environment. 247 248OpenSSL is configured with `no-engine`. Engines require dynamic loading so engines are disabled permanently in `15-ios.conf`. 249 250### iOS build 251 252Finally, once OpenSSL are built, then the Travis script configures and builds LDNS. The full recipe looks as follows. 253 254``` 255elif [ "$IOS" = "yes" ]; then 256 export AUTOTOOLS_BUILD="$(./config.guess)" 257 export PKG_CONFIG_PATH="$IOS_PREFIX/lib/pkgconfig" 258 source ./contrib/ios/setenv_ios.sh 259 ./contrib/ios/install_openssl.sh 260 ./contrib/ios/bootstrap_ldns.sh 261 ./configure \ 262 --build="$AUTOTOOLS_BUILD" --host="$AUTOTOOLS_HOST" \ 263 --prefix="$IOS_PREFIX" \ 264 --with-ssl="$IOS_PREFIX" --disable-gost \ 265 --with-drill --with-examples 266 make -j 2 267 make install 268``` 269 270Travis only smoke tests an iOS build using a compile, link and install. The self tests are not run. TODO: figure out how to fire up an simulator, push the tests to the device and run them. 271 272### iOS flags 273 274`contrib/ios/setenv_ios.sh` uses specific flags for `CFLAGS` and `CXXFLAGS`. They are taken from Xcode, so we consider them the official flag set. It is important to use the same flags across projects to avoid subtle problems due to mixing and matching different flags. 275