www.tinc-vpn.org Git - tinc/blob - INSTALL.md

   1 # Dependencies
   2
   3 Before you can start compiling tinc from a fresh git clone, you have
   4 to install the very latest versions of the following packages:
   5
   6 - `meson`
   7 - `ninja`
   8 - `pkgconf` or `pkg-config`
   9 - `GCC` or `Clang` (any version with C11 support, although older versions might work)
  10 - `OpenSSL`\* (1.1.0+) or `LibreSSL` or `libgcrypt` (not needed if legacy protocol is disabled)
  11
  12 Plus a few optional dependencies. Support for them will be enabled if they're present:
  13
  14 - `ncurses` or `PDCurses`
  15 - `readline`
  16 - `zlib`\*
  17 - `LZO`\*
  18 - `LZ4`\*
  19
  20 If packages marked by `*` are not available, tinc will fall back to its own vendored copies.
  21 This behavior can be disabled by setting the appropriate meson option to `disabled`.
  22
  23 To build `info` documentation you'll also need these packages:
  24
  25 - `texinfo` or `makeinfo`
  26
  27 You might also need some additional command-line utilities to be able to run the integration test suite:
  28
  29 - `diffutils`
  30 - `procps`
  31 - `socat`
  32 - `netcat`
  33
  34 Please consult your operating system's documentation for more details.
  35
  36 ## Windows
  37
  38 You can build tinc using either the native [Windows SDK][sdk-ms] (which comes with Visual Studio),
  39 or with the Unix-like [msys2 environment][sdk-msys2]. Install either one of them, plus
  40 the latest version of [meson][meson-release].
  41
  42 If you prefer the native SDK, you might want to work on tinc (or build it) under Visual Studio.
  43 To do so, follow [these instructions][meson-vs].
  44
  45 By default, tinc produces a static Windows build, so you don't need to install anything
  46 in order to _run_ the compiled binaries.
  47
  48 [sdk-ms]: https://visualstudio.com/
  49 [sdk-msys2]: https://msys2.org/
  50 [meson-release]: https://github.com/mesonbuild/meson/releases
  51 [meson-vs]: https://mesonbuild.com/Using-with-Visual-Studio.html
  52
  53 # Building
  54
  55 ## Native
  56
  57 Have a look at the available configuration options in `meson_options.txt`, or run:
  58
  59     $ meson configure
  60
  61 The project can be built as any other meson project:
  62
  63     $ meson setup build -Dprefix=/usr/local -Dbuildtype=release
  64
  65 This creates a build directory (named `build`) with build type set to `release`
  66 (which enables compiler optimizations) and path prefix set to `/usr/local`.
  67
  68 Pass any additional options in the same way. Typically, this is not needed: tinc will
  69 autodetect available libraries and adjust its functionality accordingly.
  70
  71 If you'd like to reconfigure the project after running `setup`, you can either remove
  72 the build directory and start anew, or use:
  73
  74     $ meson configure build -Dlzo=disabled -Dlz4=enabled
  75
  76 You then need to build the project:
  77
  78     $ ninja -C build
  79
  80 You might want to run the test suite to ensure tinc is working correctly:
  81
  82     $ ninja -C build test
  83
  84 To install tinc to your system, run:
  85
  86     # ninja -C build install
  87
  88 Please be aware that this is not the best method of installing software
  89 because it will not be tracked by your operating system's package manager. You
  90 should use packages provided by your operating system, or build your own
  91 (this is a large and complicated topic which is out of the scope of this document).
  92
  93 To uninstall tinc, run:
  94
  95     # ninja -C build uninstall
  96
  97 ## Cross-compilation
  98
  99 ### Linux to Linux
 100
 101 Cross-compilation is easy to do on Debian or its derivatives.
 102 Set `$HOST` to your target architecture and install the cross-compilation toolchain and `-dev` versions of all libraries you'd like to link:
 103
 104     $ HOST=armhf
 105     $ dpkg --add-architecture $HOST
 106     $ apt update
 107     $ apt install -y crossbuild-essential-$HOST zlib1g-dev:$HOST …
 108
 109 If you'd like to run tests on emulated hardware, install `qemu-user`:
 110
 111     $ apt install -y qemu-user
 112     $ update-binfmts --enable
 113
 114 Set two environment variables: the C compiler, and pkg-config, and then proceed as usual:
 115
 116     $ export CC=arm-linux-gnueabihf-gcc
 117     $ export PKG_CONFIG=arm-linux-gnueabihf-pkg-config
 118     $ meson setup build --cross-file /dev/null
 119
 120 or put the names into a [cross file][cross] and pass it to meson:
 121
 122     $ cat >cross-armhf <<EOF
 123     [binaries]
 124     c = 'arm-linux-gnueabihf-gcc'
 125     pkgconfig = 'arm-linux-gnueabihf-pkg-config'
 126     EOF
 127
 128     $ meson setup build --cross-file cross-armhf
 129
 130 [cross]: https://mesonbuild.com/Cross-compilation.html
 131
 132 ### Linux to Windows
 133
 134 Install cross-compilation toolchain:
 135
 136     $ apt install -y mingw-w64 mingw-w64-tools
 137
 138 tinc will use its own vendored libraries, so you don't need to install or build anything manually.
 139
 140 Prepare the [cross file][cross] to let meson know you're building binaries for a different opearting system.
 141 Take a look at the [file](.ci/cross/windows/amd64) used by CI for an example, or refer to examples provided
 142 by the meson project: [x86][mingw32], [x86_64][mingw64].
 143
 144 Then build as usual. Because Windows binaries are built with static linkage by default,
 145 you might want to enable link-time optimization. It is much slower than building without LTO,
 146 but produces binaries that are 80%+ smaller:
 147
 148     $ meson setup build -Dbuildtype=release -Db_lto=true --cross-file cross-windows
 149     $ ninja -C build
 150
 151 [mingw64]: https://github.com/mesonbuild/meson/blob/master/cross/linux-mingw-w64-64bit.txt
 152 [mingw32]: https://github.com/mesonbuild/meson/blob/master/cross/linux-mingw-w64-32bit.txt
 153
 154 ### Linux to Android
 155
 156 First you need to install [Android NDK][ndk].
 157
 158 [ndk]: https://developer.android.com/studio/projects/install-ndk
 159
 160 Prepare a [cross file][cross]. Here's a working example for reference:
 161
 162 ```ini
 163 [host_machine]
 164 system     = 'android'
 165 cpu_family = 'arm'
 166 cpu        = 'aarch64'
 167 endian     = 'little'
 168
 169 [binaries]
 170 c = 'aarch64-linux-android24-clang'
 171 ```
 172
 173 Then build as usual:
 174
 175     $ export ANDROID_NDK_ROOT=/tmp/ndk/android-ndk-r24
 176     $ export PATH=$ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH
 177     $ meson setup android-aarch64 -Dcrypto=nolegacy --cross-file android
 178     $ ninja -C android-aarch64
 179
 180 ### macOS to iOS
 181
 182 The same instructions should work for iOS.
 183 Refer to this [cross file][ios] for an example.
 184
 185 [ios]: https://github.com/mesonbuild/meson/blob/master/cross/iphone.txt