10.1. 命令行工具 · Go 中文文檔

## 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