# 윈도우 및 macOS 환경에서의 설치 개요

#### 윈도우 개발 환경 개요

윈도우 환경에서 ROS 2 Humble을 사용하기 위해서는 먼저 다음 사항들을 검토해야 한다.

**운영체제 버전**: 일반적으로 Windows 10(빌드 19044 이상) 또는 Windows 11을 권장한다. 기업·연구 환경에서 Windows Server를 사용해야 하는 경우, 해당 버전에 대한 호환 여부를 미리 확인하자.

**필수 패키지 및 도구**: ROS 2를 설치하거나 소스에서 빌드하기 위해서는 다음과 같은 주요 툴이 필요하다.

* **Visual Studio**: 2019 이상의 버전을 권장하며, C++ 14 이상이 지원되는 툴체인(예: MSVC v142 이상)이 포함되어 있어야 한다.
* **CMake**: 프로젝트 빌드 관리 툴이며, ROS 2 빌드 시스템에서 기본적으로 사용한다.
* **Python 3**: ROS 2의 여러 스크립트 및 툴이 파이썬으로 작성되어 있으므로 필수다.

**패키지 관리자(선택 사항)**: 윈도우에서도 패키지 관리자를 적극 활용하는 편이 설치를 간소화한다.

* **Chocolatey**: 다음과 같은 명령으로 설치한다.

```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
```

* **winget**: 윈도우 11 최신 버전이나 최신 Windows 10에 포함되어 있는 경우가 많다. 윈도우 스토어를 통해 직접 설치 가능하다.

**설치 방식 결정**: 윈도우에서는 다음 두 가지 방식으로 ROS 2 Humble을 준비할 수 있다.

* **바이너리 설치**: 미리 빌드된 바이너리를 설치하는 방식으로, 빠르게 환경을 구성할 수 있다.
* **소스 빌드**: 소스를 직접 다운로드하고 CMake와 Visual Studio를 사용해 빌드한다. 원하는 설정을 조정하거나 직접 패치를 적용해야 하는 경우에 유용하다.

**환경 변수 설정**: ROS 2를 설치한 후에는 `PATH`나 `AMENT_PREFIX_PATH` 등의 환경 변수를 수정해야 한다. 예컨대 설치 후 다음과 같은 명령을 통해 환경 변수를 로드할 수 있다.

```powershell
call C:\dev\ros2_humble\local_setup.bat
```

여기서 `C:\dev\ros2_humble`은 ROS 2를 설치한 폴더 예시다.

> **참고** 윈도우에서 소스 빌드 시 Visual Studio 개발자 명령 프롬프트(Developer Command Prompt)나 PowerShell 환경을 사용해야 한다. 빌드 시 `$CMAKE_PREFIX_PATH$`에 ROS 2 의존성 라이브러리 경로가 올바르게 포함되어 있는지 확인하자.

