目录

Contents

pub global 命令

Global 命令是 Pub 工具 中的一个命令。

Global is one of the commands of the pub tool.

Pub 的 global 选项允许你在任意位置下从命令行运行 Dart 脚本。在 激活 Package 后,你可以 运行 该 Package bin 目录下的脚本。停用 Package 后你可以从全局可用的 Package 列表中将其移除。

Pub’s global option allows you to run Dart scripts from the command line when you are not currently inside a package. After activating a package, you can run scripts from that package’s bin directory. Deactivating a package removes it from your list of globally available packages.

例如,假设你想要从命令行运行 Dart 项目生成的 Stagehand

For example, say you want to run Stagehand the Dart project generator, from the command line.

$ pub global activate stagehand
$ stagehand

如果该操作无效,你可能需要 设置你的路径

If this doesn’t work, you might need to set up your path.

如果想要从 Package 中运行 Dart 脚本,或者从 Package 所依赖的其它 Package 中运行脚本,请查阅 pub run 命令。

To run a Dart script from within a package, or from a package that your package depends on, see pub run.

Package 激活

Activating a package

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

当你想从命令行运行某个 Package 中的可执行对象时你需要先激活它。该 Package 可以是在 pub.dev 网站、Git 仓库或者你当前设备上。一旦你激活了 Package,就可以参阅 Running a script 运行位于 Package bin 目录下的脚本。

Activate a package when you want to be able to run one or more of its executable files from the command line. You can activate packages that live on the pub.dev site, a Git repository, or your local machine. Once you’ve activated a package, see Running a script to run scripts from the package’s bin directory.

你可以在激活 Package 时指定一个可选的版本限制参数。关于其使用示例请查阅 版本限制参数

When you activate a package you can specify an optional version constraint. See the constraint flag for usage examples.

激活 pub.dev 网站上的 Package

Activating a package on the pub.dev site

$ pub global activate <pub.dartlang package>

激活 pub.dev 网站上的一个 Package。例如:

Specify a package on the pub.dev site to activate it. For example:

$ pub global activate markdown

激活 Git 仓库中的 Package

Activating a package with Git

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

使用 --source git(或 -sgit 简写)命令参数可以激活位于 Git 仓库中的 Package。下面的两个示例都可以用于激活位于 GitHub 网站上名为 async_await 的 Package。

Use --source git (or -sgit, for short) to activate a package in a Git repository. The following examples, which activate the async_await package on GitHub, are equivalent:

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

激活当前设备上的 Package

Activating a package on your local machine

$ pub global activate --source path <path>

使用 activate --source path <path> 命令参数激活当前设备上的 Package。下面的示例激活了位于 ~/dart 目录下名为 stopwatch 的 Package。

Use activate --source path <path> to activate a package on your local machine. The following example activates the stopwatch package from the ~/dart directory:

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

更新已经激活的 Package

Updating an activated package

你可以再次激活一个已经激活的 Package 以更新它。

Once a package has been activated, you can upgrade it by activating the package again.

运行脚本

Running a script

你可以从命令行直接运行已激活 Package 中的脚本。如果你不能直接运行脚本,可以尝试使用 pub global run 命令。

You can directly run a script from an activated package from the command line. If you are unable to run the script directly, you can also use pub global run.

运行指定路径中的脚本

Running a script from your PATH

在从命令行直接运行脚本前,你还需要将 系统缓存bin 文件目录添加至 PATH 路径中。

To run a script directly from the command line, add the system cache bin directory to your PATH environment variable.

例如,假设你已经激活了名为 Stagehand 的包,但是你依然不能运行它:

For example, say you’ve activated the Stagehand package, but you still can’t run the command:

$ pub global activate stagehand
$ stagehand
-bash: stagehand: command not found

此时你需要确认 Pub 系统缓存的 bin 目录是否已经添加至 PATH 路径中。例如在 macOS 上,使用下述命令可以查看你的 PATH 路径是否已经包含了 Pub 系统缓存的 bin 目录:

Verify that the bin directory for the system cache is in your path. The following PATH variable, on macOS, includes the system cache:

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

如果 PATH 路径中没有添加 Pub 缓存目录,你需要根据你当前设备的系统平台找到对应的 Pub 缓存目录并将之添加。

If this directory is missing from your PATH, locate the file for your platform and add it.

Platform Cache location
平台 缓存位置
macOS or Linux $HOME/.pub-cache/bin
macOS 或 Linux $HOME/.pub-cache/bin
Windows* %LOCALAPPDATA%\Pub\Cache\bin

* 对于不同版本的 Windows 系统,Pub 系统缓存的确切位置可能有所不同。

