Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve Proto generation & Build document #261

Merged
merged 2 commits into from
Dec 27, 2023
Merged

Improve Proto generation & Build document #261

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9bb148d
Library build document improvement
junwoo091400 Jun 1, 2022
b6d7382
build: adapt to my liking
julianoes Dec 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 48 additions & 75 deletions en/cpp/guide/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This section explains how to build and install the MAVSDK C++ library from sourc

Note that there are separate instructions to [build the mavsdk_server](build_mavsdk_server.md).

## Build the C++ Library {#build_sdk_cpp}
## Build the C++ Library {#build_mavsdk_cpp_library}

This section explains how to build the library along with its unit and integration tests.

Expand Down Expand Up @@ -68,13 +68,55 @@ Make sure to get all the submodules as well:
git submodule update --init --recursive
```

### Building Fundamentals

Building the MAVSDK with CMake is broken down into two steps: **Configuration** and **Build**.

#### Build Configuration Step {#configuration_step}
For configuration, you specify the type of build you want to execute in the [build step](#build_step). You can checkout the [CMake Documentation on Build Configuration](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations) for more context.

A typical configuration command example would be:

`cmake -DCMAKE_BUILD_TYPE=Debug -Bbuild/default -H.`

- Build type is set to `Debug`
- Build directory is set to `build/default`
- Chose the directory using the `H.` flag

During the configure step you can set more flags using `-DFLAG=Value`:

- `CMAKE_BUILD_TYPE`: as documented above, to chose between `Debug` and `Release` build.
- `CMAKE_INSTALL_PREFIX`: as documented above, to specify directory to install library artifacts.
- `BUILD_SHARED_LIBS`: set to `ON` to build dynamic libraries (such as .so on Linux, .dylib on macOS, .dll on Windows). Set to `OFF` to build static libraries (such as .a on Linux and macOS, .lib on Windows).
- `SUPERBUILD`: set to `OFF` to use system dependencies instead of [third party dependencies](https://github.com/mavlink/MAVSDK/tree/main/third_party) downloaded and built using cmake.
- `CMAKE_PREFIX_PATH`: can be used to set the path where the dependencies can be found if `SUPERBUILD` is set to `OFF`.
- `BUILD_MAVSDK_SERVER`: set to `ON` to build mavsdk_server, see instruction to [build mavsdk_server](build_mavsdk_server.md).
- `ASAN`: set to `ON` to enable address sanitizer.
- `UBSAN`: set to `ON` to enable undefined behavior sanitizer.
- `LSAN`: set to `ON` to enable leak sanitizer.
- `WERROR`: set to `ON` to error on warnings, mostly used for CI.

After the configuration step, everything that will be build in the [build step](#build_step) have been specified, and if you want to change your build configuration (e.g. If you want to build `Debug` build instead of `Release` build), you must execute the [configuration step](#configuration_step) again!
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here, I was conflicted since below, it says "If you already have run cmake without setting CMAKE_INSTALL_PREFIX, you may need to clean the build first:".

Which implies that doing the configuration step again isn't enough when you want to change the CMAKE_INSTALL_PREFIX setting.

I think that the 'you may need to clean the build first' part should be removed (it is wrong?!), if my understanding that rm -rf build/default is only necessary when the third party changes are present. Thoughts on this?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it works to just re-run the configure step (no need to clean build) 👍. Not 100% sure it always does, though.


#### Build Step {#build_step}
In the build step, we finally build the library and binaries and link them.

The stripped down version of the build command would be:

`cmake --build build/default`

- The `--build` signals the CMake to execute the build
- It uses the build configuration built from the [configuration step](#configuration_step), located at `build/default` folder

Additionally, you can install it in the system with the `--target install` command added as well, which is explained in detail in the [Installing the C++ Library](#install_mavsdk_cpp_library) section below.

### Building

#### Debug

To build the MAVSDK C++ Library for development, use the debug build.

Configure first, then build:
There are 2 steps in building a library: Configure and build.
```bash
cmake -DCMAKE_BUILD_TYPE=Debug -Bbuild/default -H.
cmake --build build/default -j8
Expand All @@ -100,14 +142,14 @@ cmake --build build/default -j8 --config Release

> Note: It is not usual to use CMAKE_BUILD_TYPE on Windows (with MSVC), however, our build requires it for the dependencies which are built at configure time.

## Installing the C++ Library {#build_sdk_cpp}
## Installing the C++ Library {#install_mavsdk_cpp_library}

*Installing* builds the SDK **and** copies the libraries and header files into a "public" location so that they can be referenced by C++ applications (see [Building C++ Apps](../guide/toolchain.md)).


