pubspec 파일

pubspec 파일

모든 pub 패키지는 자기 의존성을 지정할 수 있도록 몇 가지 메타데이터가 필요해요. 다른 사람과 공유되는 pub 패키지는 사용자들이 찾을 수 있도록 추가 정보도 제공해야 해요. 이 모든 메타데이터는 패키지의 pubspec, 즉 YAML 언어로 작성된 pubspec.yaml 파일에 들어가요.

출처: The pubspec file

본문

모든 pub 패키지는 의존성을 지정할 수 있도록 메타데이터가 필요해요. 다른 사람과 공유되는 pub 패키지는 사용자들이 패키지를 발견할 수 있도록 다른 정보도 제공해야 해요. 이 모든 메타데이터는 패키지의 pubspec, 즉 YAML 언어로 작성된 pubspec.yaml 파일에 들어가요.

지원되는 필드

pubspec에는 다음 필드가 있을 수 있어요.

• name: 모든 패키지에 필수예요. 더 알아보기.
• version: pub.dev 사이트에 호스팅되는 패키지에 필수예요. 더 알아보기.
• description: pub.dev 사이트에 호스팅되는 패키지에 필수예요. 더 알아보기.
• homepage: 선택. 패키지의 홈페이지(또는 소스 코드 저장소) URL이에요. 더 알아보기.
• repository: 선택. 패키지의 소스 코드 저장소 URL이에요. 더 알아보기.
• issue_tracker: 선택. 패키지의 이슈 트래커 URL이에요. 더 알아보기.
• documentation: 선택. 패키지 문서 URL이에요. 더 알아보기.
• dependencies: 패키지에 의존성이 없으면 생략할 수 있어요. 더 알아보기.
• dev_dependencies: dev 의존성이 없으면 생략할 수 있어요. 더 알아보기.
• dependency_overrides: 의존성을 오버라이드할 필요가 없으면 생략할 수 있어요. 더 알아보기.
• environment: Dart 2부터 필수예요. 더 알아보기.
• executables: 선택. 패키지의 실행 파일을 PATH에 넣는 데 사용해요. 더 알아보기.
• platforms: 선택. pub.dev 사이트에서 지원 플랫폼을 명시적으로 선언하는 데 사용해요. 더 알아보기.
• publish_to: 선택. 패키지를 어디에 게시할지 지정해요. 더 알아보기.
• funding: 선택. 사용자가 패키지 개발을 후원할 수 있는 URL 목록이에요. 더 알아보기.
• false_secrets: 선택. 잠재적인 비밀 유출을 검색할 때 무시할 파일을 지정해요. 더 알아보기.
• screenshots: 선택. pub.dev 사이트에 표시할 스크린샷 파일 목록을 지정해요. 더 알아보기.
• topics: 선택. 패키지의 주제 목록이에요. 더 알아보기.
• ignored_advisories: 선택. 무시할 보안 권고 목록이에요. 더 알아보기.
• hooks: 선택. 네이티브 빌드나 링크 훅 같은 패키지별 훅을 구성해요. 더 알아보기.

pub은 그 외의 모든 필드는 무시해요.

Flutter 참고

Flutter 앱용 pubspec은 환경 구성과 에셋 관리를 위한 추가 필드를 가질 수 있어요.

사용자 정의 필드를 추가한다면 미래의 pubspec 필드와 충돌하지 않도록 고유한 이름을 지으세요. 예를 들어 bugs를 추가하는 대신 my_pkg_bugs라는 필드를 추가할 수 있어요.

예시

간단하지만 완전한 pubspec은 대략 다음과 같아요.

name: newtify
description: >-
  Have you been turned into a newt? Would you like to be?
  This package can help. It has all of the
  newt-transmogrification functionality you have been looking
  for.
version: 1.2.3
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs

environment:
  sdk: '^3.2.0'

dependencies:
  efts: ^2.0.4
  transmogrify: ^0.4.0

dev_dependencies:
  test: '>=1.15.0 <2.0.0'

상세 내용

이 섹션에서는 각 pubspec 필드에 대한 더 자세한 정보를 다뤄요.