* The exact location of the system cache may vary for different versions of Windows.

现在你可以直接调用命令了:

You can now directly invoke the command:

$ mkdir angular_project
$ cd angular_project
$ stagehand web-angular

如果此时从命令行运行脚本依然失败,则 Package 可能没有针对此功能进行 配置。但你仍然可以使用 pub global run 命令运行它。

If the script still fails to run from the command line, the package may not be configured for this feature. You can still run the script using pub global run.

使用 pub global run 命令运行脚本

Running a script using pub global run

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

即使某个脚本没有配置成可以从命令行运行,你依然可以使用 pub global run 命令运行它。下述命令传递两个参数从名为 foo 的 Package 运行 bin/bar.dart 脚本。

Even if a script is not configured to be run from the command line, you can still use pub global run. The following command runs the bin/bar.dart script from the foo package, passing in two arguments.

$ pub global run foo:bar arg1 arg2

配置 Package 为可运行的

Configuring package executables

如果你不是一个 Package 开发者,你可以跳过本节。

If you are not a package developer, you can skip this section.

Package 可以暴露它的一些脚本以直接从命令行运行。这些脚本必须在 pubspec 文件的 executables 标签下列出。例如,下述名为 helloworld 的 Package 在其 pubspec 文件中将 bin/helloworld.dart 暴露为可以运行:

A package can expose some of its scripts as executables that can be run directly from the command line. The script or scripts must be listed in the executables entry of the pubspec file. For example, the following pubspec file identifies bin/helloworld.dart as an executable for the helloworld package:

name: helloworld

executables:
  helloworld:

没有在 executables 标签下列出的脚本可能会降低脚本的易用性:这些脚本虽然可以使用 pub global run 命令运行,但是不能直接从命令行运行。

Failing to list a script under the executables tag reduces the script’s usability: unlisted scripts can be executed using pub global run, but not directly from the command line.

停用 Pacakge

Deactivating a package

$ pub global deactivate <package>

使用 deactivate 命令参数可以将 Package 从全局可用的 Package 列表移除。例如:

Use deactivate to remove a package from the list of available global packages. For example:

$ pub global deactivate markdown

此时你不能使用 pub global run 命令或从命令行运行该 Package 的脚本。

You can no longer invoke the package’s scripts using pub global run, or at the command line.

列出激活的 Package

Listing active packages

$ pub global list

使用 list 列出当前所有已激活的 Package。

Use list to list all currently active packages.

选项

Options

你可以查阅 全局选项 获取 Pub 命令所支持的命令选项。

For options that apply to all pub commands, see Global options.

<constraint>
Optional for pub global activate. The constraint allows you to pull in a specific version of the package. For example, the following command pulls the 0.6.0 version of the markdown package:

<版本限制参数>pub global activate 命令的可选选项。使用版本限制参数可以允许你拉取 Package 的指定版本。例如,下述命令会拉取 markdown 这个 Package 的 0.6.0 版本:

  $ pub global activate markdown 0.6.0

如果你指定的是一个范围,Pub 则会在这个范围内选取一个最适合的版本。例如:

If you specify a range, pub picks the best version that meets that constraint. For example:

  $ pub global activate foo <3.0.0
--executable=<name> or -x<name>
Optional for pub global activate. Adds the specified executable to your PATH. You can pass more than one of these flags. For example, the following command adds bar and baz (but not any other executables that foo might define) to your PATH.
$ pub global activate foo -x bar -x baz

--executable=<name>-x<name>pub global activate 命令的可选选项。将指定的可执行对象添加至你的 PATH 路径中。你可以在一次命令执行中多次使用该选项以添加多个可执行对象到你的 PATH 路径中。例如,下述命令添加了 foo 中的 barbaz 两个可执行对象(不包括 foo 中定义的其它可执行对象)到你的 PATH 中。

--no-executables
Optional for pub global activate. Globally activates the package but doesn’t put any executables in bin. You have to use pub global run to run any executables.

--no-executablespub global activate 命令的可选选项。会在全局范围内激活 Package 但不会在 bin 目录下生成任何文件。你必须使用 pub global run 来运行任意这些可执行的对象。

--overwrite
Optional for pub global activate. Normally, if executables from two global packages have a name collision, the preexisting executable wins. If you specify this flag, the new executable overwrites the previously activated executable.

--overwritepub global activate 命令的可选选项。默认情况下,如果执行的两个全局 Package 名字冲突了,那么会优先执行最先执行过的那个。但是如果你指定该标识,那么新执行的 Package 则会覆盖之前执行的那些。