패키지 사용하기

Dart 생태계는 라이브러리나 도구 같은 공유 소프트웨어를 관리하기 위해 *패키지(package)*를 사용해요. Dart 패키지를 가져오려면 pub 패키지 매니저를 사용하면 돼요. 공개된 패키지는 pub.dev 사이트에서 찾을 수 있고, 로컬 파일 시스템이나 Git 저장소 같은 다른 곳에서도 불러올 수 있어요. 패키지가 어디서 오든 pub이 버전 의존성을 관리해 줘서, 서로 그리고 SDK 버전과도 잘 맞는 패키지 버전을 받을 수 있어요.

출처: How to use packages

본문

Dart 생태계는 패키지를 사용해 라이브러리와 도구 같은 공유 소프트웨어를 관리해요. Dart 패키지를 가져오려면 pub 패키지 매니저를 사용해요. 공개적으로 이용 가능한 패키지는 pub.dev 사이트에서 찾을 수 있고, 로컬 파일 시스템이나 Git 저장소 같은 다른 곳에서도 패키지를 불러올 수 있어요. 패키지가 어디서 왔든 pub이 버전 의존성을 관리해서, 서로 그리고 SDK 버전과도 잘 맞는 패키지 버전을 받을 수 있게 해 줘요.

대부분의 Dart 지원 IDE는 패키지 생성, 다운로드, 업데이트, 게시를 포함하는 pub 지원을 제공해요. 아니면 커맨드라인에서 dart pub을 사용할 수도 있어요.

최소한 Dart 패키지는 pubspec 파일을 담은 하나의 디렉터리예요. pubspec에는 패키지에 대한 몇 가지 메타데이터가 들어 있어요. 추가로 패키지는 의존성(pubspec에 나열), Dart 라이브러리, 앱, 리소스, 테스트, 이미지, 예시를 포함할 수 있어요.

패키지를 사용하려면 이렇게 하세요.

pubspec을 만드세요(패키지 의존성을 나열하고 버전 번호 같은 다른 메타데이터를 담는 pubspec.yaml 파일).
dart pub get으로 패키지의 의존성을 가져오세요.
Dart 코드가 패키지의 라이브러리에 의존한다면 그 라이브러리를 import하세요.

pubspec 만들기

pubspec은 애플리케이션의 최상위 디렉터리에 있는 pubspec.yaml 파일이에요. 가장 단순한 pubspec은 패키지 이름만 나열해요.

name: my_app

다음은 pub.dev 사이트에 호스팅된 두 패키지(intl, path)에 의존성을 선언하는 pubspec 예시예요.

name: my_app

dependencies:
  intl: ^0.20.3
  path: ^1.9.1

pubspec.yaml 파일을 수동으로 편집하지 않고 갱신하려면 dart pub add 명령을 실행하면 돼요. 다음 예시는 vector_math에 의존성을 추가해요.

$ dart pub add vector_math
Resolving dependencies...
+ vector_math 2.1.3
Downloading vector_math 2.1.3...
Changed 1 dependency!

pubspec 만드는 방법에 대한 자세한 내용은 pubspec 문서와 사용하려는 패키지의 문서를 참고하세요.

패키지 가져오기

pubspec이 생겼으면 애플리케이션의 최상위 디렉터리에서 dart pub get을 실행할 수 있어요.

$ cd <path-to-my_app>
$ dart pub get

이 과정을 *의존성 가져오기(getting the dependencies)*라고 해요.

dart pub get 명령은 앱이 의존하는 패키지를 결정하고, 이를 중앙 시스템 캐시에 넣어요. 앱이 게시된 패키지에 의존한다면, pub은 pub.dev 사이트에서 그 패키지를 내려받아요. Git 의존성의 경우에는 pub이 Git 저장소를 클론해요. 전이 의존성(transitive dependency)도 함께 포함돼요. 예를 들어 js 패키지가 test 패키지에 의존한다면, pub은 js 패키지와 test 패키지를 모두 가져와요.

pub은 앱이 의존하는 각 패키지 이름을 시스템 캐시의 해당 패키지에 매핑하는 package_config.json 파일(.dart_tool/ 디렉터리 아래)을 만들어요.

패키지에서 라이브러리 import하기

패키지에서 라이브러리를 import하려면 package: 접두사를 사용해요.

import 'package:js/js.dart' as js;
import 'package:intl/intl.dart';

Dart 런타임은 package: 뒤의 모든 것을 가지고 앱의 package_config.json 파일에서 찾아봐요.

이 스타일을 여러분 자신의 패키지 안의 라이브러리를 import하는 데에도 사용할 수 있어요. transmogrify 패키지가 다음과 같이 구성되어 있다고 해 볼게요.

