6.1 Zenoh C/C++ 바인딩 개요 및 개발 환경 구축

6.1 Zenoh C/C++ 바인딩 개요 및 개발 환경 구축

C++ 세계에 입문한 백엔드 엔지니어라면 알 것이다. CMakeLists.txt 와 빌드 링커 에러(undefined reference)로 며칠을 허비하고 나면, 코어 로직 한 줄 짜보기도 전에 퇴사하고 싶어지는 그 감각을.

Zenoh의 Rust 코어 위에는 C ABI를 맞춘 zenoh-c 라이브러리가 존재하며, 그 위를 감싸는 모던 래퍼(Wrapper)인 zenoh-cpp가 있다.
이 생태계 구성은 C++ 컴파일러(GCC, Clang, MSVC)의 수많은 의존성 버그 파면에서 엔지니어를 구출하기 위한 완벽한 방파제 역할을 한다. 이번 챕터에서는 무지성 코딩을 멈추고, vcpkg/Conan 같은 패키지 관리자와 현대적인 CMake 3.0 이상을 이용하여 당신의 C++ 시스템에 단 5분 만에 Zenoh 코어를 안착시키는 프로덕션 빌드 런북을 살펴본다.

1. Zenoh C API의 아키텍처 및 철학

본질적으로 C 코드는 포인터와의 처절한 생존 싸움이다. Rust 코어가 보장하는 절대적인 메모리 안전성(Memory Safety)을 C 컴파일러 환경으로 어떻게 끌어내리기 위해 Zenoh 아키텍트들은 “소유권 위임 모델(Ownership Delegation)“을 도입했다.

1.0.1 [Runbook] 메모리 생명주기 제어 원칙

Zenoh C API(zenoh.h)의 구조체 네이밍과 라이프사이클 룰은 세 가지로 요약된다.

1. 불변 데이터 핸들링: 빌림(Borrowing)
z_borrow() 나 파라미터로 넘겨진 원격 문자열 덩어리는, 콜백 함수 내부에서만 읽어 제쳐야(Read-only) 한다. 이 포인터를 멋대로 메인 구역의 전역 변수로 할당하면 곧바로 시스템 세그폴트(Segmentation Fault)의 비소가 울려 퍼진다.

void data_callback(const z_sample_t *sample, void *context) {
    // [경고] sample 포인터에 있는 byte 덩어리는 이 블록을 나가면 즉시 증발한다(Dropped).
    // 백그라운드 큐에 넣고 싶다면 반드시 'memcpy' 로 깊은 복사(Deep Copy)를 해야 한다.
}

2. 메모리 회수 강제화 (z_drop)
객체를 만들면(alloc), 반드시 소멸(drop)시켜야 한다. Zenoh C API는 가비지 컬렉터의 혜택을 받지 못하므로 모든 C 구조체(z_owned_session_t) 뒤집개는 매뉴얼로 수거된다.

z_owned_config_t config = z_config_default();
z_owned_session_t session = z_open(z_move(config));

// 사용이 끝나면 즉시 파괴
z_close(z_move(session));
// config 객체는 z_move 매크로에 의해 소유권이 이전되었으므로 다시 drop 할 필요가 없다. (Rust의 소유권 이전과 동일)

[아키텍처 철학] z_move 매크로의 진실
이것은 C++의 std::move 와 개념적으로 완전히 같다. 당신이 z_move(config) 라고 호출하는 순간 함수 포인터는 껍데기만 남겨지며 이중 해제(Double Free)를 막기 위한 무서운 안전장치가 작동한다.
C 언어라는 가장 오래된 총알로 코딩하더라도, Rust의 엄격한 규율과 소유권 철학을 모방하여 프로덕션 시스템을 수호하는 마법이다.

2. C API와 C++ 바인딩(zenoh-cpp)의 차이점 이해

공장에서 돌릴 자율주행 코드 베이스가 C++14 이상이라면, zenoh.h (C API)를 직접 갖다 쓰는 것은 “스틸 프레임 대신 통나무로 집을 짓는 꼴“이다. zenoh-cpp 라이브러리는 그 고통스러운 포인터 락과 메모리 관리를 모던 C++ 문법 위로 우아하게 추상화했다.

