---
title: "WIZnet-PICO-C Docker Build System"
url: "https://maker.wiznet.io/josephsr/projects/wiznet-pico-c-docker-build-system/"
markdown_url: "https://maker.wiznet.io/josephsr/projects/wiznet-pico-c-docker-build-system/md"
type: "WCC: WIZnet Created Content"
author: "josephsr"
author_url: "https://maker.wiznet.io/josephsr/"
published: "2026-02-10"
language: "en"
likes: 1
views: 835
comments: 0
source: "WIZnet Makers (https://maker.wiznet.io/)"
---

# WIZnet-PICO-C Docker Build System

> A cross-platform, Docker-based build system for WIZnet Ethernet boards with RP2040/RP2350.

## Documents and links

- [wiznet_pico_c_dockerbuild](https://github.com/simryang/wiznet_pico_c_dockerbuild) (code)

## Article

## WIZnet-PICO-C Docker 빌드 시스템

RP2040/RP2350 기반 WIZnet 이더넷 보드를 위한 크로스 플랫폼 Docker 빌드 시스템

---

## 목차

1. 개요

2. 주요 특징

3. 시작하기

4. 사용법 - Interactive 모드

5. 사용법 - 명령줄 모드

6. 성능 최적화

7. 고급 기능

8. 성능 분석

9. 문제 해결

10. 향후 계획

---

## 개요

### 문제점

WIZnet 이더넷 보드용 펌웨어를 빌드하려면 전통적으로:

- Pico SDK 및 의존성 설치 필요

- 툴체인 설정 (arm-none-eabi-gcc)

- 여러 라이브러리 버전 관리

- 플랫폼별 빌드 스크립트 작성

이는 초보자에게 진입 장벽이 되고, 환경 설정에 시간을 낭비하게 합니다.

### 해결책

**WIZnet-PICO-C Docker 빌드 시스템**은 다음을 제공합니다:

- **한 번의 명령으로 빌드**: 수동 설정 불필요

- **크로스 플랫폼**: Windows, Linux, macOS 지원

- **격리된 환경**: Docker 컨테이너로 충돌 방지

- **성능 최적화**: tmpfs + ccache로 빠른 빌드

### 지원 하드웨어

**10종 보드:**

- WIZnet Ethernet HAT (W5100S)

- W5100S-EVB-Pico

- W5500-EVB-Pico ← 권장

- W55RP20-EVB-Pico (이더넷 내장 SiP)

- W6100-EVB-Pico (IPv6)

- W6300-EVB-Pico (QSPI)

- W5100S-EVB-Pico2 (RP2350)

- W5500-EVB-Pico2 (RP2350)

- W6100-EVB-Pico2 (RP2350)

- W6300-EVB-Pico2 (RP2350)

**16종 예제:**

- 기본: loopback, udp, http, tcp_server_multi_socket

- 프로토콜: dhcp_dns, sntp, mqtt, tftp, netbios, pppoe, upnp

- 보안: tcp_client_over_ssl, tcp_server_over_ssl

- 고급: udp_multicast, can, network_install

---

## 주요 특징

### 🚀 빠른 빌드 성능

- **tmpfs**: RAM에 빌드 디렉토리 생성 (20GB)

- **ccache**: 컴파일 캐시 (재빌드 시 100% 적중)

- **병렬 빌드**: 16개 동시 작업

### 🌐 크로스 플랫폼

- **Windows**: PowerShell 스크립트 (build.ps1)

- **Linux**: Bash 스크립트 (build.sh)

- **macOS**: Bash 스크립트 (build.sh)

### 👥 사용자 친화적

- **Interactive 모드**: 초보자를 위한 안내 UI

- **명령줄 모드**: 고급 사용자를 위한 빠른 빌드

- **단일 예제 빌드**: 필요한 것만 빌드

### 🔧 고급 기능

- **CleanOutput**: 전체 클린 없이 빠른 재빌드

- **호스트 examples**: 호스트에서 예제 편집, 컨테이너에서 빌드

- **자동 초기화**: 서브모듈 자동 처리

---

## 시작하기

### 사전 요구사항

**필수:**

- Docker Desktop (Windows/macOS) 또는 Docker Engine (Linux)

- Git

- 20GB 여유 RAM (tmpfs용)

- 5GB 여유 디스크 공간 (ccache용)

**선택:**

- Windows: PowerShell 5.1+ (Windows 10/11에 기본 설치)

- Linux/macOS: Bash 4.0+

### 설치

**1단계: Docker 설치Windows/macOS**: [Docker Desktop](https://www.docker.com/products/docker-desktop)에서 다운로드

**Linux (Ubuntu/Debian)**:

```plaintext
sudo apt-get update
sudo apt-get install docker.io
sudo usermod -aG docker $USER
# 로그아웃 후 다시 로그인
```

**2단계: 저장소 클론**

```plaintext
git clone https://github.com/your-username/wiznet-pico-c-docker.git
cd wiznet-pico-c-docker
```

**3단계: Docker 확인**

```plaintext
# Windows
docker --version

# Linux/macOS
docker --version
```

---

## 사용법 - Interactive 모드

Interactive 모드는 초보자를 위한 안내 UI를 제공합니다.

### 1단계: Interactive 모드 실행

**Windows:**

```plaintext
powershell -ExecutionPolicy Bypass -File .\build.ps1 -Interactive
```

**Linux/macOS:**

```plaintext
./build.sh -i
```

### 2단계: 보드 선택

시스템이 10종의 지원 보드를 표시합니다:

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770743735%2Epng)

**예시:**

- W5500-EVB-Pico를 위해 `3` 선택 (권장)

### 3단계: 예제 선택

난이도 별표(⭐)가 표시된 16종 예제 중 선택:

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770743751%2Epng)

