3.3 Rust에서 Zenoh 개발을 위한 환경 구축

3.3 Rust에서 Zenoh 개발을 위한 환경 구축

Eclipse Zenoh의 심장부(Core Engine)는 Rust(러스트) 언어로 작성되었다. C++에 필적하는 극단적인 실행 속도와 하드웨어 제어 능력을 갖추었으면서도, 컴파일러 차원에서 메모리 안전성(Memory Safety)과 데이터 스레드 경합(Data Race)을 원천 차단하는 Rust의 철학은, “가볍고 빠르면서도 절대 죽지 않아야 하는” 차세대 통신 미들웨어의 이상향과 정확히 일치한다.

따라서 Zenoh를 가장 깊숙한 수준에서 이해하고, 극한의 성능을 쥐어짜 내는 퍼포먼스 크리티컬(Performance-critical) 애플리케이션을 개발하고자 한다면 Rust 기반의 네이티브 API를 다루는 것이 필수적이다.

이 장에서는 어떠한 운영체제(Linux, macOS, Windows)에서든 상관없이 Rust 공식 툴체인을 로컬 장비에 설치하고 설정하여, 완벽하게 통제 가능한 Zenoh 애플리케이션 빌드 파이프라인을 구축하는 튜토리얼을 밟아 나간다. 막연하게 어렵게만 느껴졌던 Rust의 초기 진입 장벽을 영리하게 허물어보자.

1. Rust 공식 툴체인(rustup, cargo) 설치

Rust 개발의 첫 단추는 C/C++ 시대처럼 컴파일러(gcc나 clang)와 빌드 시스템(cmake나 make)을 일일이 찾아다니며 설치하는 것이 아니다. 현대적인 언어답게, 모든 컴파일러 버전과 크로스 컴파일(Cross-compile) 타겟을 한 번에 관리해 주는 영리한 설치 매니저인 rustup 단 하나만 설치하면 모든 준비가 끝난다.

이 rustup을 통해 Rust 컴파일러(rustc)와 만능 패키지 매니저이자 빌드 시스템인 **cargo**가 개발자의 PC에 완전히 장착된다.

1.1 운영체제별 rustup 설치

1) Linux / macOS 호환 설치 (스크립트 방식):
대부분의 유닉스 기반 환경에서는 공식 홈페이지에서 제공하는 쉘 스크립트 한 줄로 설치가 끝난다. 터미널을 열고 다음 명령어를 실행하라.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

설치 도중 1) Proceed with installation (default) 프롬프트가 뜨면, 그대로 Enter 키를 눌러 기본(Default) 프로필로 설치를 강행한다. 설치가 완료되면 현재 쉘 프로파일에 적용하기 위해 환경 변수를 리로드(source $HOME/.cargo/env)하거나, 터미널 세션을 껐다가 다시 켜야 한다.

