10.1. 命令行工具

10.1. 命令行工具

  Name         Synopsis
  ..
  5a        5a is a version of the Plan 9 assembler.
  5c        5c is a version of the Plan 9 C compiler.
  5g        5g is the version of the gc compiler for the ARM. The $GOARCH for these tools is arm.
  5l        5l is a modified version of the Plan 9 linker.
  6a        6a is a version of the Plan 9 assembler.
  6c        6c is a version of the Plan 9 C compiler.
  6g        6g is the version of the gc compiler for the x86-64.
  6l        6l is a modified version of the Plan 9 linker.
  8a        8a is a version of the Plan 9 assembler.
  8c        8c is a version of the Plan 9 C compiler.
  8g        8g is the version of the gc compiler for the x86.
  8l        8l is a modified version of the Plan 9 linker.
  cc        This directory contains the portable section of the Plan 9 C compilers.
  cgo        Cgo enables the creation of Go packages that call C code.
  cov        Cov is a rudimentary code coverage tool.
  ebnflint    Ebnflint verifies that EBNF productions are consistent and gramatically correct.
  gc        Gc is the generic label for the family of Go compilers that function as part of the (modified) Plan 9 tool chain.
  godefs    Godefs is a bootstrapping tool for porting the Go runtime to new systems.
  godoc        Godoc extracts and generates documentation for Go programs.
  gofmt        Gofmt Go程序格式化.
  goinstall    Goinstall 尝试自动安装包的工具。
  gomake    gomake是针对go语言对GNU make命令的简单包装。
  gopack    Gopack is a variant of the Plan 9 ar tool.
  gotest    Gotest is an automated testing tool for Go packages.
  goyacc    Goyacc is a version of yacc for Go.
  hgpatch    Hgpatch applies a patch to the local Mercurial repository.
  ld        This directory contains the portable section of the Plan 9 C linkers.
  nm        Nm is a version of the Plan 9 nm command.
  prof        Prof is a rudimentary real-time profiler.

10.1.1. 8g

  8g is the version of the gc compiler for the x86.
  The $GOARCH for these tools is 386.

  It reads .go files and outputs .8 files. The flags are documented in ../gc/doc.go.

  There is no instruction optimizer, so the -N flag is a no-op.

  8g是x86系统的gc编译器。

  当$GOARCH设置为386时，该命令有效。输入“.go”文件，输出“.8”文件。命令行选择可以参考``../gc/doc.go``说明。

  该版本编译器没有进行指令优化，因此不支持``-N``参数。

  用法: 8g [flags] file.go...

  选项:
    -I DIR search for packages in DIR 指定包的查找路径
    -d print declarations 打印声明
    -e no limit on number of errors printed 打印全部的错误
    -f print stack frame structure 打印栈帧结构
    -h panic on an error 遇到错误停止
    -o file specify output file 指定输出文件名
    -S print the assembly language 打印编译后的汇编代码
    -V print the compiler version 打印编译器版本
    -u disable package unsafe 禁用unsafe包
    -w print the parse tree after typing 打印分析树
    -x print lex tokens 打印词法分析结果

