Profile Image of the Author
Moodturn
Welcome to MoodturnPost!

Dart 튜토리얼 30편: 빌드·컴파일·자동화(dart build·dart compile·build_runner·webdev)

2026-01-04
study
dart study

요약#

핵심 요지#

  • 문제 정의: “빌드”와 “컴파일”과 “코드 생성” 도구가 섞이면, 명령을 잘못 선택해 실패하거나 산출물이 일관되지 않다.
  • 핵심 주장: build hooks가 있으면 dart build1를 사용해야 하고, 그렇지 않으면 dart compile2로 실행 파일/스냅샷/JS/Wasm을 만든다. 코드 생성/웹 개발 워크플로는 build_runner3와 webdev4로 구성한다.
  • 주요 근거: build hooks가 있으면 dart compile exe/dart compile aot-snapshot이 훅을 실행하지 않아 실패할 수 있다는 주의, dart build cli 출력 구조, dartaotruntime로 AOT 스냅샷 실행 예시, build_runner build/webdev serve/build 흐름이 제시된다.
  • 실무 기준: (1) 훅 여부 확인 → (2) 빌드 도구 선택 → (3) 산출물 타입(exe/aot/JS/Wasm) 선택 → (4) 코드 생성/웹 빌드는 전용 도구로 분리.

문서가 설명하는 범위#

  • dart build의 목적(빌드 훅 실행 + 코드/자산 번들링)과 CLI 빌드 옵션
  • dart compile의 출력 타입(exe/aot-snapshot/jit-snapshot/kernel/js/wasm)과 예시
  • dartaotruntime로 AOT 스냅샷 실행
  • build_runner의 설치/명령(build/serve/test/watch)
  • webdev의 설치/설정(빌드 도구 의존성)과 serve/build/test 흐름

읽는 시간: 16분 | 난이도: 초급

참고 자료#

문제 상황#

처음에는 “실행 파일만 만들면 되지”라고 생각하기 쉽습니다.
하지만 프로젝트에 코드 생성이나 자산 빌드 훅이 들어오면, 단순 컴파일 명령이 실패할 수 있습니다.
또 웹 개발은 build_runner/webdev 같은 별도 도구 흐름이 있습니다.
따라서 먼저 “어떤 프로젝트인지”를 구분하고, 그에 맞는 도구를 선택해야 합니다.

해결 방법#

단계 1: build hooks가 있으면 dart build를 선택한다#

Why#

NOTE

프로젝트나 의존성이 build hooks를 사용하면, 실행 파일을 만들기 전에 “코드/자산을 생성하거나 다운로드”해야 할 수 있습니다.
이 과정을 빼먹으면 빌드가 실패할 수 있습니다.

What#

NOTE

dart build는 프로젝트와 의존성의 build hooks를 자동 실행하고, 코드 자산을 번들링하는 도구로 설명됩니다.
또한 Dart 3.10부터 지원된다는 버전 안내가 있습니다.

How#

TIP

CLI 앱은 dart build cli로 빌드할 수 있으며, 결과 번들은 다음 구조로 설명됩니다.

bundle/
  bin/
    <compiled_executable>
  lib/
    <dynamic_libraries>

출력 디렉터리/타깃 엔트리포인트 등을 --output, --target 옵션으로 제어할 수 있다는 설명이 함께 제시됩니다.

Watch out#

WARNING

dart compile exe/dart compile aot-snapshot은 build hooks를 실행하지 않으며, 훅이 존재하면 실패할 수 있다는 주의가 제시되어 있습니다.
즉, 훅이 있는 프로젝트에서는 compile을 먼저 선택하면 안 됩니다.

결론: build hooks가 있는 프로젝트는 dart build로 빌드 흐름을 고정해야 합니다.

단계 2: 훅이 없다면 dart compile로 원하는 산출물(exe/aot/js/wasm)을 만든다#

Why#

NOTE

배포 대상에 따라 필요한 산출물이 달라집니다.
CLI는 실행 파일(exe), 여러 앱을 묶어 배포하면 AOT 스냅샷, 웹은 JS/Wasm 같은 식입니다.

What#

NOTE

dart compile은 exe, aot-snapshot, js, wasm 등 다양한 출력 타입을 제공한다고 설명됩니다.
또한 -o/--output으로 출력 경로를 지정할 수 있다고 안내합니다.

How#

TIP

네이티브 실행 파일(exe) 예시:

Terminal window
$ dart compile exe bin/myapp.dart
Generated: /Users/me/myapp/bin/myapp.exe

AOT 스냅샷 예시:

Terminal window
$ dart compile aot-snapshot bin/myapp.dart
Generated: /Users/me/myapp/bin/myapp.aot

