Skip to content

Commit

Permalink
Merge pull request #261 from junwoo091400/pr_mavsdk_proto_build_doc_i…
Browse files Browse the repository at this point in the history 
…mprovement

Improve Proto generation & Build document
  • Loading branch information
@julianoes
julianoes authored Dec 27, 2023
2 parents 270724c + b6d7382 commit 5d87ab7
Showing 1 changed file with 48 additions and 75 deletions.
123 changes: 48 additions & 75 deletions en/cpp/guide/build.md
View file
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!

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

0 comments on commit 5d87ab7

Please sign in to comment.