라이브러리와 패키지

Dart 코드는 라이브러리와 패키지라는 두 단위로 나뉩니다. 라이브러리는 코드를 묶고 공개 범위를 정하는 단위이고, 패키지는 라이브러리와 설정, 의존성을 함께 배포하는 단위입니다. 이 장에서는 import와 export, 패키지 관리자 pub와 pubspec.yaml, 패키지 디렉터리 구조, pub.dev에 공개하는 방법을 살펴봅니다.

라이브러리와 import

Dart에서는 파일 하나가 곧 라이브러리 하나입니다. 이름이 밑줄(_)로 시작하는 최상위 선언과 멤버는 그 라이브러리 안에서만 보이므로, 별도의 private 키워드가 없습니다. 다른 라이브러리를 쓰려면 import로 가져옵니다.

import 'dart:math';
import 'dart:convert' show jsonDecode, jsonEncode; // 필요한 이름만
import 'package:path/path.dart' as p;              // 접두사로 이름 충돌 방지
import 'src/internal.dart' hide debugHelper;       // 특정 이름 제외

void main() {
  print(sqrt(16));                                  // dart:math
  print(jsonEncode({'ok': true}));                  // dart:convert
  print(p.join('assets', 'images', 'logo.png'));    // package:path
}

show는 지정한 이름만 가져오고, hide는 지정한 이름을 뺀 나머지를 가져옵니다. as로 접두사를 붙이면 서로 다른 라이브러리에 같은 이름이 있어도 충돌하지 않습니다. 웹에서는 deferred as로 라이브러리를 필요할 때 늦게 불러올 수도 있습니다.

export로 공개 API 모으기

패키지의 실제 구현은 보통 lib/src 아래에 두고, lib 바로 아래의 대표 파일에서 공개할 것만 export합니다. 사용자는 대표 파일 하나만 가져오면 됩니다.

// lib/shapes.dart: 패키지의 대표 라이브러리
library;

export 'src/circle.dart';
export 'src/square.dart' show Square;
// src/geometry_utils.dart 는 export 하지 않으므로 내부 구현으로 남습니다

lib/src 안의 파일은 관례상 비공개 구현으로 취급합니다. 다른 패키지가 package:shapes/src/...를 직접 가져오는 것은 가능하지만 권장되지 않으며, 분석기가 경고합니다.

pub와 pubspec.yaml

pub는 Dart의 패키지 관리자이고, 공개 패키지 저장소는 pub.dev입니다. 패키지의 이름, 버전, 지원하는 SDK 범위, 의존성은 프로젝트 루트의 pubspec.yaml에 적습니다.

name: weather_cli
description: 명령줄에서 날씨를 보여 주는 예제 도구입니다.
version: 1.0.0
publish_to: none   # pub.dev 에 실수로 올리지 않도록 막습니다

environment:
  sdk: ^3.5.0      # dart create 가 지금 SDK 에 맞춰 채워 줍니다

dependencies:
  http: ^1.2.0
  path: ^1.9.0

dev_dependencies:
  lints: ^5.0.0
  test: ^1.25.0

버전 앞의 ^(캐럿)는 "이 버전 이상, 다음 주 버전 미만"을 뜻합니다. 예를 들어 ^1.2.0은 1.2.0 이상 2.0.0 미만을 허용합니다. dependencies는 실행에 필요한 패키지이고, dev_dependencies는 테스트나 린트처럼 개발할 때만 쓰는 패키지입니다. 위의 버전 번호는 예시이며, 직접 적기보다 아래 명령으로 추가하면 그때의 최신 호환 버전이 채워집니다.

dart pub 명령

dart pub add http             # dependencies 에 추가
dart pub add --dev test       # dev_dependencies 에 추가
dart pub remove http          # 제거
dart pub get                  # pubspec.yaml 대로 내려받기
dart pub upgrade              # 허용 범위 안에서 최신으로 올리기
dart pub outdated             # 더 새 버전이 있는 의존성 보기
dart pub deps                 # 의존성 트리 보기

dart pub get을 실행하면 실제로 고른 버전이 pubspec.lock에 기록됩니다. 실행 프로그램이나 앱 패키지는 pubspec.lock을 저장소에 커밋해 모든 개발자와 CI가 같은 버전을 쓰게 합니다. 다른 패키지가 가져다 쓰는 라이브러리 패키지는 사용하는 쪽에서 버전이 다시 정해지므로 잠금 파일이 그만큼 중요하지 않습니다. 내려받은 패키지는 시스템 공용 캐시(pub cache)에 저장되고, 프로젝트의 .dart_tool/ 디렉터리에는 패키지 위치 정보가 기록됩니다.

Git 저장소나 로컬 경로의 패키지도 의존성으로 쓸 수 있습니다.

dependencies:
  my_utils:
    path: ../my_utils
  shared_models:
    git:
      url: https://github.com/example/shared_models.git
      ref: main

패키지 디렉터리 구조

pub 도구와 pub.dev는 정해진 디렉터리 구조를 기대합니다.

lib 밖의 파일(bin, test 등)에서 자기 패키지의 라이브러리를 쓸 때는 import 'package:weather_cli/weather_cli.dart';처럼 package: 형태로 가져옵니다.

pub.dev에 공개하기

공개 패키지를 만들 때는 publish_to: none을 지우고, description, repository 또는 homepage, LICENSE, README.md, CHANGELOG.md를 갖춥니다. 공개하기 전에는 반드시 미리 검사합니다.

dart pub publish --dry-run    # 실제로 올리지 않고 문제만 검사
dart pub publish              # Google 계정 인증 후 pub.dev 에 공개

공개한 버전은 지울 수 없고, 같은 버전 번호로 다시 올릴 수도 없습니다. 실수한 버전은 공개 직후 일정 기간 안에 철회(retract)할 수 있지만, 일반적으로는 수정한 새 버전을 올립니다. 버전 번호는 시맨틱 버전 규칙을 따라, 호환되지 않는 변경이 있으면 주 버전을 올립니다. pub.dev는 문서, 분석 결과, 지원 플랫폼을 바탕으로 패키지 점수를 매기므로 dart analyze와 dart doc으로 미리 점검해 두면 좋습니다.

정리

Dart에서는 파일 하나가 라이브러리이고 _로 시작하는 이름은 라이브러리 밖에 숨겨집니다. import의 show, hide, as로 가져올 이름을 조절하고, export로 공개 API를 대표 파일에 모읍니다. 의존성은 pubspec.yaml에 적고 dart pub add, get, upgrade로 관리하며, 정해진 디렉터리 구조를 지켜 dart pub publish로 pub.dev에 공개합니다.