**옵션:**

- `0`: 전체 16개 예제 빌드 (약 10분)

- `1-16`: 특정 예제 빌드

- 다중 선택: `1 2 3` (loopback, udp, http 빌드)

**예시:**

- HTTP 서버를 위해 `3` 선택 (⭐⭐ 난이도)

### 4단계: 빌드 완료

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770743764%2Epng)

**빌드 결과:**

- 빌드 시간: **2분 6초**

- 출력: `wizchip_http_server.uf2` (103KB)

- 위치: `out/` 디렉토리

- tmpfs 사용량: 27MB

**다음 단계:**

1. W5500-EVB-Pico를 USB로 연결

2. BOOTSEL 버튼을 누른 채 RESET 버튼 클릭

3. `out/wizchip_http_server.uf2`를 드래그앤드롭

4. 시리얼 터미널 열기 (115200 baud)

---

## 사용법 - 명령줄 모드

명령줄 모드는 고급 사용자를 위한 빠른 빌드를 제공합니다.

### 전체 예제 빌드

**Windows:**

```plaintext
powershell -ExecutionPolicy Bypass -File .\build.ps1 -Board W5500_EVB_PICO -All
```

**Linux/macOS:**

```plaintext
./build.sh -b W5500_EVB_PICO -a
```

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770743997%2Epng)

**빌드 진행:**

- Docker 이미지 pull: `simryang/w55rp20:latest`

- 서브모듈 초기화

- CMake 설정

- Ninja 빌드 (16 병렬 작업)

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770744019%2Epng)

**빌드 결과:**

- 빌드 시간: **33분 24초**

- 출력: 16개 예제, 총 20개 .uf2 파일

- tmpfs 사용량: 129MB (최대)

### 단일 예제 빌드

**Windows:**

```plaintext
powershell -ExecutionPolicy Bypass -File .\build.ps1 -Board W5500_EVB_PICO -Example http
```

**Linux/macOS:**

```plaintext
./build.sh -b W5500_EVB_PICO -e http
```

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770743922%2Epng)

**HTTP 예제만 빌드:**

- 타겟: `wizchip_http_server`

- 다른 예제는 빌드하지 않음

### 여러 예제 빌드

**Windows:**

```plaintext
powershell -ExecutionPolicy Bypass -File .\build.ps1 -Board W5500_EVB_PICO -Example "http mqtt"
```

**Linux/macOS:**

```plaintext
./build.sh -b W5500_EVB_PICO -e "http mqtt"
```

**빌드 결과:**

- `wizchip_http_server.uf2`

- `wizchip_mqtt_publish.uf2`

- `wizchip_mqtt_publish_subscribe.uf2`

- `wizchip_mqtt_subscribe.uf2`

---

## 성능 최적화