2.0.1 [Runbook] 프로덕션 레벨 인터페이스 전환 (C vs C++)

같은 동작(Session 연결)을 하는 코드가 두 언어의 철학에 따라 얼마나 달라지는지 극명하게 보여준다.

[안티 패턴] 순수 C (에러 덩어리와 지저분한 매크로)

#include "zenoh.h"

int main() {
    z_owned_config_t config = z_config_default();
    z_owned_session_t session;
    
    // 에러 검증 코드를 짤 때마다 if return 이 수십 줄씩 붙는다.
    if (z_open(&session, z_move(config), NULL) != Z_OK) {
        printf("세션 개방 실패\n");
        return 1;
    }
    
    z_close(z_move(session));
    return 0;
}

[정석] 모던 C++ (RAII 와 예외 처리의 융합)

#include "zenoh.hxx"
#include <iostream>

int main() {
    try {
        auto config = zenoh::Config::create_default();
        
        // RAII 패턴: session 변수가 블록 스코프를 벗어나는 순간,
        // C++ 소멸자(Destructor)가 알아서 z_close() 를 호출하여 포트를 깨끗이 분리한다.
        auto session = zenoh::Session::open(std::move(config));
        
        std::cout << "네트워크 접속 완료" << std::endl;
        
    } catch (const zenoh::ZException& e) {
        // [강력한 포렌식] Rust 단에서 터진 에러(Network Invalid 등)가
        // C++ std::exception 파생 객체로 이쁘장하게 승격되어 날아온다!
        std::cerr << "치명적 장애: " << e.what() << std::endl;
        return 1;
    }
    return 0;
}

당신이 auto session 구문을 짜는 순간, C++ 스파게티 코드에서 발생하는 90% 이상의 메모리 누수 위험이 증발해 버린다. 이것이 zenoh-cpp 헤더 파이프라인의 진가다.

3. 지원 플랫폼(Windows, Linux, macOS) 및 컴파일러 요구사항

당신의 개발 노트북 속의 아키텍처 세팅 무결성이 보장되지 않으면, 컴파일 버튼을 누른 순간 피를 말리는 링커 에러 폭풍(.dll missing, .so not found)을 만나게 된다.

3.0.1 [Runbook] 프로덕션 타겟별 하드코어 컴파일러 세팅

Zenoh C/C++ 레이어가 요구하는 OS별 최소 장비 규격을 콘크리트처럼 타설 하라.

1. Linux 계열 (Ubuntu 20.04+, RHEL 8+)
서버 코어의 근본이다. 절대 옛날 gcc 4.8 찌꺼기를 쓰지 마라.

  • 최소 요구사항: GCC 9.0 이상 또는 Clang 10 이상. (C++17 표준 문법 풀 지원 필수)
  • 필수 툴체인 구축: 
    sudo apt install build-essential cmake pkg-config
# 특히 Rust 링커가 요구하는 C++ 스탠다드 라이브러리 심볼 보장
sudo apt install libstdc++-11-dev