10.1.2. 8l

  8l is a modified version of the Plan 9 linker.  The original is documented at

  8l是Plan 9系统连接器的修改版。文档在：

      http://plan9.bell-labs.com/magic/man2html/1/2l

  Its target architecture is the x86, referred to by these tools for historical reasons as 386.
  It reads files in .8 format generated by 8g, 8c, and 8a and emits
  a binary called 8.out by default.

  输出的目标文件针对x86系统（由于历史原因，这些工具中叫386）。
  它的输入是8g, 8c,和8a生成的“.8”格式文件，然后默认输出8.out文件。

  Major changes include:
      - support for ELF and Mach-O binary files
      - support for segmented stacks (this feature is implemented here, not in the compilers).

  重要的改动:
      - 支持ELF和Mach-O格式的二进制文件 
      - 支持分段的栈（该特性不是在编译器实现，是在这里）

  Original options are listed in the link above.

  原有的选项在上面提到的文档中。

  Options new in this version:

  这里是新加选项：

  -d
      Elide the dynamic linking header.  With this option, the binary
      is statically linked and does not refer to dynld.  Without this option
      (the default), the binary's contents are identical but it is loaded with dynld.
  -H6
      Write Apple Mach-O binaries (default when $GOOS is darwin)
      生成Apple Mach-O格式文件（$GOOS为darwin）
  -H7
      Write Linux ELF binaries (default when $GOOS is linux)
      生成Linux的ELF格式文件
  -L dir1,dir2,..
      Search for libraries (package files) in the comma-separated list of directories.
      The default is the single location $GOROOT/pkg/$GOOS_386.
      包的目录列表，以逗号分隔。默认有一个目录$GOROOT/pkg/$GOOS_386.
  -r dir1:dir2:...
      Set the dynamic linker search path when using ELF.
      设置动态链接的查找路径（针对ELF）
  -V
      Print the linker version.
      输出连接器的版本号

10.1.3. 8a

  8a is a version of the Plan 9 assembler.  The original is documented at

  8a是Plan 9的汇编器，文档在

      http://plan9.bell-labs.com/magic/man2html/1/2a

  Its target architecture is the x86, referred to by these tools for historical reasons as 386.

  目标是x86结构，由于历史原因，这些工具中叫386。

10.1.4. gomake

  The gomake command runs GNU make with an appropriate environment
  for using the conventional Go makefiles.  If $GOROOT is already
  set in the environment, running gomake is exactly the same
  as running make (or, on BSD systems, running gmake).

  gomake是针对go语言对GNU make命令的简单包装。

  如果已经设置了$GOROOT环境变量的话，gomake是和gmake等价的。如果没有设置$GOROOT的话，会将go代码所在位置设置到$GOROOT。

  用法: gomake [ 目标 ... ]

  支持的目标:

      all (默认)
          build the package or command, but do not install it.
          构建全部的包和命令，但是不进行安装操作。

      install
          build and install the package or command
          构建全部的包和命令，然后安装。

      test
          run the tests (packages only)
          运行包的测试代码。

      bench
          run benchmarks (packages only)
          运行包的基准测试。

      clean
          remove object files from the current directory
          清空构建时生成的临时文件。

      nuke
          make clean and remove the installed package or command
          清空构建时生成的临时文件，并且删除已经安装的包和命令。

  查看 http://golang.org/doc/code.html 页面，获取关于makefiles的详细信息。

10.1.5. cgo