transmogrify/
- lib/
  - transmogrify.dart
  - parser.dart
- test/
  - parser/
    - parser_test.dart

parser_test.dart 파일은 parser.dart를 이렇게 import할 수 있어요.

import 'package:transmogrify/parser.dart';

의존성 업그레이드하기

처음으로 패키지에 새 의존성을 가져오면, pub은 다른 의존성들과 호환되는 최신 버전을 내려받아요. 그러고 나서 lockfile을 만들어 패키지를 항상 그 버전을 사용하도록 잠가요. 이것은 pub이 pubspec 옆에 만들어 저장하는 pubspec.lock 파일이에요. 패키지가 사용하는 각 의존성(직접 의존성과 전이 의존성 모두)의 구체적인 버전을 나열해요.

패키지가 애플리케이션 패키지라면, 이 파일을 소스 제어에 체크인해야 해요. 그래야 앱에서 작업하는 모든 사람이 모든 의존성의 같은 버전을 사용하게 돼요. lockfile을 체크인하면 배포된 앱도 같은 버전의 코드를 사용한다는 걸 보장해 줘요.

의존성을 최신 버전으로 업그레이드할 준비가 되면 dart pub upgrade 명령을 사용하세요.

$ dart pub upgrade

dart pub upgrade 명령은 패키지 의존성의 사용 가능한 최신 버전을 사용해 lockfile을 다시 생성하도록 pub에 지시해요. 의존성 하나만 업그레이드하고 싶다면 업그레이드할 패키지를 지정할 수 있어요.

$ dart pub upgrade transmogrify

이 명령은 transmogrify만 최신 버전으로 업그레이드하고 나머지는 그대로 둬요.

pubspec의 버전 제약이 충돌하기 때문에 dart pub upgrade가 항상 모든 패키지를 최신 버전으로 업그레이드할 수는 없어요. pubspec을 편집해야 하는 오래된 패키지를 식별하려면 dart pub outdated를 사용하세요.

프로덕션용 의존성 가져오기

어떤 상황에서는 dart pub get이 pubspec.lock 파일에 잠긴 정확한 패키지 버전을 가져오지 못할 수 있어요.

pubspec.lock 파일이 마지막으로 갱신된 뒤 pubspec.yaml에 새 의존성이 추가되거나 제거된 경우.
잠긴 버전이 더 이상 패키지 저장소에 존재하지 않는 경우.
다른 버전의 Dart SDK로 바꿨는데 일부 패키지가 그 새 버전과 더 이상 호환되지 않는 경우.

이런 경우 dart pub get은 다음을 수행해요.

해석이 가능해질 만큼 잠긴 의존성 버전의 잠금을 풀어요.
기존 pubspec.lock을 기준으로 의존성 변경 사항을 알려줘요.

예를 들어 의존성에 retry: ^3.0.0을 추가한 뒤에는 이렇게 나와요.

$ dart pub get
Resolving dependencies... (1.0s)
Downloading packages...
+ retry 3.1.2

또한 게시된 패키지 버전의 콘텐츠 해시가 pubspec.lock 파일의 해시와 다르면, pub이 경고하고 게시된 버전을 반영해 lockfile을 갱신해요.

예를 들어 pubspec.lock에서 retry의 해시를 수동으로 바꾼 경우:

$ dart pub get
Resolving dependencies...
Downloading packages...
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://pub.dev"

This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.

The content-hashes in pubspec.lock has been updated.

For more information see:
https://dart.dev/go/content-hashes
Changed 1 dependency!

프로젝트를 프로덕션에 배포할 때는 dart pub get --enforce-lockfile로 의존성을 가져오세요.

프로젝트의 의존성 제약을 pubspec.lock의 정확한 버전과 콘텐츠 해시로 만족시킬 수 없다면, 패키지 가져오기와 명령이 실패해요. 이렇게 해서 테스트되지 않은 의존성과 의존성 버전이 프로덕션에 배포되는 걸 막을 수 있어요.

$ dart pub get --enforce-lockfile
Resolving dependencies...
Downloading packages...
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://pub.dev"

This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.

For more information see:
https://dart.dev/go/content-hashes
Would change 1 dependency.
Unable to satisfy `pubspec.yaml` using `pubspec.lock`.

To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`.

더 알아보기

pubspec 파일 — pubspec.yaml의 모든 필드 참고.
pub 의존성 — 패키지 의존성 선언 방식.
패키지 게시하기 — 패키지를 pub.dev에 게시하는 방법.

패키지 사용하기