Skip to content

Commit 9cd5ff9

Browse files
jb-balajijb-balaji
committed
Update Collaborative SLAM to support oneAPI 2025 and enhance build process
- Added a new `safe-package` target in the Makefile for memory-safe builds, recommended for systems with less than 32GB RAM. - Updated README.md to include hardware requirements and detailed build instructions for both safe and full-speed builds. - Introduced a `safe-build.sh` script to automate safe build processes and manage parallel job limits based on available memory. - Updated changelogs across various packages to reflect the transition to oneAPI 2025. - Enhanced Docker build commands to ensure compatibility with oneAPI 2025 and improved dependency management. - Added troubleshooting sections in the documentation for common issues related to SYCL library errors and memory exhaustion during builds.
1 parent 83070d7 commit 9cd5ff9

File tree

28 files changed

+442
-6
lines changed

28 files changed

+442
-6
lines changed

‎robotics-ai-suite/components/collaborative-slam/Makefile‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,17 @@ else
2121
endif
2222

2323
.DEFAULT_GOAL := help
24-
.PHONY: help clean clean-colcon clean-debian license-check lint lint-all lint-clang lint-python lint-yaml lint-githubactions lint-bash lint-markdown lint-json package source-package
24+
.PHONY: help clean clean-colcon clean-debian license-check lint lint-all lint-clang lint-python lint-yaml lint-githubactions lint-bash lint-markdown lint-json package safe-package source-package
2525

2626
license-check:
2727
@# Help: Perform a REUSE license check using docker container https://hub.docker.com/r/fsfe/reuse
2828
docker run --rm --volume ${ROOT_DIR}:/data fsfe/reuse:5.0.2 lint
2929

30+
safe-package:
31+
@# Help: Build Debian package with memory-safe parallel job limits (recommended for systems with <32GB RAM)
32+
@echo "Building with memory-safe limits to prevent system crashes..."
33+
@bash scripts/safe-build.sh $(ROS_DISTRO) $(PARALLEL_JOBS)
34+
3035
package:
3136
@# Help: Build Debian package
3237
docker run --rm -t --platform linux/amd64 \
@@ -46,7 +51,8 @@ package:
4651
curl https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB | \
4752
gpg --yes --dearmor --output /usr/share/keyrings/oneapi-archive-keyring.gpg && \
4853
echo \"deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg] https://apt.repos.intel.com/oneapi all main\" > /etc/apt/sources.list.d/oneAPI.list && \
49-
apt update && apt install -y quilt equivs devscripts && \
54+
apt update && \
55+
apt install -y quilt equivs devscripts && \
5056
scripts/uni-build.sh $(ROS_DISTRO) && cp -r /tmp/$(ROS_DISTRO)_cslam_deb_packages/ /src/$(ROS_DISTRO)_cslam_deb_packages"
5157

5258
lint:
@@ -113,7 +119,7 @@ clean-colcon:
113119
clean-debian:
114120
@# Help: Clean up Debian packaging artifacts
115121
rm -rf debian
116-
rm -f *.deb *.build *.changes *.dsc *.tar.gz *.buildinfo
122+
rm -f *.deb *.ddeb *.build *.changes *.dsc *.tar.gz *.buildinfo
117123

118124
clean: clean-debian clean-colcon
119125
@# Help: Clean up all build artifacts

‎robotics-ai-suite/components/collaborative-slam/README.md‎