注：该命令有较大更新，有些特性提供的例子中没有展示。

  Cgo enables the creation of Go packages that call C code.

  cgo用于创建要调用C语言函数的包。

  Usage: cgo [compiler options] file.go

  The compiler options are passed through uninterpreted when
  invoking gcc to compile the C parts of the package.

  编译器的选项在调用gcc编译C代码的时候，传入gcc。

  The input file.go is a syntactically valid Go source file that imports
  the pseudo-package "C" and then refers to types such as C.size_t,
  variables such as C.stdout, or functions such as C.putchar.

  file.go输入文件是一个导入了"C"虚拟包的go源文件。然后可以通过“C.”前缀访问C
  的内容，如 C.size_t、C.stdout、C.putchar。

  If the import of "C" is immediately preceded by a comment, that
  comment is used as a header when compiling the C parts of
  the package.  For example:

  如果注释后紧跟着导入了"C"包，那么"C"之前的注释将作为有效的C代码处理。例如：

      // #include <stdio.h>
      // #include <errno.h>
      import "C"

  C identifiers or field names that are keywords in Go can be
  accessed by prefixing them with an underscore: if x points at
  a C struct with a field named "type", x._type accesses the field.

  The standard C numeric types are available under the names
  C.char, C.schar (signed char), C.uchar (unsigned char),
  C.short, C.ushort (unsigned short), C.int, C.uint (unsigned int),
  C.long, C.ulong (unsigned long), C.longlong (long long),
  C.ulonglong (unsigned long long), C.float, C.double.

  标准的Ｃ数值类型：
  C.char, C.schar (signed char), C.uchar (unsigned char),
  C.short, C.ushort (unsigned short), C.int, C.uint (unsigned int),
  C.long, C.ulong (unsigned long), C.longlong (long long),
  C.ulonglong (unsigned long long), C.float, C.double.

  To access a struct, union, or enum type directly, prefix it with
  struct_, union_, or enum_, as in C.struct_stat.

  如果是struct, union,　或 enum　类型，添加前缀struct_, union_, or enum_，
  例如： C.struct_stat.

  Any C function that returns a value may be called in a multiple
  assignment context to retrieve both the return value and the
  C errno variable as an os.Error.  For example:

  任意有返回值的Ｃ函数，可以在go中当作返回多个值处理——第二个返回值转为os.Error类型的errno。
  例如：

      n, err := C.atoi("abc")

  In C, a function argument written as a fixed size array
  actually requires a pointer to the first element of the array.
  C compilers are aware of this calling convention and adjust
  the call accordingly, but Go cannot.  In Go, you must pass
  the pointer to the first element explicitly: C.f(&x[0]).

  C函数参数中，数组类型参数实际上是指向数组第一个元素的指针。在C语言中
  可以直接将数组传递给函数参数，但是go不允许。go中必须明确传递第一个元素的
  指针：C.f(&x[0]).

  Cgo transforms the input file into four output files: two Go source
  files, a C file for 6c (or 8c or 5c), and a C file for gcc.

  cgo处理后，每个输出的文件生成4个输出文件：2个是go文件，1个针对8c/6c的C文件，
  1个针对gcc的C文件。

  The standard package makefile rules in Make.pkg automate the
  process of using cgo.  See $GOROOT/misc/cgo/stdio and
  $GOROOT/misc/cgo/gmp for examples.

  标准库的makefile模板文件Make.pkg支持cgo语法。例子请参考：$GOROOT/misc/cgo/stdio
  和$GOROOT/misc/cgo/gmp。

  Cgo does not yet work with gccgo.

  cgo目前不支持gccgo。

10.1.6. gotest

  Gotest is an automated testing tool for Go packages.

  gotest是包的自动测试工具。

  Normally a Go package is compiled without its test files.  Gotest
  is a simple script that recompiles the package along with any files
  named *_test.go.  Functions in the test sources named TestXXX
  (where XXX is any alphanumeric string starting with an upper case
  letter) will be run when the binary is executed.  Gotest requires
  that the package have a standard package Makefile, one that
  includes go/src/Make.pkg.

  包的测试文件默认是没有编译的。gotest是一个用于编译*_test.go文件的脚本。
  测试文件中所有的TestXXX（XXX是大写字母开头的单词）函数会被执行。Gotest
  需要包的makefile文件包含go/src/Make.pkg模板。

  The test functions are run in the order they appear in the source.
  They should have signature

  测试函数安装在源文件中出现的顺序被执行，必须是以下类型：

      func TestXXX(t *testing.T) { ... }

  Benchmark functions can be written as well; they will be run only
  when the -benchmarks flag is provided.  Benchmarks should have
  signature

  基准测试也已经支持，只要在命令行增加 -benchmarks 选项。基准测试函数的类型：

      func BenchmarkXXX(b *testing.B) { ... }

  See the documentation of the testing package for more information.

  查看testing包文档，可以获取详细信息。

  By default, gotest needs no arguments.  It compiles all the .go files
  in the directory, including tests, and runs the tests.  If file names
  are given, only those test files are added to the package.
  (The non-test files are always compiled.)

  gotest默认不需要参数。它编译目录中的所有go文件，包含测试文件，然后执行
  测试。如果设置文件名参数，那么只有对应测试文件才会被编译执行（无测试的文件依然编译）。

  The package is built in a special subdirectory so it does not
  interfere with the non-test installation.

  包构建的中间文件默认放在一个特殊的子目录，因此不会干扰测试。

  Usage:
      gotest [pkg_test.go ...]

  The resulting binary, called (for amd64) 6.out, has a couple of
  arguments.

  输出6.out文件（针对amd64）。有一组命令行参数

  Usage:
      6.out [-v] [-match pattern] [-benchmarks pattern]

  The -v flag causes the tests to be logged as they run.  The -match
  flag causes only those tests whose names match the regular expression
  pattern to be run. By default all tests are run silently.  If all
  the specified test pass, 6.out prints PASS and exits with a 0 exit
  code.  If any tests fail, it prints FAIL and exits with a non-zero
  code.  The -benchmarks flag is analogous to the -match flag, but
  applies to benchmarks.  No benchmarks run by default.

  选项-v执行并记录全部执行的测试。选项-match只执行匹配的测试。
  所有测试默认没有输出。如果全部测试通过，打印PASS，返回0后退出。
  如果有测试识别，打印FAIL，返回非零值退出。选项-benchmarks启动基准测试。
  默认基准测试没有启动。