### System-wide Install {#sdk_system_wide_install}

By default (when `CMAKE_INSTALL_PREFIX` is not set, cmake tries to install system-wide. For Linux/macOS that's `/usr/local`, for Windows it is somewhere in `C:\Program Files`.
You can configure to install system wide by not setting the `CMAKE_INSTALL_PREFIX` in the [configuration step](#configuration_step), since CMake tries to install system wide by default. For Linux/macOS that's `/usr/local`, for Windows it is somewhere in `C:\Program Files`.

To install system-wide the command needs to be run with sudo on Linux/macOS:

Expand All @@ -127,10 +169,10 @@ runas cmake --build build/default --target install

### Local Install {#sdk_local_install}

The install path can be set in the configure call using `CMAKE_INSTALL_PREFIX`:
The install path can be set in the [configuration step](#configuration_step) using `CMAKE_INSTALL_PREFIX`:

For example, to install into the `MAVSDK/install/` folder you would set the `CMAKE_INSTALL_PREFIX` variable to specify a path relative to the folder from which you call `cmake` (or an absolute path).
```
```bash
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install -Bbuild/default -H.
cmake --build build/default --target install
```
Expand All @@ -140,75 +182,6 @@ cmake --build build/default --target install
rm -rf build/default
```

Once installed locally, you can then use the installed headers and library from the local folder by setting it using `CMAKE_PREFIX_PATH`.

For instance, to build the examples, you would do:

```
cd examples
cmake -DCMAKE_PREFIX_PATH=$(pwd)/../install -Bbuild -H.
cmake --build build -j8
```

## MAVLink headers and dialects

MAVSDK uses the dialect [common.xml](https://mavlink.io/en/messages/common.html) by default.
It does so by checking out the [mavlink/mavlink](https://github.com/mavlink/mavlink/) repository at configure time and using [Pymavlink](https://github.com/ArduPilot/pymavlink) to generate the C headers.

There are two options to change the default mentioned above.

### Change dialect

If you need to build with a dialect other than `common`, you can specify that during the configure step:

```sh
cmake -Bbuild/default -DMAVLINK_DIALECT=mydialect -H.
```

If you also want to swap out the repository and git commit, you can do so in [third_party/mavlink/CMakeLists.txt](https://github.com/mavlink/MAVSDK/blob/bbdb9e96f5567a488925093f641d249f8e01b2de/third_party/mavlink/CMakeLists.txt#L20-L21).

### Provide C headers manually

Instead of depending on the generation of the MAVLink C headers as part of the cmake configure step, you can provide the generated C headers manually.
This can be useful if you already have the headers generated in your worspace or CI, or if you don't have Python available during the configure step (e.g. as is the case for the dockcross images).

To provide the generated C headers manually, you have to set the path during the configure step:

Let's say the mavlink headers are "next to" the MAVSDK directory:
```sh
cmake -Bbuild/default -DMAVLINK_DIALECT=mydialect -DMAVLINK_HEADERS=../mavlink-headers -H.
```

Note that the structure of the headers needs to be like this:

```sh
mavlink-headers # <-- This is the directory referenced
└── mavlink
└── v2.0
├── checksum.h
├── mydialect
│   ├── mydialect.h
│   ├── mavlink.h
│   ├── mavlink_msg_...

```

## Other build flags

During the configure step, there are various flags that an be set using `-DFLAG=Value`:

- `CMAKE_BUILD_TYPE`: as documented above, to choose between `Debug` and `Release` build.
- `CMAKE_INSTALL_PREFIX`: as documented above, to specify the directory in which to install library artefacts.
- `BUILD_SHARED_LIBS`: set to `ON` to build dynamic libraries (such as `.so` on Linux, `.dylib` on macOS, `.dll` on Windows).
Set to `OFF` to build static libraries (such as `.a` on Linux and macOS, `.lib` on Windows).
- `SUPERBUILD`: set to `OFF` to use system dependencies instead of dependencies downloaded and built using cmake.
- `CMAKE_PREFIX_PATH`: can be used to set the path where the dependencies can be found if `SUPERBUILD` is set to `OFF`.
- `BUILD_MAVSDK_SERVER`: set to `ON` to build mavsdk_server, see instruction to [build mavsdk_server](build_mavsdk_server.md).
- `ASAN`: set to `ON` to enable address sanitizer.
- `UBSAN`: set to `ON` to enable undefined behavior sanitizer.
- `LSAN`: set to `ON` to enable leak sanitizer.
- `WERROR`: set to `ON` to error on warnings, mostly used for CI.

## Troubleshooting

### Git submodules out of date
Expand Down