X-Git-Url: https://www.tinc-vpn.org/git/browse?a=blobdiff_plain;f=INSTALL.md;h=7fbc8b1bc357fa3d0a779e1adfaf300f398b5368;hb=refs%2Fheads%2F1.1;hp=fb99d038a0efd4a5822c0cc5ba9fb44a26b3933f;hpb=61a08ba67b37200659f49f14aeb03f23789b84c6;p=tinc diff --git a/INSTALL.md b/INSTALL.md index fb99d038..7fbc8b1b 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,15 +1,31 @@ # Dependencies -Before you can start compiling tinc from a fresh git clone, you have -to install the very latest versions of the following packages: +## Required -- `meson` -- `ninja` +Before you can start compiling tinc from a fresh git clone, you have to install +the very latest versions of the following packages: + +- `meson` or `muon` (read below) +- `ninja` or `samurai` - `pkgconf` or `pkg-config` -- `GCC` or `Clang` (any version with C11 support, although older versions might work) -- `OpenSSL`\* (1.1.0+) or `LibreSSL` or `libgcrypt` (not needed if legacy protocol is disabled) +- `GCC` or `Clang` (any version with C11 support, although older versions might + work) +- `OpenSSL`\* (1.1.0+) or `LibreSSL` or `libgcrypt` (not needed if legacy + protocol is disabled) + +### No Python? + +If you're on a constrained system that doesn't have (or cannot run) Python, you +can try building tinc with [muon][muon], which is a pure C reimplementation of +the same idea. Please note that `meson` is considered to be the main way of +building tinc, and `muon` is supported on a best-effort basis. + +[muon]: https://git.sr.ht/~lattis/muon + +## Optional -Plus a few optional dependencies. Support for them will be enabled if they're present: +Plus a few optional dependencies. Support for them will be enabled if they're +present: - `ncurses` or `PDCurses` - `readline` @@ -17,115 +33,180 @@ Plus a few optional dependencies. Support for them will be enabled if they're pr - `LZO`\* - `LZ4`\* -If packages marked by `*` are not available, tinc will fall back to its own vendored copies. -This behavior can be disabled by setting the appropriate meson option to `disabled`. +If packages marked by `*` are not available, tinc will fall back to its own +vendored copies. This behavior can be disabled by setting the appropriate meson +option to `disabled`. To build `info` documentation you'll also need these packages: - `texinfo` or `makeinfo` -You might also need some additional command-line utilities to be able to run the integration test suite: +You might also need some additional command-line utilities to be able to run the +integration test suite: - `diffutils` - `procps` - `socat` - `netcat` -Please consult your operating system's documentation for more details. + +## Linux + +Depending on the distribution, one of the following commands can be used to install all dependencies: +- Arch Linux: `sudo pacman --needed --sync base-devel meson ninja pkg-config openssl ncurses readline zlib lzo lz4 texinfo diffutils procps socat openbsd-netcat` +- Debian: `sudo apt install meson ninja-build pkg-config build-essential libssl-dev libncurses-dev libreadline-dev zlib1g-dev liblzo2-dev liblz4-dev texinfo diffutils procps socat netcat-openbsd` +- Alpine Linux: `doas apk add meson ninja pkgconf build-base linux-headers openssl-dev ncurses-dev readline-dev zlib-dev lzo-dev lz4-dev texinfo diffutils procps-ng socat netcat-openbsd` +- Fedora: `sudo dnf install meson ninja-build pkgconf-pkg-config @development-tools openssl-devel ncurses-devel readline-devel zlib-devel lzo-devel lz4-devel texinfo diffutils procps-ng socat netcat` ## Windows -You can build tinc using either the native [Windows SDK][sdk-ms] (which comes with Visual Studio), -or with the Unix-like [msys2 environment][sdk-msys2]. Install either one of them, plus -the latest version of [meson][meson-release]. +You can build tinc using either the native [Windows SDK][sdk-ms] (which comes +with Visual Studio), or with the Unix-like [msys2 environment][sdk-msys2]. +Install either one of them, plus the latest version of [meson][meson-release]. -If you prefer the native SDK, you might want to work on tinc (or build it) under Visual Studio. -To do so, follow [these instructions][meson-vs]. +If you prefer the native SDK, you might want to work on tinc (or build it) under +Visual Studio. To do so, follow [these instructions][meson-vs]. -By default, tinc produces a static Windows build, so you don't need to install anything -in order to _run_ the compiled binaries. +By default, tinc produces a static Windows build, so you don't need to install +anything in order to _run_ the compiled binaries. [sdk-ms]: https://visualstudio.com/ [sdk-msys2]: https://msys2.org/ [meson-release]: https://github.com/mesonbuild/meson/releases [meson-vs]: https://mesonbuild.com/Using-with-Visual-Studio.html -# Building +# Building from source ## Native -Have a look at the available configuration options in `meson_options.txt`, or run: +### Setup + +Tinc's functionality can vary greatly depending on how you configure it. Have a +look at the available options in [`meson_options.txt`](meson_options.txt), or +run: + +```sh +meson configure +``` - $ meson configure +First you need to create a build directory. If you want the default experience, +run: -The project can be built as any other meson project: +```sh +meson setup builddir +``` - $ meson setup build -Dprefix=/usr/local -Dbuildtype=release +or with configuration options (your shell can probably autocomplete them on +`Tab`, try it): -This creates a build directory (named `build`) with build type set to `release` -(which enables compiler optimizations) and path prefix set to `/usr/local`. +```sh +meson setup builddir -Dprefix=/usr/local -Dbuildtype=release +``` -Pass any additional options in the same way. Typically, this is not needed: tinc will -autodetect available libraries and adjust its functionality accordingly. +(For autotools users: this is a rough equivalent of +`autoreconf -fsi && ./configure --prefix=/usr/local --with-foobar`). -If you'd like to reconfigure the project after running `setup`, you can either remove -the build directory and start anew, or use: +This creates a build directory (named `builddir`) with build type set to +`release` (which enables compiler optimizations) and path prefix set to +`/usr/local`. - $ meson configure build -Dlzo=disabled -Dlz4=enabled +Pass any additional options in the same way. Typically, this is not needed: tinc +will autodetect available libraries and adjust its functionality accordingly. + +If you'd like to reconfigure the project after running `setup`, you can either +remove the build directory and start anew, or use: + +```sh +meson configure builddir -Dlzo=disabled -Dlz4=enabled +``` + +### Compile You then need to build the project: - $ ninja -C build +```sh +meson compile -C builddir +``` + +(For autotools users: this is an equivalent of `make -j$(nproc)`). + +### Test You might want to run the test suite to ensure tinc is working correctly: - $ ninja -C build test +```sh +meson test -C builddir +``` + +(For autotools users: this is an equivalent of `make -j$(nproc) test`). + +### Install To install tinc to your system, run: - # ninja -C build install +```sh +meson install -C builddir +``` -Please be aware that this is not the best method of installing software -because it will not be tracked by your operating system's package manager. You -should use packages provided by your operating system, or build your own -(this is a large and complicated topic which is out of the scope of this document). +(For autotools users: this is an equivalent of `make install`). + +Please be aware that this is not the best method of installing software because +it will not be tracked by your operating system's package manager. You should +use packages provided by your operating system, or build your own (this is a +large and complicated topic which is out of the scope of this document). + +### Uninstall To uninstall tinc, run: - # ninja -C build uninstall +```sh +ninja -C builddir uninstall +``` + +(For autotools users: this is an equivalent of `make uninstall`). ## Cross-compilation ### Linux to Linux -Cross-compilation is easy to do on Debian or its derivatives. -Set `$HOST` to your target architecture and install the cross-compilation toolchain and `-dev` versions of all libraries you'd like to link: +Cross-compilation is easy to do on Debian or its derivatives. Set `$HOST` to +your target architecture and install the cross-compilation toolchain and `-dev` +versions of all libraries you'd like to link: - $ HOST=armhf - $ dpkg --add-architecture $HOST - $ apt update - $ apt install -y crossbuild-essential-$HOST zlib1g-dev:$HOST … +```sh +HOST=armhf +dpkg --add-architecture $HOST +apt update +apt install -y crossbuild-essential-$HOST zlib1g-dev:$HOST … +``` If you'd like to run tests on emulated hardware, install `qemu-user`: - $ apt install -y qemu-user - $ update-binfmts --enable +```sh +apt install -y qemu-user +update-binfmts --enable +``` -Set two environment variables: the C compiler, and pkg-config, and then proceed as usual: +Set two environment variables: the C compiler, and pkg-config, and then proceed +as usual: - $ export CC=arm-linux-gnueabihf-gcc - $ export PKG_CONFIG=arm-linux-gnueabihf-pkg-config - $ meson setup build --cross-file /dev/null +```sh +export CC=arm-linux-gnueabihf-gcc +export PKG_CONFIG=arm-linux-gnueabihf-pkg-config +meson setup build --cross-file /dev/null +``` -or put the names into a [cross file][cross] and pass it to meson: +Or put the names into a [cross file][cross] and pass it to meson: - $ cat >cross-armhf <cross-armhf <