Skip to content

Commit

Permalink
iox-#482 fix spell findings in installation guides and Contributing.md
Browse files Browse the repository at this point in the history
Signed-off-by: Dietrich Krönke <dietrich.kroenke@apex.ai>
  • Loading branch information
dkroenke committed Mar 27, 2021
1 parent 6348159 commit 86a35e3
Show file tree
Hide file tree
Showing 6 changed files with 44 additions and 44 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ Iceoryx needs to be build as static library for working with gcov flags. The scr
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.
Codecov gives a brief overview of the code coverage and also indicates in Pull-Requests if new 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`
Expand Down
2 changes: 1 addition & 1 deletion doc/conceptual-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 10 additions & 10 deletions doc/website/advanced/configuration-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## 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 the resource management. These limits are used to create management structures in the shared memory segment called `iceoryx_mgmt` when starting up RouDi.
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 |
|:---------|:-------------|
Expand All @@ -26,20 +26,20 @@ Example:
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)).
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 amount of chunks and their size.
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.

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
2. Chunksize needs to be a multiple of the alignment

The value for the alignment is set to 32.

Expand All @@ -61,7 +61,7 @@ target_link_libraries(custom-roudi
)
```

The TOML config file can be passed to RouDi with the `-c` command line option.
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
Expand Down Expand Up @@ -89,7 +89,7 @@ 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.
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:

Expand Down Expand Up @@ -143,8 +143,8 @@ When no config file is specified, a hard-coded version similar to the [default c

### 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.
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 how a static config could look like can be found [here](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_examples/iceperf/roudi_main_static_config.cpp).
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).
42 changes: 22 additions & 20 deletions doc/website/advanced/installation-guide-for-contributors.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,26 @@
## Build and run tests

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 which are executing the tests. First we need to build them:
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 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.
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 the all tests:
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
Expand All @@ -46,22 +46,22 @@ Let's assume you want to execute only `ServiceDescription_test` from posh_module

## 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.

The below listed sanitizers are enabled at the moment.
The below-listed 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 AddressSanitizer.
LeakSanitizer is a run-time memory leak detector. In iceoryx, it runs as part of the AddressSanitizer.
- [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)
UndefinedBehaviorSanitizer (UBSan) is a fast undefined behavior detector. iceoryx uses default behavior ie `print a verbose error report and continue execution`
UndefinedBehaviorSanitizer (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:
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:

```bash
sudo apt install clang
Expand All @@ -79,26 +79,28 @@ After that we can run the tests with enabled sanitizer options:
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.
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

The iceoryx build 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.
In the default case, the iceoryx libraries are installed by `make install` into `/usr/lib` which requires root access. As 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 provided build script `iceoryx_build_test.sh` in the tools folder use iceoryx_meta for building.
Iceoryx_meta is a CMake file that collects all libraries (utils, posh etc.) and extensions (binding_c, dds) together to have a single point for the CMake build. The provided build script `iceoryx_build_test.sh` in the `tools` folder uses iceoryx_meta.

Per default iceoryx is build 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 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 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 a flag in the build script.

If iceoryx is build as shared libraries and you installed them in a custom path (e.g. build/install/prefix) you need to set
If iceoryx builds shared libraries you have to copy them into a custom path and you need to set the LD_LIBRARY_PATH to this custom path (e.g. build/install/prefix).

If iceoryx is built as shared library and you installed them in a custom path (e.g. build/install/prefix) you need to set
the `LD_LIBRARY_PATH` to the directory containing the libiceoryx_*.so files. This can be done by calling:

```bash
Expand Down
20 changes: 9 additions & 11 deletions doc/website/getting-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,19 @@ All iceoryx libraries are deployed as independent CMake packages. Posh is using
- [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

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 dependency.
Furthermore you have to install:
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

Expand Down Expand Up @@ -56,13 +55,13 @@ 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 [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).

The 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:
Expand All @@ -83,7 +82,7 @@ X86_64:
## Build with CMake

!!! note
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.
Expand Down Expand Up @@ -135,8 +134,7 @@ The `CMakeLists.txt` from `iceoryx_meta` can be used to easily develop iceoryx w
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 enable 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

Expand All @@ -145,7 +143,7 @@ to get an overview of the available build options for enabling additional featur

## Build with script

As an alternative we provide a build-test script which we use to integrate iceoryx into our infrastructure.
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.

Expand Down
2 changes: 1 addition & 1 deletion doc/website/getting-started/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---------|---------|------------------|------------------------|
Expand Down

0 comments on commit 86a35e3

Please sign in to comment.