### ccache: 100% 캐시 적중

동일한 코드를 재빌드할 때, ccache는 거의 즉시 컴파일을 제공합니다.

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770744143%2Epng)

**성능 비교:**

| 빌드 타입 | 첫 빌드 | 재빌드 (ccache) | 속도 향상 |
| --- | --- | --- | --- |
| 단일 예제 (http) | 2분 6초 | **25초** | **5배 빠름** |
| 전체 예제 | 33분 24초 | ~2-3분 | **11배 빠름** |

**ccache 통계:**

- 적중: 142 / 142 (100%)

- 캐시 크기: 0.03GB / 5.00GB (0.66%)

- tmpfs 사용량: 27MB (단일 예제)

### tmpfs: RAM 기반 빌드

RAM(tmpfs)에서 빌드하는 것이 디스크보다 훨씬 빠릅니다:

**tmpfs vs 디스크:**

- tmpfs (RAM): ~2분 (단일 예제)

- SSD: ~3-4분

- HDD: ~5-8분

**tmpfs 설정:**

- 크기: 20GB (설정 가능)

- 마운트: `/work/src/build`

- 빌드 후 자동 정리

---

## 고급 기능

### CleanOutput: 빠른 재빌드

일반 clean은 모든 것을 삭제하여 33분 재빌드가 필요합니다.

**CleanOutput**은 빌드 출력만 삭제하고 빌드 캐시를 보존합니다:

**Windows:**

```plaintext
powershell -ExecutionPolicy Bypass -File .\build.ps1 -CleanOutput
```

**Linux/macOS:**

```plaintext
./build.sh -co
```

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770744193%2Epng)

**결과:**

- 삭제: `out/` 디렉토리 (8개 파일)

- 보존: `WIZnet-PICO-C/build/` (CMake 캐시)

- 다음 빌드: 33분 대신 **1-2분사용 사례:**

- 다른 보드 테스트

- Debug/Release 빌드 전환

- 디스크 공간 정리

### 호스트 Examples: 편집 및 빌드

전체 저장소를 포크하는 대신, examples를 호스트로 복사:

**1단계: Examples 초기화Windows:**

```plaintext
powershell -ExecutionPolicy Bypass -File .\build.ps1 -InitExamples
```

**Linux/macOS:**

```plaintext
./build.sh --init-examples
```

`WIZnet-PICO-C/examples/`를 `./examples/`로 복사합니다.

**2단계: Examples 편집**

```plaintext
vi ./examples/http/w5x00_http_server.c
# 코드 수정
```

**3단계: 수정된 Examples로 빌드Windows:**

```plaintext
powershell -ExecutionPolicy Bypass -File .\build.ps1 -Board W5500_EVB_PICO -All
```

**Linux/macOS:**

```plaintext
./build.sh -b W5500_EVB_PICO -a
```

빌드 시스템이 자동으로 `./examples/`를 컨테이너에 마운트하여 수정된 코드를 사용합니다.

**장점:**

- 서브모듈 관리 불필요

- 쉬운 버전 관리 (Git)

- 빠른 반복 개발

---

## 성능 분석

### CPU 활용률

Docker 빌드 시스템이 모든 CPU 코어를 효율적으로 활용합니다.

**테스트 환경:**

- CPU: AMD Ryzen 7 5700G (8코어, 16스레드)

- RAM: 32GB

- OS: Windows 11

### 빌드 전: 유휴 상태

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770744721%2Epng)

**측정값:**

- CPU 사용률: 1%

- 클럭 속도: 3.98GHz

- 프로세스: 434

- 스레드: 7129

### 빌드 중: 전체 부하

