diff options
Diffstat (limited to 'debian/man')
| -rw-r--r-- | debian/man/go-build.1 | 80 | ||||
| -rw-r--r-- | debian/man/go-clean.1 | 82 | ||||
| -rw-r--r-- | debian/man/go-doc.1 | 35 | ||||
| -rw-r--r-- | debian/man/go-env.1 | 21 | ||||
| -rw-r--r-- | debian/man/go-fix.1 | 25 | ||||
| -rw-r--r-- | debian/man/go-fmt.1 | 37 | ||||
| -rw-r--r-- | debian/man/go-get.1 | 59 | ||||
| -rw-r--r-- | debian/man/go-install.1 | 28 | ||||
| -rw-r--r-- | debian/man/go-list.1 | 104 | ||||
| -rw-r--r-- | debian/man/go-packages.7 | 66 | ||||
| -rw-r--r-- | debian/man/go-path.7 | 77 | ||||
| -rw-r--r-- | debian/man/go-remote.7 | 166 | ||||
| -rw-r--r-- | debian/man/go-run.1 | 24 | ||||
| -rw-r--r-- | debian/man/go-test.1 | 75 | ||||
| -rw-r--r-- | debian/man/go-testflag.7 | 87 | ||||
| -rw-r--r-- | debian/man/go-testfunc.7 | 63 | ||||
| -rw-r--r-- | debian/man/go-tool.1 | 26 | ||||
| -rw-r--r-- | debian/man/go-version.1 | 13 | ||||
| -rw-r--r-- | debian/man/go-vet.1 | 35 | ||||
| -rw-r--r-- | debian/man/go.1 | 66 | ||||
| -rw-r--r-- | debian/man/godoc.1 | 209 | ||||
| -rw-r--r-- | debian/man/gofmt.1 | 108 |
22 files changed, 1486 insertions, 0 deletions
diff --git a/debian/man/go-build.1 b/debian/man/go-build.1 new file mode 100644 index 000000000..6e1794c7d --- /dev/null +++ b/debian/man/go-build.1 @@ -0,0 +1,80 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-BUILD 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go build +.RB [\|\-o +.IR output \|] +.RB [ +.IR "build flags" +.RB ] +.RB [ +.IR packages +.RB ] +.SH DESCRIPTION +Build compiles the packages named by the import paths, +along with their dependencies, but it does not install the results. + +If the arguments are a list of .go files, build treats them as a list +of source files specifying a single package. + +When the command line specifies a single main package, +build writes the resulting executable to output. +Otherwise build compiles the packages but discards the results, +serving only as a check that the packages can be built. + +The \-o flag specifies the output file name. If not specified, the +name is packagename.a (for a non-main package) or the base +name of the first source file (for a main package). +.SH OPTIONS +The build flags are shared by the build, install, run, and test commands: +.TP +.B \-a +force rebuilding of packages that are already up-to-date. +.TP +.B \-n +print the commands but do not run them. +.TP +.B \-p n +the number of builds that can be run in parallel. The default is the number of CPUs available. +.TP +.B \-v +print the names of packages as they are compiled. +.TP +.B \-work +print the name of the temporary work directory and do not delete it when exiting. +.TP +.B \-x +print the commands. +.TP +.B \-compiler name +name of compiler to use, as in runtime.Compiler (gccgo or gc) +.TP +.B \-gccgoflags 'arg list' +arguments to pass on each gccgo compiler/linker invocation +.TP +.B \-gcflags 'arg list' +arguments to pass on each 5g, 6g, or 8g compiler invocation +.TP +.B \-ldflags 'flag list' +arguments to pass on each 5l, 6l, or 8l linker invocation +.TP +.B \-tags 'tag list' +a list of build tags to consider satisfied during the build. +See the documentation for the go/build package for +more information about build tags. +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.P +For more about where packages and binaries are installed, see \fBgo-gopath\fP(1). + +.SH SEE ALSO +.BR go-install (1), +.BR go-get (1), +.BR go-clean (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-clean.1 b/debian/man/go-clean.1 new file mode 100644 index 000000000..bff689e2a --- /dev/null +++ b/debian/man/go-clean.1 @@ -0,0 +1,82 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-CLEAN 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go clean +.RB [\|\-i\|] +.RB [\|\-r\|] +.RB [\|\-n\|] +.RB [\|\-x\|] +.RB [ +.IR packages +.RB ] +.SH DESCRIPTION +Clean removes object files from package source directories. +The go command builds most objects in a temporary directory, +so go clean is mainly concerned with object files left by other +tools or by manual invocations of go build. + +Specifically, clean removes the following files from each of the +source directories corresponding to the import paths: + +.TP +.B _obj/ +old object directory, left from Makefiles +.TP +.B _test/ +old test directory, left from Makefiles +.TP +.B _testmain.go +old gotest file, left from Makefiles +.TP +.B test.out +old test log, left from Makefiles +.TP +.B build.out +old test log, left from Makefiles +.TP +.B *.[568ao] +object files, left from Makefiles + +.TP +.B DIR(.exe) +from go build +.TP +.B DIR.test(.exe) +from go test \-c +.TP +.B MAINFILE(.exe) +from go build MAINFILE.go +.P +In the list, DIR represents the final path element of the +directory, and MAINFILE is the base name of any Go source +file in the directory that is not included when building +the package. +.SH OPTIONS +.TP +.B \-i +The \-i flag causes clean to remove the corresponding installed +archive or binary (what 'go install' would create). + +.TP +.B \-n +The \-n flag causes clean to print the remove commands it would execute, +but not run them. + +.TP +.B \-r +The \-r flag causes clean to be applied recursively to all the +dependencies of the packages named by the import paths. + +.TP +.B \-x +The \-x flag causes clean to print remove commands as it executes them. +.P +For more about specifying packages, see \fBgo-packages\fP(7). + +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-doc.1 b/debian/man/go-doc.1 new file mode 100644 index 000000000..cf20d784d --- /dev/null +++ b/debian/man/go-doc.1 @@ -0,0 +1,35 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-DOC 1 "2012-06-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go doc +.RB [\|\-n\|] +.RB [\|\-x\|] +.RB [ +.IR packages +.RB ] +.SH DESCRIPTION +Doc runs the godoc command on the packages named by the +import paths. +.P +For more about godoc, see 'godoc godoc'. +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.P +To run godoc with specific options, run godoc itself. +.SH OPTIONS +.TP +.B \-n +The \-n flag causes tool to print the command that would be +executed but not execute it. +.TP +.B \-x +The \-x flag causes clean to print remove commands as it executes them. +.SH SEE ALSO +.BR godoc (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-env.1 b/debian/man/go-env.1 new file mode 100644 index 000000000..48a506dcd --- /dev/null +++ b/debian/man/go-env.1 @@ -0,0 +1,21 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-ENV 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go env +.RB [ +.IR "var ..." +.RB ] +.SH DESCRIPTION +Env prints Go environment information. + +By default env prints information as a shell script +(on Windows, a batch file). If one or more variable +names is given as arguments, env prints the value of +each named variable on its own line. +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-fix.1 b/debian/man/go-fix.1 new file mode 100644 index 000000000..ed368882d --- /dev/null +++ b/debian/man/go-fix.1 @@ -0,0 +1,25 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-FIX 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go fix +.RB [ +.IR packages +.RB ] +.SH DESCRIPTION +Fix runs the Go fix command on the packages named by the import paths. +.P +For more about fix, see 'godoc fix'. +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.P +To run fix with specific options, run 'go tool fix'. +.SH SEE ALSO +.BR go-fmt (1), +.BR go-vet (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-fmt.1 b/debian/man/go-fmt.1 new file mode 100644 index 000000000..fc555b821 --- /dev/null +++ b/debian/man/go-fmt.1 @@ -0,0 +1,37 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-FMT 1 "2012-06-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go fmt +.RB [\|\-n\|] +.RB [\|\-x\|] +.RB [ +.IR packages +.RB ] +.SH DESCRIPTION +Fmt runs the command 'gofmt \-l \-w' on the packages named +by the import paths. It prints the names of the files that are modified. +.P +For more about gofmt, see 'godoc gofmt'. +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.P +To run gofmt with specific options, run gofmt itself. +.SH OPTIONS +.TP +.B \-n +The \-n flag causes tool to print the command that would be +executed but not execute it. +.TP +.B \-x +The \-x flag causes clean to print remove commands as it executes them. +.SH SEE ALSO +.BR go-doc (1), +.BR go-fix (1), +.BR go-vet (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-get.1 b/debian/man/go-get.1 new file mode 100644 index 000000000..8f09ed1c8 --- /dev/null +++ b/debian/man/go-get.1 @@ -0,0 +1,59 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-GET 1 "2012-06-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go get +.RB [\|\-a\|] +.RB [\|\-d\|] +.RB [\|\-fix\|] +.RB [\|\-n\|] +.RB [\|\-p +.IR n \|] +.RB [\|\-u\|] +.RB [\|\-v\|] +.RB [\|\-x\|] +.RB [ +.IR packages +.RB ] +.SH DESCRIPTION +Get downloads and installs the packages named by the import paths, +along with their dependencies. + +When checking out or updating a package, get looks for a branch or tag that +matches the locally installed version of Go. The most important rule is that if +the local installation is running version "go1", get searches for a branch or +tag named "go1". If no such version exists it retrieves the most recent version +of the package. + +.SH OPTIONS +.TP +.B \-a, \-n, \-v, \-x, \-p +The \-a, \-n, \-v, \-x, and \-p flags have the same meaning as in 'go build' +and 'go install'. See \fBgo-build\fP(1). +.TP +.B \-d +The \-d flag instructs get to stop after downloading the packages; that is, +it instructs get not to install the packages. +.TP +.B \-fix +The \-fix flag instructs get to run the fix tool on the downloaded packages +before resolving dependencies or building the code. +.TP +.B \-u +The \-u flag instructs get to use the network to update the named packages +and their dependencies. By default, get uses the network to check out +missing packages but does not use it to look for updates to existing packages. +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.P +For more about how 'go get' finds source code to download, see \fBgo-remote\fP(7). +.SH SEE ALSO +.BR go-build (1), +.BR go-install (1), +.BR go-clean (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-install.1 b/debian/man/go-install.1 new file mode 100644 index 000000000..9e53bb2d8 --- /dev/null +++ b/debian/man/go-install.1 @@ -0,0 +1,28 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-INSTALL 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go install +.RB [ +.IR "build flags" +.RB ] +.RB [ +.IR packages +.RB ] +.SH DESCRIPTION +Install compiles and installs the packages named by the import paths, +along with their dependencies. +.P +For more about the build flags, see \fBgo-build\fP(1). +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.SH SEE ALSO +.BR go-build (1), +.BR go-get (1), +.BR go-clean (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-list.1 b/debian/man/go-list.1 new file mode 100644 index 000000000..b97c2504f --- /dev/null +++ b/debian/man/go-list.1 @@ -0,0 +1,104 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-LIST 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go list +.RB [\|\-e\|] +.RB [\|\-f +.IR format \|] +.RB [\|\-json\|] +.RB [ +.IR packages +.RB ] +.SH DESCRIPTION +List lists the packages named by the import paths, one per line. + +The default output shows the package import path: + +.Vb 6 +\& code.google.com/p/google-api-go-client/books/v1 +\& code.google.com/p/goauth2/oauth +\& code.google.com/p/sqlite +.Ve + +.SH OPTIONS + +.TP +.B \-f +The \-f flag specifies an alternate format for the list, +using the syntax of package template. The default output +is equivalent to \-f '{{.ImportPath}}'. The struct +being passed to the template is: + +.Vb 6 +\& type Package struct { +\& Dir string // directory containing package sources +\& ImportPath string // import path of package in dir +\& Name string // package name +\& Doc string // package documentation string +\& Target string // install path +\& Goroot bool // is this package in the Go root? +\& Standard bool // is this package part of the standard Go library? +\& Stale bool // would 'go install' do anything for this package? +\& Root string // Go root or Go path dir containing this package +\& +\& // Source files +\& GoFiles []string // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles) +\& CgoFiles []string // .go sources files that import "C" +\& CFiles []string // .c source files +\& HFiles []string // .h source files +\& SFiles []string // .s source files +\& SysoFiles []string // .syso object files to add to archive +\& +\& // Cgo directives +\& CgoCFLAGS []string // cgo: flags for C compiler +\& CgoLDFLAGS []string // cgo: flags for linker +\& CgoPkgConfig []string // cgo: pkg-config names +\& +\& // Dependency information +\& Imports []string // import paths used by this package +\& Deps []string // all (recursively) imported dependencies +\& +\& // Error information +\& Incomplete bool // this package or a dependency has an error +\& Error *PackageError // error loading package +\& DepsErrors []*PackageError // errors loading dependencies +\& +\& TestGoFiles []string // _test.go files in package +\& TestImports []string // imports from TestGoFiles +\& XTestGoFiles []string // _test.go files outside package +\& XTestImports []string // imports from XTestGoFiles +\& } +.Ve +.TP +.B \-json +The \-json flag causes the package data to be printed in JSON format +instead of using the template format. +.TP +.B \-e +The \-e flag changes the handling of erroneous packages, those that +cannot be found or are malformed. By default, the list command +prints an error to standard error for each erroneous package and +omits the packages from consideration during the usual printing. +With the \-e flag, the list command never prints errors to standard +error and instead processes the erroneous packages with the usual +printing. Erroneous packages will have a non-empty ImportPath and +a non-nil Error field; other information may or may not be missing +(zeroed). +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-packages.7 b/debian/man/go-packages.7 new file mode 100644 index 000000000..ab6078d48 --- /dev/null +++ b/debian/man/go-packages.7 @@ -0,0 +1,66 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-PACKAGES 7 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +Many commands apply to a set of packages: + +.Vb 6 +\& go action [packages] +.Ve + +Usually, [packages] is a list of import paths. + +An import path that is a rooted path or that begins with +a . or .. element is interpreted as a file system path and +denotes the package in that directory. + +Otherwise, the import path P denotes the package found in +the directory DIR/src/P for some DIR listed in the GOPATH +environment variable (see 'go help gopath'). + +If no import paths are given, the action applies to the +package in the current directory. + +The special import path "all" expands to all package directories +found in all the GOPATH trees. For example, 'go list all' +lists all the packages on the local system. + +The special import path "std" is like all but expands to just the +packages in the standard Go library. + +An import path is a pattern if it includes one or more "..." wildcards, +each of which can match any string, including the empty string and +strings containing slashes. Such a pattern expands to all package +directories found in the GOPATH trees with names matching the +patterns. As a special case, x/... matches x as well as x's subdirectories. +For example, net/... expands to net and packages in its subdirectories. + +An import path can also name a package to be downloaded from +a remote repository. Run 'go help remote' for details. + +Every package in a program must have a unique import path. +By convention, this is arranged by starting each path with a +unique prefix that belongs to you. For example, paths used +internally at Google all begin with 'google', and paths +denoting remote repositories begin with the path to the code, +such as 'code.google.com/p/project'. + +As a special case, if the package list is a list of .go files from a +single directory, the command is applied to a single synthesized +package made up of exactly those files, ignoring any build constraints +in those files and ignoring any other files in the directory. +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-path.7 b/debian/man/go-path.7 new file mode 100644 index 000000000..13f696a5c --- /dev/null +++ b/debian/man/go-path.7 @@ -0,0 +1,77 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-PATH 7 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +The Go path is used to resolve import statements. +It is implemented by and documented in the go/build package. + +The GOPATH environment variable lists places to look for Go code. +On Unix, the value is a colon-separated string. +On Windows, the value is a semicolon-separated string. +On Plan 9, the value is a list. + +GOPATH must be set to build and install packages outside the +standard Go tree. + +Each directory listed in GOPATH must have a prescribed structure: + +The src/ directory holds source code. The path below 'src' +determines the import path or executable name. + +The pkg/ directory holds installed package objects. +As in the Go tree, each target operating system and +architecture pair has its own subdirectory of pkg +(pkg/GOOS_GOARCH). + +If DIR is a directory listed in the GOPATH, a package with +source in DIR/src/foo/bar can be imported as "foo/bar" and +has its compiled form installed to "DIR/pkg/GOOS_GOARCH/foo/bar.a". + +The bin/ directory holds compiled commands. +Each command is named for its source directory, but only +the final element, not the entire path. That is, the +command with source in DIR/src/foo/quux is installed into +DIR/bin/quux, not DIR/bin/foo/quux. The foo/ is stripped +so that you can add DIR/bin to your PATH to get at the +installed commands. If the GOBIN environment variable is +set, commands are installed to the directory it names instead +of DIR/bin. + +Here's an example directory layout: + +.Vb 4 +\& GOPATH=/home/user/gocode +\& +\& /home/user/gocode/ +\& src/ +\& foo/ +\& bar/ (go code in package bar) +\& x.go +\& quux/ (go code in package main) +\& y.go +\& bin/ +\& quux (installed command) +\& pkg/ +\& linux_amd64/ +\& foo/ +\& bar.a (installed package object) +.Ve + +Go searches each directory listed in GOPATH to find source code, +but new packages are always downloaded into the first directory +in the list. +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-remote.7 b/debian/man/go-remote.7 new file mode 100644 index 000000000..a1ca7a9fb --- /dev/null +++ b/debian/man/go-remote.7 @@ -0,0 +1,166 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-REMOTE 7 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +An import path (see \fBgo-importpath\fP(1)) denotes a package +stored in the local file system. Certain import paths also +describe how to obtain the source code for the package using +a revision control system. + +A few common code hosting sites have special syntax: + +.TP +.B BitBucket (Mercurial) +.Vb 4 +\&import "bitbucket.org/user/project" +\&import "bitbucket.org/user/project/sub/directory" +.Ve + +.TP +.B GitHub (Git) +.Vb 4 +\&import "github.com/user/project" +\&import "github.com/user/project/sub/directory" +.Ve + +.TP +.B Google Code Project Hosting (Git, Mercurial, Subversion) +.Vb 4 +\&import "code.google.com/p/project" +\&import "code.google.com/p/project/sub/directory" +.Ve + +.Vb 4 +\&import "code.google.com/p/project.subrepository" +\&import "code.google.com/p/project.subrepository/sub/directory" +.Ve + +.TP +.B Launchpad (Bazaar) + +.Vb 4 +\&import "launchpad.net/project" +\&import "launchpad.net/project/series" +\&import "launchpad.net/project/series/sub/directory" +.Ve + +.Vb 4 +\&import "launchpad.net/~user/project/branch" +\&import "launchpad.net/~user/project/branch/sub/directory" +.Ve + +.P +For code hosted on other servers, import paths may either be qualified +with the version control type, or the go tool can dynamically fetch +the import path over https/http and discover where the code resides +from a <meta> tag in the HTML. + +To declare the code location, an import path of the form + +.Vb 6 +\& repository.vcs/path +.Ve + +specifies the given repository, with or without the .vcs suffix, +using the named version control system, and then the path inside +that repository. The supported version control systems are: + +.TP +.B Bazaar + .bzr +.TP +.B Git + .git +.TP +.B Mercurial + .hg +.TP +.B Subversion + .svn + +.P +For example, + +.Vb 6 +\& import "example.org/user/foo.hg" +.Ve + +denotes the root directory of the Mercurial repository at +example.org/user/foo or foo.hg, and + +.Vb 6 +\& import "example.org/repo.git/foo/bar" +.Ve + +denotes the foo/bar directory of the Git repository at +example.com/repo or repo.git. + +When a version control system supports multiple protocols, +each is tried in turn when downloading. For example, a Git +download tries git://, then https://, then http://. + +If the import path is not a known code hosting site and also lacks a +version control qualifier, the go tool attempts to fetch the import +over https/http and looks for a <meta> tag in the document's HTML +<head>. + +The meta tag has the form: + +.Vb 6 +\& <meta name="go-import" content="import-prefix vcs repo-root"> +.Ve + +The import-prefix is the import path corresponding to the repository +root. It must be a prefix or an exact match of the package being +fetched with "go get". If it's not an exact match, another http +request is made at the prefix to verify the <meta> tags match. + +The vcs is one of "git", "hg", "svn", etc, + +The repo-root is the root of the version control system +containing a scheme and not containing a .vcs qualifier. + +For example, + +.Vb 6 +\& import "example.org/pkg/foo" +.Ve + +will result in the following request(s): + +.Vb 6 +\& https://example.org/pkg/foo?go-get=1 (preferred) +\& http://example.org/pkg/foo?go-get=1 (fallback) +.Ve + +If that page contains the meta tag + +.Vb 6 +\& <meta name="go-import" content="example.org git https://code.org/r/p/exproj"> +.Ve + +the go tool will verify that https://example.org/?go-get=1 contains the +same meta tag and then git clone https://code.org/r/p/exproj into +GOPATH/src/example.org. + +New downloaded packages are written to the first directory +listed in the GOPATH environment variable (see \fBgo-path\fP(1)). + +The go command attempts to download the version of the +package appropriate for the Go release being used. +See \fBgo-install\fP(1) for more. +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-run.1 b/debian/man/go-run.1 new file mode 100644 index 000000000..a43f5038e --- /dev/null +++ b/debian/man/go-run.1 @@ -0,0 +1,24 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-RUN 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go run +.RB [ +.IR "build flags" +.RB ] +.IR gofiles... +.RB [ +.IR arguments... +.RB ] +.SH DESCRIPTION +Run compiles and runs the main package comprising the named Go source files. +.P +For more about build flags, see \fBgo-build\fP(1). +.SH SEE ALSO +.BR go-build (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-test.1 b/debian/man/go-test.1 new file mode 100644 index 000000000..3fdfa20b0 --- /dev/null +++ b/debian/man/go-test.1 @@ -0,0 +1,75 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-TEST 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go test +.RB [\|\-c\|] +.RB [\|\-i\|] +.RB [ +.IR "build flags" +.RB ] +.RB [ +.IR packages +.RB ] +.RB [ +.IR "flags for test binary" +.RB ] +.SH DESCRIPTION +"Go test" automates testing the packages named by the import paths. +It prints a summary of the test results in the format: + +.Vb 6 +\& ok archive/tar 0.011s +\& FAIL archive/zip 0.022s +\& ok compress/gzip 0.033s +\& ... +.Ve + +followed by detailed output for each failed package. + +"Go test" recompiles each package along with any files with names matching +the file pattern "*_test.go". These additional files can contain test functions, +benchmark functions, and example functions. See \fBgo-testfunc\fP(7) for more. + +By default, go test needs no arguments. It compiles and tests the package +with source in the current directory, including tests, and runs the tests. + +The package is built in a temporary directory so it does not interfere with the +non-test installation. + +.SH OPTIONS + +In addition to the build flags, the flags handled by 'go test' itself are: + +.TP +.B \-c +Compile the test binary to pkg.test but do not run it. +.TP +.B \-i +Install packages that are dependencies of the test. +Do not run the test. +.P +The test binary also accepts flags that control execution of the test; these +flags are also accessible by 'go test'. See \fBgo-testflag\fP(7) for details. +.P +For more about build flags, see \fBgo-build\fP(1). +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.SH SEE ALSO +.BR go-build (1), +.BR go-vet (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-testflag.7 b/debian/man/go-testflag.7 new file mode 100644 index 000000000..f2b9f4903 --- /dev/null +++ b/debian/man/go-testflag.7 @@ -0,0 +1,87 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-TESTFLAG 7 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +The 'go test' command takes both flags that apply to 'go test' itself +and flags that apply to the resulting test binary. + +The test binary, called pkg.test, where pkg is the name of the +directory containing the package sources, has its own flags: + +.TP +.B \-test.v +Verbose output: log all tests as they are run. +.TP +.B \-test.run pattern +Run only those tests and examples matching the regular expression. +.TP +.B \-test.bench pattern +Run benchmarks matching the regular expression. +By default, no benchmarks run. +.TP +.B \-test.cpuprofile cpu.out +Write a CPU profile to the specified file before exiting. +.TP +.B \-test.memprofile mem.out +Write a memory profile to the specified file when all tests +are complete. +.TP +.B \-test.memprofilerate n +Enable more precise (and expensive) memory profiles by setting +runtime.MemProfileRate. See 'godoc runtime MemProfileRate'. +To profile all memory allocations, use \-test.memprofilerate=1 +and set the environment variable GOGC=off to disable the +garbage collector, provided the test can run in the available +memory without garbage collection. +.TP +.B \-test.parallel n +Allow parallel execution of test functions that call t.Parallel. +The value of this flag is the maximum number of tests to run +simultaneously; by default, it is set to the value of GOMAXPROCS. +.TP +.B \-test.short +Tell long-running tests to shorten their run time. +It is off by default but set during all.bash so that installing +the Go tree can run a sanity check but not spend time running +exhaustive tests. +.TP +.B \-test.timeout t +If a test runs longer than t, panic. +.TP +.B \-test.benchtime n +Run enough iterations of each benchmark to take n seconds. +The default is 1 second. +.TP +.B \-test.cpu 1,2,4 +Specify a list of GOMAXPROCS values for which the tests or +benchmarks should be executed. The default is the current value +of GOMAXPROCS. +.P +For convenience, each of these \-test.X flags of the test binary is +also available as the flag \-X in 'go test' itself. Flags not listed +here are passed through unaltered. For instance, the command + +.Vb 6 +\& go test \-x \-v \-cpuprofile=prof.out \-dir=testdata \-update +.Ve + +will compile the test binary and then run it as + +.Vb 6 +\& pkg.test \-test.v \-test.cpuprofile=prof.out \-dir=testdata \-update +.Ve +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-testfunc.7 b/debian/man/go-testfunc.7 new file mode 100644 index 000000000..839fe1561 --- /dev/null +++ b/debian/man/go-testfunc.7 @@ -0,0 +1,63 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GO-TESTFUNC 7 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH DESCRIPTION +The 'go test' command expects to find test, benchmark, and example functions +in the "*_test.go" files corresponding to the package under test. + +A test function is one named TestXXX (where XXX is any alphanumeric string +not starting with a lower case letter) and should have the signature, + +.Vb 6 +\& func TestXXX(t *testing.T) { ... } +.Ve + +A benchmark function is one named BenchmarkXXX and should have the signature, + +.Vb 6 +\& func BenchmarkXXX(b *testing.B) { ... } +.Ve + +An example function is similar to a test function but, instead of using *testing.T +to report success or failure, prints output to os.Stdout and os.Stderr. +That output is compared against the function's "Output:" comment, which +must be the last comment in the function body (see example below). An +example with no such comment, or with no text after "Output:" is compiled +but not executed. + +Godoc displays the body of ExampleXXX to demonstrate the use +of the function, constant, or variable XXX. An example of a method M with +receiver type T or *T is named ExampleT_M. There may be multiple examples +for a given function, constant, or variable, distinguished by a trailing _xxx, +where xxx is a suffix not beginning with an upper case letter. + +Here is an example of an example: + +.Vb 6 +\& func ExamplePrintln() { +\& Println("The output of\\nthis example.") +\& // Output: The output of +\& // this example. +\& } +.Ve + +The entire test file is presented as the example when it contains a single +example function, at least one other function, type, variable, or constant +declaration, and no test or benchmark functions. + +See the documentation of the testing package for more information. +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-tool.1 b/debian/man/go-tool.1 new file mode 100644 index 000000000..ebf8c26e0 --- /dev/null +++ b/debian/man/go-tool.1 @@ -0,0 +1,26 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-TOOL 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go tool +.RB [\|\-n\|] +.IR command +.RB [ +.IR args... +.RB ] +.SH DESCRIPTION +Tool runs the go tool command identified by the arguments. +With no arguments it prints the list of known tools. +.SH OPTIONS +.TP +.B \-n +The \-n flag causes tool to print the command that would be +executed but not execute it. +.P +For more about each tool command, see 'go tool command \-h'. +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-version.1 b/debian/man/go-version.1 new file mode 100644 index 000000000..2c1ebe0a4 --- /dev/null +++ b/debian/man/go-version.1 @@ -0,0 +1,13 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-VERSION 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go version +.SH DESCRIPTION +Version prints the Go version, as reported by runtime.Version. +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go-vet.1 b/debian/man/go-vet.1 new file mode 100644 index 000000000..a165fd5e6 --- /dev/null +++ b/debian/man/go-vet.1 @@ -0,0 +1,35 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO-VET 1 "2012-06-15" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go vet +.RB [\|\-n\|] +.RB [\|\-x\|] +.RB [ +.IR packages +.RB ] +.SH DESCRIPTION +Vet runs the Go vet command on the packages named by the import paths. +.P +For more about vet, see 'godoc vet'. +.P +For more about specifying packages, see \fBgo-packages\fP(7). +.P +To run the vet tool with specific options, run 'go tool vet'. +.SH OPTIONS +.TP +.B \-n +The \-n flag causes tool to print the command that would be +executed but not execute it. +.TP +.B \-x +The \-x flag causes clean to print remove commands as it executes them. +.SH SEE ALSO +.BR go-fmt (1), +.BR go-fix (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/go.1 b/debian/man/go.1 new file mode 100644 index 000000000..27ae4df98 --- /dev/null +++ b/debian/man/go.1 @@ -0,0 +1,66 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH GO 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +go \- tool for managing Go source code +.SH SYNOPSIS +.B go +.RI command +.RI [ arguments ] +.SH DESCRIPTION +The Go distribution includes a command, named \fBgo\fP, that automates the +downloading, building, installation, and testing of Go packages and commands. +.SH COMMANDS +Each command is documented in its own manpage. For example, the \fBbuild\fP +command is documented in \fBgo-build\fP(1). The commands are: +.TP +.B build +compile packages and dependencies +.TP +.B clean +remove object files +.TP +.B doc +run godoc on package sources +.TP +.B env +print Go environment information +.TP +.B fix +run go tool fix on packages +.TP +.B fmt +run gofmt on package sources +.TP +.B get +download and install packages and dependencies +.TP +.B install +compile and install packages and dependencies +.TP +.B list +list packages +.TP +.B run +compile and run Go program +.TP +.B test +test packages +.TP +.B tool +run specified go tool +.TP +.B version +print Go version +.TP +.B vet +run go tool vet on packages +.SH EXAMPLES +TODO +.SH SEE ALSO +.BR go-build (1), +.BR go-clean (1). +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/godoc.1 b/debian/man/godoc.1 new file mode 100644 index 000000000..1894445ac --- /dev/null +++ b/debian/man/godoc.1 @@ -0,0 +1,209 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GODOC 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +godoc \- extracts and generates documentation for Go programs +.SH SYNOPSIS +.B godoc +.RI [ flag ] +.RI command +.RI [ +.IR "name ..." +.RI ] +.SH DESCRIPTION +Godoc extracts and generates documentation for Go programs. + +It has two modes. + +Without the \-http flag, it runs in command-line mode and prints plain +text documentation to standard output and exits. If both a library +package and a command with the same name exists, using the prefix cmd/ +will force documentation on the command rather than the library package. +If the \-src flag is specified, godoc prints the exported interface of a +package in Go source form, or the implementation of a specific exported +language entity: + +.Vb 6 +\& godoc fmt # documentation for package fmt +\& godoc fmt Printf # documentation for fmt.Printf +\& godoc cmd/go # force documentation for the go command +\& godoc \-src fmt # fmt package interface in Go source form +\& godoc \-src fmt Printf # implementation of fmt.Printf +.Ve + +In command-line mode, the \-q flag enables search queries against a godoc +running as a webserver. If no explicit server address is specified with +the \-server flag, godoc first tries localhost:6060 and then +http://golang.org. + +.Vb 6 +\& godoc \-q Reader +\& godoc \-q math.Sin +\& godoc \-server=:6060 \-q sin +.Ve + +With the \-http flag, it runs as a web server and presents the +documentation as a web page. + +.Vb 6 +\& godoc \-http=:6060 +.Ve + +By default, godoc looks at the packages it finds via $GOROOT and $GOPATH +(if set). Additional directories may be specified via the \-path flag +which accepts a list of colon-separated paths; unrooted paths are +relative to the current working directory. Each path is considered as an +additional root for packages in order of appearance. The last (absolute) +path element is the prefix for the package path. For instance, given the +flag value: + +.Vb 6 +\& path=".:/home/bar:/public" +.Ve + +for a godoc started in /home/user/godoc, absolute paths are mapped to +package paths as follows: + +.Vb 6 +\& /home/user/godoc/x -> godoc/x +\& /home/bar/x -> bar/x +\& /public/x -> public/x +.Ve + +When godoc runs as a web server and \-index is set, a search index is +maintained. The index is created at startup. + +The index contains both identifier and full text search information +(searchable via regular expressions). The maximum number of full text +search results shown can be set with the \-maxresults flag; if set to 0, +no full text results are shown, and only an identifier index but no full +text search index is created. + +The presentation mode of web pages served by godoc can be controlled +with the "m" URL parameter; it accepts a comma-separated list of flag +names as value: + +.TP +.B all +show documentation for all declarations, not just the exported ones +.TP +.B methods +show all embedded methods, not just those of unexported anonymous fields +.TP +.B src +show the original source code rather then the extracted documentation +.TP +.B text +present the page in textual (command-line) form rather than HTML +.TP +.B flat +present flat (not indented) directory listings using full paths +.P +For instance, http://golang.org/pkg/math/big/?m=all,text shows the +documentation for all (not just the exported) declarations of package +big, in textual form (as it would appear when using godoc from the +command line: "godoc \-src math/big .*"). + +By default, godoc serves files from the file system of the underlying +OS. Instead, a .zip file may be provided via the \-zip flag, which +contains the file system to serve. The file paths stored in the .zip +file must use slash ('/') as path separator; and they must be unrooted. +$GOROOT (or \-goroot) must be set to the .zip file directory path +containing the Go root directory. For instance, for a .zip file created +by the command: + +.Vb 6 +\& zip go.zip $HOME/go +.Ve + +one may run godoc as follows: + +.Vb 6 +\& godoc \-http=:6060 \-zip=go.zip \-goroot=$HOME/go +.Ve + +See "Godoc: documenting Go code" for how to write good comments for +godoc: http://golang.org/doc/articles/godoc_documenting_go_code.html + +.SH OPTIONS + +.TP +.B \-v +verbose mode +.TP +.B \-q +arguments are considered search queries: a legal query is a +single identifier (such as ToLower) or a qualified identifier +(such as math.Sin). +.TP +.B \-src +print (exported) source in command-line mode +.TP +.B \-tabwidth=4 +width of tabs in units of spaces +.TP +.B \-timestamps=true +show timestamps with directory listings +.TP +.B \-index +enable identifier and full text search index +(no search box is shown if \-index is not set) +.TP +.B \-index_files="" +glob pattern specifying index files; if not empty, +the index is read from these files in sorted order +.TP +.B \-index_throttle=0.75 +index throttle value; a value of 0 means no time is allocated +to the indexer (the indexer will never finish), a value of 1.0 +means that index creation is running at full throttle (other +goroutines may get no time while the index is built) +.TP +.B \-write_index=false +write index to a file; the file name must be specified with +\-index_files +.TP +.B \-maxresults=10000 +maximum number of full text search results shown +(no full text index is built if maxresults <= 0) +.TP +.B \-path="" +additional package directories (colon-separated) +.TP +.B \-html +print HTML in command-line mode +.TP +.B \-goroot=$GOROOT +Go root directory +.TP +.B \-http=addr +HTTP service address (e.g., '127.0.0.1:6060' or just ':6060') +.TP +.B \-server=addr +webserver address for command line searches +.TP +.B \-templates="" +directory containing alternate template files; if set, +the directory may provide alternative template files +for the files in $GOROOT/lib/godoc +.TP +.B \-url=path +print to standard output the data that would be served by +an HTTP request for path +.TP +.B \-zip="" +zip file providing the file system to serve; disabled if empty + +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). diff --git a/debian/man/gofmt.1 b/debian/man/gofmt.1 new file mode 100644 index 000000000..969a245e1 --- /dev/null +++ b/debian/man/gofmt.1 @@ -0,0 +1,108 @@ +.\" Hey, EMACS: -*- nroff -*- +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.TH GOFMT 1 "2012-05-13" +.\" Please adjust this date whenever revising the manpage. +.SH NAME +gofmt \- formats Go programs +.SH SYNOPSIS +.B gofmt +.RI [ flags ] +.RI [ +.IR "path ..." +.RI ] +.SH DESCRIPTION +Without an explicit path, it processes the standard input. Given a file, +it operates on that file; given a directory, it operates on all .go +files in that directory, recursively. (Files starting with a period are +ignored.) By default, gofmt prints the reformatted sources to standard +output. + +.SH OPTIONS +.TP +.B \-d +Do not print reformatted sources to standard output. +If a file's formatting is different than gofmt's, print diffs +to standard output. +.TP +.B \-e +Print all (including spurious) errors. +.TP +.B \-l +Do not print reformatted sources to standard output. +If a file's formatting is different from gofmt's, print its name +to standard output. +.TP +.B \-r rule +Apply the rewrite rule to the source before reformatting. +.TP +.B \-s +Try to simplify code (after applying the rewrite rule, if any). +.TP +.B \-w +Do not print reformatted sources to standard output. +If a file's formatting is different from gofmt's, overwrite it +with gofmt's version. +.P +Formatting control flags: +.TP +.B \-comments=true +Print comments; if false, all comments are elided from the output. +.TP +.B \-tabs=true +Indent with tabs; if false, spaces are used instead. +.TP +.B \-tabwidth=8 +Tab width in spaces. +.P + +The rewrite rule specified with the \-r flag must be a string of the +form: + +.Vb 6 +\& pattern -> replacement +.Ve + +Both pattern and replacement must be valid Go expressions. In the +pattern, single-character lowercase identifiers serve as wildcards +matching arbitrary sub-expressions; those expressions will be +substituted for the same identifiers in the replacement. + +When gofmt reads from standard input, it accepts either a full Go +program or a program fragment. A program fragment must be a +syntactically valid declaration list, statement list, or expression. +When formatting such a fragment, gofmt preserves leading indentation as +well as leading and trailing spaces, so that individual sections of a Go +program can be formatted by piping them through gofmt. +.SH EXAMPLES +To check files for unnecessary parentheses: + +.Vb 6 +\& gofmt \-r '(a) \-> a' \-l *.go +.Ve + +To remove the parentheses: + +.Vb 6 +\& gofmt \-r '(a) \-> a' \-w *.go +.Ve + +To convert the package tree from explicit slice upper bounds to implicit +ones: + +.Vb 6 +\& gofmt \-r 'α[β:len(α)] \-> α[β:]' \-w $GOROOT/src/pkg +.Ve +.SH BUGS +The implementation of \-r is a bit slow. +.SH AUTHOR +.PP +This manual page was written by Michael Stapelberg <stapelberg@debian.org>, +for the Debian project (and may be used by others). |