Go Wiki: PackagePublishing

引言

现在您已经花了大量时间编写、调试和测试您的软件包（您确实进行了测试，不是吗？），您想发布它，以便其他人可以 go get 您的软件包。

首先，您需要将其托管在某个地方。三个主要的源代码托管站点是 bitbucket (hg/git)，GitHub (git) 和 launchpad (bzr)。我建议选择您熟悉的任何版本控制系统，或者您本地机器上已经使用该系统进行版本控制的代码。Git (git) 是 Go 核心存储库使用的版本控制系统，因此它提供了最接近的保证，即希望使用您项目的开发者将拥有正确的软件。如果您从未用过版本控制，这些网站有一些很好的指南，您可以通过搜索 Google “{name} tutorial” 来找到很多优秀的教程，其中 {name} 是您想学习的版本控制系统的名称。

软件包设置

选择导入路径

您的软件包的完整导入路径通常包含标识其作者的信息（尤其是在 GitHub 等托管网站上，“github.com/kylelemons/…” 是完整导入路径），应始终包含项目名称，并且如果您的开发包名称与项目名称不同，则应以您的开发包名称结尾。例如，go-gypsy 项目提供了一个 yaml 包，由 Kyle Lemons 编写，因此具有以下导入路径：

import "github.com/kylelemons/go-gypsy/yaml"
             ^         ^          ^     ^
             |         |          |     `-- Package name
             |         |          `-------- Project name
             |         `------------------- Author's handle
             `----------------------------- Hosting site

Go >= version 1 支持软件包存储库的子目录。

子目录

通常，您为软件包使用的名称可能包含“Go”作为前缀、后缀或其缩写的一部分，您可能希望或不希望这成为实际命令或 go 源文件中的软件包名称的一部分。通常，您的软件包中可能包含库和命令，它们不能共存于同一个目录中。当发生这种情况时，您需要使用子目录来构建您的存储库。

例如，考虑一个名为“Go-PublishingExample”的项目，它提供了一个“epub”软件包和一个“publish”命令。目录结构可以是：

./epub/      # Package source, all files package "epub"
./publish/   # Command source
./doc/       # Documentation which won't be downloaded
./examples/  # Example code which won't be downloaded

软件包的导入语句将是：

import "codesite.tld/authorName/Go-PublishingExample/epub"

通常，最好确保最后一个目录路径（在本例中为“epub”）与目录中源文件使用的软件包名称匹配。在这种情况下，根目录中不包含任何可 go get 的文件，因为二进制文件或软件包都不命名为“Go-PublishingExample”。

分支和标签

请注意，本节已过时。 下面的伪版本号适用于 Go < version 1；此外，Go 存储库本身现在使用 Git 而非 Mercurial。也许我们应该删除本节。

您可以使用“go help get”和“go help importpath”获取 go get 的最新信息。

总的来说，Go 源代码树可以存在于三种基本状态。它可以检出到 Go Release 分支（在撰写本文时是 r60 (在 Google Code 上) - 这是大多数用户应该使用的），或者它可以检出到 Go Weekly（大致每周创建一个新标签），或者检出到 tip（Mercurial 中最新更改的术语）。后两者主要供 Go 语言本身的开发者或需要最新版本中尚未引入的特性或修复的开发者使用。

考虑到您可能会与团队在尚未准备好公开发布的代码上继续协作，建议您利用版本控制系统的标签或分支功能。go get 工具支持一些特殊的标签和分支，您可能希望使用它们来确保用户获得兼容版本的软件包。

  go.r60               -- A "go.r##" tag will be checked out if the user has that Go release installed
  go.weekly.2011-07-19 -- A "go.weekly.YYYY-MM-DD" tag will be checked out if the user has that weekly installed

如果安装的标签不匹配，go get 会尝试回退到上一个标签，如果没有找到，则默认安装 tip。

在 Mercurial 中创建和维护您的发布标签：

## Create or update a release tag
hg tag myProj-v0.0 # tag an easy-to-remember version number if you wish
hg tag go.r60 # tag this as being go release.r60 compatible

在 Git 中创建和维护发布分支：

## Create a release branch
git tag myProj-v0.0     # Tag an easy-to-remember version number if you wish
git checkout -b go.r60  # create a release branch
git checkout master     # to switch back to your master branch

## Update the release branch
git checkout go.r60  # switch to the release branch
git merge master     # merge in changes from the master branch since last release
git checkout master  # switch back to master branch

如果您使用其他分支名称，请将这些名称替换到相应的位置。

通常不需要维护每周标签或分支，但维护发布分支或标签可能非常有益，因为这将确保您的项目获得最广泛的受众。

命令与软件包

由于 go get 不使用您项目的 Makefiles，因此了解它将如何实际构建您的项目非常重要。

同一个目录中的所有文件应始终共享相同的软件包名称。任何命名带有 `_test` 或 `_os` 和/或 `_arch` 后缀的文件都将被忽略（除非 os/arch 匹配）。如果软件包名称是“main”，go get 将从源文件构建一个可执行文件，并根据目录名称（仅使用最后一个路径段）对其进行命名。如果软件包名称是其他任何名称，go get 将将其构建为软件包，导入路径将是您项目根目录的 Web 可访问 URL，后跟子目录。有关如何为除主要四个网站之外的代码托管站点创建导入路径的信息，请参阅 go get 文档。

同一项目中的软件包之间的依赖关系很常见。当您项目中的某个软件包或命令依赖于另一个软件包或命令时，您必须使用完整的导入路径，以便 go get 能够识别该依赖关系并确保其被构建。如果您的项目中的源文件导入了第三方软件包，go get 也会自动下载并安装这些第三方软件包（如果它们尚未安装）。

为了重用上面的示例，文件 `./publish/main.go` 可能看起来像这样：

package main

import (
    "flag"
)

import "codesite.tld/authorName/Go-PublishingExample/epub"

var dir = flag.String("dir", ".", "Directory to publish")

func main() {
    flag.Parse()
    epub.Publish(*dir)
}

想要安装此可执行文件的用户将执行：

go get codesite.tld/authorName/Go-PublishingExample/publish

由于依赖关系，这也会安装 `".../epub"` 软件包。仅想安装库的开发者可以执行：

go get codesite.tld/authorName/Go-PublishingExample/epub

（如果他们尚未安装 `publish`），并且只会下载并安装软件包。请注意，在任何这些情况下，示例或文档都不会被下载；在大多数情况下，它们都可以通过代码网站进行浏览。

文档

godoc

当您准备发布软件包时，您应该通过运行本地 godoc 副本来确保文档看起来正确。如果您的软件包已安装到 go 软件包树中，您可以使用以下命令：

  godoc -http=:6060 &

然后浏览到 https://:6060/pkg/ 并找到您的软件包。

Dashboard

Go Dashboard 将使用您的软件包级别注释的第一行（也使用普通的 godoc 格式）作为“info”文本，因此请确保已设置。例如：

// Package epub is an example publishing library.
package epub

有关 godoc 的更多信息，请参阅 Documenting Go Code 博客文章。

此内容是 Go Wiki 的一部分。

go.dev 使用 Google 的 cookie 来提供和增强其服务质量并分析流量。 了解更多。