Fixposition SDK 0.0.0-heads/main-0-g408dc89
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 Trixie)
40 - boost (≥ 1.71.0)
41 - curl (≥ 7.68.0)
42 - Eigen3 (≥ 3.3.7)
43 - yaml-cpp (≥ 0.6.2)
44 - zlib1g (≥ 1.2.11)
45 - OpenSSL (libssl) (≥ 1.1.x)
46 - nlohmann-json3 (≥ 3.7.3)
47 - Various Linux tools, including Bash, CMake, make, xxd, sed, awk, ...
48 - PROJ (*) (≥ 9.4.x)
49 - ROS1 (*) (Noetic), or
50 - ROS2 (*) (Humble or Jazzy)
51
52 (*) Optional dependencies. Without these some functionality in the libraries and apps is unavailable (compiled out).
53
54 For development additionally:
55
56 - clang-format (≥ 19, tested with 19)
57 - Doxygen (≥ 1.11.0, tested with 1.14.0)
58 - GTest (≥ 1.12.0)
59
60 Note that the list above may be incomplete or wrong. See @ref FPSDK_BUILD_CIVERSIONS for the versions used in the CI
61 builds.
62
63 <!-- trick doxygen -->
64
65 @page FPSDK_BUILD_DOC
66
67 @section FPSDK_BUILD_BUILD Building
68
69 @subsection FPSDK_BUILD_BUILD_TLDR tl;dr
70
71 @code{sh}
72 ./docker/docker.sh pull noetic-dev # Or "docker.sh build noetic-dev" to build the image locally
73 ./docker/docker.sh run noetic-dev bash
74 # Now inside Docker do:
75 source /opt/ros/noetic/setup.bash
76 make install
77 ./fpsdk/bin/fpltool -h
78 @endcode
79
80 <!-- trick doxygen -->
81
82 @subsection FPSDK_BUILD_BUILD_DEVCONTAINER VSCode devcontainer
83
84 Open the fpsdk.code-workspace, change to one of the provided devcontainers, and in a terminal do:
85
86 @code{sh}
87 make install
88 ./fpsdk/bin/fpltool
89 @endcode
90
91 <!-- trick doxygen -->
92
93 @subsection FPSDK_BUILD_BUILD_DOCKER Docker container
94
95 Docker images are provided that include all the dependencies:
96
97 @code{sh}
98 ./docker/docker.sh pull noetic-dev # Or "docker.sh build noetic-dev" to build the image locally
99 ./docker/docker.sh run noetic-dev bash
100 source /opt/ros/noetic/setup.bash
101 make install
102 ./fpsdk/bin/fpltool
103 @endcode
104
105 Note that the "docker.sh" script does not give you a suitable ROS runtime (or development, playground, ...)
106 environment! Its only purpose is to run the CI for this repo and to demonstrate the building here. For a ROS
107 run-time environment please setup a docker *container* yourself elsewhere (perhaps using the docker *image* provided
108 here). See ROS and Docker documentation and the Internet for help.
109
110 <!-- trick doxygen -->
111
112 @subsection FPSDK_BUILD_BUILD_CI Run CI
113
114 @code{sh}
115 ./docker/docker.sh run noetic-ci ./docker/ci.sh
116 ./docker/docker.sh run humble-ci ./docker/ci.sh
117 ./docker/docker.sh run jazzy-ci ./docker/ci.sh
118 @endcode
119
120 <!-- trick doxygen -->
121
122 @subsection FPSDK_BUILD_BUILD_MANUAL Manual build
123
124 This details the manual setup of the dependencies and building the SDK on a ROS1 system (for example, Ubuntu 20.04
125 with ROS Noetic). It works similarly for ROS2 (for example, Ubuntu 22.04 with ROS Humble) or non-ROS (for example,
126 Debian Trixie) based systems. Refer to the Docker configration files and scripts in the docker/ folder on installing
127 the required dependencies.
128
129 1. Setup build system, install dependencies
130
131 The exact steps required depend on your system. You'll need the dependencies mentioned above installed system
132 wide or otherwise tell CMake where to find them.
133
134 @code{sh}
135 sudo apt install libyaml-cpp-dev libboost-all-dev zlib1g-dev libeigen3-dev linux-libc-dev xxd # For building
136 sudo apt install libgtest-dev clang-format doxygen pre-commit # For development
137 source /opt/ros/noetic/setup.bash # If you have ROS1
138 @endcode
139
140 3. Configure
141
142 @code{sh}
143 cmake -B build -DCMAKE_INSTALL_PREFIX=~/fpsdk
144 @endcode
145
146 Additional parameters include (see CMakeList.txt files of the projects for details and more parameters):
147
148 - Build type: `-DCMAKE_BUILD_TYPE=Debug` or `-DCMAKE_BUILD_TYPE=Release` (default)
149 - Force ROS1 package path: `-DROS_PACKAGE_PATH=/path/to/ros` (default: auto-detect)
150 - Explicitly enable or disable testing: `-DBUILD_TESTING=OFF` or `-DBUILD_TESTING=ON`.
151 The default is to automatically enable testing if a suitable GTest library is found.
152 Note that the instead of the standard BUILD_TESTING variable the variable `FPSDK_BUILD_TESTING=...`
153 can be used.
154 - Explicitly enable or disable use of the PROJ library: `-DFPSDK_USE_PROJ=ON` or `-DFPSDK_USE_PROJ=OFF`.
155 The default is to automatically use the PROJ library if a suitable version is found
156
157 4. Build
158
159 @code{sh}
160 cmake --build build
161 @endcode
162
163 5. Install
164
165 @code{sh}
166 cmake --install build
167 @endcode
168
169 6. Enjoy!
170
171 For example:
172
173 @code{sh}
174 ~/fpsdk/bin/fpltool -h
175 @endcode
176
177 <!-- trick doxygen -->
178
179 @subsection FPSDK_BUILD_DOC_DOXYGEN Documentation
180
181 @code{sh}
182 make doc
183 @endcode
184
185
186 <!-- trick doxygen -->
187
188 @subsection FPSDK_BUILD_PACKAGE Individual packages
189
190 For example to build the fpsdk_common package (library):
191
192 @code{sh}
193 cmake -B build -S fpsdk_common -DCMAKE_INSTALL_PREFIX=~/fpsdk
194 cmake --build build
195 cmake --install build
196 @endcode
197
198
199 <!-- trick doxygen -->
200
201 @subsection FPSDK_BUILD_ROS ROS workspace
202
203 The packages build in a ROS workspace using catkin (ROS1) resp. colcon (ROS2). For example:
204
205 @code{sh}
206 catkin build fpsdk_common
207 @endcode
208
209 Note that if you clone this repository directly to your `ros_workspace/src` directory, you'll have to place
210 CATKIN_IGNORE resp. COLCON_IGNORE files in some places. For example:
211
212 @code{sh}
213 # ROS1 catkin workspace
214 touch src/fixposition-sdk/examples/CATKIN_IGNORE # Ignore all examples, or
215 touch src/fixposition-sdk/examples/ros1_fpsdk_demo/CATKIN_IGNORE # Ignore only this example
216 touch src/fixposition-sdk/fpsdk_ros2/CATKIN_IGNORE
217 @endcode
218
219 @code{sh}
220 # ROS2 colcon workspace
221 touch src/fixposition-sdk/examples/COLCON_IGNORE # Ignore all examples, or
222 touch src/fixposition-sdk/examples/ros2_fpsdk_demo/COLCON_IGNORE # Ignore only this example
223 touch src/fixposition-sdk/fpsdk_ros1/COLCON_IGNORE
224 @endcode
225
226 <!-- trick doxygen -->
227
228 @subsection FPSDK_BUILD_DETAILS Details
229
230 Refer to the various CMakeList.txt files, the CI workflow configuration (`.github/workflows/ci.yml`)
231 and the CI script (`docker/ci.sh`) for details on how things are done.
232
233
234 @section FPSDK_BUILD_CIVERSIONS Dependency versions
235
236
237 The builds using Debian 13 "Trixie" currently use:
238
239 @include fpsdk_common_versions_trixie/fpsdk_common/fpsdk_common_versions.txt
240
241
242 The builds using ROS Noetic (Ubuntu 20.04.6 LTS "Focal") currently use:
243
244 @include fpsdk_common_versions_noetic/fpsdk_common/fpsdk_common_versions.txt
245
246
247 The builds using ROS Humble (Ubuntu 22.04 LTS "Jammy") currently use:
248
249 @include fpsdk_common_versions_humble/fpsdk_common/fpsdk_common_versions.txt
250
251
252 The builds using ROS Jazzy (Ubuntu 24.04 LTS "Noble") currently use:
253
254 @include fpsdk_common_versions_jazzy/fpsdk_common/fpsdk_common_versions.txt
255*/
256
257// clang-format on
258/* ****************************************************************************************************************** */
259} // namespace fpsdk
260#endif // __FPSDK_BUILD_HPP__
Fixposition SDK.