![](https://maker.wiznet.io/upload/ckeditor5/185177575%5F1770744754%2Epng)

**측정값:**

- CPU 사용률: **61%** (최대)

- 클럭 속도: **4.36GHz** (부스트)

- 16개 스레드 모두 활용

- Ninja 병렬 빌드: `-j 16`

**빌드 성능:**

- 단일 코어: ~20분

- 16코어: **2-3분** (ccache 활성화)

- 병렬 효율: ~85%

### 빌드 특성

**CPU 사용 패턴:**

- **CMake 설정**: 낮은 CPU (단일 스레드)

- **Ninja 컴파일**: 높은 CPU (병렬)

- **링킹**: 중간 CPU (제한적 병렬화)

**권장사항:**

- 4코어 CPU: 양호 (8-10분 빌드)

- 8코어 CPU: 우수 (2-3분 빌드)

- 16코어 CPU: 최적 (ccache로 1-2분 빌드)

---

## 문제 해결

### 일반적인 문제

#### 문제 1: Docker 미실행

**오류:**

```plaintext
Error: Docker daemon not running
```

**해결:**

- Windows/macOS: Docker Desktop 실행

- Linux: `sudo systemctl start docker`

#### 문제 2: 권한 거부 (Linux)

**오류:**

```plaintext
permission denied while trying to connect to the Docker daemon
```

**해결:**

```plaintext
sudo usermod -aG docker $USER
# 로그아웃 후 다시 로그인
```

#### 문제 3: 메모리 부족

**오류:**

```plaintext
ninja: fatal error: fork: Cannot allocate memory
```

**해결:**

- tmpfs 크기 줄이기: `build.sh` 또는 `build.ps1` 편집

- `TMPFS_SIZE=20g`를 `TMPFS_SIZE=10g`로 변경

- 또는 병렬 작업 수 줄이기: `JOBS=8`

#### 문제 4: 서브모듈 미초기화

**오류:**

```plaintext
Pico SDK submodule not initialized!
```

**해결:** 빌드 시스템이 자동으로 처리합니다. 실패할 경우:

```plaintext
cd WIZnet-PICO-C
git submodule update --init --recursive
cd ..
```

#### 문제 5: 빌드 타겟을 찾을 수 없음 (Windows)

**오류:**

```plaintext
ninja: error: unknown target 'wizchip_udp_multicast_sender'
```

**해결:** 최신 버전으로 업데이트:

```plaintext
git pull
```

타겟 매핑 버그가 수정되었습니다 (커밋 `4feccb6`).

### 도움 받기

- GitHub 이슈: [버그 신고](https://github.com/your-username/wiznet-pico-c-docker/issues)

- WIZnet 포럼: [질문하기](https://forum.wiznet.io/)

- 문서: README.md

---

## 향후 계획

### Python 통합 (계획됨)

`build.ps1`과 `build.sh` 간의 코드 중복을 제거하기 위해 계획 중:

**1단계: Python 스크립트**

- 모든 플랫폼을 위한 단일 `build.py`

- `build.ps1` / `build.sh`는 얇은 래퍼로

- Python 3.6+ 필요 (Docker 사용자에게 표준)

**2단계: PyInstaller 바이너리 (선택)**

- `build.exe` (Windows)

- `build` (Linux)

- `build` (macOS)

- Python 설치 불필요

**장점:**

- 단일 코드베이스 유지

- 기능 추가가 쉬움

- 크로스 플랫폼 일관성 향상

자세한 내용은 FUTURE_PLAN_PYTHON_INTEGRATION.md 참조.

### 계획된 기능

- GitHub Actions 통합 (CI/CD)

- 모든 보드를 위한 사전 빌드 Docker 이미지

- 원격 빌드를 위한 웹 UI

- 커스텀 보드 지원

- FreeRTOS 예제 통합

---

## 결론

**WIZnet-PICO-C Docker 빌드 시스템**은 WIZnet 이더넷 보드용 펌웨어 개발을 단순화합니다:

✅ **설정 불필요**: Docker가 모든 것을 처리 ✅ **빠른 빌드**: tmpfs + ccache = 25초 ✅ **크로스 플랫폼**: Windows, Linux, macOS ✅ **사용자 친화적**: 초보자를 위한 Interactive 모드 ✅ **유연함**: 단일 또는 전체 예제

**시작하기:**

```plaintext
git clone https://github.com/your-username/wiznet-pico-c-docker.git
cd wiznet-pico-c-docker
./build.sh -i  # Linux/macOS
```

**질문이 있으신가요?**

- 문서: README.md

- 이슈: [GitHub Issues](https://github.com/your-username/wiznet-pico-c-docker/issues)

#### 저자

구현/리눅스 환경 테스트/글 내용 작성 : Joseph

윈도우 환경 테스트/실행 이미지 수집 : Aimee

---

Source: https://maker.wiznet.io/josephsr/projects/wiznet-pico-c-docker-build-system/