dart pub global로 패키지를 전역에서 실행하기

dart pub global 명령어를 쓰면 pub.dev 사이트에 호스팅된 Dart 스크립트를 커맨드라인에서 실행할 수 있어요. 패키지를 활성화하고, 스크립트를 실행하고, 비활성화하는 과정을 하나씩 살펴볼게요.

출처: dart pub global

본문

이전 명령어 안내: dart pub global에 대한 지원은 레거시예요. 권장되는 AOT 컴파일 방식의 대안은 dart install로, 자체 포함된 바이너리를 만들고 네이티브 빌드 훅(hook/build.dart)을 지원하며 더 빨리 시작돼요. dart install은 Dart 3.10 이상이 필요하다는 점을 기억하세요. 마이그레이션 참고: dart install은 바이너리를 ~/.pub-cache/bin/ 대신 $DART_DATA_HOME/install/bin/에 배치해요. PATH도 그에 맞게 갱신해 주세요. 게다가 dart install은 네이티브 실행 파일을 만들기 때문에 런타임에 Dart VM 옵션을 더 이상 전달할 수 없어요.

dart pub global은 pub 도구의 명령어 중 하나예요. pub의 global 옵션을 쓰면 패키지 안에 있지 않아도 커맨드라인에서 Dart 스크립트를 실행할 수 있어요. 패키지를 활성화하면 그 패키지의 bin 디렉터리에 있는 스크립트를 실행할 수 있고, 비활성화하면 전역으로 사용 가능한 패키지 목록에서 제거돼요.

예를 들어 webdev를 사용해서 Dart 웹 애플리케이션을 커맨드라인에서 서빙하고 싶다고 해볼게요.

$ dart pub global activate webdev
$ webdev serve

이게 동작하지 않는다면 PATH를 설정해야 할 수 있어요. 패키지 안에서 또는 패키지가 의존하는 패키지에서 Dart 스크립트를 실행하려면 dart run을 참고해 주세요.

패키지 활성화하기

dart pub global activate [--noexecutables] [--executable=<name>] [--overwrite] <package> [version-constraint]

패키지의 실행 파일 중 하나 이상을 커맨드라인에서 실행하고 싶을 때 패키지를 활성화해요. pub.dev 사이트에 있는 패키지나 Git 저장소, 또는 로컬 머신에 있는 패키지를 활성화할 수 있어요. 패키지를 활성화한 뒤에는 스크립트 실행 방법을 참고해서 패키지의 bin 디렉터리에서 스크립트를 실행하면 돼요.

패키지를 활성화할 때 선택적으로 버전 제약을 지정할 수 있어요. 사용 예시는 constraint 플래그를 참고해 주세요. dart install은 dart pub global activate의 더 새로운 대안이에요.

pub.dev 사이트의 패키지 활성화하기

$ dart pub global activate <pub.dev package>

pub.dev 사이트의 패키지를 지정해서 활성화해요. 예를 들어:

$ dart pub global activate markdown

Git으로 활성화하기

$ dart pub global activate --source git <Git URL>
$ dart pub global activate -sgit <Git URL>

--source git(줄여서 -sgit)을 사용해 Git 저장소에 있는 패키지를 활성화해요. 아래 예시들은 GitHub에 있는 async_await 패키지를 활성화하며, 서로 동일해요.

$ dart pub global activate --source git https://github.com/dart-lang/async_await.git
$ dart pub global activate -sgit https://github.com/dart-lang/async_await.git

pub은 패키지가 Git 저장소의 루트에 있기를 기대해요. 다른 위치를 지정하려면 --git-path 옵션에 저장소 루트를 기준으로 한 상대 경로를 넘겨주세요.

$ dart pub global activate -sgit https://github.com/dart-lang/http.git --git-path pkgs/http/

pub은 Git 저장소의 기본 브랜치를 사용해요. 다른 브랜치나 커밋을 지정하려면 --git-ref 옵션을 사용해요.

$ dart pub global activate -sgit https://github.com/dart-lang/http.git --git-ref 36f98e900347335af2338a0e087538009b7de2f9

로컬 머신의 패키지 활성화하기

$ dart pub global activate --source path <path>

activate --source path <path>를 사용해 로컬 머신의 패키지를 활성화해요. 다음 예시는 ~/dart 디렉터리에서 stopwatch 패키지를 활성화해요.

$ dart pub global activate --source path ~/dart/stopwatch

활성화한 패키지 갱신하기

패키지를 활성화한 뒤에는, 그 패키지를 다시 활성화해서 업그레이드할 수 있어요.

스크립트 실행하기

활성화한 패키지의 스크립트를 커맨드라인에서 직접 실행할 수 있어요. 직접 실행할 수 없다면 dart pub global run을 사용할 수도 있어요.