2) Windows 설치 (rustup-init.exe 방식):
Windows 환경에서는 공식 웹사이트(https://rustup.rs/)에 접속하여 rustup-init.exe 바이너리를 직접 다운로드하고 실행한다. 설치 과정 중에 Microsoft C++ Build Tools가 필요하다는 경고창이 뜨면, 안내에 따라 Visual Studio Build Tools를 사전 설치해야만 정상적인 C++ 링킹(Linking) 작업이 가능하다.

1.2 툴체인 정상 동작 및 버전 검증

터미널이나 명령 프롬프트를 열고, cargo와 rustc 명령어가 글로벌 환경 변수(PATH)에 올바르게 물려 있는지 즉시 테스트하라.

## 컴파일러 버전 확인
rustc --version

## 패키지 매니저 버전 확인
cargo --version

출력 결과로 rustc 1.75.0 ... 식의 버전 정보가 뜬다면 1단계는 완벽하게 성공한 것이다.

1.3 안정화(Stable) 채널 및 크로스 컴파일 타겟 추가

Zenoh 코어 라이브러리는 지속적으로 업데이트되므로, 항상 Rust 커뮤니티의 최신 안정화 컴파일러를 유지하는 것이 좋다. 다음 명령어로 툴체인을 최신 상태로 갱신하라.

rustup update stable

또한, 향후 인텔/AMD 랩탑에서 코딩한 후 ARM 기반의 라즈베리파이나 에지 보드용으로 교차 빌드(Cross-compile)를 지시하고 싶다면, rustup target add 명령을 통해 해당 빌드 타겟 아키텍처를 미리 툴체인에 내려받아 둘 수 있다.

## 64비트 ARM Linux(예: 라즈베리파이 4/5) 타겟을 랩탑에 미리 추가하는 예시
rustup target add aarch64-unknown-linux-gnu

이와 같이 rustup과 cargo 환경이 호스트 OS에 뿌무리를 내렸다면, 당신의 PC는 더 이상 단순한 워드 프로세싱 머신이 아니다. 세상에서 가장 견고하고 빠른 통신 엔진을 직접 주조해 낼 수 있는 현대적인 대장간으로 거듭난 것이다.

2. Zenoh Rust 크레이트(Crate) 의존성 추가 및 버전 관리

Rust 생태계에서는 모든 외부 라이브러리 패키지를 **크레이트(Crate)**라고 부른다. C++에서 라이브러리의 헤더 파일 경로와 링킹 옵션을 CMakeLists.txt에 장황하게 적어내려갔던 악몽에서 벗어나, Rust에서는 오직 Cargo.toml 파일 하나에 명시된 선언적 텍스트만으로 모든 의존성 스파게티 트리(Dependency Tree)를 완전히 제어한다.

이 절에서는 비어 있는 새 Rust 프로젝트를 생성하고, 중앙 저장소인 crates.io로부터 Eclipse Zenoh 핵심 크레이트를 끌어오는 절차를 확립한다.

2.1 신규 Cargo 프로젝트(바이너리) 생성

작업 디렉터리에서 cargo new 명령어를 사용하여 새로운 CLI 애플리케이션의 뼈대(Scaffolding)를 세운다.

## 'zenoh_hello' 라는 이름의 새로운 Rust 실행형 패키지 생성
cargo new zenoh_hello
cd zenoh_hello

이 명령어가 실행되면 Cargo.toml 매니페스트 파일과 로직이 들어갈 src/main.rs 구조가 자동으로 튀어나온다.

2.2 zenoh 라이브러리 의존성(Dependency) 선언

Cargo.toml 파일을 코드 에디터로 열어서 [dependencies] 색션 하단에 우리가 사용할 zenoh 코어 API 크레이트 버전을 명시해야 한다. 수동으로 타이핑할 수도 있지만, cargo add 명령어를 이용하면 가장 최신의 안정화 버전을 자동으로 스캔하여 매니페스트를 갱신해 준다.

## 최신 zenoh 라이브러리를 의존성에 자동 추가
cargo add zenoh

명령어 실행 후 Cargo.toml을 열어보면 대략 다음과 같이 수정되어 있을 것이다.

[package]
name = "zenoh_hello"
version = "0.1.0"
edition = "2021"

[dependencies]
zenoh = "1.0.0"  # 버전은 튜토리얼 시점에 따라 상이할 수 있음

2.3 기능 토글(Feature Flags)을 이용한 선택적 컴파일

모듈성과 경량화를 극도로 추구하는 Zenoh 팀은 단일 zenoh 크레이트 안에서도 컴파일할 기능들을 세부적으로 끄고 켤 수 있도록 피처 플래그(Feature Flags) 아키텍처를 도입했다.

기본적으로 cargo add zenoh를 실행하면 필수 라우팅 코어와 기본 네트워크 트랜스포트(TCP, UDP)만 컴파일되어 최종 바이너리 용량을 작게 유지한다. 하지만 만약 당신의 애플리케이션이 불안정한 무선 환경을 위한 특수 통신인 QUIC 프로토콜을 사용해야 하거나, 개발 중 복잡한 라우팅 상태를 디버깅하기 위해 라우터 통합(Router-integration) 기능이 필요하다면 다음과 같이 의존성을 수동 조정해야 한다.

Cargo.toml의 의존성 영역을 다음과 같이 재작성하라.

[dependencies]
## 기본 통신 외에 QUIC과 WebSocket 트랜스포트 계층 컴파일을 강제 활성화하는 예시
zenoh = { version = "1.0.0", features = ["transport_quic", "transport_ws"] }

2.4 첫 빌드를 통한 의존성 트리 컴파일

코드 한 줄 작성하지 않았지만, 이제 의존성이 걸려 있는 Zenoh 엔진의 무거운 코퍼스를 호스트 PC로 내려받아 링킹할 준비가 되었다. 의존성이 잘 맞물렸는지 검증하기 위해 초기 빌드를 시도하라.

cargo build

이 명령줄을 치는 순간, cargo는 crates.io를 뒤져 Zenoh가 의존하는 수십 개의 비동기 네트워크 라이브러리와 암호화 모듈을 일제히 병렬 다운로드하고 컴파일하기 시작한다. 첫 빌드는 상당한 시간이 걸리지만, 한 번 컴파일된 크레이트들은 로컬에 강력하게 캐싱되어 이후 변경된 소스코드만 찰나의 속도로 컴파일된다.

이 빌드가 에러 없이 끝났다면 당신의 프로젝트는 Zenoh의 거대한 네트워크를 호흡할 완벽한 허파를 이식받은 것이다.

3. 비동기 프로그래밍(Tokio)과의 호환성 설정

고성능 네트워크 미들웨어인 Zenoh의 내부 심장부는 수백, 수천 개의 라우팅 채널과 I/O 스트림을 단일 프로세스 자원을 쥐어짜 내며 동시다발적으로 처리하기 위해 비동기(Asynchronous) 아키텍처로 철저하게 설계되어 있다.

이 거대한 비동기 생태계의 톱니바퀴를 돌리기 위해 분산 시스템 Rust 개발자들의 사실상 표준(De facto standard) 런타임인 Tokio(토키오) 백엔드를 필연적으로 연동해야 한다.

3.1 Tokio 의존성 추가

앞 절에서 생성했던 zenoh_hello 프로젝트의 Cargo.toml 매니페스트를 다시 열어 tokio 크레이트를 주입한다. 네트워크 I/O, 타이머, 멀티스레딩 스케줄러 등 모든 풀 패키지 기능을 활용하기 위해 full 피처 빌드 옵션을 켜두는 것이 일반적이다.

cargo add tokio --features full

의존성 추가 후 Cargo.toml 리스트는 다음과 같이 구성된다.

[dependencies]
zenoh = "1.0.0"
tokio = { version = "1.30.0", features = ["full"] }

3.2 Tokio 비동기 런타임 메인 매크로 구성

Rust의 전통적인 진입점인 fn main() 함수는 태생적으로 동기식(Synchronous) 실행 컨텍스트에 묶여 있기 때문에, 그 안에서 async로 선언된 Zenoh API(예: 라우터 세션 열기, 메시지 구독 등)를 단 한 줄도 직접 호출(await)할 수 없는 치명적인 제약이 있다.

이 문제를 우회하고 Zenoh의 비동기 능력을 봉인 해제하기 위해, C언어의 main 함수 껍데기를 Tokio 런타임이 지배하는 거대한 비동기 스레드 풀(Thread pool)로 뒤바꾸는 #[tokio::main] 매크로를 반드시 씌워주어야 한다.

src/main.rs 파일의 구조를 다음과 같이 개조하라.

use zenoh::prelude::r#async::*; // Zenoh 비동기 코어 트레이트(Trait) 일괄 임포트

#[tokio::main]
async fn main() {
    println!("Tokio 비동기 런타임이 정상 기동되었습니다.");

    // Zenoh 세션을 여는 I/O 바운드 작업은 반드시 .await 키워드를 통해
    // 현 스레드의 블로킹 없이 스케줄러에게 제어권을 양보하며 실행되어야 한다.
    let session = zenoh::open(zenoh::config::peer()).await.unwrap();
    
    println!("Zenoh 피어(Peer) 세션 연결 성공!");
    
    // 이후 비동기 Pub/Sub 로직이 전개됨
}

3.3 스레드 블로킹(Thread Blocking) 주의사항

Tokio 기반의 Zenoh 프로그래밍에서 초보자가 며칠 밤을 새우게 만드는 가장 잦은 버그 패턴은 “블로킹 연산의 오남용“이다.

위 코드의 main 함수 내부나, Zenoh 메시지를 수신하는 콜백(Callback) 스트림 블록 안에서 std::thread::sleep 같은 무거운 동기식 휴식 핑을 때리거나 대용량 파일의 동기식 디스크 I/O를 발생시키면, Tokio 런타임의 작업자(Worker) 스레드가 산소 결핍에 빠져 **전체 Zenoh 네트워크의 메시지 라우팅이 원인 불명으로 셧다운(Starvation)**되는 치명타를 입는다.

따라서 Zenoh 로직 내에서는 오직 tokio::time::sleep과 같은 비동기 전용 대기 함수만을 엄격하게 사용해야 하며, 부득이하게 블로킹이 발생하는 레거시 코드를 호출해야 할 때는 tokio::task::spawn_blocking으로 격리된 스레드에서 서브루틴을 돌려야 함을 절대 명심하라.

4. IDE 환경(rust-analyzer) 및 디버깅 도구 연동 설정

Rust는 강력한 타입 시스템과 수명이 명시된 엄격한 스코프(Lifecycle) 룰을 가지는 언어이다. Zenoh처럼 수많은 추상화 팩토리(Factory) 패턴과 비동기 제네릭스(Generics)가 혼재된 거대한 라이브러리를 바닐라 텍스트 에디터만으로 코딩하려 드는 것은 눈을 감고 미로를 걷는 것과 같다.

코드 자동 완성, 실시간 타입 추론, 매크로 전개, 인라인 에러 캐칭을 완벽히 지원하는 현대적인 IDE 세팅은 Rust-Zenoh 개발 생산성(Productivity)의 8할을 차지한다. 그 정점에 있는 통합 언어 서버 프로토콜(LSP)인 rust-analyzer의 구축 방법을 알아본다.

4.1 Visual Studio Code 기반 rust-analyzer 설치

현존하는 가장 대중적이고 확실한 Rust 개발 에디터는 VS Code이다.

  1. VS Code 익스텐션(Extensions) 마켓플레이스 탭 창을 연다.
  2. rust-analyzer (주의: 공식 Rust 익스텐션이 아닌 rust-analyzer를 선택해야 함)를 검색하여 설치한다.
  3. 앞서 구성했던 zenoh_hello 디렉터리를 VS Code로 연다.
  4. 하단 상태 표시줄에 톱니바퀴가 돌며 백그라운드에서 프로젝트 전체 의존성 메타데이터와 매크로 트리를 인덱싱하는 작업이 수 분간 진행된다.

이 작업이 끝나면 Zenoh API 내부 소스코드를 마음대로 Ctrl + Click (또는 Cmd + Click)하여 추적해 들어갈 수 있고, .await를 빼먹거나 잘못된 타입의 데이터를 Publish 하려 할 때 컴파일러를 돌려보기도 전에 에디터가 붉은 밑줄을 그어 선제 방어를 해낼 것이다.

4.2 코드 디버깅 및 브레이크포인트(Breakpoint) 세팅

Zenoh의 복잡한 비동기 페이로드 라우팅 로직을 추적하려면 CLI 출력만으로는 한계가 명확하다. 변수의 현재 메모리 상태를 들여다볼 수 있는 LLDB/GDB 디버깅 환경을 연동하라.

  1. VS Code 마켓플레이스에서 CodeLLDB 익스텐션을 추가 설치한다.
  2. 에디터 좌측의 Run and Debug 메뉴 창으로 이동하여 create a launch.json file 링크를 클릭한다.
  3. 제안되는 템플릿 중 LLDB 타겟을 선택하여 자동으로 .vscode/launch.json 초기화 파일을 생성한다.
  4. 이제 main.rs 소스코드 에디터 좌측의 여백 번호줄을 클릭하여 붉은색의 브레이크포인트(중단점) 표시기를 찍어둔 후 F5 디버깅 실행 키를 누른다.

프로그램의 제어권이 중단점에서 완전히 멈추게 되며, 좌측 디버깅 패널을 통해 Zenoh 세션 객체가 물고 있는 내부 트랜스포트 계층 버퍼 크기와 메모리 번지수까지 투명하게 파고들어 진단할 수 있는 초정밀 수술대가 완성되었다.

4.3 강력한 코드 린팅(Linting) 도구: Clippy의 습관화

rust-analyzer가 실시간 가이드라면, Clippy는 코드의 구조적 안티 패턴(Anti-pattern)을 잡아내는 깐깐한 수석 엔지니어다. 터미널에서 컴파일 명령 대신 린트 검증 명령을 수시로 날려주는 습관이 중요하다.

## 코드 컨벤션 최적화 및 구조적 결함 정밀 진단
cargo clippy -- -D warnings

특히 Zenoh에서 자주 실수하는 비효율적인 메모리 복사(Clone의 남발)나, 불필요한 비동기 포장 캐스팅 등을 Clippy가 세심하게 지적하고 수정 방안까지 제시(Suggest)해 주므로, 이를 통과하지 못한 코드는 절대로 프로덕션 장비에 릴리스해서는 안 되는 엄격한 사내 규칙을 세우길 권장한다.