10.1.7. Goyacc

  Goyacc is a version of yacc for Go.
  It is written in Go and generates parsers written in Go.

  It is largely transliterated from the Inferno version written in Limbo
  which in turn was largely transliterated from the Plan 9 version
  written in C and documented at

      http://plan9.bell-labs.com/magic/man2html/1/yacc

  Yacc adepts will have no trouble adapting to this form of the tool.

  The file units.y in this directory is a yacc grammar for a version of
  the Unix tool units, also written in Go and largely transliterated
  from the Plan 9 C version.

  The generated parser is reentrant. Parse expects to be given an
  argument that conforms to the following interface:

      type yyLexer interface {
          Lex(lval *yySymType) int
          Error(e string)
      }

  Lex should return the token identifier, and place other token
  information in lval (which replaces the usual yylval).
  Error is equivalent to yyerror in the original yacc.

  Code inside the parser may refer to the variable yylex
  which holds the yyLexer passed to Parse.

10.1.8. gopack

  Gopack is a variant of the Plan 9 ar tool.  The original is documented at

      http://plan9.bell-labs.com/magic/man2html/1/ar

  It adds a special Go-specific section __.PKGDEF that collects all the
  Go type information from the files in the archive; that section is
  used by the compiler when importing the package during compilation.

  Usage: gopack [uvnbailo][mrxtdpq] archive files ...

  The new option 'g' causes gopack to maintain the __.PKGDEF section
  as files are added to the archive.

10.1.9. gofmt

  gofmt 程序格式化.

  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.)

  没有指定路径，输出到终端。指定了文件，就操作当前文件。
  指定了路径就递归指定路径下面的所有.go文件。(Files starting with a period are ignored.)

  Usage:

  gofmt [flags] [path ...]

  选项:

  -l
      just list files whose formatting differs from gofmt's; generate no other output
  unless -w is also set.
      只列出gofmt需要格式化的文件，不对文件做任何操作，除非使用 -w
  -r rule
      apply the rewrite rule to the source before reformatting.
      在代码格式化之前执行替换规则
  -s
      try to simplify code (after applying the rewrite rule, if any).
      简化代码(在执行替换或其他的操作后)
  -w
      if set, overwrite each input file with its output.
      如果有-w，把格式化后的代码写入原始文件中
  -spaces
      align with spaces instead of tabs.
      使用空格替换tab制表符
  -tabindent
      indent with tabs independent of -spaces.
      使用tab制表符替换空格
  -tabwidth=8
      tab width in spaces.
      tab的长度

  调试选项:

  -trace
      print parse trace.
      打印跟踪分析
  -ast
      print AST (before rewrites).
      打印AST (在重写之前)
  -comments=true
      print comments; if false, all comments are elided from the output.
      打印注释，如果是假(false), 所有的注释信息不做处理

  The rewrite rule specified with the -r flag must be a string of the form:
  选项 -r 的重写规则必须遵循这个模式:

  pattern -> replacement

  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.
  pattern和replacement必须是有效的Go语法。Pattern 单字符小写标识符作为通配符匹配任意表达式，
  这些表达式将被替换为相同的标识符.

  实例

  To check files for unnecessary parentheses:
  检查并输出有多余括号的文件

  gofmt -r '(a) -> a' -l *.go

  To remove the parentheses:
  去掉多余的括号

  gofmt -r '(a) -> a' -w *.go

  To convert the package tree from explicit slice upper bounds to implicit ones:
  slice使用隐形(implicit)替换

  gofmt -r 'α[β:len(α)] -> α[β:]' -w $GOROOT/src/pkg

  Bugs

  The implementation of -r is a bit slow.
  选项 -r 的实现方式效率有些低