Watch out#

WARNING

exe/aot-snapshot은 운영체제/아키텍처에 영향을 받습니다.
또한 exe는 일부 코어 라이브러리(dart:mirrors, dart:developer)를 지원하지 않는 제한이 명시되어 있습니다.
즉, 산출물 타입을 정할 때 지원 범위를 함께 고려해야 합니다.

결론: 훅이 없는 프로젝트는 dart compile로 산출물을 만들되, 산출물 타입의 제약을 함께 확인해야 합니다.

단계 3: AOT 스냅샷은 dartaotruntime로 실행한다#

Why#

NOTE

AOT 스냅샷은 “런타임이 포함되지 않은 모듈” 형태일 수 있습니다.
따라서 실행에는 런타임이 필요합니다.

What#

NOTE

dartaotruntime는 AOT 컴파일된 스냅샷을 실행하는 도구이며, Windows/macOS/Linux를 지원한다고 설명됩니다.

How#

TIP

예시는 다음과 같이 제시됩니다.

Terminal window
$ dart compile aot-snapshot bin/myapp.dart
Generated: /Users/me/simpleapp/bin/myapp.aot
$ dartaotruntime bin/simpleapp.aot

Watch out#

WARNING

dartaotruntime를 사용하려면 Dart bin 디렉터리가 PATH에 있어야 한다는 안내가 있습니다.
즉, 실행이 안 되면 “명령을 찾지 못하는 문제”부터 확인해야 합니다.

결론: AOT 스냅샷은 런타임이 분리될 수 있으므로, dartaotruntime 실행까지 포함해 검증합니다.

단계 4: 코드 생성/테스트 자동화는 build_runner, 웹 개발은 webdev로 분리한다#

Why#

NOTE

코드 생성과 웹 빌드는 “한 번만 실행”이 아니라 반복 실행이 필요합니다.
따라서 전용 도구를 사용하는 편이 관리가 쉽습니다.

What#

NOTE

build_runner는 파일 생성/테스트/서빙을 위한 범용 커맨드를 제공하고, webdev는 Dart 웹 개발에서 compile/serve 흐름을 제공한다고 설명됩니다.
또한 webdev를 쓰려면 build_runner와 build_web_compilers에 dev dependency를 추가하라는 안내가 있습니다.

How#

TIP

build_runner 설치는 dev dependency로 추가하는 예시가 제시됩니다.

dev_dependencies:
  # ···
  build_runner: ^2.10.4
  build_test: ^3.5.4

기본 빌드 예시는 다음과 같습니다.

Terminal window
$ dart run build_runner build

웹 개발 도구 webdev의 설정/설치 예시는 다음과 같습니다.

Terminal window
$ dart pub add build_runner build_web_compilers --dev
$ dart pub global activate webdev

그리고 개발 서버/배포 빌드 예시는 다음과 같이 제시됩니다.

Terminal window
$ webdev serve
$ webdev build --output web:build

Watch out#

WARNING

webdev serve는 개발 컴파일러가 Chrome만 지원한다는 제한이 명시되어 있습니다.
또한 Wasm 타깃에서는 webdev가 Wasm용 serve/build를 지원하지 않는다는 제약이 함께 제시됩니다.
즉, 웹 타깃이 JS인지 Wasm인지에 따라 도구 선택이 달라질 수 있습니다.

결론: 자동화는 목적별 도구(build_runner/webdev)로 분리하고, 브라우저/타깃 제약을 기준으로 워크플로를 고정합니다.

Footnotes#

  1. dart build(dart build): build hooks를 실행하고 코드/자산을 번들링해 앱을 빌드하는 명령이다. ↩

  2. dart compile(dart compile): Dart 코드를 다양한 출력(exe/스냅샷/JS/Wasm)으로 컴파일하는 명령이다. ↩

  3. build_runner(build_runner): 빌더 기반 코드 생성/테스트/서빙을 위한 도구다. ↩

  4. webdev(webdev): Dart 웹 개발을 위한 serve/build 도구다. ↩

공유

이 글이 도움이 되었다면 다른 사람과 공유해주세요!

Dart 튜토리얼 30편: 빌드·컴파일·자동화(dart build·dart compile·build_runner·webdev)
https://moodturnpost.net/posts/dart/dart-build-compile-toolchain/
작성자
Moodturn
게시일
2026-01-04
Moodturn
Dart 튜토리얼 31편: 코드 품질과 분석(dart analyze·lints·analyzer plugins·diagnostics)
Dart 튜토리얼 29편: Dart SDK & 기본 CLI(dart tool·create·run·test)
© 2026 Moodturn. All Rights Reserved.
Powered by Astro

목차