1
2Contents:
3 REQUIREMENTS
4 INSTALLATION
5 libdns
6 examples
7 drill
8 INFORMATION FOR SPECIFIC OPERATING SYSTEMS
9 Mac OS X
10 Solaris
11 KNOWN ISSUES
12 pyldns
13 Your Support
14
15Project page:
16http://www.nlnetlabs.nl/ldns/
17On that page you can also subscribe to the ldns mailing list.
18
19* Development
20ldns is mainly developed on Linux and FreeBSD. It is regularly tested to
21compile on other systems like Solaris and Mac OS X.
22
23REQUIREMENTS
24- OpenSSL (Optional, but needed for features like DNSSEC)
25 - OpenSSL >= 0.9.7f for DANE support
26 - OpenSSL >= 1.0.0 for ECDSA and GOST support
27- libpcap (Optional, but needed for examples/ldns-dpa)
28- (GNU) libtool (in OSX, that's glibtool, not libtool)
29- GNU make
30
31INSTALLATION
321. Unpack the tarball
332. cd ldns-<VERSION>
343. ./configure --with-examples --with-drill
35 (optionally compile python bindings too with: --with-pyldns)
364. make
375. make install
38
39
40* Building from repository
41
42If you are building from the repository you will need to have (gnu)
43autotools like libtool and autoreconf installed. A list of all the commands
44needed to build everything can be found in README.git. Note that the actual
45commands may be a little bit different on your machine. Most notably, you'll
46need to run libtoolize (or glibtoolize). If you skip this step, you'll get
47an error about missing config.sub.
48
49* Developers
50ldns is developed by the ldns team at NLnet Labs. This team currently
51consists of:
52 o Willem Toorop
53 o Wouter Wijngaards
54
55Former main developers:
56 o Jelte Jansen
57 o Miek Gieben
58 o Matthijs Mekking
59
60* Credits
61We have received patches from the following people, thanks!
62 o Bedrich Kosata
63 o Erik Rozendaal
64 o H��kan Olsson
65 o Jakob Schlyter
66 o Paul Wouters
67 o Simon Vallet
68 o Ond��ej Sur��
69 o Karel Slany
70 o Havard Eidnes
71 o Leo Baltus
72 o Dag-Erling Sm��rgrav
73 o Felipe Gasper
74
75
76INFORMATION FOR SPECIFIC OPERATING SYSTEMS
77
78MAC OS X
79
80For MACOSX 10.4 and later, it seems that you have to set the
81MACOSX_DEPLOYMENT_TARGET environment variable to 10.4 before running
82make. Apparently it defaults to 10.1.
83
84This appears to be a known problem in 10.2 to 10.4, see:
85http://developer.apple.com/qa/qa2001/qa1233.html
86for more information.
87
88
89SOLARIS
90
91In Solaris multi-architecture systems (which have both 32-bit and
9264-bit support), it can be a bit taxing to convince the system to
93compile in 64-bit mode. Jakob Schlyter has kindly contributed a build
94script that sets the right build and link options. You can find it in
95contrib/build-solaris.sh
96
97KNOWN ISSUES
98
99A complete list of currently known open issues can be found here:
100https://github.com/NLnetLabs/ldns/issues
101
102* pyldns
103Compiling pyldns produces many ``unused parameter'' warnings. Those are
104harmless and may safely be ignored.
105Also, when building with SWIG older than 2.0.4, compiling
106pyldns produces many ``missing initializer'' warnings. Those are harmless
107too.
108
109Your Support
110NLnet Labs offers all of its software products as open source, most
111published under a BSD license. You can download them, not only from the
112NLnet Labs website but also through the various OS distributions for
113which NSD, ldns, and Unbound are packaged. We therefore have little idea
114who uses our software in production environments and have no direct ties
115with 'our customers'.
116
117Therefore, we ask you to contact us at users@NLnetLabs.nl and tell us
118whether you use one of our products in your production environment,
119what that environment looks like, and maybe even share some praise.
120We would like to refer to the fact that your organization is using our
121products. We will only do that if you explicitly allow us. In all other
122cases we will keep the information you share with us to ourselves.
123
124In addition to the moral support you can also support us
125financially. NLnet Labs is a recognized not-for-profit charity foundation
126that is chartered to develop open-source software and open-standards
127for the Internet. If you use our software to satisfaction please express
128that by giving us a donation. For small donations PayPal can be used. For
129larger and regular donations please contact us at users@NLnetLabs.nl. Also
130see http://www.nlnetlabs.nl/labs/contributors/.
131
132
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