Lines changed: 120 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,63 @@ Prepare the target system following the [official documentation](https://docs.op
2727

2828
We support Ubuntu 22.04 with [ROS 2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html) and Ubuntu 24.04 with [ROS 2 Jazzy](https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html).
2929

30+
#### Hardware Requirements
31+
32+
Building Collaborative SLAM packages requires significant system resources:
33+
34+
- **Minimum RAM:** 16GB (use `make safe-package` for memory-constrained systems)
35+
- **Recommended RAM:** 32GB or more (for `make package` with full parallelism)
36+
- **Disk Space:** ~10GB free space for build artifacts
37+
- **CPU:** Multi-core processor (4+ cores recommended)
38+
- **oneAPI:** Intel oneAPI 2025.x (provides `libsycl.so.8`) for SYCL/GPU support
39+
40+
**Important:** Building with SYCL/oneAPI support is memory-intensive. Each parallel compilation job can consume 1-2GB of RAM. On systems with limited memory, use the safe build option to prevent system crashes.
41+
3042
### Build
3143

32-
To build debian packages, export `ROS_DISTRO` env variable to desired platform and run `make package` command. After build process successfully finishes, built packages will be available in the `<ROS_DISTRO>_cslam_deb_packages/` directory. The following command is an example for `Humble` distribution.
44+
To build debian packages, export `ROS_DISTRO` env variable to desired platform and run the appropriate build command.
45+
46+
#### oneAPI/SYCL Compatibility
47+
48+
Collaborative SLAM requires Intel oneAPI 2025.x with SYCL 8 (`libsycl.so.8`) for GPU acceleration support. The build system pulls ORB extractor dependencies from Intel ECI/AMR repositories.
49+
50+
**For local development with custom ORB extractor:**
51+
If you have a locally built ORB extractor with SYCL 8 support, you can use it during the build:
52+
53+
```bash
54+
#### Safe Build (Recommended for <32GB RAM)
55+
56+
For systems with limited memory (16-24GB), use the safe build option that automatically calculates optimal parallel job count:
57+
58+
```bash
59+
ROS_DISTRO=jazzy make safe-package
60+
```
61+
62+
This prevents memory exhaustion and system crashes by limiting parallelism based on available memory (approximately 2GB per parallel job).
63+
64+
**Environment variables:**
65+
- `LOCAL_ORB_PATH` - Optional path to local ORB extractor packages (for SYCL 8 development)
66+
- `PARALLEL_JOBS` - Optional override for parallel jobs (default: auto-calculated)
67+
- `http_proxy`, `https_proxy`, `no_proxy` - Proxy configuration for corporate networks
68+
69+
#### Full Speed Build (For =32GB RAM)
70+
71+
For systems with ample memory, you can use full parallelism:
3372

3473
```bash
3574
ROS_DISTRO=humble make package
3675
```
3776

77+
Or manually specify parallel jobs:
78+
79+
```bash
80+
ROS_DISTRO=jazzy PARALLEL_JOBS=8 make safe-package
81+
```
82+
83+
**Note:** CI/CD systems typically have sufficient resources and should use `make package` after SYCL 8-compatible ORB extractor is published to repositories.
84+
85+
After build process successfully finishes, built packages will be available in the `<ROS_DISTRO>_cslam_deb_packages/` directory.
86+
3887
You can list all built packages:
3988

4089
```bash
@@ -71,7 +120,15 @@ If Ubuntu 24.04 with Jazzy is used, then run
71120
source /opt/ros/jazzy/setup.bash
72121
```
73122

74-
Finally, install the Debian packages that were built via `make package`:
123+
**Important:** For systems with oneAPI 2025.x, ensure you have the SYCL 8-compatible ORB extractor installed. If you built packages with `LOCAL_ORB_PATH`, install the local ORB extractor first:
124+
125+
```bash
126+
# If using local SYCL 8 ORB extractor
127+
sudo dpkg -i /path/to/orb-extractor/liborb-lze_*.deb
128+
sudo apt --fix-broken install -y # Install any missing dependencies
129+
```
130+
131+
Finally, install the Debian packages that were built via `make package` or `make safe-package`:
75132

76133
```bash
77134
sudo apt update
@@ -126,6 +183,7 @@ lint-markdown Run Markdown linter using super-linter
126183
lint-python Run Python linter using super-linter
127184
lint-yaml Run YAML linter using super-linter
128185
package Build Debian package
186+
safe-package Build Debian package with memory-safe parallel job limits (recommended for systems with <32GB RAM)
129187
source-package Create source package tarball
130188
```
131189

@@ -333,6 +391,66 @@ Fast Mapping support. By default, Fast Mapping support is disabled, but setting
333391
will enable Fast Mapping that will result in the topics `map`(2D) and `fused_map`(3D) maps being published.
334392
The parameters for configuring Fast Mapping are present in the [tracker.yaml](tracker/config/tracker.yaml).
335393

394+
## Troubleshooting
395+
396+
### SYCL Library Errors
397+
398+
If you encounter errors like:
399+
400+
```bash
401+
error while loading shared libraries: libsycl.so.7: cannot open shared object file
402+
error while loading shared libraries: libSyclUtils.so: cannot open shared object file
403+
```
404+
405+
**Cause:** Version mismatch between installed oneAPI (SYCL 8) and packages built against older oneAPI (SYCL 7).
406+
407+
**Solution:**
408+
409+
1. **Verify oneAPI version:**
410+
```bash
411+
ls -l /opt/intel/oneapi/redist/lib/libsycl.so*
412+
# Should show libsycl.so.8 for oneAPI 2025.x
413+
```
414+
415+
2. **Check ORB extractor version:**
416+
```bash
417+
apt-cache show liborb-lze-dev | grep -E "Version|Depends.*sycl"
418+
# Should show version >= 2.3-2 with oneAPI 2025.x dependencies
419+
```
420+
421+
3. **Rebuild packages:** If repositories have outdated versions, rebuild with local SYCL 8 ORB extractor:
422+
```bash
423+
export LOCAL_ORB_PATH=/path/to/sycl8-orb-extractor
424+
ROS_DISTRO=jazzy make safe-package
425+
sudo dpkg -i jazzy_cslam_deb_packages/*.deb
426+
```
427+
428+
4. **Verify dependencies:** Check installed packages link against correct SYCL version:
429+
```bash
430+
ldd /opt/ros/jazzy/lib/univloc_tracker/univloc_tracker_ros | grep sycl
431+
# Should show: libsycl.so.8 => /opt/intel/oneapi/redist/lib/libsycl.so.8
432+
```
433+
434+
### Memory Exhaustion During Build
435+
436+
If your system freezes or runs out of memory during build:
437+
438+
**Solution:** Use the safe build option that automatically limits parallelism:
439+
```bash
440+
ROS_DISTRO=jazzy make safe-package
441+
```
442+
443+
Or manually specify fewer parallel jobs:
444+
```bash
445+
ROS_DISTRO=jazzy PARALLEL_JOBS=4 make safe-package
446+
```
447+
448+
### Proxy Issues
449+
450+
If builds fail with network errors behind proxy:
451+
452+
**Solution:** Export proxy environment variables before building:
453+
336454
## Documentation
337455
338456
Comprehensive documentation on this component is available here: [dev guide](https://docs.openedgeplatform.intel.com/dev/edge-ai-suites/robotics-ai-suite/robotics/dev_guide/tutorials_amr/navigation/collaborative-slam.html).

‎robotics-ai-suite/components/collaborative-slam/docs/GPU_CM.md‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,31 @@ lspci -v | grep -A10 VGA
3030
```
3131

3232
Second, you need to follow [specific instructions](https://dgpu-docs.intel.com/installation-guides/index.html) to install necessary software packages based on the GPU type. For example, as for the above integrated Intel GPU, it belongs to the Intel Gen12/DG1 GPU. The final step is to configure the permissions for your user account, the related commands are also listed in the above link.
33+
34+
### oneAPI Version Compatibility
35+
36+
Collaborative SLAM requires Intel oneAPI Base Toolkit for SYCL runtime support. The application must be built against the same oneAPI version installed on your system.
37+
38+
**Recommended:** Intel oneAPI 2025.x or later (provides `libsycl.so.8`)
39+
40+
To check your installed oneAPI version:
41+
42+
```bash
43+
ls -l /opt/intel/oneapi/redist/lib/libsycl.so*
44+
# For oneAPI 2024.x: libsycl.so.7.x.x
45+
# For oneAPI 2025.x: libsycl.so.8.x.x
46+
```
47+
48+
**Important:** If you install pre-built packages that were compiled against a different oneAPI version than your system has, you will encounter runtime errors like:
49+
```bash
50+
error while loading shared libraries: libsycl.so.7: cannot open shared object file
51+
```
52+
53+
To resolve this, **rebuild the packages** from source against your installed oneAPI version using:
54+
```bash
55+
make package ROS_DISTRO=jazzy # or humble
56+
```
57+
3358
After successfully installing all the packages, you are able to use `sycl-ls` (comes with oneAPI package) to verify that LevelZero is ready and exposed. You should see the line below in the output.
3459
3560
```bash
@@ -65,7 +90,14 @@ a docker. In case of EI for AMR docker, run:
6590
## Build
6691
6792
To get Collaborative SLAM with C-for-Metal GPU support, make sure that Prerequisites are done.
68-
If so, then simply run:
93+
94+
**Important:** Building with GPU/SYCL support is extremely memory-intensive. See the [Build section in README](../README.md#build) for memory requirements. For systems with 16-24GB RAM, use:
95+
96+
```sh
97+
ROS_DISTRO=jazzy make safe-package
98+
```
99+
100+
For development builds with colcon:
69101
70102
```sh
71103
colcon build --cmake-args -DUSE_GPU_CM=1 -DCM_GPU_INSTALL_DIR=/path/to/orb_extractor/install/dir

‎robotics-ai-suite/components/collaborative-slam/msgs/humble/debian/changelog‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
ros-humble-univloc-msgs (2.3-2) UNRELEASED; urgency=low
2+
3+
* Update to build using oneAPI 2025
4+
5+
-- ECI Maintainer <eci.maintainer@intel.com> Fri, 13 Feb 2025 19:10:0 +0200
6+
17
ros-humble-univloc-msgs (2.3-1) UNRELEASED; urgency=low
28

39
* Refactoring of the code and general optimizations

‎robotics-ai-suite/components/collaborative-slam/msgs/jazzy/debian/changelog‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
ros-jazzy-univloc-msgs (2.3-2) UNRELEASED; urgency=medium
2+
3+
* Update to build using oneAPI 2025
4+
5+
-- ECI Maintainer <eci.maintainer@intel.com> Fri, 13 Feb 2025 19:10:0 +0200
6+
17
ros-jazzy-univloc-msgs (2.3-1) UNRELEASED; urgency=medium
28

39
* Initial release

‎robotics-ai-suite/components/collaborative-slam/package/metapackage/humble/debian/changelog‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
ros-humble-collab-slam (2.3-2) UNRELEASED; urgency=low
2+
3+
* Update to build using oneAPI 2025
4+
5+
-- ECI Maintainer <eci.maintainer@intel.com> Fri, 13 Feb 2025 19:10:0 +0200
6+
17
ros-humble-collab-slam (2.3-1) UNRELEASED; urgency=low
28

39
* Refactoring of the code and general optimizations

‎robotics-ai-suite/components/collaborative-slam/package/metapackage/jazzy/debian/changelog‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
ros-jazzy-collab-slam (2.3-2) UNRELEASED; urgency=low
2+
3+
* Update to build using oneAPI 2025
4+
5+
-- ECI Maintainer <eci.maintainer@intel.com> Fri, 13 Feb 2025 19:10:0 +0200
6+
17
ros-jazzy-collab-slam (2.3-1) UNRELEASED; urgency=low
28

39
* Initial release

‎robotics-ai-suite/components/collaborative-slam/package/tutorial-2d-lidar/humble/debian/changelog‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
ros-humble-cslam-tutorial-2d-lidar (2.3-2) UNRELEASED; urgency=low
2+
3+
* Update to build using oneAPI 2025
4+
5+
-- ECI Maintainer <eci.maintainer@intel.com> Fri, 13 Feb 2025 19:10:0 +0200
6+
17
ros-humble-cslam-tutorial-2d-lidar (2.3-1) UNRELEASED; urgency=low
28

39
* Refactoring of the code and general optimizations

‎robotics-ai-suite/components/collaborative-slam/package/tutorial-2d-lidar/jazzy/debian/changelog‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
ros-jazzy-cslam-tutorial-2d-lidar (2.3-2) UNRELEASED; urgency=low
2+
3+
* Update to build using oneAPI 2025
4+
5+
-- ECI Maintainer <eci.maintainer@intel.com> Fri, 13 Feb 2025 19:10:0 +0200
6+
17
ros-jazzy-cslam-tutorial-2d-lidar (2.3-1) UNRELEASED; urgency=low
28

39
* Initial release

‎robotics-ai-suite/components/collaborative-slam/package/tutorial-all/humble/debian/changelog‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
ros-humble-cslam-tutorial-all (2.3-2) UNRELEASED; urgency=low
2+
3+
* Update to build using oneAPI 2025
4+
5+
-- ECI Maintainer <eci.maintainer@intel.com> Fri, 13 Feb 2025 19:10:0 +0200
6+
17
ros-humble-cslam-tutorial-all (2.3-1) UNRELEASED; urgency=low
28

39
* Refactoring of the code and general optimizations

0 commit comments

Comments
 (0)