From 7f163858cfba9242d25661acc543b773dd846f17 Mon Sep 17 00:00:00 2001 From: Hamish Coleman Date: Sun, 30 Jan 2022 17:39:10 +0000 Subject: [PATCH] Update to Compiling documentation (#945) --- doc/BuildConfig.md | 112 +++++++++++++++++++++++--------------- doc/Building.md | 126 +++++++++++++++++++++++++------------------ scripts/cmake_all.sh | 2 + 3 files changed, 144 insertions(+), 96 deletions(-) diff --git a/doc/BuildConfig.md b/doc/BuildConfig.md index a1f34c0..0c19985 100644 --- a/doc/BuildConfig.md +++ b/doc/BuildConfig.md @@ -9,15 +9,60 @@ to off. As part of simplifying cross compilation, the use of auto-detected configuration settings are being removed. -## using Makefiles and Configure +## Options + +After changing any configuration, please do no forget to `make clean` after +the (re-)configuration and before building (again) using `make`. (Or the +equivalent with `cmake`) ### `--with-zstd` -Enable ZSTD compression +ZSTD Compression Support + +In addition to the built-in LZO1x for payload compression (`-z1` at the edge's +commandline), n2n optionally supports [ZSTD](https://github.com/facebook/zstd). +As of 2020, it is considered cutting edge and [praised](https://en.wikipedia.org/wiki/Zstandard) +for reaching the currently technologically possible Pareto frontier in terms +of CPU power versus compression ratio. + +#### Makefile + +ZSTD support can be configured using + +`./configure --with-zstd` + +which then will include ZSTD. It will be available via `-z2` at the edges. Of course, it can be combined with the other optimisation features: + +`./configure --with-zstd --with-openssl CFLAGS="-O3 -march=native"` + +Again, and this needs to be reiterated sufficiently often, please do no forget to `make clean` after (re-)configuration and before building (again) using `make`. ### `--with-openssl` -Use openssl instead of the built-int AES code +Use openssl instead of the built-in AES code + +The speed of some ciphers' can take advantage of OpenSSL support This is +disabled by default as the built-in ciphers already prove reasonably fast +in most cases. + +When enabled, this will include OpenSSL 1.1. This can also be combined with +the hardware support and compiler optimizations such as. + +`./configure --with-openssl CFLAGS="-O3 -march=native"` + +#### Makefile + +Add `--with-openssl` to the `configure` command + +#### Cmake + +Add `-DN2N_OPTION_USE_OPENSSL=ON` to the cmake configure step. + +Additionally, it is possible to statically link the OpenSSL library. +Add `-DOPENSSL_USE_STATIC_LIBS=true` to the cmake configure step. + +Building statically with openssl in this way has been known to have +issues recently on Windows (See #944) ### `--with-edgex` @@ -33,7 +78,7 @@ Enable threading using the pthread library Use the libcap to provide reduction of the security privileges needed in the running daemon - + ### `--enable-pcap` If the pcap library is available then the `n2n-decode` tool can be compiled. @@ -50,6 +95,24 @@ Enables the other kind of UPnP port mapping protocol. Turning on either of these two UPnP libraries will enable UPnP support within the edge. +### Disable Multicast Local Peer Detection + +For better local peer detection, the edges try to detect local peers by sending REGISTER +packets to a certain multicast address. Also, edges listen to this address to eventually +fetch such packets. + +If these packets disturb network's peace or even get forwarded by (other) edges through the +n2n network, this behavior can be disabled + +#### Makefile + +Add +`-DSKIP_MULTICAST_PEERS_DISCOVERY` + +to your `CFLAGS` when configuring, e.g. + +`./configure --with-zstd CFLAGS="-O3 -march=native -DSKIP_MULTICAST_PEERS_DISCOVERY"` + ### Deprecation of --with options Due to historical reasons, the autoconf system does not validate the syntax @@ -70,6 +133,8 @@ e.g: Note that the names of the configure option variables used in the cmake process will probably change to make the source code consistent. +# Optimisation options + ## Compiler Optimizations The easiest way to boosting speed is by allowing the compiler to apply optimization to the code. To let the compiler know, the configuration process can take in the optionally specified compiler flag `-O3`: @@ -100,30 +165,6 @@ The compilations flags could easily be combined: There are reports of compile errors showing `n2n_seed': random_numbers.c:(.text+0x214): undefined reference to _rdseed64_step'` even though the CPU should support it, see #696. In this case, best solution found so far is to disable `RDSEED` support by adding `-U__RDSEED__` to the `CFLAGS`. -## OpenSSL Support - -Some ciphers' speed can take advantage of OpenSSL support which is disabled by default as the built-in ciphers already prove reasonably fast in most cases. OpenSSL support can be configured using - -`./configure --with-openssl` - -which then will include OpenSSL 1.1 if found on the system. This can be combined with the hardware support and compiler optimizations such as - -`./configure --with-openssl CFLAGS="-O3 -march=native"` - -Please do no forget to `make clean` after (re-)configuration and before building (again) using `make`. - -## ZSTD Compression Support - -In addition to the built-in LZO1x for payload compression (`-z1` at the edge's commandline), n2n optionally supports [ZSTD](https://github.com/facebook/zstd). As of 2020, it is considered cutting edge and [praised](https://en.wikipedia.org/wiki/Zstandard) for reaching the currently technologically possible Pareto frontier in terms of CPU power versus compression ratio. ZSTD support can be configured using - -`./configure --with-zstd` - -which then will include ZSTD if found on the system. It will be available via `-z2` at the edges. Of course, it can be combined with the other features mentioned above: - -`./configure --with-zstd --with-openssl CFLAGS="-O3 -march=native"` - -Again, and this needs to be reiterated sufficiently often, please do no forget to `make clean` after (re-)configuration and before building (again) using `make`. - ## SPECK – ARM NEON Hardware Acceleration By default, SPECK does not take advantage of ARM NEON hardware acceleration even if compiled with `-march=native`. The reason is that the NEON implementation proved to be slower than the 64-bit scalar code on Raspberry Pi 3B+, see [here](https://github.com/ntop/n2n/issues/563). @@ -134,18 +175,3 @@ Your specific ARM mileage may vary, so it can be enabled by configuring the defi Just make sure that the correct architecture is set, too. `-march=native` usually works quite well. -## Disable Multicast Local Peer Detection - -For better local peer detection, the edges try to detect local peers by sending REGISTER -packets to a certain multicast address. Also, edges listen to this address to eventually -fetch such packets. - -If these packets disturb network's peace or even get forwarded by (other) edges through the -n2n network, this behavior can be disabled, just add - -`-DSKIP_MULTICAST_PEERS_DISCOVERY` - -to your `CFLAGS` when configuring, e.g. - -`./configure --with-zstd CFLAGS="-O3 -march=native -DSKIP_MULTICAST_PEERS_DISCOVERY"` - diff --git a/doc/Building.md b/doc/Building.md index d743096..cca09c7 100644 --- a/doc/Building.md +++ b/doc/Building.md @@ -1,4 +1,33 @@ -# n2n on macOS +This document describes the process for compiling n2n in several different +scenarios. + +There are some configuration options available during the build process, +which are documented in the [Build time Configuration](BuildConfig.md) page. + +Also of use are the steps used for the automated Continuous Integration +process, which can be found in the [Github actions config file](../.github/workflows/tests.yml) + +# Git submodules + +If you are compiling with the UPnP libraries, it is possible that your +operating system or your build system do not include binaries for the +required libraries. + +Using these libraries can cause issues with some build systems, so be +aware that not all combinations are supportable. + +To make this scenario simpler, the required source code has been added +to this repository as git `submodules` which require one extra step to +complete their checkout. + +So the very first time after cloning the n2n git repo, you should run +this command in the n2n directory to fetch the submodules: + +```bash +git submodule update --init --recursive +``` + +# Build on macOS In order to use n2n on macOS, you first need to install support for TUN/TAP interfaces: @@ -11,12 +40,21 @@ If you are on a modern version of macOS (i.e. Catalina), the commands above will For more information refer to vendor documentation or the [Apple Technical Note](https://developer.apple.com/library/content/technotes/tn2459/_index.html). +Note that on the newest MacOS versions and on Apple Silicon, there may be +increasing security restrictions in the OS that make installing the TUN/TAP +kernel extension difficult. Alternative software implementations to avoid +these difficulties are being discussed for future n2n versions. -# Build on Windows (Visual Studio) +# Build on Windows -## Requirements +The following document some possible windows compile recipes. Of them, the +MinGW build process is more tested as it is more friendly to open source +development. -In order to build on Windows the following tools should be installed: +## Visual Studio + +### Requirements +In order to build with Vidual Studio on Windows the following tools should be installed: - Visual Studio. For a minimal install, the command line only build tools can be downloaded and installed from https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017. @@ -27,35 +65,20 @@ In order to build on Windows the following tools should be installed: you may have issues finding libraries (e.g: the installed OpenSSL library). If you still have problems, you can try invoking it with `C:\Program Files\CMake\bin\cmake`. -- (optional) The OpenSSL library. Pre-built binaries can be downloaded from +- (optional) The OpenSSL library. This optional library can be enabled as + per the steps in the [Build time Configuration](BuildConfig.md) + + Pre-built OpenSSL binaries can be downloaded from https://slproweb.com/products/Win32OpenSSL.html. The full version is required, i.e. not the "Light" version. The Win32 version of it is usually required for a standard build. - NOTE: In order to enable OpenSSL compilation, add the option - `-DN2N_OPTION_USE_OPENSSL=ON` to the `cmake ..` command below. - - NOTE: To statically link OpenSSL, add the option - `-DOPENSSL_USE_STATIC_LIBS=true` to the `cmake ..` command below. - -NOTE: Sticking to this tool chain has historically meant that resulting -executables are more likely to be able to communicate with Linux or other -OS builds, however efforts are being made to address this concern. - -## Build (CLI) +### CLI steps In order to build from the command line, open a terminal window change to the directory where the git checkout of this repository is and run the following commands: -The `libnatpmp` and `libminiupnp` have been moved to separated repositories. -So the very first time, you should run this command in the n2n directory to -install them: - -```bash -git submodule update --init --recursive -``` - Building using `cmake` works as follows: ```batch @@ -70,9 +93,33 @@ cmake --build . --config Release The compiled `.exe` files should now be available in the `build\Release` directory. -## Run +## MinGW -In order to run n2n, you will need the following: +These steps were tested on a fresh install of Windows 10 Pro with all patches +applied as of 2021-09-29. + +- Install Chocolatey (Following instructions on https://chocolatey.org/install) +- from an admin cmd prompt + - `choco install git mingw make` +- All the remaining commands must be run from inside a bash shell ("C:\Program Files\Git\usr\bin\bash.exe") + - `git clone $THIS_REPO` + - `cd n2n` + - `./scripts/hack_fakeautoconf.sh` + - `make` + - `make test` + +Due to limitations in the Windows environment, the normal autotools steps have +been emulated by the `hack_fakeautoconf` - This currently results in the +version number reported by the compiled software being inaccurate. + +Note: MinGW builds have had a history of incompatibility reports with other OS +builds (for example [#617](https://github.com/ntop/n2n/issues/617) and [#642](https://github.com/ntop/n2n/issues/642)) +However, if the tests pass, you should have a high confidence that your build +will be compatible. + +## Run on Windows + +In order to run n2n on Windows, you will need the following: - The TAP drivers should be installed into the system. They can be installed from http://build.openvpn.net/downloads/releases, search for "tap-windows". @@ -89,33 +136,6 @@ and [supernode.conf](../packages/etc/n2n/supernode.conf.sample) are available. See `edge.exe --help` and `supernode.exe --help` for a full list of supported options. -# Build on Windows (MinGW) - -These steps were tested on a fresh install of Windows 10 Pro with all patches -applied as of 2021-09-29. - -- Install Chocolatey (Following instructions on https://chocolatey.org/install) -- from an admin cmd prompt - - choco install git mingw make -- All the remaining commands must be run from inside a bash shell ("C:\Program Files\Git\usr\bin\bash.exe") - - git clone $THIS_REPO - - cd n2n - - ./scripts/hack_fakeautoconf.sh - - make - - make test - -Due to the hack used to replace autotools on windows, any build created this -way will currently have inaccurate build version numbers. - -Note: MinGW builds have a history of incompatibility reports with other OS -builds, please see [#617](https://github.com/ntop/n2n/issues/617) and [#642](https://github.com/ntop/n2n/issues/642). -However, if the tests pass, you should have a high confidence that your build -will be compatible. - -# General Building Options - -[Build time Configuration](BuildConfig.md) - # Cross compiling on Linux ## Using the Makefiles and Autoconf diff --git a/scripts/cmake_all.sh b/scripts/cmake_all.sh index e58300e..843764e 100755 --- a/scripts/cmake_all.sh +++ b/scripts/cmake_all.sh @@ -17,6 +17,8 @@ OPTS="" #OPTS+=" -DN2N_OPTION_USE_ZSTD=ON" #OPTS+=" -DN2N_OPTION_USE_PORTMAPPING=ON" +#OPTS+=" -DOPENSSL_USE_STATIC_LIBS=true" + set -e rm -rf build