**2. Windows 환경 (자율주행 콘솔용 C++ 앱)**
MSVC 특유의 난해한 매크로 종속성(`__declspec`)을 극복하기 위해 최신판을 강제한다.
- **최소 요구사항:** `Visual Studio 2022` (v143 툴셋)
- **런북:** 최상위 `CMakeLists.txt`에 MSVC의 잔혹한 컴파일 경고를 무시하는 플래그를 심어라.
  ```cmake
  if(MSVC)
      # C4251 (dll 인터페이스 노출 에러) 등 끔찍한 MSVC 예외 문법 강제 침묵
      add_compile_options(/wd4251 /wd4275) 
  endif()

3. macOS (Apple Silicon ARM64의 이빨)
M1/M2 맥북 개발자는 x86_64 브릿지(Rosetta)가 섞여 들어가는 치명상을 조심해야 한다.

  • 최소 요구사항: Xcode Command Line Tools 최신판
  • 런북: CMake가 무조건 Native ARM64 로 빌드 타겟을 잡아당기게 아키텍처를 강제 할당하라. 
    cmake -B build -S . -DCMAKE_OSX_ARCHITECTURES=arm64


**[DevOps 아키텍트의 교훈]**
각기 다른 OS의 C++ 파편화를 해결하기 위해, 웬만한 규모 10인 이상의 C++ 팀에서는 로컬 빌드를 금지시키고 Docker Container 안에 일관된 툴체인(Clang-14 탑재) 버전을 꽂아둔 "통일된 DevContainer 환경"에서 작업하게 만드는 것이 정신병을 예방하는 지름길이다.


## 4.  CMake를 활용한 프로젝트 구성 및 빌드 환경 설정


MakeFile 로 100줄짜리 스크립트를 짜는 삽질은 이제 끝났다. 현대 C++ 빌드 파이프라인의 황제는 **CMake(모던 CMake > 3.10)** 이다.
문제는 "외부 라이브러리인 zenoh-cpp를 어떻게 내 타겟 실행 파일에 깔끔하게 링크(Link)시킬 것인가?"이다. 모던 CMake의 생명인 '타겟 종속성 추이(Transitive Dependencies)'를 활용한 우아한 연동법을 서술한다.

#### 4.0.1 [Runbook] 프로덕션 보일러플레이트 CMakeLists.txt


디렉토리 어딘가에 `libzenohc.so` 가 컴파일 되어 있다는 전제하에, 내 깡통 프로젝트에 이 엔진을 덜컥 붙여버리는 마법의 파일이다.

**프로젝트 Root `/CMakeLists.txt` 완벽 코드**
```cmake
cmake_minimum_required(VERSION 3.16 FATAL_ERROR)
project(RobotFleetControl VERSION 1.0.0 LANGUAGES CXX)

## [가드 레일] C++17 규격을 강제화한다. (zenoh-cpp 필수 조건)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

## 1. 시스템에 설치된 패키지(zenohc, zenoh-cpp)를 긁어오거나, 
## 없다면 vcpkg나 pkg-config 가 찾아줄 때까지 강제 대기(REQUIRED)
find_package(zenohc REQUIRED)
find_package(zenoh-cpp REQUIRED)

## 2. 내 타겟 실행 파일 생성
add_executable(drone_controller src/main.cpp src/navigation.cpp)

## 3. [핵심] 타겟 종속성(Target Dependency) 연결 마법
## 단순히 -lzenohc 플래그를 박는 옛날 방식이 아니라, 
## 'zenoh-cpp' 라는 라이브러리가 들고 있는 include 디렉토리 위치 전파까지 한 방에 해결!
target_link_libraries(drone_controller PRIVATE 
    zenoh-cpp::zenoh-cpp
    pthread
)

## 4. 프로덕션 빌드 속도 튜닝 (O3)
if(CMAKE_BUILD_TYPE STREQUAL "Release")
    target_compile_options(drone_controller PRIVATE -O3 -flto)
endif()

이 target_link_libraries 전술을 사용하면, 리눅스 서버에서 헤더 파일 패스를 빙빙 꼬아가며 -I/usr/local/include 따위를 스크립트에 하드코딩하는 더러운 잔재를 없앨 수 있다.

5. 패키지 관리자(vcpkg, Conan)를 통한 설치 파이프라인 구축

개발 노트북 환경을 새로 세팅할 때 구글을 뒤지며 .tar.gz 파일을 다운받아 /usr/local에 풀고 sudo make install을 치는 행위는 야생의 방식이다.

엔터프라이즈 환경에서는 종속성 엔진인 vcpkg 나 Conan 을 통해, 스위치 한 번에 10만 대의 개발 PC에 동일 버전의 Zenoh 바이너리를 꽂는 완전 자동화 CI/CD 체계를 요구한다.

5.0.1 [Runbook] Vcpkg 초고속 격리가동(Isolation) 전술

여기서는 Microsoft 에서 배포하여 업계 표준이 되어버린 vcpkg를 런북으로 서술한다.

1. Vcpkg 코어 레지스트리 다운로드 및 부트스트랩
프로젝트 폴더 안이나 전역에 vcpkg를 심고 망치질(bootstrap)을 개시.

git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh

2. [치명적 팁] Manifest 모드 (vcpkg.json) 이식
명령어로 vcpkg install을 직접 치는 건 초보자다.
C++ 프로젝트 폴더 최상단에 vcpkg.json 선언문을 던져놔서 버전을 못 박아버리는 것이 DevOps의 제1법칙이다.

