From 75838ae9947a1e373b2e9e20c0fab13234011008 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Ma=C5=82ecki?= Date: Tue, 24 Sep 2019 12:45:06 +0200 Subject: [PATCH 01/10] Added build options description. Added entry info in README. Removed unnecessary descr in cmake. Fixed duplicated enable-unittests --- CMakeLists.txt | 9 - README.md | 2 + configure-data.tcl | 1 - docs/BuildOptions.md | 411 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 413 insertions(+), 10 deletions(-) create mode 100644 docs/BuildOptions.md diff --git a/CMakeLists.txt b/CMakeLists.txt index 27993477a..c9b382e25 100755 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -110,15 +110,6 @@ option(ENABLE_CXX_DEPS "Extra library dependencies in srt.pc for the CXX librari option(USE_STATIC_LIBSTDCXX "Should use static rather than shared libstdc++" OFF) option(ENABLE_INET_PTON "Set to OFF to prevent usage of inet_pton when building against modern SDKs while still requiring compatibility with older Windows versions, such as Windows XP, Windows Server 2003 etc." ON) option(ENABLE_CODE_COVERAGE "Enable code coverage reporting" OFF) - -# ENABLE_MONOTONIC_CLOCK: enforces the use of clock_gettime to get the current -# time, instead of gettimeofday. This function allows to force a monotonic -# clock, which is independent on the currently set time in the system. The CV, -# for which the *_timedwait() functions are used with so obtained current time, -# must be appropriately configured. The consequence of enabling this option, -# however, may be portability issues around the clock_gettime() function, which -# is not available on every SDK, or extra -lrt option is sometimes required -# (this requirement will be autodetected). option(ENABLE_MONOTONIC_CLOCK "Enforced clock_gettime with monotonic clock on GC CV /temporary fix for #729/" OFF) option(USE_OPENSSL_PC "Use pkg-config to find OpenSSL libraries" ON) option(USE_BUSY_WAITING "Enable more accurate sending times at a cost of potentially higher CPU load" OFF) diff --git a/README.md b/README.md index 2a1165c83..12e6b1830 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,8 @@ As audio/video packets are streamed from a source to a destination device, SRT d * OpenSSL * Pthreads (for POSIX systems it's builtin, for Windows there's a library) +For detailed description of the build system and options, please [read here](BuildOptions.md). + ## For Linux: Install cmake and openssl-devel (or similar name) package. For pthreads diff --git a/configure-data.tcl b/configure-data.tcl index 85bcf34bc..446b9514b 100644 --- a/configure-data.tcl +++ b/configure-data.tcl @@ -35,7 +35,6 @@ set internal_options { set cmake_options { cygwin-use-posix "Should the POSIX API be used for cygwin. Ignored if the system isn't cygwin. (default: OFF)" enable-encryption "Should encryption features be enabled (default: ON)" - enable-unittests "Should the unit tests be enabled (default: OFF)" enable-c++11 "Should the c++11 parts (srt-live-transmit) be enabled (default: ON)" enable-apps "Should the Support Applications be Built? (default: ON)" enable-testing "Should developer testing applications be built (default: OFF)" diff --git a/docs/BuildOptions.md b/docs/BuildOptions.md new file mode 100644 index 000000000..9f7eb330b --- /dev/null +++ b/docs/BuildOptions.md @@ -0,0 +1,411 @@ +Build system +============ + +The main build system for SRT is provided by `cmake` tool. You can always use +it directly, if you want. However, there's also a wrapper script that can make +operating with the options easier (requires Tcl interpreter), which is a +script named `configure`. + + +Portability +=========== + +The cmake build system was tested on the following platforms: + + - Linux + - MaxOS (you may want to see [separate document](build_iOS.md) + - Windows with MinGW + - Windows with Microsoft Visual Studio + - Android (see [separate document](Android/Compiling.md)) + - Cygwin (only for testing) + +The configure script wasn't tested on Windows (unless on Cygwin) + + +The configure helper script +=========================== + +This script is designed to look similar as the Autotools' configure script +so usually it handles `--long-options`, possibly with values. It handles +two kinds of options: + +* special options to be resolved inside the script and possibly do some +advanced checks; this should later turn into a set of specific cmake +variable declarations + +* options that are directly translated to cmake variables + +The last one always does a simple transformation: + +* all letters uppercase +* dash into underscore +* plus into X +* when no value is supplied, it defaults to 1 + +So, e.g., `--enable-c++11` turns into `-DENABLE_CXX11=1` option passed +to cmake. + +Additionally, if you specify `--disable-`, the `configure` script +will automatically turn it into an associated `--enable-` option +with passing `0` as its value. So e.g. `--disable-encryption` will +be translated for cmake into `-DENABLE_ENCRYPTION=0`. + +All options below will be presented in the `configure` convention. All +these options are available as well in cmake with appropriately changed +name format. + + +Build options +============= + +`--cygwin-use-posix` (default:OFF) +---------------------------------- + +When ON, compile on Cygwin using POSIX API (otherwise it will use MinGW environment). + + +`--enable-apps` (default: ON) +----------------------------- + +Enables compiling user applications. + + +`--enable-code-coverage` (default: OFF) +--------------------------------------- + +Enable instrumentation for code coverage. Note that this is only available +on POSIX-compatible platforms. + + +`--enable-c++-deps` (default: OFF) +---------------------------------- + +The `pkg-confg` file (`srt.pc`) will be generated with having the +libstdc++ library among dependencies. This may be required in some +cases where you have an application written in C and therefore it +won't link against libstdc++ by default. + +`--enable-c++11` (default: ON) +------------------------------- + +Enable compiling in C++11 mode for those parts that require it. + +NOTE: Currently this embraces all user applications (such as +`srt-live-transmit`), testing applications and unit tests, but this may be +changed in future. Anyway, the SRT library itself is still guaranteed to be +compiled and not functionally impaired, even if C++11 is turned off, although +this need not be supported on all platforms. + + +`--enable-debug=<0,1,2>` +------------------------------- + +This option allows a control through the `CMAKE_BUILD_TYPE` variable: + +* 0 (default): `Release` (highly optimized, no debug info) +* 1: `Debug` (not optimized, full debug info) +* 2: `DebWithRelInfo` (highly optimized, but with debug info) + +Please note that when the value is other than 0, it makes the +`--enable-heavy-logging` option also ON by default. + + +`--enable-encryption` (default: ON) +----------------------------------- + +Encryption feature enabled, which involves dependency on an external encryption +library (default: openssl). If you disable encryption, the library will be unable +to set encryption options, although it will be compatible with a peer that has +encryption enabled, just doesn't use encryption for the connection. + + +`--enable-getnameinfo` (default: OFF) +------------------------------------- + +Enables the use of `getnameinfo` in a "rich" style that allows +using reverse DNS to resolve an internal IP address into a readable +internet domain name, so that it can be shown nicely in the log +file. Not turned on by default because it may cause a dirty impact +on performance in general. This is actually useful only for +development when testing in the local network. + + +`--enable-haicrypt-logging` +------------------------------- + +Enables loggin in the *haicrypt* module, which serves as a connector to +an encryption library. Logging here might be seen as unsafe sometimes, +therefore it's turned off by default. + + +`--enable-heavy-logging` (default: OFF in release mode) +------------------------------------------------------- + +This option enables the logging instructions in the code that are considered +heavy, they occur often and inform about very detailed parts of the library +behavior (usually debug-level logs). Turning this option ON will allow you +using the `debug` level of logging and get a very detailed information as to what +happens inside the library. Note however that this may influence the processing +by changing times, use less preferred thread switching layout, and generally +worsen the functionality and performance of the library. Therefore this option +is not turned on by default. + + +`--enable-inet-pton` (default: ON) +---------------------------------- + +Enables usage of `inet_pton` function by the applications, which should be used +to resolve the network endpoint name into an IP address. This may be not +availabe on some version of Windows, in which case you can turn this OFF, +however at the expense of not being able to resolve IP address by name, +as the `inet_pton` function gets a poor-man's simple replacement that can +only resolve numeric IPv4 addresses. + + +`--enable-logging` (default: ON) +------------------------------- + +Enables logging. When you turn this option OFF, logging will not be +done at all. Could be tried when you suspect the logging system of +impairing the performance, at the expense of not having some information +about errors happening during runtime. + + +`--enable-monotonic-clock` (default: OFF) +----------------------------------------- + +Enforced `clock_gettime` with monotonic clock on Garbage Collector CV. +This is a temporary fix for #729: The library could got stuck when you +modify the system clock while a transmission is done over SRT. + +This option enforces the use of `clock_gettime` to get the current +time, instead of `gettimeofday`. This function allows to force a monotonic +clock, which is independent on the currently set time in the system. The CV, +for which the `*_timedwait()` functions are used with so obtained current time, +must be appropriately configured (and this is done so for now only for the +GarbageCollector controlling CV, not every CV used in SRT). The consequence of +enabling this option, however, may be portability issues around the +`clock_gettime()` function, which is not available on every SDK, or extra +`-lrt` option is sometimes required (this requirement will be autodetected). + +This option will be removed when the problem is fixed globally. + + +`--enable-pktinfo` (default: OFF) +--------------------------------- + +This option allows for extraction the target IP address from the incoming +UDP packets and forceful setting of the source IP address in the outgoing +UDP packets. This ensures that if a packet comes in to raise a new connection +to be established, the UDP packet sent in response will have the source IP +address set the same as the target IP address was in the incoming UDP packet. + +When this is OFF, the source IP address in such outgoing UDP packet will +be set automatically, and it will be the local IP address assigned to the +network broadcast address that matches the target IP address. This may +cause a problem in case when you have more than one local IP address +assigned to the same broadcast and other than first in order will be +contacted by the caller peer. Example: + +You have the following local IP addreses: + +* 192.168.10.11: broadcast 192.168.10.0 +* 10.0.1.15: broadcast 10.0.1.0 +* 10.0.1.20: broadcast 10.0.1.0 + +When a caller is contacting this first address (no matter where it came +from), the response packet will be sent back to this address and the +route path will use this first one as well, so the IP address will +be 192.168.10.11, same as the one that was contacted. + +However, if the caller handshake packet comes from the address that +matches the 10.0.1.0 broadcast, that is, common for the second and +third address, and the target address will be 10.0.1.20, the response +packet will be sent back to this address over the network assigned +to the 10.0.1.0 broadcast, but the source address will be then 10.0.1.15 +because this is the first local address assigned to this route path. + +When this happens, the caller can see that it has sent the handshake +packets to 10.0.1.20, but the returning packet has 10.0.1.15 as source, +and this will be treated as an attack attempt, so the handshake response +will be rejected. + +This fixes this problem by forcefully setting the source IP address +in such a response packet to 10.0.1.20 as in the above example and +this will be interpreted by the caller correctly. + +This feature is turned off because the impact on performance here is +not well enough determined. The problem here is that this causes +that the CMSG information be read from and set on every packet in case +when the socket was bound to the "any" address. + + +`--enable-profile` (default: OFF) +------------------------------- + +Enables code instrumentation for profiling. +This is available only for GNU-compatible compilers. + + +`--enable-relative-libpath` (default: OFF) +------------------------------------------ + +Enables adding the relative path to a library that allows applications +to get linked against a shared SRT library by reaching out to a sibling +`../lib` directory, provided that the library and applications are installed +in the POSIX/GNU style directories. This might be useful when instaling +SRT and the applications in some its own directory, where the global library +path does not lead. There have been reported problems that it may cause +additionally, so this is OFF by default. + + +`--enable-shared` and `--enable-static` (both default: ON) +---------------------------------------------------------- + +Enables building SRT as a shared and static library. + +As both are ON by default, this option allows you for turning +off building a library in a style that is not of your interest, +for example, leave only static one by `--disable-shared`. + + +`--enable-testing` (default: OFF) +--------------------------------- + +Enables compiling developer testing appliactions. + + +`--enable-thread-check` +------------------------------- + +Enable `#include ` that implements `THREAD_*` macros" + +`--enable-unittests` (default: OFF) +----------------------------------- + +Developer option. When ON, the unit tests, possibly with downloading and installing +the google test library in the build directory, will be enabled, and the tests will +be run as part of the build process. + + +`--openssl-crypto-library=` +------------------------------- + +Configure the path to an OpenSSL Crypto library. + + +`--openssl-include-dir=` +------------------------------- + +Configure the path to include files for OpenSSL library. + + +`--openssl-ssl-library=` +------------------------------- + +Configure the path to an OpenSSL SSL library. + + +`--pkg-config-executable=` +------------------------------- + +Configure the path to `pkg-config` tool. + + +`--pthread-include-dir=` +------------------------------- + +Configure the path to include files for pthread library +(note that this makes sense only on Windows; on Linux +and MacOS this path should be available in the system) + + +`--pthread-library=` +------------------------------- + +Configure the path to a pthread library. + + +`--use-busy-waiting` (default: OFF) +----------------------------------- + +Enable more accurate sending times at a cost of potentially higher CPU load. + +This option will cause more empty loop running, which may cost +more CPU usage, but in case of processing high bitrate streams +the share of empty loop runs will decrease the more the +higher the bitrate, whereas without system-supported waiting it +may give more chance to switch to the right thread at the time +when it is expected to be revived. + + +`--use-gnustl` +------------------------------- + +Use `pkg-config` with `gnustl` package name to extract the +header and library path for the C++ standard library (instead +of using the compiler-builtin one). + + +`--use-enclib=` +------------------------------- + +Encryption library to be used. Possible choice for ``: + +* openssl(default) +* gnutls (with nettle) +* mbedtls + + +`--use-gnutls` +------------------------------- + +DEPRECATED. Use `--use-enclib=gnutls` instead. + + +`--use-openssl-pc` (default: ON) +-------------------------------- + +Use `pkg-config` to find OpenSSL libraries. You can turn this +off to force cmake to find OpenSSL by its own most preferred +method. + + +`--use-static-libstdc++` (default: OFF) +--------------------------------------- + +Enforces linking the SRT library against the static libstdc++ +library. This may be useful if you are using SRT library in +an environment, where it would by default link against the +wrong version of the C++ standard library, or the library in +this version that was used by the compiler is not available +as shared. + + +`--with-compiler-prefix=` +--------------------------------- + +Set C/C++ toolchains `gcc` and `g++`. + +This option will override the compiler and it's handled inside cmake. +This sets variables `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER`. Given +prefix is then appropriately extended with a suffix dependent on the +compiler type - see `--with-compiler-type`. + + +`--with-compiler-type=` +----------------------------- + +Sets the compiler type to be used when `--with-compiler-prefix`: + +* gcc (default): gcc and g++ +* cc: cc and c++ +* others: use the `` as C compiler and `++` as C++ compiler + + + + + + + + From ed1c43684b0cd6762c0db3511813e97c257d1e8c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Ma=C5=82ecki?= Date: Tue, 24 Sep 2019 12:53:36 +0200 Subject: [PATCH 02/10] Fixed some typos and added lacking option --- docs/BuildOptions.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/BuildOptions.md b/docs/BuildOptions.md index 9f7eb330b..e134893a6 100644 --- a/docs/BuildOptions.md +++ b/docs/BuildOptions.md @@ -12,8 +12,8 @@ Portability The cmake build system was tested on the following platforms: - - Linux - - MaxOS (you may want to see [separate document](build_iOS.md) + - Linux (various flavors) + - Mac OS (you may want to see [separate document](build_iOS.md)) - Windows with MinGW - Windows with Microsoft Visual Studio - Android (see [separate document](Android/Compiling.md)) @@ -312,6 +312,16 @@ Configure the path to an OpenSSL SSL library. Configure the path to `pkg-config` tool. +`--prefix=` +----------------- + +This is an alias to `--cmake-install-prefix`. This is the root +directory for installation, inside which next GNU/POSIX compatible +directory layout will be used for particular parts. As on all +known build systems, this defaults to `/usr/local` on POSIX +compatible systems. + + `--pthread-include-dir=` ------------------------------- From 7d3f90ff87d5b69528be7feb37690a0275f30c7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Ma=C5=82ecki?= Date: Tue, 24 Sep 2019 13:36:48 +0200 Subject: [PATCH 03/10] Fixed some more typos and improved description --- docs/BuildOptions.md | 109 +++++++++++++++++++++++++++---------------- 1 file changed, 68 insertions(+), 41 deletions(-) diff --git a/docs/BuildOptions.md b/docs/BuildOptions.md index e134893a6..db9f1b12e 100644 --- a/docs/BuildOptions.md +++ b/docs/BuildOptions.md @@ -88,13 +88,25 @@ won't link against libstdc++ by default. `--enable-c++11` (default: ON) ------------------------------- -Enable compiling in C++11 mode for those parts that require it. +Enable compiling in C++11 mode for those parts that may require it. +Parts that don't require it will be compiled still in C++03 mode, +although which parts are affected, may change in future. -NOTE: Currently this embraces all user applications (such as -`srt-live-transmit`), testing applications and unit tests, but this may be -changed in future. Anyway, the SRT library itself is still guaranteed to be -compiled and not functionally impaired, even if C++11 is turned off, although -this need not be supported on all platforms. +If this option is turned off, it affects building this project twofold: + +* an alternative C++03 implementation can be used, if available +* otherwise the component that requires it will be disabled + +Parts that currently require C++11 and have no alternative implementation +are: + +* unit tests +* user and testing applications (such as `srt-live-transmit`) +* some of the example applications + +The SRT library alone should be able to be compiled without C++11 +support, however this alternative C++03 implementation may be unsupported +on some platforms. `--enable-debug=<0,1,2>` @@ -104,7 +116,7 @@ This option allows a control through the `CMAKE_BUILD_TYPE` variable: * 0 (default): `Release` (highly optimized, no debug info) * 1: `Debug` (not optimized, full debug info) -* 2: `DebWithRelInfo` (highly optimized, but with debug info) +* 2: `RelWithDebInfo` (highly optimized, but with debug info) Please note that when the value is other than 0, it makes the `--enable-heavy-logging` option also ON by default. @@ -133,7 +145,7 @@ development when testing in the local network. `--enable-haicrypt-logging` ------------------------------- -Enables loggin in the *haicrypt* module, which serves as a connector to +Enables logging in the *haicrypt* module, which serves as a connector to an encryption library. Logging here might be seen as unsafe sometimes, therefore it's turned off by default. @@ -175,7 +187,7 @@ about errors happening during runtime. ----------------------------------------- Enforced `clock_gettime` with monotonic clock on Garbage Collector CV. -This is a temporary fix for #729: The library could got stuck when you +**This is a temporary fix for #729**: The library could got stuck when you modify the system clock while a transmission is done over SRT. This option enforces the use of `clock_gettime` to get the current @@ -194,20 +206,24 @@ This option will be removed when the problem is fixed globally. `--enable-pktinfo` (default: OFF) --------------------------------- -This option allows for extraction the target IP address from the incoming +This option allows extracting the target IP address from the incoming UDP packets and forceful setting of the source IP address in the outgoing -UDP packets. This ensures that if a packet comes in to raise a new connection -to be established, the UDP packet sent in response will have the source IP -address set the same as the target IP address was in the incoming UDP packet. +UDP packets. This ensures that if a packet comes in from a peer that requests a +new connection, the agent will respond with a UDP packet, which has the +source IP address exactly the same as the one, which the peer is trying to +connect to. When this is OFF, the source IP address in such outgoing UDP packet will -be set automatically, and it will be the local IP address assigned to the -network broadcast address that matches the target IP address. This may -cause a problem in case when you have more than one local IP address -assigned to the same broadcast and other than first in order will be -contacted by the caller peer. Example: +be set automatically the following way: -You have the following local IP addreses: +* For given destination IP address in the UDP packet to be sent, find +the routing table that matches this address, get its network device +and configured network broadcast address + +* set the **first** local IP address that matches the broadcast +address as found above as the source IP address for this UDP packet + +Exmaple: You have the following local IP addreses: * 192.168.10.11: broadcast 192.168.10.0 * 10.0.1.15: broadcast 10.0.1.0 @@ -225,25 +241,37 @@ packet will be sent back to this address over the network assigned to the 10.0.1.0 broadcast, but the source address will be then 10.0.1.15 because this is the first local address assigned to this route path. -When this happens, the caller can see that it has sent the handshake -packets to 10.0.1.20, but the returning packet has 10.0.1.15 as source, -and this will be treated as an attack attempt, so the handshake response -will be rejected. - -This fixes this problem by forcefully setting the source IP address -in such a response packet to 10.0.1.20 as in the above example and -this will be interpreted by the caller correctly. - -This feature is turned off because the impact on performance here is -not well enough determined. The problem here is that this causes +When this happens, the caller peer will see a mismatch between the +source 10.0.1.15 address and the address it tried to contact, that +is, 10.0.1.20. It will be then treated as an attack attempt and +rejected. + +This problem can be slightly mitigated by binding the listening socket +to the exact address. So, if you bind it to 10.0.1.20 in the above +example, then wherever you try to send the packet over such a socket, +it will always have the source address 10.0.1.20 (and the fix provided +by this option will also not apply in this case). However, this problem +still exists if the listener socket is bound to the "whole machine", +that is, it's set to "any" address. + +This option fixes this problem by forcefully setting the source IP address in +such a response packet to 10.0.1.20 as in the above example and this will be +interpreted by the caller peer correctly. + +This feature is turned off by default because the impact on performance +here is currently unknown. The problem here is that this causes that the CMSG information be read from and set on every packet in case -when the socket was bound to the "any" address. +when the socket was bound to the "any" address, so effectively it will +be extracted from every incoming packet, as long as it is not bound +to a specific address, including data packets coming in within the +frames of an existing connection. `--enable-profile` (default: OFF) ------------------------------- Enables code instrumentation for profiling. + This is available only for GNU-compatible compilers. @@ -266,7 +294,8 @@ Enables building SRT as a shared and static library. As both are ON by default, this option allows you for turning off building a library in a style that is not of your interest, -for example, leave only static one by `--disable-shared`. +for example, leave only static one by `--disable-shared`. You +can't disable both at once. `--enable-testing` (default: OFF) @@ -275,10 +304,14 @@ for example, leave only static one by `--disable-shared`. Enables compiling developer testing appliactions. -`--enable-thread-check` -------------------------------- +`--enable-thread-check` (default: OFF) +-------------------------------------- + +Enable `#include ` that implements `THREAD_*` macros". + +This is a solution used by one of the users to support better thread +debugging. -Enable `#include ` that implements `THREAD_*` macros" `--enable-unittests` (default: OFF) ----------------------------------- @@ -367,12 +400,6 @@ Encryption library to be used. Possible choice for ``: * mbedtls -`--use-gnutls` -------------------------------- - -DEPRECATED. Use `--use-enclib=gnutls` instead. - - `--use-openssl-pc` (default: ON) -------------------------------- From 28d2b6117f8d77c9991f56cd5197b459aeeba724 Mon Sep 17 00:00:00 2001 From: Sektor van Skijlen Date: Wed, 25 Sep 2019 11:35:20 +0200 Subject: [PATCH 04/10] Fixed link. Updated link name. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 12e6b1830..0ad295152 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ As audio/video packets are streamed from a source to a destination device, SRT d * OpenSSL * Pthreads (for POSIX systems it's builtin, for Windows there's a library) -For detailed description of the build system and options, please [read here](BuildOptions.md). +For detailed description of the build system and options, please [read](docs/BuildOptions.md). ## For Linux: From bda090d082bbce5d1a5bc33823ebb38f3ae9c37f Mon Sep 17 00:00:00 2001 From: Sektor van Skijlen Date: Wed, 25 Sep 2019 12:18:29 +0200 Subject: [PATCH 05/10] Fixed ON/OFF description for pktinfo --- docs/BuildOptions.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/BuildOptions.md b/docs/BuildOptions.md index db9f1b12e..184861fce 100644 --- a/docs/BuildOptions.md +++ b/docs/BuildOptions.md @@ -213,8 +213,8 @@ new connection, the agent will respond with a UDP packet, which has the source IP address exactly the same as the one, which the peer is trying to connect to. -When this is OFF, the source IP address in such outgoing UDP packet will -be set automatically the following way: +When this is OFF (default), the source IP address in such outgoing UDP +packet will be set automatically the following way: * For given destination IP address in the UDP packet to be sent, find the routing table that matches this address, get its network device @@ -254,9 +254,11 @@ by this option will also not apply in this case). However, this problem still exists if the listener socket is bound to the "whole machine", that is, it's set to "any" address. -This option fixes this problem by forcefully setting the source IP address in -such a response packet to 10.0.1.20 as in the above example and this will be -interpreted by the caller peer correctly. +When this option is ON, a mechanism is added to forcefully set the source +IP address in such a response packet to 10.0.1.20 in the above example, +as well as this address is first extracted from the incoming packet as the +target address. This fixes the problem, as this will be interpreted by +the caller peer correctly. This feature is turned off by default because the impact on performance here is currently unknown. The problem here is that this causes From 386f908dcc1e8e1576f5c0fa1031429e30d95419 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Ma=C5=82ecki?= Date: Thu, 26 Sep 2019 11:08:55 +0200 Subject: [PATCH 06/10] Fixed after review: round 1 --- docs/BuildOptions.md | 462 +++++++++++++++++++------------------------ 1 file changed, 201 insertions(+), 261 deletions(-) diff --git a/docs/BuildOptions.md b/docs/BuildOptions.md index db9f1b12e..b4ee8c048 100644 --- a/docs/BuildOptions.md +++ b/docs/BuildOptions.md @@ -1,98 +1,86 @@ -Build system -============ +# Build System -The main build system for SRT is provided by `cmake` tool. You can always use -it directly, if you want. However, there's also a wrapper script that can make -operating with the options easier (requires Tcl interpreter), which is a -script named `configure`. +The main build system for SRT is provided by the `cmake` tool, which can be +used directly. There's also a wrapper script named `configure` (requires Tcl +interpreter) that can make operating with the options easier. -Portability -=========== +## Portability -The cmake build system was tested on the following platforms: +The `cmake` build system was tested on the following platforms: - Linux (various flavors) - - Mac OS (you may want to see [separate document](build_iOS.md)) + - macOS (see this [separate document](build_iOS.md)) - Windows with MinGW - Windows with Microsoft Visual Studio - - Android (see [separate document](Android/Compiling.md)) + - Android (see this [separate document](Android/Compiling.md)) - Cygwin (only for testing) -The configure script wasn't tested on Windows (unless on Cygwin) +The `configure` script wasn't tested on Windows (other than on Cygwin). -The configure helper script -=========================== +## The `configure` Script -This script is designed to look similar as the Autotools' configure script -so usually it handles `--long-options`, possibly with values. It handles +This script is similar in design to the Autotools' `configure` script, and +so usually handles `--long-options`, possibly with values. It handles two kinds of options: -* special options to be resolved inside the script and possibly do some -advanced checks; this should later turn into a set of specific cmake +* special options to be resolved inside the script and that may do some +advanced checks; this should later turn into a set of specific `cmake` variable declarations -* options that are directly translated to cmake variables +* options that are directly translated to `cmake` variables. -The last one always does a simple transformation: +The direct translate option always does a simple transformation: * all letters uppercase * dash into underscore * plus into X * when no value is supplied, it defaults to 1 -So, e.g., `--enable-c++11` turns into `-DENABLE_CXX11=1` option passed -to cmake. +For example, `--enable-c++11` turns into `-DENABLE_CXX11=1` when passed +to `cmake`. Additionally, if you specify `--disable-`, the `configure` script -will automatically turn it into an associated `--enable-` option -with passing `0` as its value. So e.g. `--disable-encryption` will -be translated for cmake into `-DENABLE_ENCRYPTION=0`. +will automatically turn it into an associated `--enable-` option, + passing `0` as its value. For example, `--disable-encryption` will +be translated for `cmake` into `-DENABLE_ENCRYPTION=0`. -All options below will be presented in the `configure` convention. All -these options are available as well in cmake with appropriately changed -name format. +### Build Options +All options below are presented using the `configure` convention. They can all +be used in `cmake` with the appropriate format changes. -Build options -============= -`--cygwin-use-posix` (default:OFF) ----------------------------------- +**`--cygwin-use-posix`** (default:OFF) When ON, compile on Cygwin using POSIX API (otherwise it will use MinGW environment). -`--enable-apps` (default: ON) ------------------------------ +**`--enable-apps`** (default: ON) Enables compiling user applications. -`--enable-code-coverage` (default: OFF) ---------------------------------------- +**`--enable-code-coverage`** (default: OFF) Enable instrumentation for code coverage. Note that this is only available -on POSIX-compatible platforms. +on platforms with GNU-compatible compiler. -`--enable-c++-deps` (default: OFF) ----------------------------------- +**`--enable-c++-deps`** (default: OFF) -The `pkg-confg` file (`srt.pc`) will be generated with having the -libstdc++ library among dependencies. This may be required in some -cases where you have an application written in C and therefore it -won't link against libstdc++ by default. +The `pkg-confg` file (`srt.pc`) will be generated with the `libstdc++` library +as a dependency. This may be required in some cases where you have an application +written in C which therefore won't link against `libstdc++` by default. -`--enable-c++11` (default: ON) -------------------------------- +**`--enable-c++11`** (default: ON) Enable compiling in C++11 mode for those parts that may require it. -Parts that don't require it will be compiled still in C++03 mode, -although which parts are affected, may change in future. +Parts that don't require it will still be compiled in C++03 mode, +although which parts are affected may change in future. -If this option is turned off, it affects building this project twofold: +If this option is turned OFF, it affects building a project in two ways: * an alternative C++03 implementation can be used, if available * otherwise the component that requires it will be disabled @@ -104,67 +92,58 @@ are: * user and testing applications (such as `srt-live-transmit`) * some of the example applications -The SRT library alone should be able to be compiled without C++11 -support, however this alternative C++03 implementation may be unsupported -on some platforms. +It should be possible to compile the SRT library without C++11 support. However, +this alternative C++03 implementation may be unsupported on certain platforms. -`--enable-debug=<0,1,2>` -------------------------------- +**`--enable-debug=<0,1,2>`** -This option allows a control through the `CMAKE_BUILD_TYPE` variable: +This option allows control through the `CMAKE_BUILD_TYPE` variable: * 0 (default): `Release` (highly optimized, no debug info) * 1: `Debug` (not optimized, full debug info) * 2: `RelWithDebInfo` (highly optimized, but with debug info) -Please note that when the value is other than 0, it makes the -`--enable-heavy-logging` option also ON by default. +Please note that when the value is other than 0, the +`--enable-heavy-logging` option is also turned ON by default. -`--enable-encryption` (default: ON) ------------------------------------ +**`--enable-encryption`** (default: ON) Encryption feature enabled, which involves dependency on an external encryption library (default: openssl). If you disable encryption, the library will be unable -to set encryption options, although it will be compatible with a peer that has -encryption enabled, just doesn't use encryption for the connection. +to set encryption options. It will be compatible with a peer that has +encryption enabled, but just won't use encryption for the connection. -`--enable-getnameinfo` (default: OFF) -------------------------------------- +**`--enable-getnameinfo`** (default: OFF) -Enables the use of `getnameinfo` in a "rich" style that allows -using reverse DNS to resolve an internal IP address into a readable -internet domain name, so that it can be shown nicely in the log -file. Not turned on by default because it may cause a dirty impact -on performance in general. This is actually useful only for -development when testing in the local network. +Enables the use of `getnameinfo` using options that allow using reverse DNS to +resolve an internal IP address into a readable internet domain name, so that it +can be shown nicely in the log file. This option is turned OFF by default +because it may have an impact on general performance. It is recommended only for +development when testing on a local network. -`--enable-haicrypt-logging` -------------------------------- +**`--enable-haicrypt-logging`** (default: OFF) Enables logging in the *haicrypt* module, which serves as a connector to -an encryption library. Logging here might be seen as unsafe sometimes, -therefore it's turned off by default. +an encryption library. Logging here might be seen as unsafe, therefore this +option is turned OFF by default. -`--enable-heavy-logging` (default: OFF in release mode) -------------------------------------------------------- +**`--enable-heavy-logging`** (default: OFF in release mode) -This option enables the logging instructions in the code that are considered -heavy, they occur often and inform about very detailed parts of the library -behavior (usually debug-level logs). Turning this option ON will allow you -using the `debug` level of logging and get a very detailed information as to what -happens inside the library. Note however that this may influence the processing -by changing times, use less preferred thread switching layout, and generally -worsen the functionality and performance of the library. Therefore this option -is not turned on by default. +This option enables the logging instructions in the code, which are considered +heavy as they occur often and cover many detailed aspects of library behavior. +Turning this option ON will allow you to use the `debug` level of logging and get +detailed information as to what happens inside the library. Note, however, that +this may influence processing by changing times, using less preferred thread +switching layouts, and generally worsen the functionality and performance of +the library. For these reasons this option is turned OFF by default. -`--enable-inet-pton` (default: ON) ----------------------------------- +**`--enable-inet-pton`** (default: ON) Enables usage of `inet_pton` function by the applications, which should be used to resolve the network endpoint name into an IP address. This may be not @@ -174,275 +153,236 @@ as the `inet_pton` function gets a poor-man's simple replacement that can only resolve numeric IPv4 addresses. -`--enable-logging` (default: ON) -------------------------------- +**`--enable-logging`** (default: ON) -Enables logging. When you turn this option OFF, logging will not be -done at all. Could be tried when you suspect the logging system of -impairing the performance, at the expense of not having some information -about errors happening during runtime. +Enables logging. When you turn this option OFF, the library will not report +any runtime information through the logging system, including errors. +This option may be useful if you suspect the logging system of +impairing performance. -`--enable-monotonic-clock` (default: OFF) ------------------------------------------ - -Enforced `clock_gettime` with monotonic clock on Garbage Collector CV. -**This is a temporary fix for #729**: The library could got stuck when you -modify the system clock while a transmission is done over SRT. +**`--enable-monotonic-clock`** (default: OFF) This option enforces the use of `clock_gettime` to get the current -time, instead of `gettimeofday`. This function allows to force a monotonic -clock, which is independent on the currently set time in the system. The CV, -for which the `*_timedwait()` functions are used with so obtained current time, -must be appropriately configured (and this is done so for now only for the -GarbageCollector controlling CV, not every CV used in SRT). The consequence of -enabling this option, however, may be portability issues around the -`clock_gettime()` function, which is not available on every SDK, or extra +time, instead of `gettimeofday`. This function forces the use of a monotonic +clock that is independent of the currently set time in the system. +The condition variables, for which the `*_timedwait()` functions are used +with time specification basing on the time obtained from `clock_gettime` +must be appropriately configured. For now, this is only done for the +GarbageCollector controlling CV, not every CV used in SRT. The consequence +of enabling this option, however, may be portability issues resulting from +the fact that `clock_gettime` function may be unavailable in some SDKs or an extra `-lrt` option is sometimes required (this requirement will be autodetected). -This option will be removed when the problem is fixed globally. +**NOTE:** *This is a temporary fix for Issue #729* where the library could get +stuck if the system clock is modified during an SRT transmission. This option +will be removed when the problem is fixed globally. -`--enable-pktinfo` (default: OFF) ---------------------------------- +**`--enable-pktinfo`** (default: OFF) -This option allows extracting the target IP address from the incoming -UDP packets and forceful setting of the source IP address in the outgoing +This option allows the extraction of a target IP address from incoming +UDP packets and the forceful setting of the source IP address in outgoing UDP packets. This ensures that if a packet comes in from a peer that requests a -new connection, the agent will respond with a UDP packet, which has the -source IP address exactly the same as the one, which the peer is trying to -connect to. +new connection, the agent will respond with a UDP packet that has the +same source IP address as the one to which the peer is trying to connect. -When this is OFF, the source IP address in such outgoing UDP packet will -be set automatically the following way: +When this option is OFF (default), the source IP address in an outgoing +UDP packet will be set automatically the following way: -* For given destination IP address in the UDP packet to be sent, find -the routing table that matches this address, get its network device +* For a given destination IP address in the UDP packet to be sent, find +the routing table entry that matches this address, then get its network device and configured network broadcast address -* set the **first** local IP address that matches the broadcast -address as found above as the source IP address for this UDP packet +* Set the **first** local IP address that matches the broadcast +address found above as the source IP address for this UDP packet. -Exmaple: You have the following local IP addreses: +Example: Let's say you have the following local IP addresses: * 192.168.10.11: broadcast 192.168.10.0 * 10.0.1.15: broadcast 10.0.1.0 * 10.0.1.20: broadcast 10.0.1.0 -When a caller is contacting this first address (no matter where it came -from), the response packet will be sent back to this address and the -route path will use this first one as well, so the IP address will -be 192.168.10.11, same as the one that was contacted. - -However, if the caller handshake packet comes from the address that -matches the 10.0.1.0 broadcast, that is, common for the second and -third address, and the target address will be 10.0.1.20, the response -packet will be sent back to this address over the network assigned -to the 10.0.1.0 broadcast, but the source address will be then 10.0.1.15 -because this is the first local address assigned to this route path. - -When this happens, the caller peer will see a mismatch between the -source 10.0.1.15 address and the address it tried to contact, that -is, 10.0.1.20. It will be then treated as an attack attempt and -rejected. - -This problem can be slightly mitigated by binding the listening socket -to the exact address. So, if you bind it to 10.0.1.20 in the above -example, then wherever you try to send the packet over such a socket, -it will always have the source address 10.0.1.20 (and the fix provided -by this option will also not apply in this case). However, this problem -still exists if the listener socket is bound to the "whole machine", -that is, it's set to "any" address. - -This option fixes this problem by forcefully setting the source IP address in -such a response packet to 10.0.1.20 as in the above example and this will be -interpreted by the caller peer correctly. - -This feature is turned off by default because the impact on performance -here is currently unknown. The problem here is that this causes -that the CMSG information be read from and set on every packet in case -when the socket was bound to the "any" address, so effectively it will -be extracted from every incoming packet, as long as it is not bound -to a specific address, including data packets coming in within the -frames of an existing connection. - - -`--enable-profile` (default: OFF) -------------------------------- +When a caller is contacting this first address (no matter where it came from), +the response packet will be sent back to this address. The route path will use +this first address as well, so the source IP address will be 192.168.10.11, same as +the one that was contacted. -Enables code instrumentation for profiling. +If the caller handshake packet comes from the address that matches the 10.0.1.0 +broadcast (which is common to the second and third addresses), and the target +address is 10.0.1.20, the response packet will be sent back to this address over +the network assigned to the 10.0.1.0 broadcast. But the source address will then +be 10.0.1.15 because it is the first local address assigned to the route path. -This is available only for GNU-compatible compilers. +When this happens, the caller peer will see a mismatch between the source +10.0.1.15 address and the address it tried to contact (i.e. 10.0.1.20). It will +be treated as an attack attempt and rejected. + +This problem can be slightly mitigated by binding the listening socket to a +specific address. So, if you bind it to 10.0.1.20 in the above example, then +wherever you try to send a packet over that socket it will always have the +source address 10.0.1.20 (and the fix provided by this option will also not +apply in this case). However, this problem still exists if the listener socket +is bound to the "whole machine" (i.e. set to "any" address). + +When the `--enable-pktinfo` option is ON, a mechanism is added to forcefully set +the source IP address in a response packet (to 10.0.1.20 in the above example). +This address is first extracted from the incoming packet as the target address. +This fixes the problem, as it will be interpreted by the caller peer correctly. +This feature is turned off by default because the impact on performance is +currently unknown. The problem is that it causes the CMSG information to be read +from (and set on) every packet when a socket is bound to "any" address. The +CMSG information will effectively be extracted from every incoming packet, as +long as the socket, through which it is sent or received, is not bound to a +specific address, including data packets coming in within the frames of an +existing connection. -`--enable-relative-libpath` (default: OFF) ------------------------------------------- -Enables adding the relative path to a library that allows applications -to get linked against a shared SRT library by reaching out to a sibling -`../lib` directory, provided that the library and applications are installed -in the POSIX/GNU style directories. This might be useful when instaling -SRT and the applications in some its own directory, where the global library -path does not lead. There have been reported problems that it may cause -additionally, so this is OFF by default. +**`--enable-profile`** (default: OFF) + +Enables code instrumentation for profiling. + +This is available only for GNU-compatible compilers. -`--enable-shared` and `--enable-static` (both default: ON) ----------------------------------------------------------- +**`--enable-relative-libpath`** (default: OFF) -Enables building SRT as a shared and static library. +Enables adding a relative path to a library. This allows applications to be +linked against a shared SRT library by reaching out to a sibling `../lib` +directory, provided that the library and applications are installed in POSIX/GNU +style directories. This might be useful when installing SRT and applications +in a directory, in which the library subdirectory is not explicitly defined +among the global library paths (such as `/opt/srt-1.4/lib`, for example). +This option is OFF by default because of reports +that it may cause problems in case of default installation. -As both are ON by default, this option allows you for turning -off building a library in a style that is not of your interest, -for example, leave only static one by `--disable-shared`. You -can't disable both at once. +**`--enable-shared`** and **`--enable-static`** (default for both: ON) -`--enable-testing` (default: OFF) ---------------------------------- +Enables building SRT as a shared and/or static library, as required for your +application. The only practical use is by disabling one of them +(e.g. by `--disable-shared`). Note that you can't disable both at once. -Enables compiling developer testing appliactions. +**`--enable-testing`** (default: OFF) -`--enable-thread-check` (default: OFF) --------------------------------------- +Enables compiling of developer testing applications. -Enable `#include ` that implements `THREAD_*` macros". -This is a solution used by one of the users to support better thread -debugging. +**`--enable-thread-check`** (default: OFF) +Enables `#include `, which implements `THREAD_*` macros" to +support better thread debugging. This is used by one of dependent projects. -`--enable-unittests` (default: OFF) ------------------------------------ -Developer option. When ON, the unit tests, possibly with downloading and installing -the google test library in the build directory, will be enabled, and the tests will -be run as part of the build process. +**`--enable-unittests`** (default: OFF) +When ON, this option enables unit tests, possibly with the download +and installation of the Google test library in the build directory. The tests +will be run as part of the build process. This is predicted for developers only. -`--openssl-crypto-library=` -------------------------------- + +**`--openssl-crypto-library=`** Configure the path to an OpenSSL Crypto library. -`--openssl-include-dir=` -------------------------------- +**`--openssl-include-dir=`** -Configure the path to include files for OpenSSL library. +Configure the path to include files for an OpenSSL library. -`--openssl-ssl-library=` -------------------------------- +**`--openssl-ssl-library=`** Configure the path to an OpenSSL SSL library. -`--pkg-config-executable=` -------------------------------- +**`--pkg-config-executable=`** -Configure the path to `pkg-config` tool. +Configure the path to the `pkg-config` tool. -`--prefix=` ------------------ +**`--prefix=`** -This is an alias to `--cmake-install-prefix`. This is the root -directory for installation, inside which next GNU/POSIX compatible -directory layout will be used for particular parts. As on all -known build systems, this defaults to `/usr/local` on POSIX -compatible systems. +This is an alias to `--cmake-install-prefix`. This is the root directory for +installation, inside which next the GNU/POSIX compatible directory layout will +be used. As on all known build systems, this defaults to +`/usr/local` on POSIX compatible systems. -`--pthread-include-dir=` -------------------------------- +**`--pthread-include-dir=`** -Configure the path to include files for pthread library -(note that this makes sense only on Windows; on Linux -and MacOS this path should be available in the system) +Configure the path to include files for a pthread library. Note that this +is useful only on Windows. On Linux and macOS this path should be available in +the system. -`--pthread-library=` -------------------------------- +**`--pthread-library=`** Configure the path to a pthread library. -`--use-busy-waiting` (default: OFF) ------------------------------------ +**`--use-busy-waiting`** (default: OFF) -Enable more accurate sending times at a cost of potentially higher CPU load. +Enable more accurate sending times at the cost of potentially higher CPU load. -This option will cause more empty loop running, which may cost -more CPU usage, but in case of processing high bitrate streams -the share of empty loop runs will decrease the more the -higher the bitrate, whereas without system-supported waiting it -may give more chance to switch to the right thread at the time -when it is expected to be revived. +This option will cause more empty loop running, which may cause more CPU usage. +Although when processing high bitrate streams the share of empty loop runs will decrease +as the bitrate increases. This way higher CPU usage would still be productive, +while without system-supported waiting this option may increase the likelihood of +switching to the right thread at the time when it is expected to be revived. -`--use-gnustl` -------------------------------- +**`--use-gnustl`** -Use `pkg-config` with `gnustl` package name to extract the -header and library path for the C++ standard library (instead -of using the compiler-builtin one). +Use `pkg-config` with the `gnustl` package name to extract the header and +library path for the C++ standard library (instead of using the compiler +built-in one). -`--use-enclib=` -------------------------------- +**`--use-enclib=`** -Encryption library to be used. Possible choice for ``: +Encryption library to be used. Possible options for ``: * openssl(default) * gnutls (with nettle) * mbedtls -`--use-openssl-pc` (default: ON) --------------------------------- +**`--use-openssl-pc`** (default: ON) -Use `pkg-config` to find OpenSSL libraries. You can turn this -off to force cmake to find OpenSSL by its own most preferred -method. +Use `pkg-config` to find OpenSSL libraries. You can turn this OFF to force +`cmake` to find OpenSSL by its own preferred method. -`--use-static-libstdc++` (default: OFF) ---------------------------------------- +**`--use-static-libstdc++`** (default: OFF) -Enforces linking the SRT library against the static libstdc++ -library. This may be useful if you are using SRT library in -an environment, where it would by default link against the -wrong version of the C++ standard library, or the library in -this version that was used by the compiler is not available -as shared. +Enforces linking the SRT library against the static libstdc++ library. This may +be useful if you are using SRT library in an environment where it would by +default link against the wrong version of the C++ standard library, or when the +library in the version used by the compiler is not available as shared. -`--with-compiler-prefix=` ---------------------------------- +**`--with-compiler-prefix=`** -Set C/C++ toolchains `gcc` and `g++`. +Sets C/C++ toolchains as `` and ``. -This option will override the compiler and it's handled inside cmake. -This sets variables `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER`. Given -prefix is then appropriately extended with a suffix dependent on the -compiler type - see `--with-compiler-type`. +This option will override the default compiler autodetected by `cmake`. +It is handled inside `cmake`. It sets the variables `CMAKE_C_COMPILER` and +`CMAKE_CXX_COMPILER`. The values for the above `` and +`` are controlled by the `--with-compiler-type` option. +Instead of `--with-compiler-prefix` you can use as well `--cmake-c-compiler` +and `--cmake-c++-compiler` options. This can be then thought of as a +shortcut, useful when you have a long path to the compiler command. -`--with-compiler-type=` ------------------------------ +**`--with-compiler-type=`** -Sets the compiler type to be used when `--with-compiler-prefix`: +Sets the compiler type to be used with `--with-compiler-prefix` as +`` and `` respectively: * gcc (default): gcc and g++ * cc: cc and c++ -* others: use the `` as C compiler and `++` as C++ compiler - - - - - - - +* others: use `` as C compiler and `++` as C++ compiler From cbc15bccd31a8b0e5991f9eded07f05b4ced9946 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Ma=C5=82ecki?= Date: Thu, 26 Sep 2019 18:13:16 +0200 Subject: [PATCH 07/10] Post-review fixes phase 2 --- docs/BuildOptions.md | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/docs/BuildOptions.md b/docs/BuildOptions.md index 85b583bd7..614c88ce6 100644 --- a/docs/BuildOptions.md +++ b/docs/BuildOptions.md @@ -166,13 +166,21 @@ impairing performance. This option enforces the use of `clock_gettime` to get the current time, instead of `gettimeofday`. This function forces the use of a monotonic clock that is independent of the currently set time in the system. -The condition variables, for which the `*_timedwait()` functions are used -with time specification basing on the time obtained from `clock_gettime` +The condition variables (CV), for which the `*_timedwait()` functions are used +with time specification based on the time obtained from `clock_gettime` must be appropriately configured. For now, this is only done for the GarbageCollector controlling CV, not every CV used in SRT. The consequence of enabling this option, however, may be portability issues resulting from -the fact that `clock_gettime` function may be unavailable in some SDKs or an extra -`-lrt` option is sometimes required (this requirement will be autodetected). +the fact that `clock_gettime` function may be unavailable in some SDKs or that an +extra `-lrt` option is sometimes required (this requirement will be autodetected). + +The problem is based on the fact that POSIX functions that use timeout +specification (all of `*_timedwait`) expect the absolute time value. +A relative timeout value can be then only specified by adding it to +the current time, which can be specified as either system or monotonic +clock (which one, is configured in the resources used in the operation). +However the current time of the monotonic clock can only be obtained by +the `clock_gettime` function. **NOTE:** *This is a temporary fix for Issue #729* where the library could get stuck if the system clock is modified during an SRT transmission. This option @@ -254,15 +262,27 @@ linked against a shared SRT library by reaching out to a sibling `../lib` directory, provided that the library and applications are installed in POSIX/GNU style directories. This might be useful when installing SRT and applications in a directory, in which the library subdirectory is not explicitly defined -among the global library paths (such as `/opt/srt-1.4/lib`, for example). -This option is OFF by default because of reports -that it may cause problems in case of default installation. +among the global library paths. Consider, for example, this application and its +required library: + +* `/opt/srt/bin/srt-live-transmit` +* `/opt/srt/lib64/libsrt.so` + +By using the `--enable-relative-libpath` option, the `srt-live-transmit` +application has a relative library path defined inside as `../lib64`. A dynamic +linker will find the required `libsrt.so` file by this path: `../lib64/libsrt.so`. +This way the dynamic linkage will work even if `/opt/srt/lib64` path isn't added +to the system paths in `/etc/ld.so.conf` or in the `LD_LIBRARY_PATH` environment +variable. + +This option is OFF by default because of reports that it may cause problems in +case of default installation. **`--enable-shared`** and **`--enable-static`** (default for both: ON) Enables building SRT as a shared and/or static library, as required for your -application. The only practical use is by disabling one of them +application. In practice, you would only disable one or the other (e.g. by `--disable-shared`). Note that you can't disable both at once. From e214088f8e889765fa524690d0fa5492020ccc8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Ma=C5=82ecki?= Date: Fri, 27 Sep 2019 09:41:34 +0200 Subject: [PATCH 08/10] Review fixes (final phase) --- docs/BuildOptions.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/BuildOptions.md b/docs/BuildOptions.md index 614c88ce6..4e4e78d89 100644 --- a/docs/BuildOptions.md +++ b/docs/BuildOptions.md @@ -294,14 +294,14 @@ Enables compiling of developer testing applications. **`--enable-thread-check`** (default: OFF) Enables `#include `, which implements `THREAD_*` macros" to -support better thread debugging. This is used by one of dependent projects. +support better thread debugging. Included to support an existing project. **`--enable-unittests`** (default: OFF) When ON, this option enables unit tests, possibly with the download and installation of the Google test library in the build directory. The tests -will be run as part of the build process. This is predicted for developers only. +will be run as part of the build process. This is intended for developers only. **`--openssl-crypto-library=`** @@ -326,10 +326,11 @@ Configure the path to the `pkg-config` tool. **`--prefix=`** -This is an alias to `--cmake-install-prefix`. This is the root directory for -installation, inside which next the GNU/POSIX compatible directory layout will -be used. As on all known build systems, this defaults to -`/usr/local` on POSIX compatible systems. +This is an alias to the `--cmake-install-prefix` variable that establishes the +root directory for installation, inside of which a GNU/POSIX compatible +directory layout will be used. As on all known build systems, this defaults to +`/usr/local` on GNU/POSIX compatible systems, with lower level GNU/POSIX +directories created inside: `/usr/local/bin`,`/usr/local/lib`, etc. **`--pthread-include-dir=`** @@ -349,10 +350,11 @@ Configure the path to a pthread library. Enable more accurate sending times at the cost of potentially higher CPU load. This option will cause more empty loop running, which may cause more CPU usage. -Although when processing high bitrate streams the share of empty loop runs will decrease -as the bitrate increases. This way higher CPU usage would still be productive, -while without system-supported waiting this option may increase the likelihood of -switching to the right thread at the time when it is expected to be revived. +Keep in mind, however, that when processing high bitrate streams the share of +empty loop runs will decrease as the bitrate increases. This way higher CPU +usage would still be productive, while without system-supported waiting this +option may increase the likelihood of switching to the right thread at the time +when it is expected to be revived. **`--use-gnustl`** @@ -394,8 +396,8 @@ It is handled inside `cmake`. It sets the variables `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER`. The values for the above `` and `` are controlled by the `--with-compiler-type` option. -Instead of `--with-compiler-prefix` you can use as well `--cmake-c-compiler` -and `--cmake-c++-compiler` options. This can be then thought of as a +Instead of `--with-compiler-prefix` you can use `--cmake-c-compiler` +and `--cmake-c++-compiler` options. This can be thought of as a shortcut, useful when you have a long path to the compiler command. **`--with-compiler-type=`** From a9564ac95058450156c2bd52b09ae27ad76e7e33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Ma=C5=82ecki?= Date: Tue, 5 Nov 2019 16:52:55 +0100 Subject: [PATCH 09/10] Post-review fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0ad295152..2262552ca 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ As audio/video packets are streamed from a source to a destination device, SRT d * OpenSSL * Pthreads (for POSIX systems it's builtin, for Windows there's a library) -For detailed description of the build system and options, please [read](docs/BuildOptions.md). +For detailed description of the build system and options, please read [BuildOptions.md](docs/BuildOptions.md). ## For Linux: From fbea9bfaa47ae6af2bb7f041c20332d7e46cabbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20Ma=C5=82ecki?= Date: Wed, 6 Nov 2019 10:05:10 +0100 Subject: [PATCH 10/10] Post-review fixes --- docs/BuildOptions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/BuildOptions.md b/docs/BuildOptions.md index 4e4e78d89..82e12a099 100644 --- a/docs/BuildOptions.md +++ b/docs/BuildOptions.md @@ -147,8 +147,8 @@ the library. For these reasons this option is turned OFF by default. Enables usage of `inet_pton` function by the applications, which should be used to resolve the network endpoint name into an IP address. This may be not -availabe on some version of Windows, in which case you can turn this OFF, -however at the expense of not being able to resolve IP address by name, +availabe on some version of Windows, in which case you can turn this OFF. +When this option is OFF, however, IP addresses cannot be resolved by name, as the `inet_pton` function gets a poor-man's simple replacement that can only resolve numeric IPv4 addresses. @@ -178,7 +178,7 @@ The problem is based on the fact that POSIX functions that use timeout specification (all of `*_timedwait`) expect the absolute time value. A relative timeout value can be then only specified by adding it to the current time, which can be specified as either system or monotonic -clock (which one, is configured in the resources used in the operation). +clock (as configured in the resources used in the operation). However the current time of the monotonic clock can only be obtained by the `clock_gettime` function. @@ -234,9 +234,9 @@ apply in this case). However, this problem still exists if the listener socket is bound to the "whole machine" (i.e. set to "any" address). When this option is ON, a mechanism is added to forcefully set the source -IP address in such a response packet to 10.0.1.20 in the above example, -as well as this address is first extracted from the incoming packet as the -target address. This fixes the problem, as this will be interpreted by +IP address in such a response packet (e.g. to 10.0.1.20 in the above example). +This address is first extracted from the incoming packet as the +target address, which fixes the problem, as this will be interpreted by the caller peer correctly. This feature is turned off by default because the impact on performance is @@ -368,7 +368,7 @@ built-in one). Encryption library to be used. Possible options for ``: -* openssl(default) +* openssl (default) * gnutls (with nettle) * mbedtls