Fixposition SDK 0.0.0-heads/main-0-g5656422
Collection of c++ libraries and apps for use with Fixposition products on Linux
Loading...
Searching...
No Matches
fpsdk_build.hpp
Go to the documentation of this file.
1/**
2 * \verbatim
3 * ___ ___
4 * \ \ / /
5 * \ \/ / Copyright (c) Fixposition AG (www.fixposition.com) and contributors
6 * / /\ \ License: see the LICENSE file
7 * /__/ \__\
8 * \endverbatim
9 *
10 * @file
11 * @brief Fixposition SDK: Documentation
12 */
13
14#ifndef __FPSDK_BUILD_HPP__
15#define __FPSDK_BUILD_HPP__
16
17namespace fpsdk {
18/* ****************************************************************************************************************** */
19// clang-format off
20
21/*!
22
23 @page FPSDK_BUILD_DOC Fixposition SDK: Build and installation
24
25 @section FPSDK_BUILD_DOC_OVERVIEW Overview
26
27 This page describes how the Fixposition SDK can be built and installed. This is intended for users who are familiar
28 with developing c++ code and building software and who want to build their own applications using the @ref
29 FPSDK_COMMON_DOC (etc.)
30
31 For users interested in simply *using* the @ref FPSDK_APPS_DOC it is recommended to use the @ref FPSDK_RUN_DOC
32 instead of building and installing those themselves.
33
34
35 @section FPSDK_BUILD_DEPS Dependencies
36
37 For building the libraries and apps:
38
39 - **Linux**, GCC (C++-17), glibc, cmake, bash, etc. (tested with Ubuntu 20.04/22.04/24.04 and Debian Bookworm)
40 - boost (≥ 1.71.0, tested with 1.71.0, 1.74.1, 1.83.0)
41 - curl (≥ 7.68.0, tested with 7.68.0, 7.88.1, 8.5.0)
42 - Eigen3 (≥ 3.3.7, tested with 3.3.7, 3.4.0)
43 - yaml-cpp (≥ 0.6.2, tested with 0.6.2, 0.7.0, 0.8.0)
44 - zlib1g (≥ 1.2.11, tested with 1.2.11, 1.2.13, 1.3)
45 - OpenSSL (libssl) (≥ 1.1.x, tested with 1.1.1, 3.0.2, 3.0.13, 3.0.15)
46 - nlohmann-json3 (≥ 3.7.3, tested with 3.7.3, 3.11.3)
47 - PROJ (*) (≥ 9.4.x, tested with 9.4.0, 9.4.1)
48 - ROS1 (*) (Noetic), or
49 - ROS2 (*) (Humble or Jazzy)
50
51 (*) Optional dependencies. Without these some functionality in the libraries and apps is unavailable (compiled out).
52
53 For development additionally:
54
55 - clang-format (≥ 17, tested with 17)
56 - Doxygen (≥ 1.11.0, tested with 1.11.0)
57 - GTest (≥ 1.12.0, tested with 1.12.1 and 1.13.0)
58
59 <!-- trick doxygen -->
60
61 @page FPSDK_BUILD_DOC
62
63 @section FPSDK_BUILD_BUILD Building
64
65 @subsection FPSDK_BUILD_BUILD_TLDR tl;dr
66
67 @code{sh}
68 ./docker/docker.sh pull noetic-dev # Or "docker.sh build noetic-dev" to build the image locally
69 ./docker/docker.sh run noetic-dev bash
70 # Now inside Docker do:
71 source /opt/ros/noetic/setup.bash
72 make install
73 ./fpsdk/bin/fpltool -h
74 @endcode
75
76 <!-- trick doxygen -->
77
78 @subsection FPSDK_BUILD_BUILD_DEVCONTAINER VSCode devcontainer
79
80 Open the fpsdk.code-workspace, change to one of the provided devcontainers, and in a terminal do:
81
82 @code{sh}
83 make install
84 ./fpsdk/bin/fpltool
85 @endcode
86
87 <!-- trick doxygen -->
88
89 @subsection FPSDK_BUILD_BUILD_DOCKER Docker container
90
91 Docker images are provided that include all the dependencies:
92
93 @code{sh}
94 ./docker/docker.sh pull noetic-dev # Or "docker.sh build noetic-dev" to build the image locally
95 ./docker/docker.sh run noetic-dev bash
96 source /opt/ros/noetic/setup.bash
97 make install
98 ./fpsdk/bin/fpltool
99 @endcode
100
101 Note that the "docker.sh" script does not give you a suitable ROS runtime (or development, playground, ...)
102 environment! Its only purpose is to run the CI for this repo and to demonstrate the building here. For a ROS
103 run-time environment please setup a docker *container* yourself elsewhere (perhaps using the docker *image* provided
104 here). See ROS and Docker documentation and the Internet for help.
105
106 <!-- trick doxygen -->
107
108 @subsection FPSDK_BUILD_BUILD_CI Run CI
109
110 @code{sh}
111 ./docker/docker.sh run noetic-ci ./docker/ci.sh
112 ./docker/docker.sh run humble-ci ./docker/ci.sh
113 ./docker/docker.sh run jazzy-ci ./docker/ci.sh
114 @endcode
115
116 <!-- trick doxygen -->
117
118 @subsection FPSDK_BUILD_BUILD_MANUAL Manual build
119
120 This details the manual setup of the dependencies and building the SDK on a ROS1 system (for example, Ubuntu 20.04
121 with ROS Noetic). It works similarly for ROS2 (for example, Ubuntu 22.04 with ROS Humble) or non-ROS (for example,
122 Debian Bookworm) based systems. Refer to the Docker configration files and scripts in the docker/ folder on
123 installing the required dependencies.
124
125 1. Setup build system, install dependencies
126
127 The exact steps required depend on your system. You'll need the dependencies mentioned above installed system
128 wide or otherwise tell CMake where to find them.
129
130 @code{sh}
131 sudo apt install libyaml-cpp-dev libboost-all-dev zlib1g-dev libeigen3-dev linux-libc-dev # For building
132 sudo apt install libgtest-dev clang-format doxygen pre-commit # For development
133 source /opt/ros/noetic/setup.bash # If you have ROS1
134 @endcode
135
136 3. Configure
137
138 @code{sh}
139 cmake -B build -DCMAKE_INSTALL_PREFIX=~/fpsdk
140 @endcode
141
142 Additional parameters include (see CMakeList.txt files of the projects for details):
143
144 - Build type: `-DCMAKE_BUILD_TYPE=Debug` or `-DCMAKE_BUILD_TYPE=Release` (default)
145 - Force ROS1 package path: `-DROS_PACKAGE_PATH=/path/to/ros` (default: auto-detect)
146 - Explicitly enable or disable testing: `-DBUILD_TESTING=OFF` or `-DBUILD_TESTING=ON`.
147 The default is to automatically enable testing if a suitable GTest library is found.
148 Note that the instead of the standard BUILD_TESTING variable the variable `FPSDK_BUILD_TESTING=...`
149 can be used.
150 - Explicitly enable or disable use of the PROJ library: `-DUSE_PROJ=ON` or `-DUSE_PROJ=OFF`.
151 The default is to automatically use the PROJ library if a suitable version is found
152
153 4. Build
154
155 @code{sh}
156 cmake --build build
157 @endcode
158
159 5. Install
160
161 @code{sh}
162 cmake --install build
163 @endcode
164
165 6. Enjoy!
166
167 For example:
168
169 @code{sh}
170 ~/fpsdk/bin/fpltool -h
171 @endcode
172
173 <!-- trick doxygen -->
174
175 @subsection FPSDK_BUILD_DOC_DOXYGEN Documentation
176
177 @code{sh}
178 make doc
179 @endcode
180
181
182 <!-- trick doxygen -->
183
184 @subsection FPSDK_BUILD_PACKAGE Individual packages
185
186 For example to build the fpsdk_common package (library):
187
188 @code{sh}
189 cmake -B build -S fpsdk_common -DCMAKE_INSTALL_PREFIX=~/fpsdk
190 cmake --build build
191 cmake --install build
192 @endcode
193
194
195 <!-- trick doxygen -->
196
197 @subsection FPSDK_BUILD_ROS ROS workspace
198
199 The packages build in a ROS workspace using catkin (ROS1) resp. colcon (ROS2). For example:
200
201 @code{sh}
202 catkin build fpsdk_common
203 @endcode
204
205 Note that if you clone this repository directly to your `ros_workspace/src` directory, you'll have to place
206 CATKIN_IGNORE resp. COLCON_IGNORE files in some places. For example:
207
208 @code{sh}
209 # ROS1 catkin workspace
210 touch src/fixposition-sdk/examples/CATKIN_IGNORE # Ignore all examples, or
211 touch src/fixposition-sdk/examples/ros1_fpsdk_demo/CATKIN_IGNORE # Ignore only this example
212 touch src/fixposition-sdk/fpsdk_ros2/CATKIN_IGNORE
213 @endcode
214
215 @code{sh}
216 # ROS2 colcon workspace
217 touch src/fixposition-sdk/examples/COLCON_IGNORE # Ignore all examples, or
218 touch src/fixposition-sdk/examples/ros2_fpsdk_demo/COLCON_IGNORE # Ignore only this example
219 touch src/fixposition-sdk/fpsdk_ros1/COLCON_IGNORE
220 @endcode
221
222 <!-- trick doxygen -->
223
224 @subsection FPSDK_BUILD_DETAILS Details
225
226 Refer to the various CMakeList.txt files, the CI workflow configuration (`.github/workflows/ci.yml`)
227 and the CI script (`docker/ci.sh`) for details on how things are done.
228
229
230
231*/
232
233// clang-format on
234/* ****************************************************************************************************************** */
235} // namespace fpsdk
236#endif // __FPSDK_BUILD_HPP__
fpsdk
Fixposition SDK.
Definition fpsdk_build.hpp:17