10.1.10. goinstall

  Goinstall is an experiment in automatic package installation.
  It installs packages, possibly downloading them from the internet.
  It maintains a list of public Go packages at http://godashboard.appspot.com/package.

  Usage:
      goinstall [flags] importpath...
      goinstall [flags] -a

  Flags and default settings:
          -a=false          install all previously installed packages
      -dashboard=true   tally public packages on godashboard.appspot.com
      -log=true         log installed packages to $GOROOT/goinstall.log for use by -a
      -u=false          update already-downloaded packages
      -v=false          verbose operation

  Goinstall installs each of the packages identified on the command line.  It
  installs a package's prerequisites before trying to install the package
  itself. Unless -log=false is specified, goinstall logs the import path of each
  installed package to $GOROOT/goinstall.log for use by goinstall -a.

  If the -a flag is given, goinstall reinstalls all previously installed
  packages, reading the list from $GOROOT/goinstall.log.  After updating to a
  new Go release, which deletes all package binaries, running

      goinstall -a

  will recompile and reinstall goinstalled packages.

  Another common idiom is to use

      goinstall -a -u

  to update, recompile, and reinstall all goinstalled packages.

  The source code for a package with import path foo/bar is expected
  to be in the directory $GOROOT/src/pkg/foo/bar/.  If the import
  path refers to a code hosting site, goinstall will download the code
  if necessary.  The recognized code hosting sites are:

      BitBucket (Mercurial)

          import "bitbucket.org/user/project"
          import "bitbucket.org/user/project/sub/directory"

      GitHub (Git)

          import "github.com/user/project.git"
          import "github.com/user/project.git/sub/directory"

      Google Code Project Hosting (Mercurial, Subversion)

          import "project.googlecode.com/hg"
          import "project.googlecode.com/hg/sub/directory"

          import "project.googlecode.com/svn/trunk"
          import "project.googlecode.com/svn/trunk/sub/directory"

      Launchpad

          import "launchpad.net/project"
          import "launchpad.net/project/series"
          import "launchpad.net/project/series/sub/directory"

          import "launchpad.net/~user/project/branch"
          import "launchpad.net/~user/project/branch/sub/directory"

  If the destination directory (e.g., $GOROOT/src/pkg/bitbucket.org/user/project)
  already exists and contains an appropriate checkout, goinstall will not
  attempt to fetch updates.  The -u flag changes this behavior,
  causing goinstall to update all remote packages encountered during
  the installation.

  When downloading or updating, goinstall first looks for a tag or branch
  named "release".  If there is one, it uses that version of the code.
  Otherwise it uses the default version selected by the version control
  system, typically HEAD for git, tip for Mercurial.

  After a successful download and installation of a publicly accessible
  remote package, goinstall reports the installation to godashboard.appspot.com,
  which increments a count associated with the package and the time
  of its most recent installation.  This mechanism powers the package list
  at http://godashboard.appspot.com/package, allowing Go programmers
  to learn about popular packages that might be worth looking at.
  The -dashboard=false flag disables this reporting.

  By default, goinstall prints output only when it encounters an error.
  The -v flag causes goinstall to print information about packages
  being considered and installed.

  Goinstall does not attempt to be a replacement for make.
  Instead, it invokes "make install" after locating the package sources.
  For local packages without a Makefile and all remote packages,
  goinstall creates and uses a temporary Makefile constructed from
  the import path and the list of Go files in the package.

2011-03-02