{% @mermaid/diagram content="flowchart LR
A\["윈도우\n설치 준비"] --> B\["Chocolatey\n또는 winget 설치"]
B --> C\["Visual Studio,\nCMake,\nPython 3 설치"]
C --> D\["환경 변수 설정"]
D --> E\["바이너리\n또는 소스 빌드"]" %}

#### macOS 개발 환경 개요

**운영체제 버전**: macOS 10.15(Catalina) 이상의 환경에서 ROS 2 Humble 설치가 일반적으로 가능하다. 공식적으로는 Big Sur(11), Monterey(12) 등도 적극 지원된다.

**개발 툴체인**: Xcode Command Line Tools: C++ 컴파일러를 포함하며, 다음과 같은 명령을 통해 설치할 수 있다.

```bash
xcode-select --install
```

Homebrew: macOS에서 패키지 관리를 단순화하는 툴이다. 기존에 설치되어 있지 않다면 다음 명령으로 설치할 수 있다.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

**Python 3**: Homebrew를 통해 간단히 설치하거나, macOS에 기본 탑재된 파이썬 버전이 3.x 이상인지 확인하여 사용할 수도 있다.

**설치 방식 결정**

* **바이너리 설치**: 공식적으로 macOS용 ROS 2 Humble 바이너리가 제공되지만, 리눅스·윈도우만큼 성숙하지는 않다.
* 소스 빌드: Homebrew로 CMake, OpenSSL 등 의존성을 준비하고, 소스를 빌드한다.

  다음은 Homebrew로 핵심 의존성을 설치하는 예시다.

```bash
brew install cmake openssl
```

**환경 변수 설정**: 설치를 마친 후에는 `$PATH$`나 ROS 2 관련 환경 변수를 적절히 설정해야 한다.

```bash
source /opt/ros/humble/setup.bash
```

예시로 `/opt/ros/humble` 경로를 기준으로 스크립트를 실행한다고 가정했다. 만약 다른 폴더에 설치했다면 해당 경로를 반영해 명령어를 실행하면 된다.

{% @mermaid/diagram content="flowchart TD
A\["macOS 설치 준비"] --> B\["Homebrew 설치"]
B --> C\["Xcode Command Line Tools 설치"]
C --> D\["Python 3, CMake, OpenSSL 등 설치"]
D --> E\["환경 변수 설정"]
E --> F\["바이너리 또는 소스 빌드"]" %}

#### 윈도우 설치 시 고려 사항

윈도우 환경에서 ROS 2 Humble을 설치하거나 빌드할 때 다음과 같은 세부 사항을 주의 깊게 살펴봐야 한다.

**우분투 on WSL과의 비교**: ROS 2가 리눅스 우분투 환경에서 가장 활발히 개발되고 있기 때문에, 윈도우 환경에서 빌드 또는 실행 시 상대적으로 제한 사항이 존재한다. 이를 보완하기 위해 Windows Subsystem for Linux(WSL) 환경을 고려하는 경우도 있다. 다만 전혀 다른 커널 레벨에서 동작하므로, GUI 툴 사용이나 일부 하드웨어 관련 기능(예: USB 카메라, 시리얼 장치 등)을 활용하기 어려울 수 있다.

**Visual Studio 버전 호환성**:

* ROS 2 Humble은 C++ 14 이상이 필요하고, MSVC 2019 이상의 컴파일러를 권장한다.
* 만약 구버전인 MSVC 2017 환경에서 빌드 시도가 필요하다면, 소스 패치 적용이나 추가 설정이 필요할 수 있다.
* Visual Studio Community 버전을 활용해도 무방하나, 엔터프라이즈 환경에서 사용 시 라이선스 조항을 확인해야 한다.

**빌드 옵션 설정**: 소스 빌드 시 CMake 설정 옵션을 유연하게 제어할 수 있다. 예를 들어, ROS 2의 다양한 패키지를 모두 빌드하지 않고 필요한 패키지만 선택적으로 빌드하려면 다음과 같은 CMake 옵션을 활용한다.

```powershell
colcon build --merge-install --packages-select rclcpp sensor_msgs
```

위 예시는 `rclcpp`, `sensor_msgs` 패키지만 빌드하는 명령이다.

**Python 가상 환경 활용**: Python 3가 여러 버전으로 혼재되어 있거나, 다른 프로젝트에서 파이썬 패키지 충돌이 발생할 수 있다면 가상 환경(venv)을 고려한다. 예:

```powershell
python -m venv ros2_venv
.\ros2_venv\Scripts\activate
```

이후 필요한 파이썬 의존성을 설치하면 윈도우 시스템 전역 환경에 영향을 주지 않고 ROS 2 프로젝트를 진행할 수 있다.

**빌드 캐시 및 병렬 빌드**:

* 윈도우 환경에서 빌드는 상대적으로 시간이 오래 걸릴 수 있다.
* `$ninja$` 또는 Visual Studio의 병렬 옵션을 활성화하여 빌드를 가속할 수 있다. 예를 들어 `colcon build` 시 `--parallel-workers` 옵션을 조정하는 것이 한 방법이다.

```powershell
colcon build --merge-install --parallel-workers 8
```

**디버깅 환경**:

* 빌드 후 Visual Studio에서 디버그 구성을 사용할 수 있다.
* `ros2 run` 명령어 대신 프로젝트 솔루션을 직접 열고, 특정 노드나 라이브러리에 브레이크포인트를 설정한 뒤 디버거를 실행할 수 있다.

#### macOS 설치 시 고려 사항

**Gatekeeper와 보안 설정**: macOS는 앱을 설치하거나 실행할 때 Gatekeeper가 강력한 검증을 수행한다. Homebrew 등을 통해 설치한 소프트웨어가 정상적으로 동작하려면,

* `System Preferences` > `Security & Privacy` > `General`에서 ‘허용’ 설정을 확인하거나,
* 명령줄에서 신뢰성 검증을 해제해야 할 수도 있다. 다만 보안에 주의를 기울일 필요가 있다.

**OpenSSL 경로 문제**: macOS에서 OpenSSL을 Homebrew로 설치하면, `$usr/local/opt/openssl@3$`(또는 `$opt/homebrew/opt/openssl@3$`) 등에 설치된다. CMake 빌드 시 해당 경로가 자동으로 인식되지 않을 경우, 다음과 같이 경로를 지정해야 할 수 있다.

```bash
export OPENSSL_ROOT_DIR="/usr/local/opt/openssl@3"
export OPENSSL_LIBRARIES="/usr/local/opt/openssl@3/lib"
```

혹은

```bash
export OPENSSL_ROOT_DIR="/opt/homebrew/opt/openssl@3"
export OPENSSL_LIBRARIES="/opt/homebrew/opt/openssl@3/lib"
```

위 두 경로 중 실제 설치된 위치를 확인하여 사용한다.

**CMake 정책**: macOS에서 최신 CMake(예: 3.20 이상)를 사용하는 경우, 일부 정책(Warnings, RPATH 등)이 이전 버전과 다르게 동작할 수 있다. `$CMAKE_MACOSX_RPATH$` 설정이나 `$CMAKE_OSX_DEPLOYMENT_TARGET$` 설정이 프로젝트 빌드 성공 여부에 영향을 줄 수 있으므로, 유의해서 설정한다.

**Rosdep 활용**: macOS에서도 rosdep을 사용해 일부 의존 패키지를 자동으로 설치할 수 있으나, Homebrew tap 정보를 명시적으로 업데이트해야 하는 경우가 있다.

```bash
sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src -y
```

사용 도중 Homebrew가 정상적으로 소스나 패키지를 찾지 못한다면, `brew tap ros/homebrew-ros`와 같은 tap을 수동으로 등록해야 할 수도 있다.

#### 설치 검증

ROS 2 Humble을 정상적으로 설치했다면, 간단한 토픽(pub/sub) 예제를 통해 동작을 확인할 수 있다. 예를 들어 다음 명령으로 `talker` 노드를 실행하고,

```bash
ros2 run demo_nodes_cpp talker
```

다른 터미널에서 `listener` 노드를 실행한다.

```bash
ros2 run demo_nodes_cpp listener
```

두 노드가 서로 메시지를 주고받으며 동작한다면, ROS 2 핵심 통신이 정상적으로 작동한다고 볼 수 있다.

#### 시스템 아키텍처와 호환성

윈도우 및 macOS 환경 모두에서 주의해야 할 사항은 시스템 아키텍처와 호환성 이슈다.

1. **64비트 아키텍처** ROS 2 Humble은 기본적으로 64비트(x86\_64) 환경을 전제로 한다.
   * 최신 애플 실리콘(M1, M2) 칩이 탑재된 macOS의 경우, Rosetta 2를 통해 x86\_64 바이너리를 구동하거나, 네이티브 arm64 빌드가 가능한 지점들을 확인해야 한다.
   * 윈도우 역시 64비트 버전이어야 하며, ARM64 윈도우 환경(예: Surface Pro X)에서는 ROS 2 지원이 제한적이다.
2. **의존 패키지의 호환성** ROS 2 내의 핵심 소프트웨어 패키지(예: rclcpp, rmw, DDS 등)가 클라이언트 라이브러리와 호환되는지 검토해야 한다.
   * macOS에서 Homebrew를 이용해 설치한 패키지들이 arm64/Intel x86\_64 모두를 지원하는지 체크해야 한다.
   * 윈도우 환경에서 바이너리 설치본을 사용할 때도, 공식적으로 제공되는 설치본이 64비트만 지원함을 유의한다.
3. **네트워크 스택 차이** 윈도우와 macOS의 소켓 및 방화벽 정책이 리눅스와 다를 수 있다.
   * 윈도우에서는 방화벽을 통해 특정 포트를 차단하거나, 네트워크 디스커버리를 제한하는 경우 ROS 2의 DDS 통신이 정상적으로 동작하지 않을 수 있다.
   * macOS에서도 시스템 환경설정 > 보안 및 개인정보 보호(Security & Privacy) > 방화벽 설정을 확인하여, ROS 2 관련 프로세스가 포트 접근을 할 수 있도록 허용해야 한다.
4. **실시간(Real-time) 기능 제약** ROS 2는 실시간성을 고려하기 위해 다양한 QoS(서비스 품질) 기능을 갖추고 있지만, 윈도우와 macOS의 기본 커널 구조상 리눅스에서의 RT(Real-Time) 패치만큼의 특성을 얻기 어렵다.
   * 윈도우는 Windows RT, macOS는 별도의 실시간 커널이 존재하지 않는다.
   * 하드 실시간 요건이 있는 경우, 별도의 RTOS 또는 리눅스 RT 커널 기반 환경을 검토해야 한다.

#### 추가 툴과 통합

ROS 2는 DevOps, CI/CD, 시뮬레이션, 그리고 다양한 툴과의 결합을 전제로 광범위하게 사용된다. 윈도우와 macOS 환경에서도 이러한 툴들을 함께 활용할 수 있다.

1. **CI/CD 파이프라인**
   * **GitHub Actions**: macOS 호스트를 제공하므로, ROS 2 Humble 소스 코드의 macOS 빌드·테스트를 자동화할 수 있다. 윈도우 호스트도 제공하며, YAML 설정을 통해 Windows 환경용 빌드·테스트를 수행한다.
   * **Azure DevOps**: 마이크로소프트가 운영하는 CI/CD 플랫폼으로, 윈도우 빌드 환경에 대한 호환성이 높다.
2. **시뮬레이션 툴**
   * **Gazebo**(Ignition 포함): macOS와 윈도우에서도 Gazebo를 빌드해서 동작시킬 수 있지만, 리눅스 우분투 환경에 비해 추가 의존성 충돌이 발생할 가능성이 있다.
   * **Unity 혹은 Unreal Engine**: 윈도우, macOS 모두에서 실행 가능하며, ROS 2와 연결하기 위한 플러그인(ROS/ROS 2 Integration)이 존재한다.
3. **IDE 통합**
   * **Visual Studio Code(VSCode)**: 윈도우와 macOS에서 공통으로 사용이 가능하며, C++ 확장과 Python 확장을 통해 ROS 2 프로젝트를 편리하게 관리할 수 있다.
   * **CLion**: macOS와 윈도우에서 모두 동작하며, CMake 프로젝트를 보다 깊이 있게 다룰 수 있는 장점이 있다.

#### 업스트림 패치와 소스 트리 이해

**ros2.repos**: ROS 2 Humble의 소스 트리를 내려받기 위해서는 `ros2.repos` 파일이 사용된다. 이는 Git 저장소 목록을 담고 있으며, `$vcs$`(Version Control System) 툴을 통해 일괄 다운로드할 수 있다.

```bash
mkdir -p ~/ros2_humble/src
cd ~/ros2_humble
wget https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
vcs import src < ros2.repos
```

윈도우에서도 PowerShell에서 동일하게 실행 가능하지만, `wget` 대신 `curl`을 사용할 수 있다.

**ROS 2 패치 적용**: 만약 특정 패키지에 대한 수정 사항이나 커뮤니티 패치가 필요한 경우, Git branch를 변경하거나 직접 패치를 적용한 후 로컬 빌드를 실행해야 한다.

* 윈도우는 Visual Studio 솔루션 파일이 생성된 후, IDE에서 소스 코드를 수정할 수도 있다.
* macOS는 터미널에서 CMake 기반 빌드 스크립트를 반복 실행하거나, CLion 등을 통해 진행할 수 있다.

**빌드 트리 구조**: colcon을 사용해 빌드할 경우, 일반적으로 아래와 유사한 디렉터리 구조가 형성된다.

```
ros2_humble/
├── build/
├── install/
├── log/
├── src/
└── ...
```

* `build/` 폴더: CMake를 통한 중간 빌드 산출물(obj, dll, etc.)이 저장된다.
* `install/` 폴더: 최종 빌드 산출물(실행 파일, 라이브러리, ROS 패키지 설정 파일 등)이 위치한다.
* `log/` 폴더: 빌드 및 실행 로그가 저장된다.

#### 빌드 시 자주 발생하는 오류와 해결 방법

**환경 변수 누락 혹은 충돌**:

* **증상**: `colcon build` 시 특정 라이브러리를 찾지 못하거나, `$PATH$`에 등록된 Python 버전이 달라서 모듈 로딩에 실패한다.
* **대처**: 새로운 터미널을 열어 올바른 `setup.bat`(윈도우) 혹은 `setup.bash`(macOS)를 실행했는지 확인한다. 파이썬 가상환경(venv) 활성화 여부도 점검한다.

**권한 문제**:

* **윈도우**: 시스템 경로(C:\Program Files, C:\Windows 등)에 ROS 2를 설치하면, 관리자 권한이 필요할 수 있다.
* **macOS**: `/opt`처럼 루트 디렉터리 아래에 설치 시 `sudo` 권한이 필요할 수 있고, 보안 정책에 의해 Gatekeeper 예외 설정이 필요할 수 있다.
* **대처**: 일반 사용자 계정에도 쓸 수 있는 디렉터리에 설치하거나, 필요 시 명령에 `sudo`를 추가한다(단, 과도한 `sudo` 사용은 권장되지 않는다).

**CMake 빌드 에러**:

* **증상**: `Could NOT find <PackageName>` 형태의 에러 메시지.
* **대처**: Homebrew(맥)나 Chocolatey/winget(윈도우)로 해당 라이브러리를 설치했는지 확인한다. CMake 변수(예: `$OPENSSL_ROOT_DIR$`, `$BOOST_ROOT$`)가 정확히 설정되어 있는지 점검한다.

**Visual Studio 솔루션 에러** (윈도우):

* **증상**: Visual Studio에서 프로젝트를 열었을 때 프로젝트 파일이 손상되었거나 일부 프로젝트를 로드하지 못함.
* **대처**: `colcon clean` 후 다시 빌드하거나, 솔루션을 삭제하고 `colcon build`로 새로 생성해 본다.
* **추가 팁**: 만약 병렬 빌드 도중 에러가 발생하면, 빌드 스레드 수(`--parallel-workers`)를 줄여서 다시 시도해본다.

**Python 모듈 충돌**:

* **증상**: `pip install`로 설치한 파이썬 모듈 버전이 ROS 2가 기대하는 버전과 달라서 생기는 문제.
* **대처**: 가상 환경(venv) 안에서 `$pip freeze | grep <ModuleName>$` 명령으로 설치 버전을 확인 후, 요구 버전으로 재설치한다.
* **추가 팁**: ROS 2 패키지가 내부적으로 특정 파이썬 라이브러리에 의존하는 경우(예: `numpy`, `empy`, `argcomplete` 등)가 있으므로, 충돌이 잦다면 해당 의존성들을 따로 관리하는 것을 권장한다.

#### 디버깅 및 로깅 설정

**ROS 2 로깅 레벨**:

```
$RCL_LOG_LEVEL$
```

환경 변수를 통해 로그 레벨을 조정할 수 있다. 예컨대, 아래 예시는 ROS 2 로그 레벨을 Debug로 설정한다.

```powershell
$env:RCL_LOG_LEVEL="DEBUG"
```

```bash
export RCL_LOG_LEVEL="DEBUG"
```

또는 노드를 실행할 때 `--ros-args --log-level DEBUG` 형태로 지정 가능하다.

1. **콜콘(colcon) 빌드 로그**
   * 빌드 시 표준 출력에는 요약된 정보만 노출될 수 있다. 에러가 발생하면 `build/` 디렉터리에 있는 세부 빌드 로그 파일을 확인한다.
   * 예: `build/<package_name>/CMakeFiles/CMakeOutput.log` 또는 `build/<package_name>/CMakeFiles/CMakeError.log` 등을 점검한다.
2. **Visual Studio 디버거** (윈도우)
   * **단계**: Visual Studio에서 `File > Open > Project/Solution`을 선택해 `build/` 폴더 아래 생성된 `.sln` 파일을 연다.
   * **브레이크포인트 설정**: ROS 2 노드의 main 함수 또는 주요 콜백 함수에 브레이크포인트를 걸고, 디버그 모드로 실행한다.
   * **ROS 2 실행 인자**: 필요하다면 프로젝트 속성에서 실행 인자를 지정하거나, `ros2 run`이 수행하는 인자를 동일하게 설정한다.
3. **LLDB 디버거** (macOS)
   * **단계**: CLion 또는 Xcode에서 CMake 프로젝트를 열고, 빌드 구성(Debug)으로 설정한다.
   * **브레이크포인트 설정**: ROS 2 코어 라이브러리(rcl, rclcpp 등)에 대한 디버깅이 필요한 경우, 해당 심볼(소스 코드 위치)이 정확히 로드되었는지 확인한다.
   * **실행 시 환경 변수 설정**: `$PATH$`, `$DYLD_LIBRARY_PATH$` 등을 세팅해줌으로써 런타임 시에 ROS 2 라이브러리를 정상적으로 참조하게 한다.

#### 그래픽 툴·GUI 관련 사항

1. **RViz 2**
   * **윈도우**: 바이너리 설치본 사용 시 RViz 2가 함께 설치될 수 있다. 다만 GPU 드라이버에 따라 시각화가 정상 동작하지 않는 경우, OpenGL 버전이나 그래픽 드라이버를 업데이트한다.
   * **macOS**: OpenGL 지원이 제한되는 경우가 있어, 특정 플러그인이 비정상 동작할 수 있다. RViz 2 실행 시 콘솔에 경고가 뜬다면 해당 플러그인을 비활성화해본다.
2. **rqt**
   * `rqt_graph`, `rqt_topic`, `rqt_plot` 등은 Qt 기반이므로, macOS나 윈도우에서도 Qt 라이브러리를 올바르게 참조해야 한다.
   * **Homebrew**: `qt@5` 등 별도의 Qt 버전을 설치해야 하는 경우가 있다.
   * **윈도우**: Qt 설치 경로가 `$PATH$`에 올바르게 잡혀 있지 않으면 rqt 실행 시 DLL 로딩에 실패할 수 있다.
3. **시각화 보조 툴**
   * **PlotJuggler** 등은 추가로 빌드가 필요할 수 있으므로, 의존성을 확인하고 설치한다.
   * **foxglove studio**(웹 기반 시각화) 같은 경우, OS와 무관하게 동작하지만, 토픽 브리징(node)이 필요하므로 별도의 세팅이 필요할 수 있다.