open-edge-platform · jb-balaji · Feb 16, 2026 · Feb 14, 2026 · Feb 16, 2026
@@ -21,12 +21,17 @@ else
 endif
 
 .DEFAULT_GOAL := help
-.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
+.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
 
 license-check:
 	@# Help: Perform a REUSE license check using docker container https://hub.docker.com/r/fsfe/reuse
 	docker run --rm --volume ${ROOT_DIR}:/data fsfe/reuse:5.0.2 lint
 
+safe-package:
+	@# Help: Build Debian package with memory-safe parallel job limits (recommended for systems with <32GB RAM)
+	@echo "Building with memory-safe limits to prevent system crashes..."
+	@bash scripts/safe-build.sh $(ROS_DISTRO) $(PARALLEL_JOBS)
+
 package:
 	@# Help: Build Debian package
 	docker run --rm -t --platform linux/amd64 \
@@ -46,7 +51,8 @@ package:
 			curl https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB | \
 				gpg --yes --dearmor --output /usr/share/keyrings/oneapi-archive-keyring.gpg && \
 			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 && \
-			apt update && apt install -y quilt equivs devscripts && \
+			apt update && \
+			apt install -y quilt equivs devscripts && \
 			scripts/uni-build.sh $(ROS_DISTRO) && cp -r /tmp/$(ROS_DISTRO)_cslam_deb_packages/ /src/$(ROS_DISTRO)_cslam_deb_packages"
 
 lint:
@@ -113,7 +119,7 @@ clean-colcon:
 clean-debian:
 	@# Help: Clean up Debian packaging artifacts
 	rm -rf debian
-	rm -f *.deb *.build *.changes *.dsc *.tar.gz *.buildinfo
+	rm -f *.deb *.ddeb *.build *.changes *.dsc *.tar.gz *.buildinfo
 
 clean: clean-debian clean-colcon
 	@# Help: Clean up all build artifacts

@@ -27,14 +27,63 @@ Prepare the target system following the [official documentation](https://docs.op
 
 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).
 
+#### Hardware Requirements
+
+Building Collaborative SLAM packages requires significant system resources:
+
+- **Minimum RAM:** 16GB (use `make safe-package` for memory-constrained systems)
+- **Recommended RAM:** 32GB or more (for `make package` with full parallelism)
+- **Disk Space:** ~10GB free space for build artifacts
+- **CPU:** Multi-core processor (4+ cores recommended)
+- **oneAPI:** Intel oneAPI 2025.x (provides `libsycl.so.8`) for SYCL/GPU support
+
+**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.
+
 ### Build
 
-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.
+To build debian packages, export `ROS_DISTRO` env variable to desired platform and run the appropriate build command.
+
+#### oneAPI/SYCL Compatibility
+
+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.
+
+**For local development with custom ORB extractor:**
+If you have a locally built ORB extractor with SYCL 8 support, you can use it during the build:
+
+```bash
+#### Safe Build (Recommended for <32GB RAM)
+
+For systems with limited memory (16-24GB), use the safe build option that automatically calculates optimal parallel job count:
+
+```bash
+ROS_DISTRO=jazzy make safe-package
+```
+
+This prevents memory exhaustion and system crashes by limiting parallelism based on available memory (approximately 2GB per parallel job).
+
+**Environment variables:**
+- `LOCAL_ORB_PATH` - Optional path to local ORB extractor packages (for SYCL 8 development)
+- `PARALLEL_JOBS` - Optional override for parallel jobs (default: auto-calculated)
+- `http_proxy`, `https_proxy`, `no_proxy` - Proxy configuration for corporate networks
+
+#### Full Speed Build (For =32GB RAM)
+
+For systems with ample memory, you can use full parallelism:
 
 ```bash
 ROS_DISTRO=humble make package
 ```
 
+Or manually specify parallel jobs:
+
+```bash
+ROS_DISTRO=jazzy PARALLEL_JOBS=8 make safe-package
+```
+
+**Note:** CI/CD systems typically have sufficient resources and should use `make package` after SYCL 8-compatible ORB extractor is published to repositories.
+
+After build process successfully finishes, built packages will be available in the `<ROS_DISTRO>_cslam_deb_packages/` directory.
+
 You can list all built packages:
 
 ```bash