PATH에서 스크립트 실행하기

커맨드라인에서 스크립트를 직접 실행하려면 시스템 캐시의 bin 디렉터리를 PATH 환경 변수에 추가해 주세요. 예를 들어 webdev 패키지를 활성화했는데도 여전히 명령어가 실행되지 않는다면:

$ dart pub global activate webdev
$ webdev serve
-bash: webdev: command not found

시스템 캐시의 bin 디렉터리가 PATH에 있는지 확인해 보세요. macOS에서 시스템 캐시를 포함하는 PATH 변수의 예시는 다음과 같아요.

$ echo $PATH
/Users/<user>/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/Users/<user>/.pub-cache/bin

이 디렉터리가 PATH에 없다면, 여러분의 플랫폼에 맞는 위치를 찾아서 추가해 주세요. 시스템 캐시의 정확한 위치는 Windows 버전에 따라 달라질 수 있어요. 이제 명령어를 직접 호출할 수 있어요.

$ cd web_project
$ webdev serve

그래도 스크립트가 커맨드라인에서 실행되지 않는다면, 패키지가 이 기능을 위해 구성되지 않았을 수 있어요. 그래도 dart pub global run으로 스크립트를 실행할 수는 있어요.

dart pub global run으로 스크립트 실행하기

$ dart pub global run <package>:<executable> [args...]

스크립트가 커맨드라인 실행용으로 구성되지 않았어도 dart pub global run을 사용할 수 있어요. 다음 명령어는 foo 패키지의 bin/bar.dart 스크립트를 두 개의 인자를 넘겨 실행해요.

$ dart pub global run foo:bar arg1 arg2

패키지 실행 파일 구성하기

패키지 개발자가 아니라면 이 부분은 건너뛰어도 돼요. 패키지는 자신의 스크립트 중 일부를 커맨드라인에서 직접 실행 가능한 실행 파일로 노출할 수 있어요. 그 스크립트들은 pubspec 파일의 executables 항목에 나열돼 있어야 해요. 예를 들어 다음 pubspec 파일은 helloworld 패키지에서 bin/helloworld.dart를 실행 파일로 지정해요.

name: helloworld
executables:
  helloworld:

스크립트를 executables 태그에 나열하지 않으면 그 스크립트의 사용성이 떨어져요. 나열되지 않은 스크립트는 dart pub global run으로는 실행할 수 있어도 커맨드라인에서 직접 실행할 수는 없어요.

패키지 비활성화하기

$ dart pub global deactivate <package>

deactivate를 사용해 패키지를 사용 가능한 전역 패키지 목록에서 제거해요. 예를 들어:

$ dart pub global deactivate markdown

이제 그 패키지의 스크립트를 dart pub global run이나 커맨드라인에서 더 이상 호출할 수 없어요.

활성 패키지 목록 보기

$ dart pub global list

list를 사용해 현재 활성화된 모든 패키지를 나열해요.

옵션 (Options)

모든 pub 명령어에 적용되는 옵션은 글로벌 옵션 문서에서 확인할 수 있어요.

[version-constraint]

dart pub global activate <package> [version-constraint]을 사용해 패키지의 특정 버전을 지정할 수 있어요. 예를 들어 다음 명령어는 markdown 패키지의 0.6.0 버전을 가져와요.

$ dart pub global activate markdown 0.6.0

범위를 지정하면 pub은 그 제약을 만족하는 가장 좋은 버전을 골라요. 예를 들어:

$ dart pub global activate foo <3.0.0

--no-executables

dart pub global activate <package> --no-executables을 사용해 지정한 패키지를 전역으로 활성화하되, bin에 아무 실행 파일도 넣지 않아요. 실행 파일을 실행하려면 dart pub global run을 사용해야 해요.

--executable= 또는 -x

dart pub global activate와 함께 사용해 지정한 실행 파일을 PATH에 추가해요. 이 플래그는 여러 개 넘길 수 있어요. 예를 들어 다음 명령어는 foo가 정의할 수 있는 다른 실행 파일을 제외하고 bar와 baz만 PATH에 추가해요.

$ dart pub global activate foo -x bar -x baz

--overwrite

dart pub global activate <package> --overwrite을 사용해 이전에 활성화한 같은 이름의 전역 실행 파일을 덮어써요. 이 플래그를 지정하지 않으면 기존 실행 파일은 교체되지 않아요. 자세한 문제 해결 방법은 pub 문제 해결 가이드를 확인해 주세요.

더 알아보기

dart run — 패키지 내부/의존 패키지의 스크립트 실행하기
dart install — AOT 컴파일된 바이너리를 만드는 새 명령어 살펴보기