// vcpkg.json
{
  "name": "factory-auto-robot",
  "version": "1.0.0",
  "dependencies": [
    { "name": "fmt", "version>=": "10.0.0" },
    { "name": "zenohc", "version": "0.10.1-rc" } // Zenoh C 패키지 (포트가 살아있을 때)
  ]
}

3. CMake 연동 폭격 (Toolchain 마운트)
이제 빌드를 돌릴 때 CMake 뒤 꼬리에 “vcpkg가 매니징하는 툴체인 주소“만 슬며시 끼워 넣어 준다.

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=./vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release

기적이 일어난다. CMake 가 스스로 판단하여 인터넷에서 zenoh-c 코드를 긁어오고, 타겟 아키텍처에 맞게 C 컴파일을 때려버린 뒤 알아서 링킹까지 해결해 낸다. 팀원들이 당신의 레포지토리를 클론(Clone)하고 나서 환경 세팅 때문에 고통받는 시간이 ’0’초로 줄어드는 순간이다.

6. 소스코드 직접 빌드 및 크로스 컴파일 설정

“나는 vcpkg 같은 블랙박스 매니저를 믿지 않는다. 내 리눅스는 임베디드 라즈베리 파이(ARM64)라서 수동으로 극한의 컴파일 옵션을 비틀어야 한다.”
이런 상남자 C++ 개발자들을 위한 최후의 런북이다. Zenoh-C 와 Zenoh-CPP 소스코드를 rustc 와 cmake 조합으로 현장에서 직접 도축(Compile)하여 라이브러리를 추출하는 전술.

6.0.1 [Runbook] Rust 코어부터 C++ 헤더까지 다이렉트 교차 컴파일

1. 빌드 전초기지(Rust) 세팅
Zenoh-C의 본체는 철저하게 Rust 코드다. 따라서 Cargo 엔진과, 타겟 아키텍처 지원 툴체인이 박혀 있어야 한다.

## 타겟 장비가 라즈베리 파이(AArch64) 리눅스라고 가정
rustup target add aarch64-unknown-linux-gnu
sudo apt install gcc-aarch64-linux-gnu cmake

2. Zenoh-C 소스 클론 및 Rust 빌드 폭격

git clone https://github.com/eclipse-zenoh/zenoh-c.git
cd zenoh-c

mkdir build && cd build
## [고급 전술] -DZENOHC_BUILD_WITH_SHARED_MEMORY=ON 을 켜서 제로 카피 코끼리를 소환한다!
cmake .. \
  -DCMAKE_SYSTEM_NAME=Linux \
  -DCMAKE_SYSTEM_PROCESSOR=aarch64 \
  -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
  -DZENOHC_BUILD_WITH_SHARED_MEMORY=ON \
  -DCMAKE_INSTALL_PREFIX=/opt/zenoh-aarch64

## 크로스 컴파일된 바이너리를 /opt/zenoh-aarch64 로 밀어 넣기
make -j$(nproc) install

3. Zenoh-CPP (C++ 래퍼) 헤더 결합
이제 알맹이(.so)는 다 만들었으니, 그 위를 감쌀 C++ 껍데기(Header)를 이식해야 한다.

cd ../..
git clone https://github.com/eclipse-zenoh/zenoh-cpp.git
cd zenoh-cpp

mkdir build && cd build
## C++ 빌더에게 아까 만든 '/opt/zenoh-aarch64' 기지를 바라보라고 명령!
cmake .. \
  -DCMAKE_SYSTEM_NAME=Linux \
  -DCMAKE_SYSTEM_PROCESSOR=aarch64 \
  -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \
  -DCMAKE_PREFIX_PATH=/opt/zenoh-aarch64 \
  -DCMAKE_INSTALL_PREFIX=/opt/zenoh-cpp-aarch64

make -j$(nproc) install

이제 /opt/zenoh-cpp-aarch64 폴더를 통째로 압축해서 흙먼지 날리는 라이다(LiDAR) 센서 코어 옆에 던져 놓기만 하면 된다! 당신은 방금 완벽한 크로스 빌드(Cross-Compilation) 독립 부대를 창설했다.