@@ -71,7 +120,15 @@ If Ubuntu 24.04 with Jazzy is used, then run
 source /opt/ros/jazzy/setup.bash
 ```
 
-Finally, install the Debian packages that were built via `make package`:
+**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:
+
+```bash
+# If using local SYCL 8 ORB extractor
+sudo dpkg -i /path/to/orb-extractor/liborb-lze_*.deb
+sudo apt --fix-broken install -y  # Install any missing dependencies
+```
+
+Finally, install the Debian packages that were built via `make package` or `make safe-package`:
 
 ```bash
 sudo apt update
@@ -126,6 +183,7 @@ lint-markdown        Run Markdown linter using super-linter
 lint-python          Run Python linter using super-linter
 lint-yaml            Run YAML linter using super-linter
 package              Build Debian package
+safe-package         Build Debian package with memory-safe parallel job limits (recommended for systems with <32GB RAM)
 source-package       Create source package tarball
 ```
 
@@ -333,6 +391,66 @@ Fast Mapping support. By default, Fast Mapping support is disabled, but setting
 will enable Fast Mapping that will result in the topics `map`(2D) and `fused_map`(3D) maps being published.
 The parameters for configuring Fast Mapping are present in the [tracker.yaml](tracker/config/tracker.yaml).
 
+## Troubleshooting
+
+### SYCL Library Errors
+
+If you encounter errors like:
+
+```bash
+error while loading shared libraries: libsycl.so.7: cannot open shared object file
+error while loading shared libraries: libSyclUtils.so: cannot open shared object file
+```
+
+**Cause:** Version mismatch between installed oneAPI (SYCL 8) and packages built against older oneAPI (SYCL 7).
+
+**Solution:**
+
+1. **Verify oneAPI version:**
+   ```bash
+   ls -l /opt/intel/oneapi/redist/lib/libsycl.so*
+   # Should show libsycl.so.8 for oneAPI 2025.x
+   ```
+
+2. **Check ORB extractor version:**
+   ```bash
+   apt-cache show liborb-lze-dev | grep -E "Version|Depends.*sycl"
+   # Should show version >= 2.3-2 with oneAPI 2025.x dependencies
+   ```
+
+3. **Rebuild packages:** If repositories have outdated versions, rebuild with local SYCL 8 ORB extractor:
+   ```bash
+   export LOCAL_ORB_PATH=/path/to/sycl8-orb-extractor
+   ROS_DISTRO=jazzy make safe-package
+   sudo dpkg -i jazzy_cslam_deb_packages/*.deb
+   ```
+
+4. **Verify dependencies:** Check installed packages link against correct SYCL version:
+   ```bash
+   ldd /opt/ros/jazzy/lib/univloc_tracker/univloc_tracker_ros | grep sycl
+   # Should show: libsycl.so.8 => /opt/intel/oneapi/redist/lib/libsycl.so.8
+   ```
+
+### Memory Exhaustion During Build
+
+If your system freezes or runs out of memory during build:
+
+**Solution:** Use the safe build option that automatically limits parallelism:
+```bash
+ROS_DISTRO=jazzy make safe-package
+```
+
+Or manually specify fewer parallel jobs:
+```bash
+ROS_DISTRO=jazzy PARALLEL_JOBS=4 make safe-package
+```
+
+### Proxy Issues
+
+If builds fail with network errors behind proxy:
+
+**Solution:** Export proxy environment variables before building:
+
 ## Documentation
 
 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).

@@ -30,6 +30,31 @@ lspci -v | grep -A10 VGA
 ```
 
 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.
+
+### oneAPI Version Compatibility
+
+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.
+
+**Recommended:** Intel oneAPI 2025.x or later (provides `libsycl.so.8`)
+
+To check your installed oneAPI version:
+
+```bash
+ls -l /opt/intel/oneapi/redist/lib/libsycl.so*
+# For oneAPI 2024.x: libsycl.so.7.x.x
+# For oneAPI 2025.x: libsycl.so.8.x.x
+```
+
+**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:
+```bash
+error while loading shared libraries: libsycl.so.7: cannot open shared object file
+```
+
+To resolve this, **rebuild the packages** from source against your installed oneAPI version using:
+```bash
+make package ROS_DISTRO=jazzy  # or humble
+```
+
 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.
 
 ```bash
@@ -65,7 +90,14 @@ a docker. In case of EI for AMR docker, run:
 ## Build
 
 To get Collaborative SLAM with C-for-Metal GPU support, make sure that Prerequisites are done.
-If so, then simply run:
+
+**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:
+
+```sh
+ROS_DISTRO=jazzy make safe-package
+```
+
+For development builds with colcon:
 
 ```sh
 colcon build --cmake-args -DUSE_GPU_CM=1 -DCM_GPU_INSTALL_DIR=/path/to/orb_extractor/install/dir

@@ -1,3 +1,9 @@
+ros-humble-univloc-msgs (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-humble-univloc-msgs (2.3-1) UNRELEASED; urgency=low
 
   * Refactoring of the code and general optimizations

@@ -1,3 +1,9 @@
+ros-jazzy-univloc-msgs (2.3-2) UNRELEASED; urgency=medium
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-jazzy-univloc-msgs (2.3-1) UNRELEASED; urgency=medium
 
   * Initial release

@@ -1,3 +1,9 @@
+ros-humble-collab-slam (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-humble-collab-slam (2.3-1) UNRELEASED; urgency=low
 
   * Refactoring of the code and general optimizations

@@ -1,3 +1,9 @@
+ros-jazzy-collab-slam (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-jazzy-collab-slam (2.3-1) UNRELEASED; urgency=low
 
   * Initial release

@@ -1,3 +1,9 @@
+ros-humble-cslam-tutorial-2d-lidar (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-humble-cslam-tutorial-2d-lidar (2.3-1) UNRELEASED; urgency=low
 
   * Refactoring of the code and general optimizations

@@ -1,3 +1,9 @@
+ros-jazzy-cslam-tutorial-2d-lidar (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-jazzy-cslam-tutorial-2d-lidar (2.3-1) UNRELEASED; urgency=low
 
   * Initial release

@@ -1,3 +1,9 @@
+ros-humble-cslam-tutorial-all (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-humble-cslam-tutorial-all (2.3-1) UNRELEASED; urgency=low
 
   * Refactoring of the code and general optimizations

@@ -1,3 +1,9 @@
+ros-jazzy-cslam-tutorial-all (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-jazzy-cslam-tutorial-all (2.3-1) UNRELEASED; urgency=low
 
   * Initial release

@@ -1,3 +1,9 @@
+ros-humble-cslam-tutorial-common (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-humble-cslam-tutorial-common (2.3-1) UNRELEASED; urgency=low
 
   * Refactoring of the code and general optimizations

@@ -1,3 +1,9 @@
+ros-jazzy-cslam-tutorial-common (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-jazzy-cslam-tutorial-common (2.3-1) UNRELEASED; urgency=low
 
   * Initial release

@@ -1,3 +1,9 @@
+ros-humble-cslam-tutorial-fastmapping (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-humble-cslam-tutorial-fastmapping (2.3-1) UNRELEASED; urgency=low
 
   * Refactoring of the code and general optimizations

@@ -1,3 +1,9 @@
+ros-jazzy-cslam-tutorial-fastmapping (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-jazzy-cslam-tutorial-fastmapping (2.3-1) UNRELEASED; urgency=low
 
   * Initial release

@@ -1,3 +1,9 @@
+ros-humble-cslam-tutorial-multi-camera (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-humble-cslam-tutorial-multi-camera (2.3-1) UNRELEASED; urgency=low
 
   * Refactoring of the code and general optimizations

@@ -1,3 +1,9 @@
+ros-jazzy-cslam-tutorial-multi-camera (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-jazzy-cslam-tutorial-multi-camera (2.3-1) UNRELEASED; urgency=low
 
   * Initial release

@@ -1,3 +1,9 @@
+ros-humble-cslam-tutorial-region-remap (2.3-2) UNRELEASED; urgency=low
+
+  * Update to build using oneAPI 2025
+
+ -- ECI Maintainer <eci.maintainer@intel.com>  Fri, 13 Feb 2025 19:10:0 +0200
+
 ros-humble-cslam-tutorial-region-remap (2.3-1) UNRELEASED; urgency=low
 
   * Refactoring of the code and general optimizations