Name

모든 패키지에는 이름이 필요해요. 이름은 다른 패키지가 여러분의 패키지를 가리키는 방식이고, 게시한다면 세상에 보이는 이름이에요.

이름은 모두 소문자여야 하고, 단어는 밑줄로 구분해요(just_like_this처럼). 기본 라틴 문자와 아라비아 숫자([a-z0-9_])만 사용하세요. 또한 이름이 유효한 Dart 식별자인지 확인하세요—숫자로 시작하면 안 되고 예약어면 안 돼요.

명확하고 간결하며 아직 사용되지 않은 이름을 고르세요. pub.dev 사이트에서 패키지를 빠르게 검색해 다른 누구도 여러분의 이름을 쓰고 있지 않은지 확인하는 걸 권장해요.

Version

모든 패키지에는 버전이 있어요. 버전 번호는 pub.dev 사이트에 패키지를 호스팅하기 위해 필요하지만, 로컬 전용 패키지에서는 생략할 수 있어요. 생략하면 패키지는 암묵적으로 0.0.0 버전으로 취급돼요.

버전 관리는 코드가 빠르게 진화하면서도 재사용하기 위해 필요해요. 버전 번호는 0.2.43처럼 점으로 구분된 세 숫자예요. 선택적으로 빌드( +1, +2, +hotfix.oopsie)나 사전 릴리스(-dev.4, -alpha.12, -beta.7, -rc.5) 접미사를 가질 수도 있어요.

패키지를 게시할 때마다 특정 버전으로 게시해요. 한 번 게시되면 그 버전은 완전히 고정된다고 생각하세요. 더 이상 건드릴 수 없어요. 변경을 하려면 새 버전이 필요해요.

버전을 고를 때는 시맨틱 버전 관리를 따르세요.

Description

개인용 패키지에서는 선택이지만, 패키지를 게시하려면 (영어로 작성된) description을 반드시 제공해야 해요. description은 비교적 짧게—60~180자—작성하고, 가볍게 보는 독자에게 패키지에 대해 알고 싶어 할 만한 내용을 전달해야 해요.

description을 패키지의 세일즈 피치라고 생각하세요. 사용자들은 패키지를 검색할 때 이 내용을 봐요. description은 평문이에요. markdown이나 HTML이 없어요.

Homepage

패키지의 웹사이트를 가리키는 URL이어야 해요. 호스팅 패키지의 경우 이 URL이 패키지 페이지에서 링크돼요. homepage를 제공하는 것은 선택이지만, homepage나 repository(또는 둘 다)는 꼭 제공해 주세요. 사용자들이 패키지가 어디서 나왔는지 이해하는 데 도움이 돼요.

Repository

선택적 repository 필드에는 패키지의 소스 코드 저장소 URL을 넣어야 해요—예: https://github.com/<user>/<repository>. 패키지를 pub.dev 사이트에 게시하면 패키지 페이지에 저장소 URL이 표시돼요. repository를 제공하는 것은 선택이지만, repository나 homepage(또는 둘 다)는 꼭 제공해 주세요. 사용자들이 패키지가 어디서 나왔는지 이해하는 데 도움이 돼요.

Issue tracker

