diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db7591693e..b58ac18c61 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -134,7 +134,8 @@ All new code should follow the folder structure. We use [Google test](https://github.com/google/googletest) for our unit and integration tests. We require compatibility with the version 1.8.1. -Have a look at our [best practice guidelines](./doc/website/advanced/best-practice-for-testing.md) for writing tests in iceoryx. +Have a look at our [best practice guidelines](./doc/website/advanced/best-practice-for-testing.md) for writing tests and +[installation guide for contributors](./doc/website/advanced/installation-guide-for-contributors.md#build-and-run-tests) for building them. ### Unit tests (aka module tests) @@ -167,12 +168,12 @@ example: ./tools/iceoryx_build_test.sh debug build-all -c unit ``` **NOTE** -Iceoryx needs to be build as static library for working with gcov flags. The script does it automatically. +Iceoryx needs to be built as static library for working with gcov flags. The script does it automatically. The flag `-c unit` is for having only reports for unit-tests. In the script `tools/gcov/lcov_generate.sh` is the initial scan, filtering and report generation automatically done. -All reports are stored locally in build/lcov as html report (index.html). In Github we are using for codecov for a general reporting of the code coverage. -Codecov gives a brief overview over the code coverage and also indicates in Pull-Requests if new added code is not covered by tests. +All reports are stored locally in build/lcov as html report (index.html). In Github, we are using [codecov](https://about.codecov.io) for a general reporting of the code coverage. +Codecov gives a brief overview of the code coverage and also indicates in Pull-Requests if newly added code is not covered by tests. If you want to download the detailed html reports from the Pull-Requests or master build you can do it by the following way: 1. Open the "Checks" view in the PR 2. Open the "Details" link for the check `iceoryx-coverage-doxygen-ubuntu` in `Test Coverage + Doxygen Documentation` diff --git a/doc/conceptual-guide.md b/doc/conceptual-guide.md index c1846fe2a1..873d4239d4 100644 --- a/doc/conceptual-guide.md +++ b/doc/conceptual-guide.md @@ -78,7 +78,7 @@ The number of segments used by an iceoryx system, along with the configuration o provided to the system via configuration. The configuration can be provided at compile time (as a header) or at runtime (as a toml-formatted text file). -See the [usage guide](website/advanced/installation-guide-for-contributors.md#iceoryx-library-build) for more details. +See the [configuration guide](https://github.com/eclipse-iceoryx/iceoryx/blob/master/doc/website/advanced/configuration-guide.md#configuring-mempools-for-roudi) for more details. # Communication Mechanisms In this section we will have a look at the concepts employed to structure the communication between diff --git a/doc/website/advanced/configuration-guide.md b/doc/website/advanced/configuration-guide.md new file mode 100644 index 0000000000..d167863133 --- /dev/null +++ b/doc/website/advanced/configuration-guide.md @@ -0,0 +1,150 @@ +# Configuration guide + +## CMake switches for configuring iceoryx_posh build + +When building iceoryx_posh, there are several configuration options set by default. +These options adjust the limits of Publisher and Subscriber Ports for resource management. These limits are used to create management structures in the shared memory segment called `iceoryx_mgmt` when starting up RouDi. + + | switch | description | + |:---------|:-------------| + | `IOX_MAX_PUBLISHERS` | Maximum number of publishers which can be managed by one `RouDi` instance | + | `IOX_MAX_SUBSCRIBERS_PER_PUBLISHER` | Maximum number of connected subscriber ports per publisher port | + | `IOX_MAX_PUBLISHER_HISTORY` | Maximum number of chunks available for the publisher history | + | `IOX_MAX_CHUNKS_ALLOCATED_PER_PUBLISHER_SIMULTANEOUSLY` | Maximum number of chunks a publisher can allocate at a given time | + | `IOX_MAX_SUBSCRIBERS` | Maximum number of subscribers which can be managed by one `RouDi` instance | + | `IOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY` | Maximum number of chunks a subscriber can hold at a given time (subscriber history size)| + | `IOX_MAX_INTERFACE_NUMBER` | Maximum number of interface ports which are used for gateways | + +Have a look at [iceoryx_posh_deployment.cmake](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_posh/cmake/iceoryx_posh_deployment.cmake) for the default values of the constants. + +!!! hint + With the default values set, the size of `iceoryx_mgmt` is ~64.5 MByte. You can reduce the size by decreasing the values from the table via the CMake options. The current values are printed in the CMake stage when building iceoryx. + +Example: + +```bash +cmake -Bbuild -Hiceoryx_meta -DIOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY=64 +``` + +With that change, the footprint of the management segment is reduced to ~52.7 MBytes. For larger use cases you can increase the value to avoid that samples are dropped on the subscriber side (see also [#615](https://github.com/eclipse-iceoryx/iceoryx/issues/615)). + +## Configuring Mempools for RouDi + +RouDi supports several shared memory segments with different access rights, to limit the read and write access between different applications. Inside of these segments reside mempools where the user payload data for transfer is stored. +Based on the [conceptual guide](https://github.com/eclipse-iceoryx/iceoryx/blob/master/doc/conceptual-guide.md) the end-user may want to configure the mempools with the number of chunks and their size. + +For building RouDi, iceoryx ships a library named `iceoryx_posh_roudi`. This lib gives you an API for compiling your own RouDi application and is part of `iceoryx_posh`. + +!!! note + The chunk size for the mempool needs to follow these restrictions: + + 1. Chunksize needs to be greater than the alignment + 2. Chunksize needs to be a multiple of the alignment + +The value for the alignment is set to 32. + +### Dynamic configuration + +One way is to read a configuration dynamically at RouDi runtime (startup). +Using TOML Config in RouDi is not mandatory for configuring segments and mempools, but a comfortable alternative. + +To enable the TOML config in iceoryx, the CMake option `-DTOML_CONFIG=ON` must be used (enabled by default). +The `iox-roudi` provided by iceoryx is with TOML support and can be used out of the box. + +If you create your own RouDi application you need to link against `iceoryx_posh_config`: + +```cmake +target_link_libraries(custom-roudi + PRIVATE + iceoryx_posh::iceoryx_posh_roudi + iceoryx_posh::iceoryx_posh_config +) +``` + +The TOML config file can be passed to RouDi with the `-c` command-line option. + +```bash +./iox-roudi -c /absolute/path/to/config/file.toml +``` + +This is a common config file with format version 1: + +```TOML +[general] +version = 1 + +[[segment]] + +[[segment.mempool]] +size = 32 +count = 10000 + +[[segment.mempool]] +size = 128 +count = 10000 + +[[segment.mempool]] +size = 1024 +count = 1000 +``` + +With this configuration, one payload segment will be created. The access rights are set to the RouDi group id. +There are three mempools within this segment. One with 10000 chunks of 32 byte payload size, one with 10000 chunks of 128 bytes, and one with 1000 chunks of 1024 bytes. + +To restrict the access, a reader and writer group can be set: + +```TOML +[general] +version = 1 + +[[segment]] +reader = "foo" +writer = "bar" + +[[segment.mempool]] +size = 32 +count = 10000 + +[[segment.mempool]] +size = 128 +count = 10000 + +[[segment.mempool]] +size = 1024 +count = 1000 +``` + +With this configuration, only applications from the `bar` group have write access and can allocate chunks. Applications from the `foo` group have only read access. + +This is an example with multiple segments: + +```TOML +[general] +version = 1 + +[[segment]] +reader = "foo" +writer = "bar" + +[[segment.mempool]] +size = 32 +count = 10000 + +[[segment]] +reader = "alice" +writer = "eve" + +[[segment.mempool]] +size = 1024 +count = 100 +``` + +When no config file is specified, a hard-coded version similar to the [default config](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_posh/etc/iceoryx/roudi_config_example.toml) will be used. + +### Static configuration + +Another way is to have a static config that is compile-time dependent, this means that you have to recompile your RouDi application if you want to change your config (not the iceoryx_posh_roudi lib). +You can have your source file with `main()` method where you can create your custom configuration and pass it to a RouDi instantiation. +In your CMake file for your custom RouDi you need to ensure that it is **not** linking against `iceoryx_posh_config` to have a static config. + +A good example of a static config can be found [here](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_examples/iceperf/roudi_main_static_config.cpp). diff --git a/doc/website/advanced/installation-guide-for-contributors.md b/doc/website/advanced/installation-guide-for-contributors.md index dd535bb3e4..0b8dbcdb62 100644 --- a/doc/website/advanced/installation-guide-for-contributors.md +++ b/doc/website/advanced/installation-guide-for-contributors.md @@ -2,95 +2,111 @@ ## Build and run tests -While developing on iceoryx you want to know if your changes are breaking existing functions or if your newly written googletests are passing. -For that purpose we are generating cmake targets which are executing the tests. But first we need to build them: -``` +While developing on iceoryx you want to know if your changes are breaking existing functions or if your newly written tests are passing. +For that purpose, we are generating CMake targets that are executing the tests. First, we need to build them: + +```bash cmake -Bbuild -Hiceoryx_meta -DBUILD_TEST=ON cmake --build build ``` -Cmake is automatically installing googletest as dependency and build the tests against it. Please note that if you want to build tests for extensions like the C-Binding you need to enable that in the cmake build. To build all tests simply add `-DBUILD_ALL` to the cmake command -Now lets execute the all tests: -``` +CMake is automatically installing GoogleTest as a local dependency and build the tests against it. Please note that if you want to build tests for extensions like the DDS-Gateway you need to enable this extension as well in the CMake build. To build tests for all extensions simply add `-DBUILD_ALL` to the CMake command. + +!!! hint + Before creating a Pull-Request, you should check your code for compiler warnings. For that purpose is the `-DBUILD_STRICT` CMake option available which treats compiler warnings as errors. This flag is enabled on the GitHub CI for building Pull-Requests. + +Now let's execute tests: + +```bash cd iceoryx/build make all_tests ``` -Some of the tests are timing critical and needs a stable environment. We call them timing tests and have them in a separate targets available: -``` + +Some of the tests are timing critical and need a stable environment. We call them timing tests and have them in separate targets available: + +```bash make timing_module_tests make timing_integration_tests ``` -In iceoryx we distinguish between different testlevels. The most important are: Moduletests and Integrationtests. -Moduletests are basically Unit-tests where the focus is on class level with black-box testing. -In Integrationtests are multiple classes within one component (e.g. iceoryx_posh) tested together. -The sourcecode of the tests is placed into the folder `test` within the different iceoryx components. You can find there at least a folder `moduletests` and sometimes ``integrationtests`. -when you now want to create a new test you can place the sourcefile directly into the right folder. Cmake will automatically detect the new file when doing a clean build and will add it to a executable. There is no need to add a gtest main function because we already provide it. +In iceoryx we distinguish between different test levels. The most important are: Module tests and Integration tests. +Module tests are basically Unit-tests where the focus is on class level with black-box testing. +In integration tests multiple classes (e.g. mepoo config) are tested together. +The source code of the tests is placed into the folder `test` within the different iceoryx components. You can find there at least a folder `moduletests` and sometimes `integrationtests`. + +If you now want to create a new test you can place the sourcefile directly into the right folder. CMake will automatically detect the new file when doing a clean build and will add it to a executable. There is no need to add a gtest main function because we already provide it. For every test level are executables created, for example `posh_moduletests`. They are placed into the corresponding build folder (e.g. `iceoryx/build/posh/test/posh_moduletests`). -If you want to execute only individual testcases then you can use these executables and a gtest filter. Let's assume you want to execute only the `ServiceDescription_test` from the posh_moduletests, then you can do the following: -``` +If you want to execute only individual test cases, you can use these executables together with a filter command. +Let's assume you want to execute only `ServiceDescription_test` from posh_moduletests: + +```bash ./build/posh/test/posh_moduletests --gtest_filter="ServiceDescription_test*" ``` ## Use Sanitizer Scan -Due to the fact that iceoryx works a lot with system memory it should be ensured that errors like memory leaks are not introduced. -To prevent these, we use the clang toolchain which offers several tools for scanning the codebase. One of them is the [Address-Sanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) which checks for example on dangling pointers. +Due to the fact that iceoryx works a lot with system memory, it should be ensured that errors like memory leaks are not introduced. +To prevent this, we use the clang toolchain which offers several tools for scanning the codebase. One of them is the [Address-Sanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) which checks for example on dangling pointers. -In iceoryx below sanitizers are enabled at the moment. -- [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) -AddressSanitizer is a fast memory error detector. -**NOTE :** AddressSanitizer exits on the first detected error, which means there could be more errors in the codebase when this error is reported. -- [LeakSanitizer](https://clang.llvm.org/docs/LeakSanitizer.html) -LeakSanitizer is a run-time memory leak detector. In iceoryx , it runs as part of the AdderssSanitizer. -- [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) -UndefinedBehaviorSanitizer (UBSan) is a fast undefined behavior detector. Iceoryx uses default behaviour ie `print a verbose error report and continue execution` +The below-listed sanitizers are enabled at the moment. + +- [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) (ASan) is a fast memory error detector. +!!! note + AddressSanitizer exits on the first detected error, which means there could be more errors in the codebase when this error is reported. +- [LeakSanitizer](https://clang.llvm.org/docs/LeakSanitizer.html) (LSan) is a run-time memory leak detector. In iceoryx, it runs as part of the AddressSanitizer. +- [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) (UBSan) is a fast undefined behavior detector. iceoryx uses default behavior i.e. `print a verbose error report and continue execution` + +With the `iceoryx_build_test.sh` script you can do the scan on your own. Additionally, the scans are running on the CI in every Pull-Request. +As a prerequisite, you need to install the clang compiler: -In iceoryx are scripts available to do the scan on your own. Additionally the Scans are running on the CI in every Pull-Request. -As Requirement you should install the clang compiler: ```bash sudo apt install clang ``` -Then you need to compile the iceoryx with the sanitizer flags: +Then you need to compile iceoryx with the sanitizer flags: + ```bash ./tools/iceoryx_build_test.sh build-strict build-all sanitize clang clean ``` -After that we can run the tests with enabled sanitizer options: + +Now we can run the tests with enabled sanitizer options: + ```bash -cd build -../tools/run_tests.sh +cd build && ./tools/run_tests.sh ``` -When the tests are running without errors then it is fine, else an error report is shown with a stacktrace to find the place where the leak occurs. If the leak comes from an external dependency or shall be handled later then it is possible to set a function on a suppression list. + +If errors occur, an error report is shown with a stack trace to find the place where the leak occurs. If the leak comes from an external dependency or shall be handled later then it is possible to set a function on a suppression list. This should be only rarely used and only in coordination with an iceoryx maintainer. -**NOTE** -Iceoryx needs to be build as static library for working with sanitizer flags. The script does it automatically. +!!! note + iceoryx needs to be built as a static library for working with sanitizer flags. The script does it automatically. + Except when you want to use the ${ICEORYX_WARNINGS} then you have to call `findpackage(iceoryx_utils)` -## Iceoryx library build +## iceoryx library build -Iceoryx consists of several libraries which have dependencies to each other. The goal is to have self-encapsulated library packages available -where the end-user can easily find it with the cmake command `find-package(...)`. -In the default case the iceoryx libraries are installed by `make install` into `/usr/lib` which need root access. To avoid that cmake gives you the possibility to install the libs into a custom folder. -This can be done by setting `-DCMAKE_INSTALL_PREFIX=/custom/install/path` as build-flag for the CMake file in iceoryx_meta. +The iceoryx build consists of several libraries which have dependencies on each other. The goal is to have self-encapsulated library packages available where the end-user can easily find it with the CMake command `find-package(...)`. +In the default case, the iceoryx libraries are installed by `make install` into `/usr/lib` which requires root access. As an alternative you can install the libs into a custom folder by setting `-DCMAKE_INSTALL_PREFIX=/custom/install/path` as build-flag for the CMake file in iceoryx_meta. -Iceoryx_meta is a CMake file which collects all libraries (utils, posh etc.) and extensions (binding_c, dds) together to have a single point for building. -The alternate solution is provided for Ubuntu-users by having a build script `iceoryx_build_test.sh` in the tools folder. +As a starting point for the CMake build, iceoryx_meta collects all libraries (utils, posh etc.) and extensions (binding_c, dds) together. The provided build script `iceoryx_build_test.sh` in the `tools` folder uses iceoryx_meta. -Per default iceoryx is build as static libraries for usability. -Additionally we offer to build as shared because it is a cleaner solution for resolving dependency issues and it reduces the linker time while building. -This is done by the flag `BUILD_SHARED_LIBS` which is set to OFF per default. If you want to have shared libraries, just pass `-DBUILD_SHARED_LIBS=ON` to CMake or use `build-shared` as flag in the build script. +Per default, iceoryx is built as static lib for better usability. +Additionally, we offer to build as shared library because it is a cleaner solution for resolving dependency issues and it reduces the linker time. +This is done by the flag `BUILD_SHARED_LIBS` which is set to OFF per default. If you want to have shared libraries, just pass `-DBUILD_SHARED_LIBS=ON` to CMake or use `build-shared` as a flag in the build script. + +If iceoryx builds shared libraries you have to copy them into a custom path and need to set the LD_LIBRARY_PATH to the custom path (e.g. build/install/prefix). -If iceoryx libs are build as shared libraries and you installed them in a custom path (e.g. build/install/prefix) you need to set -the `LD_LIBRARY_PATH` to the directory with the libiceoryx_.so files. This can be done by calling: ```bash export LD_LIBRARY_PATH=/your/path/to/iceoryx/libs ``` + or you can set it directly: + ```bash LD_LIBRARY_PATH=/your/path/to/lib iox-roudi ``` -If you want to share the iceoryx to other users, you can also create a debian package. You can create it by calling: `./tools/iceoryx_build_test.sh package` where it will be build it in `build_package`. +If you want to share iceoryx to other users, you can create a debian package. This can be done by using: `./tools/iceoryx_build_test.sh package` where it will be deployed into the `build_package` folder. +!!! note + The CMake libraries export their dependencies for easier integration. This means that you do not need to do a `findpackage()` to all the dependencies. For example, you don't need to call `findpackage(iceoryx_utils)` when you have it done for iceoryx_posh. It includes it already. diff --git a/doc/website/advanced/usage-guide.md b/doc/website/advanced/usage-guide.md deleted file mode 100644 index e55bd65842..0000000000 --- a/doc/website/advanced/usage-guide.md +++ /dev/null @@ -1,115 +0,0 @@ -# Usage guide - -## Configuring RouDi - -RouDi support several shared memory segments with different access rights, to limit the read and write access between different applications. Inside of these segments reside mempools where the user payload data for transfer is stored. -Based on the [conceptual guide](../../conceptual-guide.md) the end-user may want to configure the mempools with the amount of chunks and their size. - -Iceoryx ships a library for RouDi named in cmake `iceoryx_posh_roudi`. This lib gives you an API for compiling your own RouDi application if needed and is part of `iceoryx_posh`. - -**NOTE** -The chunk size for the mempool needs to follow these restrictions: -1. Chunksize needs to be greater than the alignment -2. Chunksize needs to be a multiple of alignment - -The value for the alignment is set to 32. - -### Dynamic configuration - -One way is to read a configuration dynamically at RouDi runtime (startup). -Using TOML Config in RouDi is not mandatory for configuring segments and mempools, but a comfortable alternative. - -RouDi can optionally be build with support to read the mempool config from a configuration file. -To build the feature in iceoryx, the cmake option `-DTOML_CONFIG=ON` must be used. -The `iox-roudi` build by iceoryx is with TOML support and can be used out of the box. - -If you create your own RouDi application you need to link against `iceoryx_posh_config`: -```cmake -target_link_libraries(custom-roudi - PRIVATE - iceoryx_posh::iceoryx_posh_roudi - iceoryx_posh::iceoryx_posh_config -) -``` - -The TOML config file can be passed to RouDi with the `-c` command line option. -``` -./iox-roudi -c /absolute/path/to/config/file.toml -``` - -This is a common config file with format version 1: -```TOML -[general] -version = 1 - -[[segment]] - -[[segment.mempool]] -size = 32 -count = 10000 - -[[segment.mempool]] -size = 128 -count = 10000 - -[[segment.mempool]] -size = 1024 -count = 1000 -``` -With this configuration, one payload segment will be created. The access rights are set to the RouDi group id. -There are three mempools within this segment. One with 10000 chunks of 32 byte payload size, one with 10000 chunks of 128 bytes and one with 1000 chunks of 1024 bytes. - -To restrict the access, a reader and writer group can be set: -```TOML -[general] -version = 1 - -[[segment]] -reader = "foo" -writer = "bar" - -[[segment.mempool]] -size = 32 -count = 10000 - -[[segment.mempool]] -size = 128 -count = 10000 - -[[segment.mempool]] -size = 1024 -count = 1000 -``` -With this configuration, only applications from the `bar` group have write access and can allocate chunks. Applications from the `foo` group have only read access. - -This is an example with multiple segments: -```TOML -[general] -version = 1 - -[[segment]] -reader = "foo" -writer = "bar" - -[[segment.mempool]] -size = 32 -count = 10000 - -[[segment]] -reader = "alice" -writer = "eve" - -[[segment.mempool]] -size = 1024 -count = 100 -``` - -When no config file is specified, a hard-coded version similar to [default config](../../../iceoryx_posh/etc/iceoryx/roudi_config_example.toml) will be used. - -### Static configuration - -Another way is to have a static config which is compile-time dependent, this means that you have to recompile your RouDi application if you want to change your config (not the iceoryx_posh_roudi lib). -You can have your own sourcefile with `main()` method where you can create your custom configuration and pass it to a RouDi instantiation. -In your CMake file for you custom RouDi you need to ensure that it is **not** linking against `iceoryx_posh_config` to have a static config. - -A good example how a static config could look like can be found [here](../../../iceoryx_examples/iceperf/roudi_main_static_config.cpp). diff --git a/doc/website/getting-started/installation.md b/doc/website/getting-started/installation.md index bde6ce22bd..bb78c0ebd6 100644 --- a/doc/website/getting-started/installation.md +++ b/doc/website/getting-started/installation.md @@ -1,31 +1,31 @@ # Installation -_iceoryx_utils_ and _iceoryx_posh_ are deployed as independent CMake packages. _iceoryx_posh_ is using some functions from _iceoryx_utils_ and is depending on it. +All iceoryx libraries are deployed as independent CMake packages. Posh is using functions from utils and is depending on it. You are able to build posh and utils and integrate them into existing CMake projects. ## Prerequisites ### Dependencies - 64-bit hardware (e.g. x86_64 or aarch64; 32-bit hardware might work, but is not supported) -- [CMake](https://cmake.org), 3.5 or later +- [CMake](https://cmake.org), 3.10 or later - One of the following compilers: - - [GCC](https://gcc.gnu.org), 7.4 or later (5.4 currently supported too) - - [Clang](https://clang.llvm.org), 9.0 or later - - [MSVC](https://visualstudio.microsoft.com/de/), part of Visual Studio 2019 or later + - [GCC](https://gcc.gnu.org), 7.4 or later (5.4 currently supported too) + - [Clang](https://clang.llvm.org), 9.0 or later + - [MSVC](https://visualstudio.microsoft.com/de/), part of Visual Studio 2019 or later - [libacl](http://download.savannah.gnu.org/releases/acl/), 2.2 or later. Only for Linux & QNX. -- optional, [ncurses](https://invisible-island.net/ncurses/), 6.2 or later. Required by introspection tool. +- optional, [ncurses](https://invisible-island.net/ncurses/), 6.2 or later. Required by introspection tool (only for Linux, QNX and MacOS). #### Optional, Cyclone DDS Gateway -If you would like to use our Cyclone DDS Gateway you have to install [Cyclone DDS](https://github.com/eclipse-cyclonedds/cyclonedds) first. -Furthermore you have to install: +The Cyclone DDS gateway depends currently on [Cyclone DDS](https://github.com/eclipse-cyclonedds/cyclonedds). +When building it with the CMake option `-DDDS_GATEWAY=ON` it will be automatically installed as a dependency. +Furthermore, you have to install: - [Apache Maven](http://maven.apache.org/download.cgi), 3.5 or later - [OpenJDK](http://jdk.java.net/11/), 11.0 or later. Alternatively, Java JDK version 8 or later !!! hint - If you are behind a corporate firewall you may have to adjust the proxy - settings of maven in `/etc/maven/settings.xml`. See: [Maven Proxy Configuration](https://maven.apache.org/settings.html#proxies) + If you are behind a corporate firewall you may have to adjust the proxy settings of maven in `/etc/maven/settings.xml`. See: [Maven Proxy Configuration](https://maven.apache.org/settings.html#proxies) ### Mac OS @@ -55,17 +55,26 @@ You will need to install the following packages: sudo apt install gcc g++ cmake libacl1-dev libncurses5-dev pkg-config ``` -Additionally, there is an optional dependency to the MIT licensed [cpptoml](https://github.com/skystrife/cpptoml) library, which is used to parse a RouDi config file for the mempool config. +Additionally, there is an optional dependency to the [cpptoml](https://github.com/skystrife/cpptoml) library, which is used to parse the RouDi config file containing mempool configuration. ### QNX QNX SDP 7.0 and 7.1 are supported (shipping with gcc 5.4 and gcc 8.3 respectively). -Easiest way to build iceoryx on QNX is using the build script and providing a toolchain file.
+The easiest way to build iceoryx on QNX is by using the build script and providing a toolchain file. We provide generic QNX SDP 7.0 toolchain files for ARM_64 and X86_64 in `./tools/toolchains/qnx` ([Direct Link](https://github.com/eclipse-iceoryx/iceoryx/tree/master/tools/toolchains/qnx)). -ARM_64: `./tools/iceoryx_build_test.sh -t /home/user/toolchains/qnx/qnx_sdp70_aarch64le.cmake`
-X86_64: `./tools/iceoryx_build_test.sh -t /home/user/toolchains/qnx/qnx_sdp70_x86_64.cmake` +ARM_64: + +```bash +./tools/iceoryx_build_test.sh -t /home/user/toolchains/qnx/qnx_sdp70_aarch64le.cmake +``` + +X86_64: + +```bash +./tools/iceoryx_build_test.sh -t /home/user/toolchains/qnx/qnx_sdp70_x86_64.cmake +``` !!! attention Please ensure that the folder `/var/lock` exist and the filesystem supports file locking. @@ -73,93 +82,109 @@ X86_64: `./tools/iceoryx_build_test.sh -t /home/user/toolchains/qnx/qnx_sdp70_x8 ## Build with CMake !!! note - Requires CMake version 3.5 or higher. Building from CMake is the preferred way, for more complex actions like a coverage scan + Building with CMake is the preferred way, for more complex actions like a coverage scan is a script available (see chapter below). The `CMakeLists.txt` from `iceoryx_meta` can be used to easily develop iceoryx with an IDE. 1. Clone the repository - git clone https://github.com/eclipse-iceoryx/iceoryx.git + ```bash + git clone https://github.com/eclipse-iceoryx/iceoryx.git + ``` 2. Generate the necessary build files - cd iceoryx - cmake -Bbuild -Hiceoryx_meta - # when you have installed external dependencies like ncurses you have to add them - # to your prefix path - cmake -Bbuild -Hiceoryx_meta -DCMAKE_PREFIX_PATH=$(PWD)/build/dependencies/ + ```bash + cd iceoryx + cmake -Bbuild -Hiceoryx_meta + # when you have installed external dependencies like ncurses you have to add them + # to your prefix path + cmake -Bbuild -Hiceoryx_meta -DCMAKE_PREFIX_PATH=$(PWD)/build/dependencies/ + ``` !!! tip To build all iceoryx components add `-DBUILD_ALL` to the CMake command 3. Compile the source code - cmake --build build + ```bash + cmake --build build + ``` !!! tip - You can fasten up the build by appending `-j 4` where 4 stands for the number of parallel build processes. + You can speed up the build by appending `-j 4` where 4 stands for the number of parallel build processes. You can choose more or less depending on your available CPU cores on your machine. 4. Install to system Mac: - cmake --build build --target install + ```bash + cmake --build build --target install + ``` Linux: - sudo cmake --build build --target install + ```bash + sudo cmake --build build --target install + ``` !!! tip The installation directory is usually left at its default, which is `/usr/local` !!! note - iceoryx is build in Release mode with `-O3` optimization by default. If you want to have debug symbols please - set `CMAKE_BUILD_TYPE=Debug`. + iceoryx is built in release mode with `-O3` optimization by default. If you want to enable debug symbols please set `CMAKE_BUILD_TYPE=Debug`. ### Build options -Please take a look at the CMake file [build_options.cmake](../../../iceoryx_meta/build_options.cmake) to get an overview of the available build options for enabling additional features. - -### Available CMake switches you can customize for the iceoryx_posh build - - | switch | description | - |:---------|:-------------| - | `IOX_MAX_PUBLISHERS` | the maximum number of publishers one `RouDi` instance can manage | - | `IOX_MAX_SUBSCRIBERS_PER_PUBLISHER` | the maximum number of subscriber a publisher can deliver chunks to| - | `IOX_MAX_PUBLISHER_HISTORY` | the maximum number chunks available for the publisher history | - | `IOX_MAX_CHUNKS_ALLOCATED_PER_PUBLISHER_SIMULTANEOUSLY` | the maximum number of chunks a publisher can allocate at a given time | - | `IOX_MAX_SUBSCRIBERS` | the maximum number of subscribers one `RouDi` instance can manage | - | `IOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY` | the maximum number of chunks a subscriber can hold at a given time | - | `IOX_MAX_INTERFACE_NUMBER` | the maximum number for interface ports, which are used for e.g. gateways | - -Have a look at [iceoryx_posh_deployment.cmake](../iceoryx_posh/cmake/iceoryx_posh_deployment.cmake) for the default values of this constants. +Please take a look at the CMake file [build_options.cmake](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_meta/build_options.cmake) +to get an overview of the available build options for enabling additional features. ## Build with script -As an alternative we provide our build-test script which we use to integrate iceoryx into our infrastructure. -The intention of the script is to more than just building with iceoryx. This is for doing a code coverage scan or for using the adress-sanitizer. -The script currently only works for Linux and QNX, it is planned to offer a multi-platform solution. +As an alternative, we provide a build-test script which we use to integrate iceoryx into our infrastructure. +The intention of the script goes beyond building iceoryx, it is also used for the code coverage scan or the address-sanitizer runs on the CI. +The script currently works for Linux and QNX only, it is planned to offer a multi-platform solution. -1. Clone the repository + 1. Clone the repository + + ```bash + git clone https://github.com/eclipse-iceoryx/iceoryx.git + ``` - git clone https://github.com/eclipse-iceoryx/iceoryx.git + 2. Build everything -1. Build everything + ```bash + cd iceoryx + ./tools/iceoryx_build_test.sh build-all + ``` - cd iceoryx - ./tools/iceoryx_build_test.sh build-all + !!! note + The build script is installing the header files and binaries into `build/install/prefix`. -You can use the help for getting an overview over the available options: +You can use the `help` argument for getting an overview of the available options: ```bash ./tools/iceoryx_build_test.sh help ``` +!!! tip + The examples can be built with `-DEXAMPLES=ON` with iceoryx_meta or by providing the `examples` argument to the build script. + ## Build with colcon -Alternatively, iceoryx can be built with [colcon](https://colcon.readthedocs.io/en/released/user/installation.html) to provide a smooth integration for ROS2 developers. +Alternatively, iceoryx can be built with [colcon](https://colcon.readthedocs.io/en/released/user/installation.html#using-debian-packages) to provide a smooth integration for ROS2 developers. +To build the iceoryx_integrationtest package one requires a minimal [ROS2 installation](https://docs.ros.org/en/foxy/Installation/Linux-Install-Debians.html). + +Install required ROS2 packages: + +```bash +sudo apt install ros-foxy-ros-testing ros-foxy-ros-base +source /opt/ros/foxy/setup.bash +``` + +build with colcon: ```bash mkdir -p iceoryx_ws/src @@ -169,4 +194,12 @@ cd .. colcon build ``` +!!! note + +If you don't want to install ROS2, you can skip the iceoryx_integrationtest package by calling: + +```bash +colcon build --packages-skip iceoryx_integrationtest +``` + This build method makes the most sense in combination with [rmw_iceoryx](https://github.com/ros2/rmw_iceoryx.git) diff --git a/doc/website/getting-started/overview.md b/doc/website/getting-started/overview.md index 533c2a1f17..b58fd0369a 100644 --- a/doc/website/getting-started/overview.md +++ b/doc/website/getting-started/overview.md @@ -33,11 +33,11 @@ Each application which wants to use iceoryx has to instantiate its runtime, whic with RouDi. Only one runtime object per user process is allowed. To do so, the following lines of code are required - +```cpp #include "iceoryx_posh/runtime/posh_runtime.hpp" iox::runtime::PoshRuntime::initRuntime("some_unique_application_name"); - +``` ### Service description A ``ServiceDescription`` in iceoryx represents the data to be transmitted and is uniquely identified by three string @@ -51,7 +51,7 @@ A triple consisting of such strings is called a ``ServiceDescription``. The serv from AUTOSAR and is still used in the API with these names. The so called canonical protocol is implemented in the namespace ``capro``. -The following table gives an overview over the different terminologies and the current mapping: +The following table gives an overview of the different terminologies and the current mapping: | | Group | Instance | Topic | |---------|---------|------------------|------------------------| diff --git a/iceoryx_posh/cmake/iceoryx_posh_deployment.cmake b/iceoryx_posh/cmake/iceoryx_posh_deployment.cmake index f063bd649d..f28cd9bd7a 100644 --- a/iceoryx_posh/cmake/iceoryx_posh_deployment.cmake +++ b/iceoryx_posh/cmake/iceoryx_posh_deployment.cmake @@ -15,42 +15,52 @@ # SPDX-License-Identifier: Apache-2.0 # configure deployment +message("[i] <<<<<<<<<<<<< Start iceoryx_posh configuration: >>>>>>>>>>>>>") if(ONE_TO_MANY_ONLY) message("[i] Using 1:n communication only!") set(IOX_COMMUNICATION_POLICY OneToManyPolicy) endif() if(NOT IOX_COMMUNICATION_POLICY) + message("[i] Using m:n communication only!") set(IOX_COMMUNICATION_POLICY ManyToManyPolicy) endif() if(NOT IOX_MAX_PUBLISHERS) set(IOX_MAX_PUBLISHERS 512) endif() +message("[i] IOX_MAX_PUBLISHERS:" ${IOX_MAX_PUBLISHERS}) if(NOT IOX_MAX_SUBSCRIBERS) set(IOX_MAX_SUBSCRIBERS 1024) endif() +message("[i] IOX_MAX_SUBSCRIBERS:" ${IOX_MAX_SUBSCRIBERS}) if(NOT IOX_MAX_INTERFACE_NUMBER) set(IOX_MAX_INTERFACE_NUMBER 4) endif() +message("[i] IOX_MAX_INTERFACE_NUMBER:" ${IOX_MAX_INTERFACE_NUMBER}) if(NOT IOX_MAX_SUBSCRIBERS_PER_PUBLISHER) set(IOX_MAX_SUBSCRIBERS_PER_PUBLISHER 256) endif() +message("[i] IOX_MAX_SUBSCRIBERS_PER_PUBLISHER:" ${IOX_MAX_SUBSCRIBERS_PER_PUBLISHER}) if(NOT IOX_MAX_CHUNKS_ALLOCATED_PER_PUBLISHER_SIMULTANEOUSLY) set(IOX_MAX_CHUNKS_ALLOCATED_PER_PUBLISHER_SIMULTANEOUSLY 8) endif() +message("[i] IOX_MAX_CHUNKS_ALLOCATED_PER_PUBLISHER_SIMULTANEOUSLY:" ${IOX_MAX_CHUNKS_ALLOCATED_PER_PUBLISHER_SIMULTANEOUSLY}) if(NOT IOX_MAX_PUBLISHER_HISTORY) set(IOX_MAX_PUBLISHER_HISTORY 16) endif() +message("[i] IOX_MAX_PUBLISHER_HISTORY:" ${IOX_MAX_PUBLISHER_HISTORY}) if(NOT IOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY) set(IOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY 256) endif() +message("[i] IOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY:" ${IOX_MAX_CHUNKS_HELD_PER_SUBSCRIBER_SIMULTANEOUSLY}) +message("[i] <<<<<<<<<<<<<< End iceoryx_posh configuration: >>>>>>>>>>>>>>") configure_file("${CMAKE_CURRENT_SOURCE_DIR}/cmake/iceoryx_posh_deployment.hpp.in" "${CMAKE_BINARY_DIR}/generated/iceoryx/include/iceoryx_posh/iceoryx_posh_deployment.hpp" @ONLY) diff --git a/mkdocs.yml b/mkdocs.yml index 888b4dd195..c4abb3b4e1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,11 @@ repo_url: https://github.com/eclipse/iceoryx docs_dir: doc/website/ remote_branch: main markdown_extensions: + - pymdownx.inlinehilite + - pymdownx.superfences + - pymdownx.highlight + - toc: + permalink: 🔗 - meta - markdown_include.include: base_path: doc diff --git a/tools/export-docu-to-website.sh b/tools/export-docu-to-website.sh index d2a160f0ac..9f013fc181 100755 --- a/tools/export-docu-to-website.sh +++ b/tools/export-docu-to-website.sh @@ -30,6 +30,7 @@ set -e WORKSPACE=$(git rev-parse --show-toplevel) WEBREPO="git@github.com:eclipse-iceoryx/iceoryx-web.git" VERSION=$1 +TYPE=${2:-local} #`local` starts a local webserver to inspect the results, `publish` pushes the generated doc to iceoryx_web cd $WORKSPACE @@ -56,10 +57,19 @@ doxybook2 --input $WORKSPACE/build/doc/iceoryx_dds/xml/ --output $WORKSPACE/doc/ mkdir -p $WORKSPACE/doc/website/API-reference/introspection doxybook2 --input $WORKSPACE/build/doc/iceoryx_introspection/xml/ --output $WORKSPACE/doc/website/API-reference/introspection -# Generate HTML and push to GitHub pages -if [ ! -d "$WORKSPACE/../iceoryx-web" ]; then - cd $WORKSPACE/../ - git clone $WEBREPO + +if [ "$TYPE" == "local" ]; then + echo "starting local webserver" + mkdocs serve --config-file ../iceoryx/mkdocs.yml +fi + +if [ "$TYPE" == "publish" ]; then + # Generate HTML and push to GitHub pages + if [ ! -d "$WORKSPACE/../iceoryx-web" ]; then + cd $WORKSPACE/../ + git clone $WEBREPO + fi + cd $WORKSPACE/../iceoryx-web + mkdocs gh-deploy --config-file ../iceoryx/mkdocs.yml --remote-branch $VERSION fi -cd $WORKSPACE/../iceoryx-web -mkdocs gh-deploy --config-file ../iceoryx/mkdocs.yml --remote-branch $VERSION + diff --git a/tools/toolchains/qnx/qnx_sdp70_common.cmake b/tools/toolchains/qnx/qnx_sdp70_common.cmake index 5a281b2b13..0af9383ce0 100644 --- a/tools/toolchains/qnx/qnx_sdp70_common.cmake +++ b/tools/toolchains/qnx/qnx_sdp70_common.cmake @@ -51,10 +51,10 @@ SET(CMAKE_OBJDUMP "${QNX_HOST}/usr/bin/nto${CMAKE_SYSTEM_PROCESSOR}-objdump" CAC SET(CMAKE_RANLIB "${QNX_HOST}/usr/bin/nto${CMAKE_SYSTEM_PROCESSOR}-ranlib" CACHE PATH "ranlib") SET(CMAKE_C_FLAGS_DEBUG "-g -O0 -fno-builtin") -SET(CMAKE_C_FLAGS_RELEASE "-O2 -DNDEBUG") +SET(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG") SET(CMAKE_CXX_FLAGS_DEBUG "-g -O0 -fno-builtin") -SET(CMAKE_CXX_FLAGS_RELEASE "-O2 -DNDEBUG") +SET(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG") SET(CMAKE_FIND_ROOT_PATH ${QNX_TARGET}) SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)