선택적 issue_tracker 필드에는 기존 버그를 보고 새 버그를 등록할 수 있는 패키지의 이슈 트래커 URL을 넣어야 해요. pub.dev 사이트는 이 필드의 값을 사용해 각 패키지의 이슈 트래커 링크를 표시하려고 해요. issue_tracker가 없고 repository가 GitHub를 가리키고 있다면, pub.dev 사이트는 기본 이슈 트래커(https://github.com/<user>/<repository>/issues)를 사용해요.

Documentation

일부 패키지는 메인 홈페이지나 Pub 생성 API 참조와 별개로 문서를 호스팅하는 사이트가 있어요. 패키지에 추가 문서가 있다면 그 URL로 documentation: 필드를 추가하세요. pub은 패키지 페이지에 이 문서 링크를 보여 줘요.

Dependencies

의존성은 pubspec의 존재 이유(raison d'être)예요. 이 섹션에서 패키지가 동작하기 위해 필요한 각 패키지를 나열해요.

의존성은 두 가지 유형으로 나뉘어요. 일반 의존성(regular dependencies) 은 dependencies: 아래에 나열돼요—여러분의 패키지를 사용하는 모든 사람에게도 필요한 패키지예요. 패키지 자체의 개발 단계에서만 필요한 의존성은 dev_dependencies 아래에 나열돼요.

개발 과정에서 의존성을 임시로 오버라이드해야 할 수도 있어요. dependency_overrides로 할 수 있어요.

자세한 내용은 패키지 의존성 문서를 참고하세요.

Executables

패키지는 자신의 스크립트 중 하나 이상을 커맨드라인에서 직접 실행할 수 있는 실행 파일로 노출할 수 있어요. 스크립트를 공개적으로 사용 가능하게 하려면 executables 필드 아래에 나열하세요. 항목은 키/값 쌍으로 나열돼요.

<name-of-executable>: <Dart-script-from-bin>

예를 들어 다음 pubspec 항목은 두 개의 스크립트를 나열해요.

executables:
  slidy: main
  fvm:

패키지가 dart pub global activate로 활성화되면, slidy를 입력하면 bin/main.dart가 실행돼요. fvm을 입력하면 bin/fvm.dart가 실행돼요. 값을 지정하지 않으면 키에서 추론돼요.

자세한 내용은 pub global 문서를 참고하세요.

Platforms

패키지를 게시하면 pub.dev가 패키지가 지원하는 플랫폼을 자동으로 감지해요. 이 플랫폼 지원 목록이 정확하지 않다면 platforms로 패키지가 어떤 플랫폼을 지원하는지 명시적으로 선언하세요.

예를 들어 다음 platforms 항목은 pub.dev가 패키지를 Android, iOS, Linux, macOS, Web, Windows를 지원한다고 나열하게 해요.

# This package supports all platforms listed below.
platforms:
  android:
  ios:
  linux:
  macos:
  web:
  windows:

패키지가 Linux와 macOS만 지원한다고 선언하는 예시는 이래요(예를 들어 Windows는 지원하지 않음).

# This package supports only Linux and macOS.
platforms:
  linux:
  macos:

Flutter를 사용한다면

Flutter 플러그인 플랫폼 지원은 기본적으로 플러그인 선언에서 파생돼요.

플러그인 선언과 실제 플랫폼 지원 사이에 차이가 있으면, 최상위 platforms 선언을 여전히 사용할 수 있고 플랫폼 지원을 결정할 때 Flutter 플러그인 선언보다 우선해요.

버전 참고

platforms 항목 지원은 Dart 2.16에서 추가됐어요.

publish_to

기본값은 pub.dev 사이트예요. 패키지가 게시되지 않게 하려면 none을 지정하세요. 이 설정은 사용자 정의 pub 패키지 서버에 게시하는 데도 사용할 수 있어요.

publish_to: none

Funding

패키지 작성자는 funding 속성으로 사용자가 패키지 개발에 자금을 지원하는 방법에 대한 정보를 제공하는 URL 목록을 지정할 수 있어요. 예를 들어:

funding:
  - https://www.buymeacoffee.com/example_user
  - https://www.patreon.com/some-account

pub.dev에 게시하면 이 링크들이 패키지 페이지에 표시돼요. 이는 사용자들이 의존하는 패키지의 개발을 후원하는 데 도움이 되기 위한 것이에요.

false_secrets

패키지를 게시하려고 하면, pub은 비밀 자격 증명, API 키, 암호화 키의 잠재적 유출을 검색해요. pub이 게시될 파일에서 잠재적 유출을 감지하면 경고하고 패키지 게시를 거부해요.

유출 감지는 완벽하지 않아요. 오탐(false positive)을 피하려면 pubspec의 false_secrets 아래에 gitignore 패턴을 사용한 허용 목록을 만들어 특정 파일에서는 유출을 검색하지 않도록 pub에 지시할 수 있어요.

예를 들어 다음 항목은 pub이 lib/src/hardcoded_api_key.dart 파일과 test/localhost_certificates/ 디렉터리의 모든 .pem 파일에서 유출을 찾지 않게 해요.

false_secrets:
  - /lib/src/hardcoded_api_key.dart
  - /test/localhost_certificates/*.pem

gitignore 패턴을 슬래시(/)로 시작하면 그 패턴이 패키지 루트 디렉터리를 기준으로 간주되게 돼요.

경고

유출 감지에 의존하지 마세요. 이 감지는 흔한 실수를 감지하기 위해 제한된 패턴 집합을 사용해요. 자격 증명을 관리하고, 우발적 유출을 막고, 우발적으로 유출된 자격 증명을 해지하는 것은 여러분의 책임이에요.

버전 참고

Dart 2.15가 false_secrets 필드에 대한 지원을 추가했어요.

Screenshots

패키지는 pub.dev 페이지에 표시되는 스크린샷으로 위젯이나 다른 시각적 요소를 소개할 수 있어요. 패키지가 표시할 스크린샷을 지정하려면 screenshots 필드를 사용하세요.

패키지는 screenshots 필드 아래에 최대 10개의 스크린샷을 나열할 수 있어요. 이 섹션에 로고나 다른 브랜딩 이미지를 포함하지 마세요. 각 스크린샷은 description 하나와 path 하나를 포함해요. description은 스크린샷이 무엇을 보여 주는지 160자 이하로 설명해요. 예를 들어:

screenshots:
  - description: 'This screenshot shows the transformation of a number of bytes
      to a human-readable expression.'
    path: path/to/image/in/package/500x500.webp
  - description: 'This screenshot shows a stack trace returning a human-readable
      representation.'
    path: path/to/image/in/package.png

Pub.dev는 스크린샷을 다음 사양으로 제한해요.

• 파일 크기: 이미지당 최대 4 MB.
• 파일 형식: png, jpg, gif, webp.
• 정적 이미지와 애니메이션 이미지 모두 허용돼요.

스크린샷 파일을 작게 유지하세요. 패키지를 다운로드할 때마다 모든 스크린샷 파일이 포함돼요.

Pub.dev는 첫 번째 스크린샷에서 패키지의 썸네일 이미지를 생성해요. 이 스크린샷이 애니메이션이면 pub.dev는 첫 프레임을 사용해요.

Topics

패키지 작성자는 topics 필드로 패키지를 분류할 수 있어요. 주제는 pub.dev에서 필터로 검색할 때 발견 가능성을 높이는 데 사용될 수 있어요. Pub.dev는 패키지 페이지와 검색 결과에 주제를 표시해요.

이 필드는 이름의 목록으로 구성돼요. 예를 들어:

topics:
  - network
  - http

Pub.dev는 주제가 다음 사양을 따르도록 요구해요.

• 각 패키지에 최대 5개의 주제를 태그하세요.

• 주제 이름을 다음 요구사항에 따라 작성하세요.

  • 2~32자 사이를 사용하세요.
  • 소문자 영숫자나 하이픈(a-z, 0-9, -)만 사용하세요.
  • 연속된 두 하이픈(--)은 사용하지 마세요.
  • 이름을 소문자 알파벳(a-z)으로 시작하세요.
  • 영숫자(a-z 또는 0-9)로 끝내세요.

주제를 고를 때는 기존 주제가 관련 있는지 고려하세요. 기존 주제로 태그하면 사용자들이 여러분의 패키지를 발견하는 데 도움이 돼요.

참고

Pub.dev는 중복을 피하고 주제별 발견을 개선하기 위해 주제의 다른 표기들을 표준(canonical) 주제로 병합해요.

GitHub에서 topics.yaml 파일을 편집하는 풀 리퀘스트를 열어 표준 주제 목록과 그 별칭에 기여할 수 있어요.

ignored_advisories

패키지가 보안 권고의 영향을 받는 의존성을 가지고 있다면, pub은 의존성 해석 중에 그 권고에 대해 경고해요. 패키지 작성자는 ignored_advisories 필드를 패키지와 관련이 없는 트리거된 권고의 허용 목록으로 사용할 수 있어요.

권고에 대한 경고를 숨기려면 ignored_advisories 목록에 권고 식별자를 추가하세요. 예를 들어:

name: myapp
dependencies:
  foo: ^1.0.0
ignored_advisories:
  - GHSA-4rgh-jx4f-qfcq

자세한 내용은 보안 권고 문서를 확인하세요.

Hooks

네이티브 빌드나 링크 훅 같은 패키지별 훅을 구성하려면 hooks 필드를 사용하세요. hooks 필드 아래에서 훅이 실행되는 방식을 사용자 정의하는 매개변수를 구성해요.

예를 들어:

hooks:
  user_defines:
    my_package:
      enable_experimental: true

훅 구성에 대해 더 알아보려면 훅 구성 문서를 확인하세요.

SDK constraints

패키지는 의존성의 어떤 버전을 지원하는지 지정할 수 있지만, 패키지에는 또 다른 암묵적인 의존성이 있어요: 바로 Dart 플랫폼 자체예요. Dart 플랫폼은 시간이 지나며 진화하고, 패키지는 플랫폼의 특정 버전에서만 동작할 수 있어요.

패키지는 SDK constraint 로 이런 버전을 지정할 수 있어요. 이 제약은 pubspec의 별도 최상위 environment 필드 안에 들어가며, 의존성과 같은 버전 제약 구문을 사용해요.

버전 참고

패키지가 2.0 이후에 도입된 기능을 사용하려면, 그 pubspec은 기능이 도입된 시점 이상인 하한 제약을 가져야 해요. 자세한 내용은 언어 버전 관리 문서를 확인하세요.

예를 들어 다음 제약은 이 패키지가 버전 3.0.0 이상의 어떤 Dart SDK와도 동작한다고 말해요.

environment:
  sdk: ^3.0.0

pub은 사용자가 설치한 Dart SDK 버전과 호환되는 SDK 제약을 가진 패키지의 최신 버전을 찾으려고 해요.

SDK 제약을 생략하는 것은 오류예요. pubspec에 SDK 제약이 없으면 dart pub get이 다음과 같은 메시지와 함께 실패해요.

pubspec.yaml has no lower-bound SDK constraint.
You should edit pubspec.yaml to contain an SDK constraint:

environment:
  sdk: '^3.2.0'

See https://dart.dev/go/sdk-constraint

버전 참고

Dart 2.19 이전에는 pub이 SDK 제약에서 캐럿(caret) 구문을 허용하지 않았어요. 이전 버전에서는 '>=2.12.0 <3.0.0' 같은 완전한 범위를 제공하세요. 자세한 내용은 캐럿 구문 문서를 확인하세요.

Flutter SDK constraints

pub은 environment: 필드 아래에 Flutter SDK 제약을 지정하는 것을 지원해요.

environment:
  sdk: ^3.2.0
  flutter: '>=3.22.0'

Flutter SDK 제약은 pub이 flutter 실행 파일의 컨텍스트에서 실행 중이고 Flutter SDK의 version 파일이 제약의 하한을 충족할 때만 충족돼요. 그렇지 않으면 패키지가 선택되지 않아요.

참고

Flutter SDK는 flutter 제약의 하한만 강제해요. 더 알아보려면 flutter/flutter 저장소의 issue #95472을 확인하세요.

Flutter SDK 제약이 있는 패키지를 게시하려면, 최소 1.19.0 이상의 최소 버전을 가진 Dart SDK 제약을 지정해야 해요. 이렇게 해야 이전 버전의 pub이 Flutter가 필요한 패키지를 실수로 설치하지 않아요.

더 알아보기

• 패키지 의존성 — pubspec에서 의존성·버전 제약 선언 방식.
• 패키지 레이아웃 관례 — 패키지 파일·디렉터리 구성.
• 보안 권고 — ignored_advisories와 보안 취약점.
• 버전 관리 — 버전과 SDK 제약의 철학.