diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/articles/go_command.html | 15 | ||||
| -rw-r--r-- | doc/articles/race_detector.html | 27 | ||||
| -rw-r--r-- | doc/asm.html | 157 | ||||
| -rw-r--r-- | doc/cmd.html | 8 | ||||
| -rw-r--r-- | doc/code.html | 187 | ||||
| -rw-r--r-- | doc/contrib.html | 33 | ||||
| -rw-r--r-- | doc/contribute.html | 674 | ||||
| -rw-r--r-- | doc/debugging_with_gdb.html | 50 | ||||
| -rw-r--r-- | doc/devel/release.html | 10 | ||||
| -rw-r--r-- | doc/devel/weekly.html | 2 | ||||
| -rw-r--r-- | doc/docs.html | 4 | ||||
| -rw-r--r-- | doc/effective_go.html | 4 | ||||
| -rw-r--r-- | doc/gccgo_contribute.html | 2 | ||||
| -rw-r--r-- | doc/gccgo_install.html | 4 | ||||
| -rw-r--r-- | doc/go1.3.html | 4 | ||||
| -rw-r--r-- | doc/go1.4.html | 896 | ||||
| -rw-r--r-- | doc/go1.html | 2 | ||||
| -rw-r--r-- | doc/go1compat.html | 35 | ||||
| -rw-r--r-- | doc/go_faq.html | 100 | ||||
| -rw-r--r-- | doc/go_mem.html | 23 | ||||
| -rw-r--r-- | doc/go_spec.html | 899 | ||||
| -rw-r--r-- | doc/gopher/biplane.jpg | bin | 0 -> 203420 bytes | |||
| -rw-r--r-- | doc/gopher/fiveyears.jpg | bin | 0 -> 220526 bytes | |||
| -rw-r--r-- | doc/help.html | 2 | ||||
| -rw-r--r-- | doc/install-source.html | 6 | ||||
| -rw-r--r-- | doc/install.html | 29 |
26 files changed, 2165 insertions, 1008 deletions
diff --git a/doc/articles/go_command.html b/doc/articles/go_command.html index fddca41e2..2978628cd 100644 --- a/doc/articles/go_command.html +++ b/doc/articles/go_command.html @@ -78,17 +78,18 @@ well-established conventions.</p> source code. For Bitbucket, GitHub, Google Code, and Launchpad, the root directory of the repository is identified by the repository's main URL, without the <code>http://</code> prefix. Subdirectories are named by -adding to that path. For example, the supplemental networking -libraries for Go are obtained by running</p> +adding to that path. +For example, the Go example programs are obtained by running</p> <pre> -hg clone http://code.google.com/p/go.net +git clone https://github.com/golang/example </pre> <p>and thus the import path for the root directory of that repository is -"<code>code.google.com/p/go.net</code>". The websocket package is stored in a -subdirectory, so its import path is -"<code>code.google.com/p/go.net/websocket</code>".</p> +"<code>github.com/golang/example</code>". +The <a href="https://godoc.org/github.com/golang/example/stringutil">stringutil</a> +package is stored in a subdirectory, so its import path is +"<code>github.com/golang/example/stringutil</code>".</p> <p>These paths are on the long side, but in exchange we get an automatically managed name space for import paths and the ability for @@ -99,7 +100,7 @@ deduce where to obtain the source code.</p> in a known way from the import path. Specifically, the first choice is <code>$GOPATH/src/<import-path></code>. If <code>$GOPATH</code> is unset, the go command will fall back to storing source code alongside the -standard Go packages, in <code>$GOROOT/src/pkg/<import-path></code>. +standard Go packages, in <code>$GOROOT/src/<import-path></code>. If <code>$GOPATH</code> is set to a list of paths, the go command tries <code><dir>/src/<import-path></code> for each of the directories in that list.</p> diff --git a/doc/articles/race_detector.html b/doc/articles/race_detector.html index 282db8ba4..6defd98f9 100644 --- a/doc/articles/race_detector.html +++ b/doc/articles/race_detector.html @@ -57,35 +57,35 @@ Here is an example: WARNING: DATA RACE Read by goroutine 185: net.(*pollServer).AddFD() - src/pkg/net/fd_unix.go:89 +0x398 + src/net/fd_unix.go:89 +0x398 net.(*pollServer).WaitWrite() - src/pkg/net/fd_unix.go:247 +0x45 + src/net/fd_unix.go:247 +0x45 net.(*netFD).Write() - src/pkg/net/fd_unix.go:540 +0x4d4 + src/net/fd_unix.go:540 +0x4d4 net.(*conn).Write() - src/pkg/net/net.go:129 +0x101 + src/net/net.go:129 +0x101 net.func·060() - src/pkg/net/timeout_test.go:603 +0xaf + src/net/timeout_test.go:603 +0xaf Previous write by goroutine 184: net.setWriteDeadline() - src/pkg/net/sockopt_posix.go:135 +0xdf + src/net/sockopt_posix.go:135 +0xdf net.setDeadline() - src/pkg/net/sockopt_posix.go:144 +0x9c + src/net/sockopt_posix.go:144 +0x9c net.(*conn).SetDeadline() - src/pkg/net/net.go:161 +0xe3 + src/net/net.go:161 +0xe3 net.func·061() - src/pkg/net/timeout_test.go:616 +0x3ed + src/net/timeout_test.go:616 +0x3ed Goroutine 185 (running) created at: net.func·061() - src/pkg/net/timeout_test.go:609 +0x288 + src/net/timeout_test.go:609 +0x288 Goroutine 184 (running) created at: net.TestProlongTimeout() - src/pkg/net/timeout_test.go:618 +0x298 + src/net/timeout_test.go:618 +0x298 testing.tRunner() - src/pkg/testing/testing.go:301 +0xe8 + src/testing/testing.go:301 +0xe8 </pre> <h2 id="Options">Options</h2> @@ -377,7 +377,8 @@ func (w *Watchdog) Start() { <h2 id="Supported_Systems">Supported Systems</h2> <p> -The race detector runs on <code>darwin/amd64</code>, <code>linux/amd64</code>, and <code>windows/amd64</code>. +The race detector runs on <code>darwin/amd64</code>, <code>freebsd/amd64</code>, +<code>linux/amd64</code>, and <code>windows/amd64</code>. </p> <h2 id="Runtime_Overheads">Runtime Overhead</h2> diff --git a/doc/asm.html b/doc/asm.html index d44cb799d..771c493cc 100644 --- a/doc/asm.html +++ b/doc/asm.html @@ -117,6 +117,9 @@ All user-defined symbols other than jump labels are written as offsets to these <p> The <code>SB</code> pseudo-register can be thought of as the origin of memory, so the symbol <code>foo(SB)</code> is the name <code>foo</code> as an address in memory. +This form is used to name global functions and data. +Adding <code><></code> to the name, as in <code>foo<>(SB)</code>, makes the name +visible only in the current source file, like a top-level <code>static</code> declaration in a C file. </p> <p> @@ -128,8 +131,11 @@ Thus <code>0(FP)</code> is the first argument to the function, When referring to a function argument this way, it is conventional to place the name at the beginning, as in <code>first_arg+0(FP)</code> and <code>second_arg+8(FP)</code>. Some of the assemblers enforce this convention, rejecting plain <code>0(FP)</code> and <code>8(FP)</code>. -For assembly functions with Go prototypes, <code>go vet</code> will check that the argument names +For assembly functions with Go prototypes, <code>go</code> <code>vet</code> will check that the argument names and offsets match. +On 32-bit systems, the low and high 32 bits of a 64-bit value are distinguished by adding +a <code>_lo</code> or <code>_hi</code> suffix to the name, as in <code>arg_lo+0(FP)</code> or <code>arg_hi+4(FP)</code>. +If a Go prototype does not name its result, the expected assembly name is <code>ret</code>. </p> <p> @@ -149,7 +155,7 @@ hardware's <code>SP</code> register. <p> Instructions, registers, and assembler directives are always in UPPER CASE to remind you that assembly programming is a fraught endeavor. -(Exceptions: the <code>m</code> and <code>g</code> register renamings on ARM.) +(Exception: the <code>g</code> register renaming on ARM.) </p> <p> @@ -206,6 +212,8 @@ The frame size <code>$24-8</code> states that the function has a 24-byte frame and is called with 8 bytes of argument, which live on the caller's frame. If <code>NOSPLIT</code> is not specified for the <code>TEXT</code>, the argument size must be provided. +For assembly functions with Go prototypes, <code>go</code> <code>vet</code> will check that the +argument size is correct. </p> <p> @@ -216,19 +224,20 @@ simple name <code>profileloop</code>. </p> <p> -For <code>DATA</code> directives, the symbol is followed by a slash and the number -of bytes the memory associated with the symbol occupies. -The arguments are optional flags and the data itself. -For instance, -</p> +Global data symbols are defined by a sequence of initializing +<code>DATA</code> directives followed by a <code>GLOBL</code> directive. +Each <code>DATA</code> directive initializes a section of the +corresponding memory. +The memory not explicitly initialized is zeroed. +The general form of the <code>DATA</code> directive is <pre> -DATA runtime·isplan9(SB)/4, $1 +DATA symbol+offset(SB)/width, value </pre> <p> -declares the local symbol <code>runtime·isplan9</code> of size 4 and value 1. -Again the symbol has the middle dot and is offset from <code>SB</code>. +which initializes the symbol memory at the given offset and width with the given value. +The <code>DATA</code> directives for a given symbol must be written with increasing offsets. </p> <p> @@ -237,15 +246,26 @@ The arguments are optional flags and the size of the data being declared as a gl which will have initial value all zeros unless a <code>DATA</code> directive has initialized it. The <code>GLOBL</code> directive must follow any corresponding <code>DATA</code> directives. -This example +</p> + +<p> +For example, </p> <pre> -GLOBL runtime·tlsoffset(SB),$4 +DATA divtab<>+0x00(SB)/4, $0xf4f8fcff +DATA divtab<>+0x04(SB)/4, $0xe6eaedf0 +... +DATA divtab<>+0x3c(SB)/4, $0x81828384 +GLOBL divtab<>(SB), RODATA, $64 + +GLOBL runtime·tlsoffset(SB), NOPTR, $4 </pre> <p> -declares <code>runtime·tlsoffset</code> to have size 4. +declares and initializes <code>divtab<></code>, a read-only 64-byte table of 4-byte integer values, +and declares <code>runtime·tlsoffset</code>, a 4-byte, implicitly zeroed variable that +contains no pointers. </p> <p> @@ -253,7 +273,7 @@ There may be one or two arguments to the directives. If there are two, the first is a bit mask of flags, which can be written as numeric expressions, added or or-ed together, or can be set symbolically for easier absorption by a human. -Their values, defined in the file <code>src/cmd/ld/textflag.h</code>, are: +Their values, defined in the standard <code>#include</code> file <code>textflag.h</code>, are: </p> <ul> @@ -299,6 +319,80 @@ This is a wrapper function and should not count as disabling <code>recover</code </li> </ul> +<h3 id="runtime">Runtime Coordination</h3> + +<p> +For garbage collection to run correctly, the runtime must know the +location of pointers in all global data and in most stack frames. +The Go compiler emits this information when compiling Go source files, +but assembly programs must define it explicitly. +</p> + +<p> +A data symbol marked with the <code>NOPTR</code> flag (see above) +is treated as containing no pointers to runtime-allocated data. +A data symbol with the <code>RODATA</code> flag +is allocated in read-only memory and is therefore treated +as implicitly marked <code>NOPTR</code>. +A data symbol with a total size smaller than a pointer +is also treated as implicitly marked <code>NOPTR</code>. +It is not possible to define a symbol containing pointers in an assembly source file; +such a symbol must be defined in a Go source file instead. +Assembly source can still refer to the symbol by name +even without <code>DATA</code> and <code>GLOBL</code> directives. +A good general rule of thumb is to define all non-<code>RODATA</code> +symbols in Go instead of in assembly. +</p> + +<p> +Each function also needs annotations giving the location of +live pointers in its arguments, results, and local stack frame. +For an assembly function with no pointer results and +either no local stack frame or no function calls, +the only requirement is to define a Go prototype for the function +in a Go source file in the same package. +For more complex situations, explicit annotation is needed. +These annotations use pseudo-instructions defined in the standard +<code>#include</code> file <code>funcdata.h</code>. +</p> + +<p> +If a function has no arguments and no results, +the pointer information can be omitted. +This is indicated by an argument size annotation of <code>$<i>n</i>-0</code> +on the <code>TEXT</code> instruction. +Otherwise, pointer information must be provided by +a Go prototype for the function in a Go source file, +even for assembly functions not called directly from Go. +(The prototype will also let <code>go</code> <code>vet</code> check the argument references.) +At the start of the function, the arguments are assumed +to be initialized but the results are assumed uninitialized. +If the results will hold live pointers during a call instruction, +the function should start by zeroing the results and then +executing the pseudo-instruction <code>GO_RESULTS_INITIALIZED</code>. +This instruction records that the results are now initialized +and should be scanned during stack movement and garbage collection. +It is typically easier to arrange that assembly functions do not +return pointers or do not contain call instructions; +no assembly functions in the standard library use +<code>GO_RESULTS_INITIALIZED</code>. +</p> + +<p> +If a function has no local stack frame, +the pointer information can be omitted. +This is indicated by a local frame size annotation of <code>$0-<i>n</i></code> +on the <code>TEXT</code> instruction. +The pointer information can also be omitted if the +function contains no call instructions. +Otherwise, the local stack frame must not contain pointers, +and the assembly must confirm this fact by executing the +pseudo-instruction <code>NO_LOCAL_POINTERS</code>. +Because stack resizing is implemented by moving the stack, +the stack pointer may change during any function call: +even pointers to stack data must not be kept in local variables. +</p> + <h2 id="architectures">Architecture-specific details</h2> <p> @@ -344,7 +438,7 @@ Here follows some descriptions of key Go-specific details for the supported arch <h3 id="x86">32-bit Intel 386</h3> <p> -The runtime pointers to the <code>m</code> and <code>g</code> structures are maintained +The runtime pointer to the <code>g</code> structure is maintained through the value of an otherwise unused (as far as Go is concerned) register in the MMU. A OS-dependent macro <code>get_tls</code> is defined for the assembler if the source includes an architecture-dependent header file, like this: @@ -356,14 +450,15 @@ an architecture-dependent header file, like this: <p> Within the runtime, the <code>get_tls</code> macro loads its argument register -with a pointer to a pair of words representing the <code>g</code> and <code>m</code> pointers. +with a pointer to the <code>g</code> pointer, and the <code>g</code> struct +contains the <code>m</code> pointer. The sequence to load <code>g</code> and <code>m</code> using <code>CX</code> looks like this: </p> <pre> get_tls(CX) -MOVL g(CX), AX // Move g into AX. -MOVL m(CX), BX // Move m into BX. +MOVL g(CX), AX // Move g into AX. +MOVL g_m(AX), BX // Move g->m into BX. </pre> <h3 id="amd64">64-bit Intel 386 (a.k.a. amd64)</h3> @@ -376,22 +471,21 @@ pointers is the same as on the 386, except it uses <code>MOVQ</code> rather than <pre> get_tls(CX) -MOVQ g(CX), AX // Move g into AX. -MOVQ m(CX), BX // Move m into BX. +MOVQ g(CX), AX // Move g into AX. +MOVQ g_m(AX), BX // Move g->m into BX. </pre> <h3 id="arm">ARM</h3> <p> -The registers <code>R9</code>, <code>R10</code>, and <code>R11</code> +The registers <code>R10</code> and <code>R11</code> are reserved by the compiler and linker. </p> <p> -<code>R9</code> and <code>R10</code> point to the <code>m</code> (machine) and <code>g</code> -(goroutine) structures, respectively. -Within assembler source code, these pointers must be referred to as <code>m</code> and <code>g</code>; -the names <code>R9</code> and <code>R10</code> are not recognized. +<code>R10</code> points to the <code>g</code> (goroutine) structure. +Within assembler source code, this pointer must be referred to as <code>g</code>; +the name <code>R10</code> is not recognized. </p> <p> @@ -434,13 +528,10 @@ Here's how the 386 runtime defines the 64-bit atomic load function. // so actually // void atomicload64(uint64 *res, uint64 volatile *addr); TEXT runtime·atomicload64(SB), NOSPLIT, $0-8 - MOVL 4(SP), BX - MOVL 8(SP), AX - // MOVQ (%EAX), %MM0 - BYTE $0x0f; BYTE $0x6f; BYTE $0x00 - // MOVQ %MM0, 0(%EBX) - BYTE $0x0f; BYTE $0x7f; BYTE $0x03 - // EMMS - BYTE $0x0F; BYTE $0x77 + MOVL ptr+0(FP), AX + LEAL ret_lo+4(FP), BX + BYTE $0x0f; BYTE $0x6f; BYTE $0x00 // MOVQ (%EAX), %MM0 + BYTE $0x0f; BYTE $0x7f; BYTE $0x03 // MOVQ %MM0, 0(%EBX) + BYTE $0x0F; BYTE $0x77 // EMMS RET </pre> diff --git a/doc/cmd.html b/doc/cmd.html index 725666f1d..5d20d3887 100644 --- a/doc/cmd.html +++ b/doc/cmd.html @@ -62,10 +62,10 @@ details. </tr> <tr> -<td><a href="//godoc.org/code.google.com/p/go.tools/cmd/cover/">cover</a></td> +<td><a href="//godoc.org/golang.org/x/tools/cmd/cover/">cover</a></td> <td> </td> <td>Cover is a program for creating and analyzing the coverage profiles -generated by <code>"go test -coverprofile"</code>. +generated by <code>"go test -coverprofile"</code>.</td> </tr> <tr> @@ -83,13 +83,13 @@ gofmt</a> command with more general options.</td> </tr> <tr> -<td><a href="//godoc.org/code.google.com/p/go.tools/cmd/godoc/">godoc</a></td> +<td><a href="//godoc.org/golang.org/x/tools/cmd/godoc/">godoc</a></td> <td> </td> <td>Godoc extracts and generates documentation for Go packages.</td> </tr> <tr> -<td><a href="//godoc.org/code.google.com/p/go.tools/cmd/vet/">vet</a></td> +<td><a href="//godoc.org/golang.org/x/tools/cmd/vet/">vet</a></td> <td> </td> <td>Vet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string.</td> diff --git a/doc/code.html b/doc/code.html index f019306fa..a4638f9ff 100644 --- a/doc/code.html +++ b/doc/code.html @@ -60,37 +60,35 @@ To give you an idea of how a workspace looks in practice, here's an example: <pre> bin/ - streak # command executable - todo # command executable + hello # command executable + outyet # command executable pkg/ linux_amd64/ - code.google.com/p/goauth2/ - oauth.a # package object - github.com/nf/todo/ - task.a # package object + github.com/golang/example/ + stringutil.a # package object src/ - code.google.com/p/goauth2/ - .hg/ # mercurial repository metadata - oauth/ - oauth.go # package source - oauth_test.go # test source - github.com/nf/ - streak/ - .git/ # git repository metadata - oauth.go # command source - streak.go # command source - todo/ - .git/ # git repository metadata - task/ - task.go # package source - todo.go # command source + <a href="https://github.com/golang/example/">github.com/golang/example/</a> + .git/ # Git repository metadata + hello/ + hello.go # command source + outyet/ + main.go # command source + main_test.go # test source + stringutil/ + reverse.go # package source + reverse_test.go # test source </pre> <p> -This workspace contains three repositories (<code>goauth2</code>, -<code>streak</code>, and <code>todo</code>) comprising two commands -(<code>streak</code> and <code>todo</code>) and two libraries -(<code>oauth</code> and <code>task</code>). +This workspace contains one repository (<code>example</code>) +comprising two commands (<code>hello</code> and <code>outyet</code>) +and one library (<code>stringutil</code>). +</p> + +<p> +A typical workspace would contain many source repositories containing many +packages and commands. Most Go programmers keep <i>all</i> their Go source code +and dependencies in a single workspace. </p> <p> @@ -277,29 +275,29 @@ Let's write a library and use it from the <code>hello</code> program. <p> Again, the first step is to choose a package path (we'll use -<code>github.com/user/newmath</code>) and create the package directory: +<code>github.com/user/stringutil</code>) and create the package directory: </p> <pre> -$ <b>mkdir $GOPATH/src/github.com/user/newmath</b> +$ <b>mkdir $GOPATH/src/github.com/user/stringutil</b> </pre> <p> -Next, create a file named <code>sqrt.go</code> in that directory with the +Next, create a file named <code>reverse.go</code> in that directory with the following contents. </p> <pre> -// Package newmath is a trivial example package. -package newmath - -// Sqrt returns an approximation to the square root of x. -func Sqrt(x float64) float64 { - z := 1.0 - for i := 0; i < 1000; i++ { - z -= (z*z - x) / (2 * z) +// Package stringutil contains utility functions for working with strings. +package stringutil + +// Reverse returns its argument string reversed rune-wise left to right. +func Reverse(s string) string { + r := []rune(s) + for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 { + r[i], r[j] = r[j], r[i] } - return z + return string(r) } </pre> @@ -308,7 +306,7 @@ Now, test that the package compiles with <code>go build</code>: </p> <pre> -$ <b>go build github.com/user/newmath</b> +$ <b>go build github.com/user/stringutil</b> </pre> <p> @@ -326,7 +324,7 @@ directory of the workspace. </p> <p> -After confirming that the <code>newmath</code> package builds, +After confirming that the <code>stringutil</code> package builds, modify your original <code>hello.go</code> (which is in <code>$GOPATH/src/github.com/user/hello</code>) to use it: </p> @@ -337,18 +335,18 @@ package main import ( "fmt" - <b>"github.com/user/newmath"</b> + <b>"github.com/user/stringutil"</b> ) func main() { - fmt.Printf("Hello, world. <b>Sqrt(2) = %v\n", newmath.Sqrt(2)</b>) + fmt.Printf(stringutil.Reverse("!oG ,olleH")) } </pre> <p> Whenever the <code>go</code> tool installs a package or binary, it also -installs whatever dependencies it has. So when you install the <code>hello</code> -program +installs whatever dependencies it has. +So when you install the <code>hello</code> program </p> <pre> @@ -356,16 +354,16 @@ $ <b>go install github.com/user/hello</b> </pre> <p> -the <code>newmath</code> package will be installed as well, automatically. +the <code>stringutil</code> package will be installed as well, automatically. </p> <p> -Running the new version of the program, you should see some numerical output: +Running the new version of the program, you should see a new, reversed message: </p> <pre> $ <b>hello</b> -Hello, world. Sqrt(2) = 1.414213562373095 +Hello, Go! </pre> <p> @@ -374,22 +372,22 @@ After the steps above, your workspace should look like this: <pre> bin/ - hello # command executable + hello # command executable pkg/ - linux_amd64/ # this will reflect your OS and architecture + linux_amd64/ # this will reflect your OS and architecture github.com/user/ - newmath.a # package object + stringutil.a # package object src/ github.com/user/ hello/ - hello.go # command source - newmath/ - sqrt.go # package source + hello.go # command source + stringutil/ + reverse.go # package source </pre> <p> -Note that <code>go install</code> placed the <code>newmath.a</code> object in a -directory inside <code>pkg/linux_amd64</code> that mirrors its source +Note that <code>go install</code> placed the <code>stringutil.a</code> object +in a directory inside <code>pkg/linux_amd64</code> that mirrors its source directory. This is so that future invocations of the <code>go</code> tool can find the package object and avoid recompiling the package unnecessarily. @@ -457,20 +455,29 @@ if the function calls a failure function such as <code>t.Error</code> or </p> <p> -Add a test to the <code>newmath</code> package by creating the file -<code>$GOPATH/src/github.com/user/newmath/sqrt_test.go</code> containing the -following Go code. +Add a test to the <code>stringutil</code> package by creating the file +<code>$GOPATH/src/github.com/user/stringutil/reverse_test.go</code> containing +the following Go code. </p> <pre> -package newmath +package stringutil import "testing" -func TestSqrt(t *testing.T) { - const in, out = 4, 2 - if x := Sqrt(in); x != out { - t.Errorf("Sqrt(%v) = %v, want %v", in, x, out) +func TestReverse(t *testing.T) { + cases := []struct { + in, want string + }{ + {"Hello, world", "dlrow ,olleH"}, + {"Hello, 世界", "界世 ,olleH"}, + {"", ""}, + } + for _, c := range cases { + got := Reverse(c.in) + if got != c.want { + t.Errorf("Reverse(%q) == %q, want %q", c.in, got, c.want) + } } } </pre> @@ -480,8 +487,8 @@ Then run the test with <code>go test</code>: </p> <pre> -$ <b>go test github.com/user/newmath</b> -ok github.com/user/newmath 0.165s +$ <b>go test github.com/user/stringutil</b> +ok github.com/user/stringutil 0.165s </pre> <p> @@ -491,7 +498,7 @@ directory, you can omit the package path: <pre> $ <b>go test</b> -ok github.com/user/newmath 0.165s +ok github.com/user/stringutil 0.165s </pre> <p> @@ -507,16 +514,16 @@ An import path can describe how to obtain the package source code using a revision control system such as Git or Mercurial. The <code>go</code> tool uses this property to automatically fetch packages from remote repositories. For instance, the examples described in this document are also kept in a -Mercurial repository hosted at Google Code, -<code><a href="//code.google.com/p/go.example">code.google.com/p/go.example</a></code>. +Git repository hosted at GitHub +<code><a href="https://github.com/golang/example">github.com/golang/example</a></code>. If you include the repository URL in the package's import path, <code>go get</code> will fetch, build, and install it automatically: </p> <pre> -$ <b>go get code.google.com/p/go.example/hello</b> +$ <b>go get github.com/golang/example/hello</b> $ <b>$GOPATH/bin/hello</b> -Hello, world. Sqrt(2) = 1.414213562373095 +Hello, Go examples! </pre> <p> @@ -533,43 +540,45 @@ tree should now look like this: <pre> bin/ - hello # command executable + hello # command executable pkg/ linux_amd64/ - code.google.com/p/go.example/ - newmath.a # package object + github.com/golang/example/ + stringutil.a # package object github.com/user/ - newmath.a # package object + stringutil.a # package object src/ - code.google.com/p/go.example/ + github.com/golang/example/ + .git/ # Git repository metadata hello/ - hello.go # command source - newmath/ - sqrt.go # package source - sqrt_test.go # test source + hello.go # command source + stringutil/ + reverse.go # package source + reverse_test.go # test source github.com/user/ hello/ - hello.go # command source - newmath/ - sqrt.go # package source - sqrt_test.go # test source + hello.go # command source + stringutil/ + reverse.go # package source + reverse_test.go # test source </pre> <p> -The <code>hello</code> command hosted at Google Code depends on the -<code>newmath</code> package within the same repository. The imports in -<code>hello.go</code> file use the same import path convention, so the <code>go -get</code> command is able to locate and install the dependent package, too. +The <code>hello</code> command hosted at GitHub depends on the +<code>stringutil</code> package within the same repository. The imports in +<code>hello.go</code> file use the same import path convention, so the +<code>go get</code> command is able to locate and install the dependent +package, too. </p> <pre> -import "code.google.com/p/go.example/newmath" +import "github.com/golang/example/stringutil" </pre> <p> This convention is the easiest way to make your Go packages available for others to use. -The <a href="//code.google.com/p/go-wiki/wiki/Projects">Go Wiki</a> +The <a href="//golang.org/wiki/Projects">Go Wiki</a> and <a href="//godoc.org/">godoc.org</a> provide lists of external Go projects. </p> @@ -618,5 +627,5 @@ The official mailing list for discussion of the Go language is <p> Report bugs using the -<a href="//code.google.com/p/go/issues/list">Go issue tracker</a>. +<a href="//golang.org/issue">Go issue tracker</a>. </p> diff --git a/doc/contrib.html b/doc/contrib.html index a615fc67a..93a609fb2 100644 --- a/doc/contrib.html +++ b/doc/contrib.html @@ -30,21 +30,16 @@ We encourage all Go users to subscribe to <h2 id="go1">Version history</h2> <h3 id="release"><a href="/doc/devel/release.html">Release History</a></h3> -<p>A summary of the changes between Go releases.</p> -<h4 id="go1notes"><a href="/doc/go1">Go 1 Release Notes</a></h4> -<p> -A guide for updating your code to work with Go 1. -</p> +<p>A <a href="/doc/devel/release.html">summary</a> of the changes between Go releases. Notes for the major releases:</p> -<h4 id="release notes"><a href="/doc/go1.1">Go 1.1 Release Notes</a></h4> -<p> -A list of significant changes in Go 1.1, with instructions for updating -your code where necessary. -Each point release includes a similar document appropriate for that -release: <a href="/doc/go1.2">Go 1.2</a>, <a href="/doc/go1.3">Go 1.3</a>, -and so on. -</p> +<ul> + <li><a href="/doc/go1.4">Go 1.4</a> <small>(December 2014)</small></li> + <li><a href="/doc/go1.3">Go 1.3</a> <small>(June 2014)</small></li> + <li><a href="/doc/go1.2">Go 1.2</a> <small>(December 2013)</small></li> + <li><a href="/doc/go1.1">Go 1.1</a> <small>(May 2013)</small></li> + <li><a href="/doc/go1">Go 1</a> <small>(March 2012)</small></li> +</ul> <h3 id="go1compat"><a href="/doc/go1compat">Go 1 and the Future of Go Programs</a></h3> <p> @@ -55,7 +50,7 @@ Go 1 matures. <h2 id="resources">Developer Resources</h2> -<h3 id="source"><a href="https://code.google.com/p/go/source">Source Code</a></h3> +<h3 id="source"><a href="https://golang.org/change">Source Code</a></h3> <p>Check out the Go source code.</p> <h3 id="golang-dev"><a href="https://groups.google.com/group/golang-dev">Developer</a> and @@ -81,13 +76,13 @@ systems and architectures.</p> <h2 id="howto">How you can help</h2> -<h3><a href="https://code.google.com/p/go/issues">Reporting issues</a></h3> +<h3><a href="//golang.org/issue">Reporting issues</a></h3> <p> If you spot bugs, mistakes, or inconsistencies in the Go project's code or documentation, please let us know by -<a href="https://code.google.com/p/go/issues/entry">filing a ticket</a> -on our <a href="https://code.google.com/p/go/issues">issue tracker</a>. +<a href="//golang.org/issue/new">filing a ticket</a> +on our <a href="//golang.org/issue">issue tracker</a>. (Of course, you should check it's not an existing issue before creating a new one.) </p> @@ -106,8 +101,8 @@ To get started, read these <a href="/doc/contribute.html">contribution guidelines</a> for information on design, testing, and our code review process. </p> <p> -Check <a href="https://code.google.com/p/go/issues">the tracker</a> for +Check <a href="//golang.org/issue">the tracker</a> for open issues that interest you. Those labeled -<a href="https://code.google.com/p/go/issues/list?q=status=HelpWanted">HelpWanted</a> +<a href="https://github.com/golang/go/issues?q=is%3Aopen+is%3Aissue+label%3Ahelpwanted">helpwanted</a> are particularly in need of outside help. </p> diff --git a/doc/contribute.html b/doc/contribute.html index 392734985..ba550d528 100644 --- a/doc/contribute.html +++ b/doc/contribute.html @@ -6,9 +6,21 @@ <p> This document explains how to contribute changes to the Go project. -It assumes you have installed Go using the +It assumes you have installed Go from source: +<p> + +<pre> +$ git clone https://go.googlesource.com/go +$ cd go/src +$ ./all.bash +</pre> +<!-- +TODO(adg): delete the above, restore the below after we have updated install-source.html <a href="/doc/install/source">installation instructions</a> and have <a href="code.html">written and tested your code</a>. +--> + +<p> (Note that the <code>gccgo</code> frontend lives elsewhere; see <a href="gccgo_contribute.html">Contributing to gccgo</a>.) </p> @@ -54,7 +66,8 @@ $ ./all.bash </p> <p> -After running for a while, the command should print "<code>ALL TESTS PASSED</code>". +After running for a while, the command should print +"<code>ALL</code> <code>TESTS</code> <code>PASSED</code>". </p> <h2 id="Code_review">Code review</h2> @@ -64,208 +77,229 @@ Changes to Go must be reviewed before they are submitted, no matter who makes the change. (In exceptional cases, such as fixing a build, the review can follow shortly after submitting.) -A Mercurial extension helps manage the code review process. -The extension is included in the Go source tree but needs -to be added to your Mercurial configuration. +A custom git command called <code>git-review</code>, +discussed below, helps manage the code review process through a Google-hosted +<a href="https://go-review.googlesource.com/">instance</a> of the code review +system called <a href="https://code.google.com/p/gerrit/">Gerrit</a>. </p> -<h3>Caveat for Mercurial aficionados</h3> +<h3>Set up authentication for code review</h3> <p> -<i>Using Mercurial with the code review extension is not the same -as using standard Mercurial.</i> +The Git code hosting server and Gerrit code review server both use a Google +Account to authenticate. You therefore need a Google Account to proceed. +(If you can use the account to +<a href="https://www.google.com/accounts/Login">sign in at google.com</a>, +you can use it to sign in to the code review server.) +The email address you use with the code review system +will be recorded in the <a href="https://go.googlesource.com/go">change log</a> +and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file. +You can <a href="https://www.google.com/accounts/NewAccount">create a Google Account</a> +associated with any address where you receive email. +</p> + +<p> +Visit the site <a href="https://go.googlesource.com">go.googlesource.com</a> +and log in using your Google Account. +Click on the "Generate Password" link that appears at the top of the page. </p> <p> -The Go repository is maintained as a single line of reviewed changes; -we prefer to avoid the complexity of Mercurial's arbitrary change graph. -The code review extension helps here: its <code>hg submit</code> command -automatically checks for and warns about the local repository -being out of date compared to the remote one. -The <code>hg submit</code> command also verifies other -properties about the Go repository. -For example, -it checks that Go code being checked in is formatted in the standard style, -as defined by <a href="/cmd/gofmt">gofmt</a>, -and it checks that the author of the code is properly recorded for -<a href="#copyright">copyright purposes</a>. +Click the radio button that says "Only <code>go.googlesource.com</code>" +to use this authentication token only for the Go project. </p> <p> -To help ensure changes are only created by <code>hg submit</code>, -the code review extension disables the standard <code>hg commit</code> -command. +Further down the page is a box containing commands to install +the authentication cookie in file called <code>.gitcookies</code> in your home +directory. +Copy the text for the commands into a Unix shell window to execute it. +That will install the authentication token. </p> -<h3>Configure the extension</h3> +<p> +(If you are on a Windows computer, you should instead follow the instructions +in the yellow box to run the command.) +</p> -<p>Edit <code>.hg/hgrc</code> in the root of your Go checkout to add:</p> +<h3>Register with Gerrit</h3> -<pre> -[extensions] -codereview = /path/to/go/lib/codereview/codereview.py +<p> +Now that you have a Google account and the authentication token, +you need to register your account with Gerrit, the code review system. +To do this, visit <a href="https://golang.org/cl">golang.org/cl</a> +and log in using the same Google Account you used above. +That is all that is required. +</p> -[ui] -username = Your Name <you@server.dom> +<h3>Install the git-review command</h3> + +<p> +Now install the <code>git-review</code> command by running, +</p> + +<pre> +go get -u golang.org/x/review/git-review </pre> <p> -The <code>username</code> information will not be used unless -you are a committer (see below), but Mercurial complains if it is missing. +Make sure <code>git-review</code> is installed in your shell path, so that the +<code>git</code> command can find it. Check that </p> +<pre> +$ git review help +</pre> + <p> -As the codereview extension is only enabled for your Go checkout, the remainder of this document assumes you -are inside the go directory when issuing commands. +prints help text, not an error. </p> -<p>To contribute to subrepositories, edit the <code>.hg/hgrc</code> for each -subrepository in the same way. For example, add the codereview extension to -<code>code.google.com/p/go.tools/.hg/hgrc</code>. +<p> +Note to Git aficionados: The <code>git-review</code> command is not required to +upload and manage Gerrit code reviews. For those who prefer plain Git, the text +below gives the Git equivalent of each git-review command. If you do use plain +Git, note that you still need the commit hooks that the git-review command +configures; those hooks add a Gerrit <code>Change-Id</code> line to the commit +message and check that all Go source files have been formatted with gofmt. Even +if you intend to use plain Git for daily work, install the hooks in a new Git +checkout by running <code>git-review</code> <code>hooks</code>). </p> -<h3>Understanding the extension</h3> +<h3>Set up git aliases</h3> -<p>After adding the code review extension, you can run</p> +<p> +The <code>git-review</code> command can be run directly from the shell +by typing, for instance, +</p> <pre> -$ hg help codereview +$ git review sync </pre> -<p>to learn more about its commands. To learn about a specific code-review-specific -command such as <code>change</code>, run</p> +<p> +but it is more convenient to set up aliases for <code>git-review</code>'s own +subcommands, so that the above becomes, +</p> <pre> -$ hg help change +$ git sync </pre> -<p> -Windows users may need to perform extra steps to get the code review -extension working. See the -<a href="https://code.google.com/p/go-wiki/wiki/CodeReview">CodeReview page</a> -on the <a href="https://code.google.com/p/go-wiki/wiki">Go Wiki</a> for details. </p> - -<h3>Log in to the code review site.</h3> +The <code>git-review</code> subcommands have been chosen to be distinct from +Git's own, so it's safe to do so. +</p> <p> -The code review server uses a Google Account to authenticate. -(If you can use the account to -<a href="https://www.google.com/accounts/Login?hl=en&continue=http://www.google.com/">sign in at google.com</a>, -you can use it to sign in to the code review server.) -The email address you use on the Code Review site -will be recorded in the <a href="https://code.google.com/p/go/source/list">Mercurial change log</a> -and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file. -You can <a href="https://www.google.com/accounts/NewAccount">create a Google Account</a> -associated with any address where you receive email. -If you've enabled the two-step verification feature, don't forget to generate an -application-specific password and use that when prompted for a password. +The aliases are optional, but in the rest of this document we will assume +they are installed. +To install them, copy this text into your Git configuration file +(usually <code>.gitconfig</code> in your home directory): </p> <pre> -$ hg code-login -Email (login for uploading to codereview.appspot.com): rsc@golang.org -Password for rsc@golang.org: - -Saving authentication cookies to /Users/rsc/.codereview_upload_cookies_codereview.appspot.com +[alias] + change = review change + gofmt = review gofmt + mail = review mail + pending = review pending + sync = review sync </pre> -<h3>Configure your account settings.</h3> +<h3>Understanding the git-review command</h3> -<p>Edit your <a href="https://codereview.appspot.com/settings">code review settings</a>. -Grab a nickname. -Many people prefer to set the Context option to -“Whole file” to see more context when reviewing changes. -</p> +<p>After installing the <code>git-review</code> command, you can run</p> + +<pre> +$ git review help +</pre> -<p>Once you have chosen a nickname in the settings page, others -can use that nickname as a shorthand for naming reviewers and the CC list. -For example, <code>rsc</code> is an alias for <code>rsc@golang.org</code>. +<p> +to learn more about its commands. +You can also read the <a href="https://godoc.org/golang.org/x/review/git-review">command documentation</a>. </p> -<h3>Switch to the default branch</h3> +<h3>Switch to the master branch</h3> <p> Most Go installations use a release branch, but new changes should -only be made to the default branch. (They may be applied later to a release -branch as part of the release process.) -Before making a change, make sure you use the default branch: +only be made based on the master branch. +(They may be applied later to a release branch as part of the release process, +but most contributors won't do this themselves.) +Before making a change, make sure you start on the master branch: </p> <pre> -$ hg update default +$ git checkout master +$ git sync </pre> +<p> +(In Git terms, <code>git</code> <code>sync</code> runs +<code>git</code> <code>pull</code> <code>-r</code>.) +</p> + <h3>Make a change</h3> <p> The entire checked-out tree is writable. -If you need to edit files, just edit them: Mercurial will figure out which ones changed. -You do need to inform Mercurial of added, removed, copied, or renamed files, -by running -<code>hg add</code>, -<code>hg rm</code>, -<code>hg cp</code>, -or -<code>hg mv</code>. +Once you have edited files, you must tell Git that they have been modified. +You must also tell Git about any files that are added, removed, or renamed files. +These operations are done with the usual Git commands, +<code>git</code> <code>add</code>, +<code>git</code> <code>rm</code>, +and +<code>git</code> <code>mv</code>. </p> -<p>When you are ready to send a change out for review, run</p> +<p> +If you wish to checkpoint your work, or are ready to send the code out for review, run</p> <pre> -$ hg change +$ git change <i><branch></i> </pre> -<p>from any directory in your Go repository. -Mercurial will open a change description file in your editor. -(It uses the editor named by the <code>$EDITOR</code> environment variable, <code>vi</code> by default.) -The file will look like: +<p> +from any directory in your Go repository to commit the changes so far. +The name <i><branch></i> is an arbitrary one you choose to identify the +local branch containing your changes. </p> -<pre> -# Change list. -# Lines beginning with # are ignored. -# Multi-line values should be indented. +<p> +(In Git terms, <code>git</code> <code>change</code> <code><branch></code> +runs <code>git</code> <code>checkout</code> <code>-b</code> <code>branch</code>, +then <code>git</code> <code>branch</code> <code>--set-upstream-to</code> <code>origin/master</code>, +then <code>git</code> <code>commit</code>.) +</p> -Reviewer: -CC: +<p> +Git will open a change description file in your editor. +(It uses the editor named by the <code>$EDITOR</code> environment variable, +<code>vi</code> by default.) +The file will look like: +</p> -Description: - <enter description here> +<pre> -Files: - src/pkg/math/sin.go - src/pkg/math/tan.go - src/pkg/regexp/regexp.go +# Please enter the commit message for your changes. Lines starting +# with '#' will be ignored, and an empty message aborts the commit. +# On branch foo +# Changes not staged for commit: +# modified: editedfile.go +# </pre> <p> -The <code>Reviewer</code> line lists the reviewers assigned -to this change, and the <code>CC</code> line lists people to -notify about the change. -These can be code review nicknames or arbitrary email addresses. -Unless explicitly told otherwise, such as in the discussion leading -up to sending in the change list, leave the reviewer field blank. -This means that the -<a href="https://groups.google.com/group/golang-codereviews">golang-codereviews@googlegroups.com</a> -mailing list will be used as the reviewer. -</p> - -<p> -Replace “<code><enter description here></code>” -with a description of your change. +At the beginning of this file is a blank line; replace it +with a thorough description of your change. The first line of the change description is conventionally a one-line summary of the change, prefixed by the primary affected package, -and is used as the subject for code review mail; the rest of the -description elaborates. -</p> - -<p> -The <code>Files</code> section lists all the modified files -in your client. -It is best to keep unrelated changes in different change lists. -In this example, we can include just the changes to package <code>math</code> -by deleting the line mentioning <code>regexp.go</code>. +and is used as the subject for code review mail. +The rest of the +description elaborates and should provide context for the +change and explain what it does. +If there is a helpful reference, mention it here. </p> <p> @@ -273,343 +307,314 @@ After editing, the template might now read: </p> <pre> -# Change list. -# Lines beginning with # are ignored. -# Multi-line values should be indented. +math: improved Sin, Cos and Tan precision for very large arguments -Reviewer: golang-codereviews@googlegroups.com -CC: math-nuts@swtch.com +The existing implementation has poor numerical properties for +large arguments, so use the McGillicutty algorithm to improve +accuracy above 1e10. -Description: - math: improved Sin, Cos and Tan precision for very large arguments. +The algorithm is described at http://wikipedia.org/wiki/McGillicutty_Algorithm - See Bimmler and Shaney, ``Extreme sinusoids,'' J. Math 3(14). - Fixes issue 159. +Fixes #159 -Files: - src/pkg/math/sin.go - src/pkg/math/tan.go +# Please enter the commit message for your changes. Lines starting +# with '#' will be ignored, and an empty message aborts the commit. +# On branch foo +# Changes not staged for commit: +# modified: editedfile.go +# </pre> <p> -The special sentence “Fixes issue 159.” associates -the change with issue 159 in the <a href="https://code.google.com/p/go/issues/list">Go issue tracker</a>. +The commented section of the file lists all the modified files in your client. +It is best to keep unrelated changes in different change lists, +so if you see a file listed that should not be included, abort +the command and move that file to a different branch. +</p> + +<p> +The special notation "Fixes #159" associates the change with issue 159 in the +<a href="https://golang.org/issue/159">Go issue tracker</a>. When this change is eventually submitted, the issue tracker will automatically mark the issue as fixed. -(These conventions are described in detail by the -<a href="https://code.google.com/p/support/wiki/IssueTracker#Integration_with_version_control">Google Project Hosting Issue Tracker documentation</a>.) +(There are several such conventions, described in detail in the +<a href="https://help.github.com/articles/closing-issues-via-commit-messages/">GitHub Issue Tracker documentation</a>.) </p> <p> -Save the file and exit the editor.</p> +Once you have finished writing the commit message, +save the file and exit the editor. +</p> <p> -The code review server assigns your change an issue number and URL, -which <code>hg change</code> will print, something like: +If you wish to do more editing, re-stage your changes using +<code>git</code> <code>add</code>, and then run </p> <pre> -CL created: https://codereview.appspot.com/99999 +$ git change </pre> -<h3>Adding or removing files from an existing change</h3> - <p> -If you need to re-edit the change description, or change the files included in the CL, -run <code>hg change 99999</code>. +to update the change description and incorporate the staged changes. The +change description contains a <code>Change-Id</code> line near the bottom, +added by a Git commit hook during the initial +<code>git</code> <code>change</code>. +That line is used by Gerrit to match successive uploads of the same change. +Do not edit or delete it. </p> <p> -Alternatively, you can use +(In Git terms, <code>git</code> <code>change</code> with no branch name +runs <code>git</code> <code>commit</code> <code>--amend</code>.) +</p> + +<h3>Mail the change for review</h3> + +<p> +Once the change is ready, mail it out for review: </p> <pre> -$ hg file 99999 somefile +$ git mail </pre> <p> -to add <code>somefile</code> to CL 99999, and +You can specify a reviewer or CC interested parties +using the <code>-r</code> or <code>-cc</code> options. +Both accept a comma-separated list of email addresses: </p> <pre> -$ hg file -d 99999 somefile +$ git mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com </pre> <p> -to remove <code>somefile</code> from the CL. +Unless explicitly told otherwise, such as in the discussion leading +up to sending in the change list, it's better not to specify a reviewer. +All changes are automatically CC'ed to the +<a href="https://groups.google.com/group/golang-codereviews">golang-codereviews@googlegroups.com</a> +mailing list. </p> <p> -A file may only belong to a single active CL at a time. <code>hg file</code> -will issue a warning if a file is moved between changes. +(In Git terms, <code>git</code> <code>mail</code> pushes the local committed +changes to Gerrit using <code>git</code> <code>push</code> <code>origin</code> +<code>HEAD:refs/for/master</code>.) </p> -<h3>Synchronize your client</h3> - -<p>While you were working, others might have submitted changes -to the repository. To update your client, run</p> - -<pre> -$ hg sync -</pre> - -<p>(For Mercurial fans, <code>hg sync</code> runs <code>hg pull -u</code> -but then also synchronizes the local change list state against the new data.)</p> - <p> -If files you were editing have changed, Mercurial does its best to merge the -remote changes into your local changes. It may leave some files to merge by hand. +If your change relates to an open issue, please add a comment to the issue +announcing your proposed fix, including a link to your CL. </p> <p> -For example, suppose you have edited <code>flag_test.go</code> but -someone else has committed an independent change. -When you run <code>hg sync</code>, you will get the (scary-looking) output -(emphasis added): +The code review server assigns your change an issue number and URL, +which <code>git</code> <code>mail</code> will print, something like: +</p> <pre> -$ hg sync -adding changesets -adding manifests -adding file changes -added 1 changeset with 2 changes to 2 files -getting src/pkg/flag/flag.go -couldn't find merge tool hgmerge -merging src/pkg/flag/flag_test.go -warning: conflicts during merge. -<i>merging src/pkg/flag/flag_test.go failed!</i> -1 file updated, 0 files merged, 0 files removed, 1 file unresolved -use 'hg resolve' to retry unresolved file merges -$ +remote: New Changes: +remote: https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments </pre> +<h3>Reviewing code</h3> + <p> -The only important part in that transcript is the italicized line: -Mercurial failed to merge your changes with the independent change. -When this happens, Mercurial leaves both edits in the file, -marked by <code><<<<<<<</code> and -<code>>>>>>>></code>. -it is now your job to edit the file to combine them. -Continuing the example, searching for those strings in <code>flag_test.go</code> -might turn up: +Running <code>git</code> <code>mail</code> will send an email to you and the +reviewers asking them to visit the issue's URL and make comments on the change. +When done, the reviewer adds comments through the Gerrit user interface +and clicks "Reply" to send comments back. +You will receive a mail notification when this happens. +You must reply through the web interface. +(Unlike with the old Rietveld review system, replying by mail has no effect.) </p> -<pre> - VisitAll(visitor); -<<<<<<< local - if len(m) != 7 { -======= - if len(m) != 8 { ->>>>>>> other - t.Error("VisitAll misses some flags"); -</pre> +<h3>Revise and upload</h3> <p> -Mercurial doesn't show it, but suppose the original text that both edits -started with was 6; you added 1 and the other change added 2, -so the correct answer might now be 9. First, edit the section -to remove the markers and leave the correct code: +You must respond to review comments through the web interface. +(Unlike with the old Rietveld review system, responding by mail has no effect.) </p> -<pre> - VisitAll(visitor); - if len(m) != 9 { - t.Error("VisitAll misses some flags"); -</pre> - <p> -Then ask Mercurial to mark the conflict as resolved: +When you have revised the code and are ready for another round of review, +stage those changes and use <code>git</code> <code>change</code> to update the +commit. +To send the update change list for another round of review, +run <code>git</code> <code>mail</code> again. </p> -<pre> -$ hg resolve -m flag_test.go -</pre> - <p> -If you had been editing the file, say for debugging, but do not -care to preserve your changes, you can run -<code>hg revert flag_test.go</code> to abandon your -changes, but you may still need to run -<code>hg resolve -m</code> to mark the conflict resolved. +The reviewer can comment on the new copy, and the process repeats. +The reviewer approves the change by giving it a positive score +(+1 or +2) and replying <code>LGTM</code>: looks good to me. </p> -<h3>Mail the change for review</h3> - <p> -Creating or uploading the change uploads a copy of the diff to the code review server, -but it does not notify anyone about it. To do that, you need to run <code>hg mail</code> -(see below). +You can see a list of your pending changes by running <code>git</code> +<code>pending</code>, and switch between change branches with <code>git</code> +<code>change</code> <code><i><branch></i></code>. </p> -<p>To send out a change for review, run <code>hg mail</code> using the change list number -assigned during <code>hg change</code>:</p> - -<pre> -$ hg mail 99999 -</pre> +<h3>Synchronize your client</h3> -<p>You can add to the <code>Reviewer:</code> and <code>CC:</code> lines -using the <code>-r</code> or <code>--cc</code> options. -In the above example, we could have left the <code>Reviewer</code> and <code>CC</code> -lines blank and then run: +<p> +While you were working, others might have submitted changes to the repository. +To update your local branch, run </p> <pre> -$ hg mail -r golang-codereviews@googlegroups.com --cc math-nuts@swtch.com 99999 +$ git sync </pre> -<p>to achieve the same effect.</p> - -<p>Note that <code>-r</code> and <code>--cc</code> cannot be spelled <code>--r</code> or <code>-cc</code>.</p> - <p> -If your change relates to an open issue, please add a comment to the issue -announcing your proposed fix, including a link to your CL. +(In git terms, git sync runs +<code>git</code> <code>pull</code> <code>-r</code>.) </p> -<h3>Reviewing code</h3> - <p> -Running <code>hg mail</code> will send an email to you and the reviewers -asking them to visit the issue's URL and make comments on the change. -When done, the reviewer clicks “Publish and Mail comments” -to send comments back. +If files you were editing have changed, Git does its best to merge the +remote changes into your local changes. +It may leave some files to merge by hand. </p> - -<h3>Revise and upload</h3> - <p> -When you have revised the code and are ready for another round of review, -you can upload your change and send mail asking the reviewers to -please take another look (<code>PTAL</code>). Use the change list number -assigned during <code>hg change</code> -</p> +For example, suppose you have edited <code>sin.go</code> but +someone else has committed an independent change. +When you run <code>git</code> <code>sync</code>, +you will get the (scary-looking) output: <pre> -$ hg mail 99999 +$ git sync +Failed to merge in the changes. +Patch failed at 0023 math: improved Sin, Cos and Tan precision for very large arguments +The copy of the patch that failed is found in: + /home/you/repo/.git/rebase-apply/patch + +When you have resolved this problem, run "git rebase --continue". +If you prefer to skip this patch, run "git rebase --skip" instead. +To check out the original branch and stop rebasing, run "git rebase --abort". </pre> - <p> -Or to upload your change without sending a notification, run +If this happens, run </p> <pre> -$ hg upload 99999 +$ git status </pre> <p> -You will probably revise your code in response to the reviewer comments. -You might also visit the code review web page and reply to the comments, -letting the reviewer know that you've addressed them or explain why you -haven't. When you're done replying, click “Publish and Mail comments” -to send the line-by-line replies and any other comments. +to see which files failed to merge. +The output will look something like this: </p> -<p> -The reviewer can comment on the new copy, and the process repeats. -The reviewer approves the change by replying with a mail that says -<code>LGTM</code>: looks good to me. -</p> +<pre> +rebase in progress; onto a24c3eb +You are currently rebasing branch 'mcgillicutty' on 'a24c3eb'. + (fix conflicts and then run "git rebase --continue") + (use "git rebase --skip" to skip this patch) + (use "git rebase --abort" to check out the original branch) -<p> -You can see a list of your pending changes by running <code>hg pending</code> (<code>hg p</code> for short). -</p> +Unmerged paths: + (use "git reset HEAD <file>..." to unstage) + (use "git add <file>..." to mark resolution) -<h3>Reviewing code by others</h3> + <i>both modified: sin.go</i> +</pre> <p> -You can import a CL proposed by someone else into your local Mercurial client -by using the <code>hg clpatch</code> command. Running +The only important part in that transcript is the italicized "both modified" +line: Git failed to merge your changes with the conflicting change. +When this happens, Git leaves both sets of edits in the file, +with conflicts marked by <code><<<<<<<</code> and +<code>>>>>>>></code>. +It is now your job to edit the file to combine them. +Continuing the example, searching for those strings in <code>sin.go</code> +might turn up: </p> <pre> -$ hg clpatch 99999 + arg = scale(arg) +<<<<<<< HEAD + if arg > 1e9 { +======= + if arg > 1e10 { +>>>>>>> mcgillicutty + largeReduce(arg) </pre> <p> -will apply the latest diff for CL 99999 to your working copy. If any of the -files referenced in CL 99999 have local modifications, <code>clpatch</code> -will refuse to apply the whole diff. Once applied, CL 99999 will show up in -the output of <code>hg pending</code> and others. -</p> - -<p> -To revert a CL you have applied locally, use the <code>hg revert</code> -command. Running +Git doesn't show it, but suppose the original text that both edits +started with was 1e8; you changed it to 1e10 and the other change to 1e9, +so the correct answer might now be 1e10. First, edit the section +to remove the markers and leave the correct code: </p> <pre> -$ hg revert @99999 + arg = scale(arg) + if arg > 1e10 { + largeReduce(arg) </pre> <p> -will revert any files mentioned on CL 99999 to their original state. This can -be an effective way of reverting one CL revision and applying another. +Then tell Git that the conflict is resolved by running </p> -<p> -Once the CL has been submitted, the next time you run <code>hg sync</code> -it will be removed from your local pending list. Occasionally the pending list -can get out of sync leaving stale references to closed or abandoned CLs. -You can use <code>hg change -D 99999</code> to remove the reference to CL 99999. -</p> - -<h3>Submit the change after the review</h3> +<pre> +$ git add sin.go +</pre> <p> -After the code has been <code>LGTM</code>'ed, it is time to submit -it to the Mercurial repository. +If you had been editing the file, say for debugging, but do not +care to preserve your changes, you can run +<code>git</code> <code>reset</code> <code>HEAD</code> <code>sin.go</code> +to abandon your changes. +Then run <code>git</code> <code>rebase</code> <code>--continue</code> to +restore the change commit. </p> +<h3>Reviewing code by others</h3> + <p> -If you are not a committer, you cannot submit the change directly. -Instead a committer, usually the reviewer who said <code>LGTM</code>, -will run: +You can import a change proposed by someone else into your local Git repository. +On the Gerrit review page, click the "Download ▼" link in the upper right +corner, copy the "Checkout" command and run it from your local Git repo. +It should look something like this: </p> <pre> -$ hg clpatch 99999 -$ hg submit 99999 +$ git fetch https://go.googlesource.com/review refs/changes/21/1221/1 && git checkout FETCH_HEAD </pre> <p> -The <code>submit</code> command submits the code. You will be listed as the -author, but the change message will also indicate who the committer was. -Your local client will notice that the change has been submitted -when you next run <code>hg sync</code>. +To revert, change back to the branch you were working in. </p> +<h3>Submit the change after the review</h3> + <p> -If you are a committer, you can run: +After the code has been <code>LGTM</code>'ed, an approver may +submit it to the master branch using the Gerrit UI. +There is a "Submit" button on the web page for the change +that appears once the change is approved (marked +2). </p> -<pre> -$ hg submit 99999 -</pre> - <p> This checks the change into the repository. The change description will include a link to the code review, and the code review will be updated with a link to the change in the repository. +Since the method used to integrate the changes is "Cherry Pick", +the commit hashes in the repository will be changed by +the submit operation. </p> -<p> -If your local copy of the repository is out of date, -<code>hg submit</code> will refuse the change: -</p> - -<pre> -$ hg submit 99999 -local repository out of date; must sync before submit -</pre> - <h3>More information</h3> <p> -In addition to the information here, the Go community maintains a <a href="https://code.google.com/p/go-wiki/wiki/CodeReview">CodeReview</a> wiki page. +In addition to the information here, the Go community maintains a <a href="https://golang.org/wiki/CodeReview">CodeReview</a> wiki page. Feel free to contribute to this page as you learn the review process. </p> @@ -617,7 +622,8 @@ Feel free to contribute to this page as you learn the review process. <p>Files in the Go repository don't list author names, both to avoid clutter and to avoid having to keep the lists up to date. -Instead, your name will appear in the <a href="https://code.google.com/p/go/source/list">Mercurial change log</a> +Instead, your name will appear in the +<a href="https://golang.org/change">change log</a> and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file and perhaps the <a href="/AUTHORS"><code>AUTHORS</code></a> file. </p> diff --git a/doc/debugging_with_gdb.html b/doc/debugging_with_gdb.html index afaedf74c..836816419 100644 --- a/doc/debugging_with_gdb.html +++ b/doc/debugging_with_gdb.html @@ -120,7 +120,7 @@ For example: <p> If you'd like to see how this works, or want to extend it, take a look at <a -href="/src/pkg/runtime/runtime-gdb.py">src/pkg/runtime/runtime-gdb.py</a> in +href="/src/runtime/runtime-gdb.py">src/runtime/runtime-gdb.py</a> in the Go source distribution. It depends on some special magic types (<code>hash<T,U></code>) and variables (<code>runtime.m</code> and <code>runtime.g</code>) that the linker @@ -153,7 +153,7 @@ the form <code>pkg.(*MyType).Meth</code>. <p> In this tutorial we will inspect the binary of the <a href="/pkg/regexp/">regexp</a> package's unit tests. To build the binary, -change to <code>$GOROOT/src/pkg/regexp</code> and run <code>go test -c</code>. +change to <code>$GOROOT/src/regexp</code> and run <code>go test -c</code>. This should produce an executable file named <code>regexp.test</code>. </p> @@ -172,7 +172,7 @@ License GPLv 3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.htm Type "show copying" and "show warranty" for licensing/warranty details. This GDB was configured as "x86_64-linux". -Reading symbols from /home/user/go/src/pkg/regexp/regexp.test... +Reading symbols from /home/user/go/src/regexp/regexp.test... done. Loading Go Runtime support. (gdb) @@ -180,7 +180,7 @@ Loading Go Runtime support. <p> The message <code>"Loading Go Runtime support"</code> means that GDB loaded the -extension from <code>$GOROOT/src/pkg/runtime/runtime-gdb.py</code>. +extension from <code>$GOROOT/src/runtime/runtime-gdb.py</code>. </p> <p> @@ -199,7 +199,7 @@ it by hand by telling gdb (assuming you have the go sources in </p> <pre> -(gdb) <b>source ~/go/src/pkg/runtime/runtime-gdb.py</b> +(gdb) <b>source ~/go/src/runtime/runtime-gdb.py</b> Loading Go Runtime support. </pre> @@ -259,7 +259,7 @@ Set a breakpoint at the <code>TestFind</code> function: <pre> (gdb) <b>b 'regexp.TestFind'</b> -Breakpoint 1 at 0x424908: file /home/user/go/src/pkg/regexp/find_test.go, line 148. +Breakpoint 1 at 0x424908: file /home/user/go/src/regexp/find_test.go, line 148. </pre> <p> @@ -268,9 +268,9 @@ Run the program: <pre> (gdb) <b>run</b> -Starting program: /home/user/go/src/pkg/regexp/regexp.test +Starting program: /home/user/go/src/regexp/regexp.test -Breakpoint 1, regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/pkg/regexp/find_test.go:148 +Breakpoint 1, regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/regexp/find_test.go:148 148 func TestFind(t *testing.T) { </pre> @@ -297,9 +297,9 @@ Look at the stack trace for where we’ve paused the program: <pre> (gdb) <b>bt</b> <i># backtrace</i> -#0 regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/pkg/regexp/find_test.go:148 -#1 0x000000000042f60b in testing.tRunner (t=0xf8404a89c0, test=0x573720) at /home/user/go/src/pkg/testing/testing.go:156 -#2 0x000000000040df64 in runtime.initdone () at /home/user/go/src/pkg/runtime/proc.c:242 +#0 regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/regexp/find_test.go:148 +#1 0x000000000042f60b in testing.tRunner (t=0xf8404a89c0, test=0x573720) at /home/user/go/src/testing/testing.go:156 +#2 0x000000000040df64 in runtime.initdone () at /home/user/go/src/runtime/proc.c:242 #3 0x000000f8404a89c0 in ?? () #4 0x0000000000573720 in ?? () #5 0x0000000000000000 in ?? () @@ -311,18 +311,18 @@ The other goroutine, number 1, is stuck in <code>runtime.gosched</code>, blocked <pre> (gdb) <b>goroutine 1 bt</b> -#0 0x000000000040facb in runtime.gosched () at /home/user/go/src/pkg/runtime/proc.c:873 +#0 0x000000000040facb in runtime.gosched () at /home/user/go/src/runtime/proc.c:873 #1 0x00000000004031c9 in runtime.chanrecv (c=void, ep=void, selected=void, received=void) - at /home/user/go/src/pkg/runtime/chan.c:342 -#2 0x0000000000403299 in runtime.chanrecv1 (t=void, c=void) at/home/user/go/src/pkg/runtime/chan.c:423 + at /home/user/go/src/runtime/chan.c:342 +#2 0x0000000000403299 in runtime.chanrecv1 (t=void, c=void) at/home/user/go/src/runtime/chan.c:423 #3 0x000000000043075b in testing.RunTests (matchString={void (struct string, struct string, bool *, error *)} - 0x7ffff7f9ef60, tests= []testing.InternalTest = {...}) at /home/user/go/src/pkg/testing/testing.go:201 + 0x7ffff7f9ef60, tests= []testing.InternalTest = {...}) at /home/user/go/src/testing/testing.go:201 #4 0x00000000004302b1 in testing.Main (matchString={void (struct string, struct string, bool *, error *)} 0x7ffff7f9ef80, tests= []testing.InternalTest = {...}, benchmarks= []testing.InternalBenchmark = {...}) -at /home/user/go/src/pkg/testing/testing.go:168 -#5 0x0000000000400dc1 in main.main () at /home/user/go/src/pkg/regexp/_testmain.go:98 -#6 0x00000000004022e7 in runtime.mainstart () at /home/user/go/src/pkg/runtime/amd64/asm.s:78 -#7 0x000000000040ea6f in runtime.initdone () at /home/user/go/src/pkg/runtime/proc.c:243 +at /home/user/go/src/testing/testing.go:168 +#5 0x0000000000400dc1 in main.main () at /home/user/go/src/regexp/_testmain.go:98 +#6 0x00000000004022e7 in runtime.mainstart () at /home/user/go/src/runtime/amd64/asm.s:78 +#7 0x000000000040ea6f in runtime.initdone () at /home/user/go/src/runtime/proc.c:243 #8 0x0000000000000000 in ?? () </pre> @@ -333,7 +333,7 @@ The stack frame shows we’re currently executing the <code>regexp.TestFind</cod <pre> (gdb) <b>info frame</b> Stack level 0, frame at 0x7ffff7f9ff88: - rip = 0x425530 in regexp.TestFind (/home/user/go/src/pkg/regexp/find_test.go:148); + rip = 0x425530 in regexp.TestFind (/home/user/go/src/regexp/find_test.go:148); saved rip 0x430233 called by frame at 0x7ffff7f9ffa8 source language minimal. @@ -410,7 +410,7 @@ We can step into the <code>String</code>function call with <code>"s"</code>: <pre> (gdb) <b>s</b> -regexp.(*Regexp).String (re=0xf84068d070, noname=void) at /home/user/go/src/pkg/regexp/regexp.go:97 +regexp.(*Regexp).String (re=0xf84068d070, noname=void) at /home/user/go/src/regexp/regexp.go:97 97 func (re *Regexp) String() string { </pre> @@ -421,12 +421,12 @@ Get a stack trace to see where we are: <pre> (gdb) <b>bt</b> #0 regexp.(*Regexp).String (re=0xf84068d070, noname=void) - at /home/user/go/src/pkg/regexp/regexp.go:97 + at /home/user/go/src/regexp/regexp.go:97 #1 0x0000000000425615 in regexp.TestFind (t=0xf840688b60) - at /home/user/go/src/pkg/regexp/find_test.go:151 + at /home/user/go/src/regexp/find_test.go:151 #2 0x0000000000430233 in testing.tRunner (t=0xf840688b60, test=0x5747b8) - at /home/user/go/src/pkg/testing/testing.go:156 -#3 0x000000000040ea6f in runtime.initdone () at /home/user/go/src/pkg/runtime/proc.c:243 + at /home/user/go/src/testing/testing.go:156 +#3 0x000000000040ea6f in runtime.initdone () at /home/user/go/src/runtime/proc.c:243 .... </pre> diff --git a/doc/devel/release.html b/doc/devel/release.html index 1a8439134..5b5d6ab5e 100644 --- a/doc/devel/release.html +++ b/doc/devel/release.html @@ -3,8 +3,7 @@ }--> <p>This page summarizes the changes between official stable releases of Go. -The <a href="//code.google.com/p/go/source/list">Mercurial change log</a> -has the full details.</p> +The <a href="//golang.org/change">change log</a> has the full details.</p> <p>To update to a specific release, use:</p> @@ -13,6 +12,13 @@ hg pull hg update <i>tag</i> </pre> +<h2 id="go1.4">go1.4 (released 2014/12/10)</h2> + +<p> +Go 1.4 is a major release of Go. +Read the <a href="/doc/go1.4">Go 1.4 Release Notes</a> for more information. +</p> + <h2 id="go1.3">go1.3 (released 2014/06/18)</h2> <p> diff --git a/doc/devel/weekly.html b/doc/devel/weekly.html index 34c87dc64..5a9c51ef1 100644 --- a/doc/devel/weekly.html +++ b/doc/devel/weekly.html @@ -5,7 +5,7 @@ <p>This page summarizes the changes between tagged weekly snapshots of Go. Such snapshots are no longer created. This page remains as a historical reference only.</p> -<p>For recent information, see the <a href="//code.google.com/p/go/source/list">Mercurial change log</a> and <a href="//groups.google.com/group/golang-dev/">development mailing list</a>.</p> +<p>For recent information, see the <a href="//golang.org/change">change log</a> and <a href="//groups.google.com/group/golang-dev/">development mailing list</a>.</p> <h2 id="2012-03-27">2012-03-27 (<a href="release.html#go1">Go 1</a>)</h2> diff --git a/doc/docs.html b/doc/docs.html index 642f36dd4..7eb3a3ad2 100644 --- a/doc/docs.html +++ b/doc/docs.html @@ -147,8 +147,8 @@ Guided tours of Go programs. <li><a href="/blog/godoc-documenting-go-code">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li> <li><a href="/blog/profiling-go-programs">Profiling Go Programs</a></li> <li><a href="/doc/articles/race_detector.html">Data Race Detector</a> - a manual for the data race detector.</li> -<li><a href="/blog/race-detector">Introducing the Go Race Detector</a> - an introduction to the race detector. -<li><a href="/doc/asm">A Quick Guide to Go's Assembler</a> - an introduction to the assembler used by Go. +<li><a href="/blog/race-detector">Introducing the Go Race Detector</a> - an introduction to the race detector.</li> +<li><a href="/doc/asm">A Quick Guide to Go's Assembler</a> - an introduction to the assembler used by Go.</li> </ul> <h4 id="articles_more">More</h4> diff --git a/doc/effective_go.html b/doc/effective_go.html index c1e310796..4dd1a3e01 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -37,7 +37,7 @@ should read first. <h3 id="examples">Examples</h3> <p> -The <a href="/src/pkg/">Go package sources</a> +The <a href="/src/">Go package sources</a> are intended to serve not only as the core library but also as examples of how to use the language. @@ -344,7 +344,7 @@ determines just which package is being used. <p> Another convention is that the package name is the base name of its source directory; -the package in <code>src/pkg/encoding/base64</code> +the package in <code>src/encoding/base64</code> is imported as <code>"encoding/base64"</code> but has name <code>base64</code>, not <code>encoding_base64</code> and not <code>encodingBase64</code>. </p> diff --git a/doc/gccgo_contribute.html b/doc/gccgo_contribute.html index 9dd6ecb85..db7d1ab0e 100644 --- a/doc/gccgo_contribute.html +++ b/doc/gccgo_contribute.html @@ -73,7 +73,7 @@ script <code>libgo/merge.sh</code>. Accordingly, most library changes should be made in the main Go repository. The files outside of <code>libgo/go</code> are gccgo-specific; that said, some of the files in <code>libgo/runtime</code> are based on files -in <code>src/pkg/runtime</code> in the main Go repository. +in <code>src/runtime</code> in the main Go repository. </p> <h2>Testing</h2> diff --git a/doc/gccgo_install.html b/doc/gccgo_install.html index 4c1a8c2f5..acb315a0a 100644 --- a/doc/gccgo_install.html +++ b/doc/gccgo_install.html @@ -42,6 +42,10 @@ identical to Go 1.1. The GCC 4.8.2 release includes a complete Go 1.1.2 implementation. </p> +<p> +The GCC 4.9 releases include a complete Go 1.2 implementation. +</p> + <h2 id="Source_code">Source code</h2> <p> diff --git a/doc/go1.3.html b/doc/go1.3.html index 042de1bc7..d51052b2e 100644 --- a/doc/go1.3.html +++ b/doc/go1.3.html @@ -298,7 +298,7 @@ For example, <h3 id="godoc">Changes to godoc</h3> <p> When invoked with the <code>-analysis</code> flag, -<a href="//godoc.org/code.google.com/p/go.tools/cmd/godoc">godoc</a> +<a href="//godoc.org/golang.org/x/tools/cmd/godoc">godoc</a> now performs sophisticated <a href="/lib/godoc/analysis/help.html">static analysis</a> of the code it indexes. The results of analysis are presented in both the source view and the @@ -318,7 +318,7 @@ call sites and their callees. The program <code>misc/benchcmp</code> that compares performance across benchmarking runs has been rewritten. Once a shell and awk script in the main repository, it is now a Go program in the <code>go.tools</code> repo. -Documentation is <a href="//godoc.org/code.google.com/p/go.tools/cmd/benchcmp">here</a>. +Documentation is <a href="//godoc.org/golang.org/x/tools/cmd/benchcmp">here</a>. </p> <p> diff --git a/doc/go1.4.html b/doc/go1.4.html new file mode 100644 index 000000000..b4f9619bb --- /dev/null +++ b/doc/go1.4.html @@ -0,0 +1,896 @@ +<!--{ + "Title": "Go 1.4 Release Notes", + "Path": "/doc/go1.4", + "Template": true +}--> + +<h2 id="introduction">Introduction to Go 1.4</h2> + +<p> +The latest Go release, version 1.4, arrives as scheduled six months after 1.3. +</p> + +<p> +It contains only one tiny language change, +in the form of a backwards-compatible simple variant of <code>for</code>-<code>range</code> loop, +and a possibly breaking change to the compiler involving methods on pointers-to-pointers. +</p> + +<p> +The release focuses primarily on implementation work, improving the garbage collector +and preparing the ground for a fully concurrent collector to be rolled out in the +next few releases. +Stacks are now contiguous, reallocated when necessary rather than linking on new +"segments"; +this release therefore eliminates the notorious "hot stack split" problem. +There are some new tools available including support in the <code>go</code> command +for build-time source code generation. +The release also adds support for ARM processors on Android and Native Client (NaCl) +and for AMD64 on Plan 9. +</p> + +<p> +As always, Go 1.4 keeps the <a href="/doc/go1compat.html">promise +of compatibility</a>, +and almost everything +will continue to compile and run without change when moved to 1.4. +</p> + +<h2 id="language">Changes to the language</h2> + +<h3 id="forrange">For-range loops</h3> +<p> +Up until Go 1.3, <code>for</code>-<code>range</code> loop had two forms +</p> + +<pre> +for i, v := range x { + ... +} +</pre> + +<p> +and +</p> + +<pre> +for i := range x { + ... +} +</pre> + +<p> +If one was not interested in the loop values, only the iteration itself, it was still +necessary to mention a variable (probably the <a href="/ref/spec#Blank_identifier">blank identifier</a>, as in +<code>for</code> <code>_</code> <code>=</code> <code>range</code> <code>x</code>), because +the form +</p> + +<pre> +for range x { + ... +} +</pre> + +<p> +was not syntactically permitted. +</p> + +<p> +This situation seemed awkward, so as of Go 1.4 the variable-free form is now legal. +The pattern arises rarely but the code can be cleaner when it does. +</p> + +<p> +<em>Updating</em>: The change is strictly backwards compatible to existing Go +programs, but tools that analyze Go parse trees may need to be modified to accept +this new form as the +<code>Key</code> field of <a href="/pkg/go/ast/#RangeStmt"><code>RangeStmt</code></a> +may now be <code>nil</code>. +</p> + +<h3 id="methodonpointertopointer">Method calls on **T</h3> + +<p> +Given these declarations, +</p> + +<pre> +type T int +func (T) M() {} +var x **T +</pre> + +<p> +both <code>gc</code> and <code>gccgo</code> accepted the method call +</p> + +<pre> +x.M() +</pre> + +<p> +which is a double dereference of the pointer-to-pointer <code>x</code>. +The Go specification allows a single dereference to be inserted automatically, +but not two, so this call is erroneous according to the language definition. +It has therefore been disallowed in Go 1.4, which is a breaking change, +although very few programs will be affected. +</p> + +<p> +<em>Updating</em>: Code that depends on the old, erroneous behavior will no longer +compile but is easy to fix by adding an explicit dereference. +</p> + +<h2 id="os">Changes to the supported operating systems and architectures</h2> + +<h3 id="android">Android</h3> + +<p> +Go 1.4 can build binaries for ARM processors running the Android operating system. +It can also build a <code>.so</code> library that can be loaded by an Android application +using the supporting packages in the <a href="https://golang.org/x/mobile">mobile</a> subrepository. +A brief description of the plans for this experimental port are available +<a href="https://golang.org/s/go14android">here</a>. +</p> + +<h3 id="naclarm">NaCl on ARM</h3> + +<p> +The previous release introduced Native Client (NaCl) support for the 32-bit x86 +(<code>GOARCH=386</code>) +and 64-bit x86 using 32-bit pointers (GOARCH=amd64p32). +The 1.4 release adds NaCl support for ARM (GOARCH=arm). +</p> + +<h3 id="plan9amd64">Plan9 on AMD64</h3> + +<p> +This release adds support for the Plan 9 operating system on AMD64 processors, +provided the kernel supports the <code>nsec</code> system call and uses 4K pages. +</p> + +<h2 id="compatibility">Changes to the compatibility guidelines</h2> + +<p> +The <a href="/pkg/unsafe/"><code>unsafe</code></a> package allows one +to defeat Go's type system by exploiting internal details of the implementation +or machine representation of data. +It was never explicitly specified what use of <code>unsafe</code> meant +with respect to compatibility as specified in the +<a href="go1compat.html">Go compatibility guidelines</a>. +The answer, of course, is that we can make no promise of compatibility +for code that does unsafe things. +</p> + +<p> +We have clarified this situation in the documentation included in the release. +The <a href="go1compat.html">Go compatibility guidelines</a> and the +docs for the <a href="/pkg/unsafe/"><code>unsafe</code></a> package +are now explicit that unsafe code is not guaranteed to remain compatible. +</p> + +<p> +<em>Updating</em>: Nothing technical has changed; this is just a clarification +of the documentation. +</p> + + +<h2 id="impl">Changes to the implementations and tools</h2> + +<h3 id="runtime">Changes to the runtime</h3> + +<p> +Prior to Go 1.4, the runtime (garbage collector, concurrency support, interface management, +maps, slices, strings, ...) was mostly written in C, with some assembler support. +In 1.4, much of the code has been translated to Go so that the garbage collector can scan +the stacks of programs in the runtime and get accurate information about what variables +are active. +This change was large but should have no semantic effect on programs. +</p> + +<p> +This rewrite allows the garbage collector in 1.4 to be fully precise, +meaning that it is aware of the location of all active pointers in the program. +This means the heap will be smaller as there will be no false positives keeping non-pointers alive. +Other related changes also reduce the heap size, which is smaller by 10%-30% overall +relative to the previous release. +</p> + +<p> +A consequence is that stacks are no longer segmented, eliminating the "hot split" problem. +When a stack limit is reached, a new, larger stack is allocated, all active frames for +the goroutine are copied there, and any pointers into the stack are updated. +Performance can be noticeably better in some cases and is always more predictable. +Details are available in <a href="https://golang.org/s/contigstacks">the design document</a>. +</p> + +<p> +The use of contiguous stacks means that stacks can start smaller without triggering performance issues, +so the default starting size for a goroutine's stack in 1.4 has been reduced from 8192 bytes to 2048 bytes. +</p> + +<p> +As preparation for the concurrent garbage collector scheduled for the 1.5 release, +writes to pointer values in the heap are now done by a function call, +called a write barrier, rather than directly from the function updating the value. +In this next release, this will permit the garbage collector to mediate writes to the heap while it is running. +This change has no semantic effect on programs in 1.4, but was +included in the release to test the compiler and the resulting performance. +</p> + +<p> +The implementation of interface values has been modified. +In earlier releases, the interface contained a word that was either a pointer or a one-word +scalar value, depending on the type of the concrete object stored. +This implementation was problematical for the garbage collector, +so as of 1.4 interface values always hold a pointer. +In running programs, most interface values were pointers anyway, +so the effect is minimal, but programs that store integers (for example) in +interfaces will see more allocations. +</p> + +<p> +As of Go 1.3, the runtime crashes if it finds a memory word that should contain +a valid pointer but instead contains an obviously invalid pointer (for example, the value 3). +Programs that store integers in pointer values may run afoul of this check and crash. +In Go 1.4, setting the <a href="/pkg/runtime/"><code>GODEBUG</code></a> variable +<code>invalidptr=0</code> disables +the crash as a workaround, but we cannot guarantee that future releases will be +able to avoid the crash; the correct fix is to rewrite code not to alias integers and pointers. +</p> + +<h3 id="asm">Assembly</h3> + +<p> +The language accepted by the assemblers <code>cmd/5a</code>, <code>cmd/6a</code> +and <code>cmd/8a</code> has had several changes, +mostly to make it easier to deliver type information to the runtime. +</p> + +<p> +First, the <code>textflag.h</code> file that defines flags for <code>TEXT</code> directives +has been copied from the linker source directory to a standard location so it can be +included with the simple directive +</p> + +<pre> +#include "textflag.h" +</pre> + +<p> +The more important changes are in how assembler source can define the necessary +type information. +For most programs it will suffice to move data +definitions (<code>DATA</code> and <code>GLOBL</code> directives) +out of assembly into Go files +and to write a Go declaration for each assembly function. +The <a href="/doc/asm#runtime">assembly document</a> describes what to do. +</p> + +<p> +<em>Updating</em>: +Assembly files that include <code>textflag.h</code> from its old +location will still work, but should be updated. +For the type information, most assembly routines will need no change, +but all should be examined. +Assembly source files that define data, +functions with non-empty stack frames, or functions that return pointers +need particular attention. +A description of the necessary (but simple) changes +is in the <a href="/doc/asm#runtime">assembly document</a>. +</p> + +<p> +More information about these changes is in the <a href="/doc/asm">assembly document</a>. +</p> + +<h3 id="gccgo">Status of gccgo</h3> + +<p> +The release schedules for the GCC and Go projects do not coincide. +GCC release 4.9 contains the Go 1.2 version of gccgo. +The next release, GCC 5, will likely have the Go 1.4 version of gccgo. +</p> + +<h3 id="internalpackages">Internal packages</h3> + +<p> +Go's package system makes it easy to structure programs into components with clean boundaries, +but there are only two forms of access: local (unexported) and global (exported). +Sometimes one wishes to have components that are not exported, +for instance to avoid acquiring clients of interfaces to code that is part of a public repository +but not intended for use outside the program to which it belongs. +</p> + +<p> +The Go language does not have the power to enforce this distinction, but as of Go 1.4 the +<a href="/cmd/go/"><code>go</code></a> command introduces +a mechanism to define "internal" packages that may not be imported by packages outside +the source subtree in which they reside. +</p> + +<p> +To create such a package, place it in a directory named <code>internal</code> or in a subdirectory of a directory +named internal. +When the <code>go</code> command sees an import of a package with <code>internal</code> in its path, +it verifies that the package doing the import +is within the tree rooted at the parent of the <code>internal</code> directory. +For example, a package <code>.../a/b/c/internal/d/e/f</code> +can be imported only by code in the directory tree rooted at <code>.../a/b/c</code>. +It cannot be imported by code in <code>.../a/b/g</code> or in any other repository. +</p> + +<p> +For Go 1.4, the internal package mechanism is enforced for the main Go repository; +from 1.5 and onward it will be enforced for any repository. +</p> + +<p> +Full details of the mechanism are in +<a href="https://golang.org/s/go14internal">the design document</a>. +</p> + +<h3 id="canonicalimports">Canonical import paths</h3> + +<p> +Code often lives in repositories hosted by public services such as <code>github.com</code>, +meaning that the import paths for packages begin with the name of the hosting service, +<code>github.com/rsc/pdf</code> for example. +One can use +<a href="/cmd/go/#hdr-Remote_import_paths">an existing mechanism</a> +to provide a "custom" or "vanity" import path such as +<code>rsc.io/pdf</code>, but +that creates two valid import paths for the package. +That is a problem: one may inadvertently import the package through the two +distinct paths in a single program, which is wasteful; +miss an update to a package because the path being used is not recognized to be +out of date; +or break clients using the old path by moving the package to a different hosting service. +</p> + +<p> +Go 1.4 introduces an annotation for package clauses in Go source that identify a canonical +import path for the package. +If an import is attempted using a path that is not canonical, +the <a href="/cmd/go/"><code>go</code></a> command +will refuse to compile the importing package. +</p> + +<p> +The syntax is simple: put an identifying comment on the package line. +For our example, the package clause would read: +</p> + +<pre> +package pdf // import "rsc.io/pdf" +</pre> + +<p> +With this in place, +the <code>go</code> command will +refuse to compile a package that imports <code>github.com/rsc/pdf</code>, +ensuring that the code can be moved without breaking users. +</p> + +<p> +The check is at build time, not download time, so if <code>go</code> <code>get</code> +fails because of this check, the mis-imported package has been copied to the local machine +and should be removed manually. +</p> + +<p> +To complement this new feature, a check has been added at update time to verify +that the local package's remote repository matches that of its custom import. +The <code>go</code> <code>get</code> <code>-u</code> command will fail to +update a package if its remote repository has changed since it was first +downloaded. +The new <code>-f</code> flag overrides this check. +</p> + +<p> +Further information is in +<a href="https://golang.org/s/go14customimport">the design document</a>. +</p> + +<h3 id="subrepo">Import paths for the subrepositories</h3> + +<p> +The Go project subrepositories (<code>code.google.com/p/go.tools</code> and so on) +are now available under custom import paths replacing <code>code.google.com/p/go.</code> with <code>golang.org/x/</code>, +as in <code>golang.org/x/tools</code>. +We will add canonical import comments to the code around June 1, 2015, +at which point Go 1.4 and later will stop accepting the old <code>code.google.com</code> paths. +</p> + +<p> +<em>Updating</em>: All code that imports from subrepositories should change +to use the new <code>golang.org</code> paths. +Go 1.0 and later can resolve and import the new paths, so updating will not break +compatibility with older releases. +Code that has not updated will stop compiling with Go 1.4 around June 1, 2015. +</p> + +<h3 id="gogenerate">The go generate subcommand</h3> + +<p> +The <a href="/cmd/go/"><code>go</code></a> command has a new subcommand, +<a href="/cmd/go/#hdr-Generate_Go_files_by_processing_source"><code>go generate</code></a>, +to automate the running of tools to generate source code before compilation. +For example, it can be used to run the <a href="/cmd/yacc"><code>yacc</code></a> +compiler-compiler on a <code>.y</code> file to produce the Go source file implementing the grammar, +or to automate the generation of <code>String</code> methods for typed constants using the new +<a href="http://godoc.org/golang.org/x/tools/cmd/stringer">stringer</a> +tool in the <code>golang.org/x/tools</code> subrepository. +</p> + +<p> +For more information, see the +<a href="https://golang.org/s/go1.4-generate">design document</a>. +</p> + +<h3 id="filenames">Change to file name handling</h3> + +<p> +Build constraints, also known as build tags, control compilation by including or excluding files +(see the documentation <a href="/pkg/go/build/"><code>/go/build</code></a>). +Compilation can also be controlled by the name of the file itself by "tagging" the file with +a suffix (before the <code>.go</code> or <code>.s</code> extension) with an underscore +and the name of the architecture or operating system. +For instance, the file <code>gopher_arm.go</code> will only be compiled if the target +processor is an ARM. +</p> + +<p> +Before Go 1.4, a file called just <code>arm.go</code> was similarly tagged, but this behavior +can break sources when new architectures are added, causing files to suddenly become tagged. +In 1.4, therefore, a file will be tagged in this manner only if the tag (architecture or operating +system name) is preceded by an underscore. +</p> + +<p> +<em>Updating</em>: Packages that depend on the old behavior will no longer compile correctly. +Files with names like <code>windows.go</code> or <code>amd64.go</code> should either +have explicit build tags added to the source or be renamed to something like +<code>os_windows.go</code> or <code>support_amd64.go</code>. +</p> + +<h3 id="gocmd">Other changes to the go command</h3> + +<p> +There were a number of minor changes to the +<a href="/cmd/go/"><code>cmd/go</code></a> +command worth noting. +</p> + +<ul> + +<li> +Unless <a href="/cmd/cgo/"><code>cgo</code></a> is being used to build the package, +the <code>go</code> command now refuses to compile C source files, +since the relevant C compilers +(<a href="/cmd/6c/"><code>6c</code></a> etc.) +are intended to be removed from the installation in some future release. +(They are used today only to build part of the runtime.) +It is difficult to use them correctly in any case, so any extant uses are likely incorrect, +so we have disabled them. +</li> + +<li> +The <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>test</code></a> +subcommand has a new flag, <code>-o</code>, to set the name of the resulting binary, +corresponding to the same flag in other subcommands. +The non-functional <code>-file</code> flag has been removed. +</li> + +<li> +The <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>test</code></a> +subcommand will compile and link all <code>*_test.go</code> files in the package, +even when there are no <code>Test</code> functions in them. +It previously ignored such files. +</li> + +<li> +The behavior of the +<a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>build</code></a> +subcommand's +<code>-a</code> flag has been changed for non-development installations. +For installations running a released distribution, the <code>-a</code> flag will no longer +rebuild the standard library and commands, to avoid overwriting the installation's files. +</li> + +</ul> + +<h3 id="pkg">Changes to package source layout</h3> + +<p> +In the main Go source repository, the source code for the packages was kept in +the directory <code>src/pkg</code>, which made sense but differed from +other repositories, including the Go subrepositories. +In Go 1.4, the<code> pkg</code> level of the source tree is now gone, so for example +the <a href="/pkg/fmt/"><code>fmt</code></a> package's source, once kept in +directory <code>src/pkg/fmt</code>, now lives one level higher in <code>src/fmt</code>. +</p> + +<p> +<em>Updating</em>: Tools like <code>godoc</code> that discover source code +need to know about the new location. All tools and services maintained by the Go team +have been updated. +</p> + + +<h3 id="swig">SWIG</h3> + +<p> +Due to runtime changes in this release, Go 1.4 requires SWIG 3.0.3. +</p> + +<h3 id="misc">Miscellany</h3> + +<p> +The standard repository's top-level <code>misc</code> directory used to contain +Go support for editors and IDEs: plugins, initialization scripts and so on. +Maintaining these was becoming time-consuming +and needed external help because many of the editors listed were not used by +members of the core team. +It also required us to make decisions about which plugin was best for a given +editor, even for editors we do not use. +</p> + +<p> +The Go community at large is much better suited to managing this information. +In Go 1.4, therefore, this support has been removed from the repository. +Instead, there is a curated, informative list of what's available on +a <a href="//golang.org/wiki/IDEsAndTextEditorPlugins">wiki page</a>. +</p> + +<h2 id="performance">Performance</h2> + +<p> +Most programs will run about the same speed or slightly faster in 1.4 than in 1.3; +some will be slightly slower. +There are many changes, making it hard to be precise about what to expect. +</p> + +<p> +As mentioned above, much of the runtime was translated to Go from C, +which led to some reduction in heap sizes. +It also improved performance slightly because the Go compiler is better +at optimization, due to things like inlining, than the C compiler used to build +the runtime. +</p> + +<p> +The garbage collector was sped up, leading to measurable improvements for +garbage-heavy programs. +On the other hand, the new write barriers slow things down again, typically +by about the same amount but, depending on their behavior, some programs +may be somewhat slower or faster. +</p> + +<p> +Library changes that affect performance are documented below. +</p> + +<h2 id="library">Changes to the standard library</h2> + +<h3 id="new_packages">New packages</h3> + +<p> +There are no new packages in this release. +</p> + +<h3 id="major_library_changes">Major changes to the library</h3> + +<h4 id="scanner">bufio.Scanner</h4> + +<p> +The <a href="/pkg/bufio/#Scanner"><code>Scanner</code></a> type in the +<a href="/pkg/bufio/"><code>bufio</code></a> package +has had a bug fixed that may require changes to custom +<a href="/pkg/bufio/#SplitFunc"><code>split functions</code></a>. +The bug made it impossible to generate an empty token at EOF; the fix +changes the end conditions seen by the split function. +Previously, scanning stopped at EOF if there was no more data. +As of 1.4, the split function will be called once at EOF after input is exhausted, +so the split function can generate a final empty token +as the documentation already promised. +</p> + +<p> +<em>Updating</em>: Custom split functions may need to be modified to +handle empty tokens at EOF as desired. +</p> + +<h4 id="syscall">syscall</h4> + +<p> +The <a href="/pkg/syscall/"><code>syscall</code></a> package is now frozen except +for changes needed to maintain the core repository. +In particular, it will no longer be extended to support new or different system calls +that are not used by the core. +The reasons are described at length in <a href="https://golang.org/s/go1.4-syscall">a +separate document</a>. +</p> + +<p> +A new subrepository, <a href="https://golang.org/x/sys">golang.org/x/sys</a>, +has been created to serve as the location for new developments to support system +calls on all kernels. +It has a nicer structure, with three packages that each hold the implementation of +system calls for one of +<a href="http://godoc.org/golang.org/x/sys/unix">Unix</a>, +<a href="http://godoc.org/golang.org/x/sys/windows">Windows</a> and +<a href="http://godoc.org/golang.org/x/sys/plan9">Plan 9</a>. +These packages will be curated more generously, accepting all reasonable changes +that reflect kernel interfaces in those operating systems. +See the documentation and the article mentioned above for more information. +</p> + +<p> +<em>Updating</em>: Existing programs are not affected as the <code>syscall</code> +package is largely unchanged from the 1.3 release. +Future development that requires system calls not in the <code>syscall</code> package +should build on <code>golang.org/x/sys</code> instead. +</p> + +<h3 id="minor_library_changes">Minor changes to the library</h3> + +<p> +The following list summarizes a number of minor changes to the library, mostly additions. +See the relevant package documentation for more information about each change. +</p> + +<ul> + +<li> +The <a href="/pkg/archive/zip/"><code>archive/zip</code></a> package's +<a href="/pkg/archive/zip/#Writer"><code>Writer</code></a> now supports a +<a href="/pkg/archive/zip/#Writer.Flush"><code>Flush</code></a> method. +</li> + +<li> +The <a href="/pkg/compress/flate/"><code>compress/flate</code></a>, +<a href="/pkg/compress/gzip/"><code>compress/gzip</code></a>, +and <a href="/pkg/compress/zlib/"><code>compress/zlib</code></a> +packages now support a <code>Reset</code> method +for the decompressors, allowing them to reuse buffers and improve performance. +The <a href="/pkg/compress/gzip/"><code>compress/gzip</code></a> package also has a +<a href="/pkg/compress/gzip/#Reader.Multistream"><code>Multistream</code></a> method to control support +for multistream files. +</li> + +<li> +The <a href="/pkg/crypto/"><code>crypto</code></a> package now has a +<a href="/pkg/crypto/#Signer"><code>Signer</code></a> interface, implemented by the +<code>PrivateKey</code> types in +<a href="/pkg/crypto/ecdsa"><code>crypto/ecdsa</code></a> and +<a href="/pkg/crypto/rsa"><code>crypto/rsa</code></a>. +</li> + +<li> +The <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> package +now supports ALPN as defined in <a href="http://tools.ietf.org/html/rfc7301">RFC 7301</a>. +</li> + +<li> +The <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> package +now supports programmatic selection of server certificates +through the new <a href="/pkg/crypto/tls/#Config.CertificateForName"><code>CertificateForName</code></a> function +of the <a href="/pkg/crypo/tls/#Config"><code>Config</code></a> struct. +</li> + +<li> +Also in the crypto/tls package, the server now supports +<a href="https://tools.ietf.org/html/draft-ietf-tls-downgrade-scsv-00">TLS_FALLBACK_SCSV</a> +to help clients detect fallback attacks. +(The Go client does not support fallback at all, so it is not vulnerable to +those attacks.) +</li> + +<li> +The <a href="/pkg/database/sql/"><code>database/sql</code></a> package can now list all registered +<a href="/pkg/database/sql/#Drivers"><code>Drivers</code></a>. +</li> + +<li> +The <a href="/pkg/debug/dwarf/"><code>debug/dwarf</code></a> package now supports +<a href="/pkg/debug/dwarf/#UnspecifiedType"><code>UnspecifiedType</code></a>s. +</li> + +<li> +In the <a href="/pkg/encoding/asn1/"><code>encoding/asn1</code></a> package, +optional elements with a default value will now only be omitted if they have that value. +</li> + +<li> +The <a href="/pkg/encoding/csv/"><code>encoding/csv</code></a> package no longer +quotes empty strings but does quote the end-of-data marker <code>\.</code> (backslash dot). +This is permitted by the definition of CSV and allows it to work better with Postgres. +</li> + +<li> +The <a href="/pkg/encoding/gob/"><code>encoding/gob</code></a> package has been rewritten to eliminate +the use of unsafe operations, allowing it to be used in environments that do not permit use of the +<a href="/pkg/unsafe/"><code>unsafe</code></a> package. +For typical uses it will be 10-30% slower, but the delta is dependent on the type of the data and +in some cases, especially involving arrays, it can be faster. +There is no functional change. +</li> + +<li> +The <a href="/pkg/encoding/xml/"><code>encoding/xml</code></a> package's +<a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> can now report its input offset. +</li> + +<li> +In the <a href="/pkg/fmt/"><code>fmt</code></a> package, +formatting of pointers to maps has changed to be consistent with that of pointers +to structs, arrays, and so on. +For instance, <code>&map[string]int{"one":</code> <code>1}</code> now prints by default as +<code>&map[one:</code> <code>1]</code> rather than as a hexadecimal pointer value. +</li> + +<li> +The <a href="/pkg/image/"><code>image</code></a> package's +<a href="/pkg/image/#Image"><code>Image</code></a> +implementations like +<a href="/pkg/image/#RGBA"><code>RGBA</code></a> and +<a href="/pkg/image/#Gray"><code>Gray</code></a> have specialized +<a href="/pkg/image/#RGBA.RGBAAt"><code>RGBAAt</code></a> and +<a href="/pkg/image/#Gray.GrayAt"><code>GrayAt</code></a> methods alongside the general +<a href="/pkg/image/#Image.At"><code>At</code></a> method. +</li> + +<li> +The <a href="/pkg/image/png/"><code>image/png</code></a> package now has an +<a href="/pkg/image/png/#Encoder"><code>Encoder</code></a> +type to control the compression level used for encoding. +</li> + +<li> +The <a href="/pkg/math/"><code>math</code></a> package now has a +<a href="/pkg/math/#Nextafter32"><code>Nextafter32</code><a/> function. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package's +<a href="/pkg/net/http/#Request"><code>Request</code></a> type +has a new <a href="/pkg/net/http/#Request.BasicAuth"><code>BasicAuth</code></a> method +that returns the username and password from authenticated requests using the +HTTP Basic Authentication +Scheme. +</li> + +<li>The <a href="/pkg/net/http/"><code>net/http</code></a> package's +<a href="/pkg/net/http/#Request"><code>Transport</code></a> type +has a new <a href="/pkg/net/http/#Transport.DialTLS"><code>DialTLS</code></a> hook +that allows customizing the behavior of outbound TLS connections. +</li> + +<li> +The <a href="/pkg/net/http/httputil/"><code>net/http/httputil</code></a> package's +<a href="/pkg/net/http/httputil/#ReverseProxy"><code>ReverseProxy</code></a> type +has a new field, +<a href="/pkg/net/http/#ReverseProxy.ErrorLog"><code>ErrorLog</code></a>, that +provides user control of logging. +</li> + +<li> +The <a href="/pkg/os/"><code>os</code></a> package +now implements symbolic links on the Windows operating system +through the <a href="/pkg/os/#Symlink"><code>Symlink</code></a> function. +Other operating systems already have this functionality. +There is also a new <a href="/pkg/os/#Unsetenv"><code>Unsetenv</code></a> function. +</li> + +<li> +The <a href="/pkg/reflect/"><code>reflect</code></a> package's +<a href="/pkg/reflect/#Type"><code>Type</code></a> interface +has a new method, <a href="/pkg/reflect/#type.Comparable"><code>Comparable</code></a>, +that reports whether the type implements general comparisons. +</li> + +<li> +Also in the <a href="/pkg/reflect/"><code>reflect</code></a> package, the +<a href="/pkg/reflect/#Value"><code>Value</code></a> interface is now three instead of four words +because of changes to the implementation of interfaces in the runtime. +This saves memory but has no semantic effect. +</li> + +<li> +The <a href="/pkg/runtime/"><code>runtime</code></a> package +now implements monotonic clocks on Windows, +as it already did for the other systems. +</li> + +<li> +The <a href="/pkg/runtime/"><code>runtime</code></a> package's +<a href="/pkg/runtime/#MemStats.Mallocs"><code>Mallocs</code></a> counter +now counts very small allocations that were missed in Go 1.3. +This may break tests using <a href="/pkg/runtime/#ReadMemStats"><code>ReadMemStats</code></a> +or <a href="/pkg/testing/#AllocsPerRun"><code>AllocsPerRun</code></a> +due to the more accurate answer. +</li> + +<li> +In the <a href="/pkg/runtime/"><code>runtime</code></a> package, +an array <a href="/pkg/runtime/#MemStats.PauseEnd"><code>PauseEnd</code></a> +has been added to the +<a href="/pkg/runtime/#MemStats"><code>MemStats</code></a> +and <a href="/pkg/runtime/#GCStats"><code>GCStats</code></a> structs. +This array is a circular buffer of times when garbage collection pauses ended. +The corresponding pause durations are already recorded in +<a href="/pkg/runtime/#MemStats.PauseNs"><code>PauseNs</code></a> +</li> + +<li> +The <a href="/pkg/runtime/race/"><code>runtime/race</code></a> package +now supports FreeBSD, which means the +<a href="/pkg/cmd/go/"><code>go</code></a> command's <code>-race</code> +flag now works on FreeBSD. +</li> + +<li> +The <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> package +has a new type, <a href="/pkg/sync/atomic/#Value"><code>Value</code></a>. +<code>Value</code> provides an efficient mechanism for atomic loads and +stores of values of arbitrary type. +</li> + +<li> +In the <a href="/pkg/syscall/"><code>syscall</code></a> package's +implementation on Linux, the +<a href="/pkg/syscall/#Setuid"><code>Setuid</code></a> +and <a href="/pkg/syscall/#Setgid"><code>Setgid</code></a> have been disabled +because those system calls operate on the calling thread, not the whole process, which is +different from other platforms and not the expected result. +</li> + +<li> +The <a href="/pkg/testing/"><code>testing</code></a> package +has a new facility to provide more control over running a set of tests. +If the test code contains a function +<pre> +func TestMain(m *<a href="/pkg/testing/#M"><code>testing.M</code></a>) +</pre> + +that function will be called instead of running the tests directly. +The <code>M</code> struct contains methods to access and run the tests. +</li> + +<li> +Also in the <a href="/pkg/testing/"><code>testing</code></a> package, +a new <a href="/pkg/testing/#Coverage"><code>Coverage</code></a> +function reports the current test coverage fraction, +enabling individual tests to report how much they are contributing to the +overall coverage. +</li> + +<li> +The <a href="/pkg/text/scanner/"><code>text/scanner</code></a> package's +<a href="/pkg/text/scanner/#Scanner"><code>Scanner</code></a> type +has a new function, +<a href="/pkg/text/scanner/#Scanner.IsIdentRune"><code>IsIdentRune</code></a>, +allowing one to control the definition of an identifier when scanning. +</li> + +<li> +The <a href="/pkg/text/template/"><code>text/template</code></a> package's boolean +functions <code>eq</code>, <code>lt</code>, and so on have been generalized to allow comparison +of signed and unsigned integers, simplifying their use in practice. +(Previously one could only compare values of the same signedness.) +All negative values compare less than all unsigned values. +</li> + +<li> +The <code>time</code> package now uses the standard symbol for the micro prefix, +the micro symbol (U+00B5 'µ'), to print microsecond durations. +<a href="/pkg/time/#ParseDuration"><code>ParseDuration</code></a> still accepts <code>us</code> +but the package no longer prints microseconds as <code>us</code>. +<br> +<em>Updating</em>: Code that depends on the output format of durations +but does not use ParseDuration will need to be updated. +</li> + +</ul> diff --git a/doc/go1.html b/doc/go1.html index 5cf5df929..1665d74e9 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -2035,4 +2035,4 @@ They are available for many combinations of architecture and operating system Installation details are described on the <a href="/doc/install">Getting Started</a> page, while the distributions themselves are listed on the -<a href="/dl/">downloads page</a>. +<a href="https://golang.org/dl/">downloads page</a>. diff --git a/doc/go1compat.html b/doc/go1compat.html index d10b9af29..d800dec0c 100644 --- a/doc/go1compat.html +++ b/doc/go1compat.html @@ -83,16 +83,16 @@ break if the bug is fixed. We reserve the right to fix such bugs. <li> Struct literals. For the addition of features in later point releases, it may be necessary to add fields to exported structs in -the API. Code that uses untagged struct literals (such as pkg.T{3, +the API. Code that uses unkeyed struct literals (such as pkg.T{3, "x"}) to create values of these types would fail to compile after -such a change. However, code that uses tagged literals (pkg.T{A: +such a change. However, code that uses keyed literals (pkg.T{A: 3, B: "x"}) will continue to compile after such a change. We will -update such data structures in a way that allows tagged struct -literals to remain compatible, although untagged literals may fail +update such data structures in a way that allows keyed struct +literals to remain compatible, although unkeyed literals may fail to compile. (There are also more intricate cases involving nested data structures or interfaces, but they have the same resolution.) We therefore recommend that composite literals whose type is defined -in a separate package should use the tagged notation. +in a separate package should use the keyed notation. </li> <li> @@ -104,6 +104,14 @@ outside of tests, and using it may cause a program to fail to compile in future releases. </li> +<li> +Use of package <code>unsafe</code>. Packages that import +<a href="/pkg/unsafe/"><code>unsafe</code></a> +may depend on internal properties of the Go implementation. +We reserve the right to make changes to the implementation +that may break such programs. +</li> + </ul> <p> @@ -145,13 +153,28 @@ developed software based on Go 1. <p> Code in sub-repositories of the main go tree, such as -<a href="//code.google.com/p/go.net">code.google.com/p/go.net</a>, +<a href="//golang.org/x/net">golang.org/x/net</a>, may be developed under looser compatibility requirements. However, the sub-repositories will be tagged as appropriate to identify versions that are compatible with the Go 1 point releases. </p> +<h2 id="operating_systems">Operating systems</h2> + +<p> +It is impossible to guarantee long-term compatibility with operating +system interfaces, which are changed by outside parties. +The <a href="/pkg/syscall/"><code>syscall</code></a> package +is therefore outside the purview of the guarantees made here. +As of Go version 1.4, the <code>syscall</code> package is frozen. +Any evolution of the system call interface must be supported elsewhere, +such as in the +<a href="//golang.org/x/sys">go.sys</a> subrepository. +For details and background, see +<a href="//golang.org/s/go1.4-syscall">this document</a>. +</p> + <h2 id="tools">Tools</h2> <p> diff --git a/doc/go_faq.html b/doc/go_faq.html index f2082ef5b..6b77f1c1e 100644 --- a/doc/go_faq.html +++ b/doc/go_faq.html @@ -228,7 +228,7 @@ document server running in a production configuration on </p> <p> -Other examples include the <a href="https://code.google.com/p/vitess/">Vitess</a> +Other examples include the <a href="//code.google.com/p/vitess/">Vitess</a> system for large-scale SQL installations and Google's download server, <code>dl.google.com</code>, which delivers Chrome binaries and other large installables such as <code>apt-get</code> packages. @@ -889,6 +889,11 @@ type is generic; if you care about how many bits an integer holds, Go encourages you to be explicit. </p> +<p> +A blog post, title <a href="http://blog.golang.org/constants">Constants</a>, +explores this topic in more detail. +</p> + <h3 id="builtin_maps"> Why are maps built in?</h3> <p> @@ -971,7 +976,7 @@ It is a handy reference for people doing code reviews for Go projects. How do I submit patches to the Go libraries?</h3> <p> -The library sources are in <code>go/src/pkg</code>. +The library sources are in the <code>src</code> directory of the repository. If you want to make a significant change, please discuss on the mailing list before embarking. </p> @@ -981,32 +986,6 @@ See the document for more information about how to proceed. </p> -<h3 id="Why_does_the_project_use_Mercurial_and_not_git"> -Why does the project use Mercurial and not git?</h3> - -<p> -The Go project, hosted by Google Code at -<a href="//code.google.com/p/go">code.google.com/p/go</a>, -uses Mercurial as its version control system. -When the project launched, -Google Code supported only Subversion and Mercurial. -Mercurial was a better choice because of its plugin mechanism -that allowed us to create the "codereview" plugin to connect -the project to the excellent code review tools at -<a href="//codereview.appspot.com">codereview.appspot.com</a>. -</p> - -<p> -Programmers who work -with the Go project's source rather than release downloads sometimes -ask for the project to switch to git. -That would be possible, but it would be a lot of work and -would also require reimplementing the codereview plugin. -Given that Mercurial works today, with code review support, -combined with the Go project's mostly linear, non-branching use of -version control, a switch to git doesn't seem worthwhile. -</p> - <h3 id="git_https"> Why does "go get" use HTTPS when cloning a repository?</h3> @@ -1110,7 +1089,7 @@ error but the situation can still be confusing, because sometimes a <a href="#different_method_sets">pointer is necessary to satisfy an interface</a>. The insight is that although a pointer to a concrete type can satisfy -an interface, with one exception <em>a pointer to an interface can never satisfy a interface</em>. +an interface, with one exception <em>a pointer to an interface can never satisfy an interface</em>. </p> <p> @@ -1351,7 +1330,7 @@ to speed it up. </p> <p> -Go's goroutine scheduler is not as good as it needs to be. In future, it +Go's goroutine scheduler is not as good as it needs to be. In the future, it should recognize such cases and optimize its use of OS threads. For now, <code>GOMAXPROCS</code> should be set on a per-application basis. </p> @@ -1571,7 +1550,7 @@ table-driven, iterating over a list of inputs and outputs defined in a data structure (Go has excellent support for data structure literals). The work to write a good test and good error messages will then be amortized over many test cases. The standard Go library is full of illustrative examples, such as in -<a href="/src/pkg/fmt/fmt_test.go">the formatting tests for the <code>fmt</code> package</a>. +<a href="/src/fmt/fmt_test.go">the formatting tests for the <code>fmt</code> package</a>. </p> @@ -1590,30 +1569,40 @@ and uses a variant of the Plan 9 loader to generate ELF/Mach-O/PE binaries. </p> <p> -We considered writing <code>gc</code>, the original Go compiler, in Go itself but +We considered using LLVM for <code>gc</code> but we felt it was too large and +slow to meet our performance goals. +</p> + +<p> +We also considered writing <code>gc</code>, the original Go compiler, in Go itself but elected not to do so because of the difficulties of bootstrapping and especially of open source distribution—you'd need a Go compiler to set up a Go environment. <code>Gccgo</code>, which came later, makes it possible to -consider writing a compiler in Go, which might well happen. -(Go would be a -fine language in which to implement a compiler; a native lexer and -parser are already available in the <a href="/pkg/go/"><code>go</code></a> package -and a type checker is in the works.) +consider writing a compiler in Go. +A plan to do that by machine translation of the existing compiler is under development. +<a href="http://golang.org/s/go13compiler">A separate document</a> +explains the reason for this approach. </p> <p> -We also considered using LLVM for <code>gc</code> but we felt it was too large and -slow to meet our performance goals. +That plan aside, +Go is a +fine language in which to implement a self-hosting compiler: a native lexer and +parser are already available in the <a href="/pkg/go/"><code>go</code></a> package +and a separate type checking +<a href="http://godoc.org/golang.org/x/tools/go/types">package</a> +has also been written. </p> <h3 id="How_is_the_run_time_support_implemented"> How is the run-time support implemented?</h3> <p> -Again due to bootstrapping issues, the run-time code is mostly in C (with a -tiny bit of assembler) although Go is capable of implementing most of -it now. <code>Gccgo</code>'s run-time support uses <code>glibc</code>. -<code>Gc</code> uses a custom library to keep the footprint under +Again due to bootstrapping issues, the run-time code was originally written mostly in C (with a +tiny bit of assembler) although much of it has been translated to Go since then +and one day all of it might be (except for the assembler bits). +<code>Gccgo</code>'s run-time support uses <code>glibc</code>. +<code>Gc</code> uses a custom C library to keep the footprint under control; it is compiled with a version of the Plan 9 C compiler that supports resizable stacks for goroutines. @@ -1637,8 +1626,8 @@ A simple C "hello, world" program compiled and linked statically using gcc on Linux is around 750 kB, including an implementation of <code>printf</code>. An equivalent Go program using <code>fmt.Printf</code> -is around 1.2 MB, but -that includes more powerful run-time support. +is around 1.9 MB, but +that includes more powerful run-time support and type information. </p> <h3 id="unused_variables_and_imports"> @@ -1646,14 +1635,17 @@ Can I stop these complaints about my unused variable/import?</h3> <p> The presence of an unused variable may indicate a bug, while -unused imports just slow down compilation. -Accumulate enough unused imports in your code tree and -things can get very slow. -For these reasons, Go allows neither. +unused imports just slow down compilation, +an effect that can become substantial as a program accumulates +code and programmers over time. +For these reasons, Go refuses to compile programs with unused +variables or imports, +trading short-term convenience for long-term build speed and +program clarity. </p> <p> -When developing code, it's common to create these situations +Still, when developing code, it's common to create these situations temporarily and it can be annoying to have to edit them out before the program will compile. </p> @@ -1695,6 +1687,14 @@ func main() { } </pre> +<p> +Nowadays, most Go programmers use a tool, +<a href="http://godoc.org/golang.org/x/tools/cmd/goimports">goimports</a>, +which automatically rewrites a Go source file to have the correct imports, +eliminating the unused imports issue in practice. +This program is easily connected to most editors to run automatically when a Go source file is written. +</p> + <h2 id="Performance">Performance</h2> <h3 id="Why_does_Go_perform_badly_on_benchmark_x"> diff --git a/doc/go_mem.html b/doc/go_mem.html index 2ea1ded7a..5dd48ff7f 100644 --- a/doc/go_mem.html +++ b/doc/go_mem.html @@ -21,6 +21,29 @@ reads of a variable in one goroutine can be guaranteed to observe values produced by writes to the same variable in a different goroutine. </p> + +<h2>Advice</h2> + +<p> +Programs that modify data being simultaneously accessed by multiple goroutines +must serialize such access. +</p> + +<p> +To serialize access, protect the data with channel operations or other synchronization primitives +such as those in the <a href="/pkg/sync/"><code>sync</code></a> +and <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> packages. +</p> + +<p> +If you must read the rest of this document to understand the behavior of your program, +you are being too clever. +</p> + +<p> +Don't be clever. +</p> + <h2>Happens Before</h2> <p> diff --git a/doc/go_spec.html b/doc/go_spec.html index 660c8535e..ca0deb56a 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,6 +1,6 @@ <!--{ "Title": "The Go Programming Language Specification", - "Subtitle": "Version of May 28, 2014", + "Subtitle": "Version of November 11, 2014", "Path": "/ref/spec" }--> @@ -479,7 +479,7 @@ Interpreted string literals are character sequences between double quotes <code>""</code>. The text between the quotes, which may not contain newlines, forms the value of the literal, with backslash escapes interpreted as they -are in rune literals (except that <code>\'</code> is illegal and +are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and <code>\"</code> is legal), with the same restrictions. The three-digit octal (<code>\</code><i>nnn</i>) and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual @@ -577,7 +577,7 @@ Numeric constants represent values of arbitrary precision and do not overflow. </p> <p> -Constants may be <a href="#Types">typed</a> or untyped. +Constants may be <a href="#Types">typed</a> or <i>untyped</i>. Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>, and certain <a href="#Constant_expressions">constant expressions</a> containing only untyped constant operands are untyped. @@ -598,6 +598,17 @@ not <code>int32</code> or <code>string</code>. </p> <p> +An untyped constant has a <i>default type</i> which is the type to which the +constant is implicitly converted in contexts where a typed value is required, +for instance, in a <a href="#Short_variable_declarations">short variable declaration</a> +such as <code>i := 0</code> where there is no explicit type. +The default type of an untyped constant is <code>bool</code>, <code>rune</code>, +<code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code> +respectively, depending on whether it is a boolean, rune, integer, floating-point, +complex, or string constant. +</p> + +<p> There are no constants denoting the IEEE-754 infinity and not-a-number values, but the <a href="/pkg/math/"><code>math</code> package</a>'s <a href="/pkg/math/#Inf">Inf</a>, @@ -636,6 +647,65 @@ of evaluating <a href="#Constant_expressions">constant expressions</a>. </p> +<h2 id="Variables">Variables</h2> + +<p> +A variable is a storage location for holding a <i>value</i>. +The set of permissible values is determined by the +variable's <i><a href="#Types">type</a></i>. +</p> + +<p> +A <a href="#Variable_declarations">variable declaration</a> +or, for function parameters and results, the signature +of a <a href="#Function_declarations">function declaration</a> +or <a href="#Function_literals">function literal</a> reserves +storage for a named variable. + +Calling the built-in function <a href="#Allocation"><code>new</code></a> +or taking the address of a <a href="#Composite_literals">composite literal</a> +allocates storage for a variable at run time. +Such an anonymous variable is referred to via a (possibly implicit) +<a href="#Address_operators">pointer indirection</a>. +</p> + +<p> +<i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>, +and <a href="#Struct_types">struct</a> types have elements and fields that may +be <a href="#Address_operators">addressed</a> individually. Each such element +acts like a variable. +</p> + +<p> +The <i>static type</i> (or just <i>type</i>) of a variable is the +type given in its declaration, the type provided in the +<code>new</code> call or composite literal, or the type of +an element of a structured variable. +Variables of interface type also have a distinct <i>dynamic type</i>, +which is the concrete type of the value assigned to the variable at run time +(unless the value is the predeclared identifier <code>nil</code>, +which has no type). +The dynamic type may vary during execution but values stored in interface +variables are always <a href="#Assignability">assignable</a> +to the static type of the variable. +</p> + +<pre> +var x interface{} // x is nil and has static type interface{} +var v *T // v has value nil, static type *T +x = 42 // x has value 42 and dynamic type int +x = v // x has value (*T)(nil) and dynamic type *T +</pre> + +<p> +A variable's value is retrieved by referring to the variable in an +<a href="#Expressions">expression</a>; it is the most recent value +<a href="#Assignments">assigned</a> to the variable. +If a variable has not yet been assigned a value, its value is the +<a href="#The_zero_value">zero value</a> for its type. +</p> + + <h2 id="Types">Types</h2> <p> @@ -662,17 +732,6 @@ type literals. </p> <p> -The <i>static type</i> (or just <i>type</i>) of a variable is the -type defined by its declaration. Variables of interface type -also have a distinct <i>dynamic type</i>, which -is the actual type of the value stored in the variable at run time. -The dynamic type may vary during execution but is always -<a href="#Assignability">assignable</a> -to the static type of the interface variable. For non-interface -types, the dynamic type is always the static type. -</p> - -<p> Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code> is one of the predeclared boolean, numeric, or string types, or a type literal, the corresponding underlying @@ -1027,14 +1086,14 @@ struct { <h3 id="Pointer_types">Pointer types</h3> <p> -A pointer type denotes the set of all pointers to variables of a given +A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given type, called the <i>base type</i> of the pointer. The value of an uninitialized pointer is <code>nil</code>. </p> <pre class="ebnf"> PointerType = "*" BaseType . -BaseType = Type . +BaseType = Type . </pre> <pre> @@ -1154,11 +1213,11 @@ interface{} <p> Similarly, consider this interface specification, which appears within a <a href="#Type_declarations">type declaration</a> -to define an interface called <code>Lock</code>: +to define an interface called <code>Locker</code>: </p> <pre> -type Lock interface { +type Locker interface { Lock() Unlock() } @@ -1174,28 +1233,35 @@ func (p T) Unlock() { … } </pre> <p> -they implement the <code>Lock</code> interface as well +they implement the <code>Locker</code> interface as well as the <code>File</code> interface. </p> + <p> -An interface may use an interface type name <code>T</code> -in place of a method specification. -The effect, called embedding an interface, -is equivalent to enumerating the methods of <code>T</code> explicitly -in the interface. +An interface <code>T</code> may use a (possibly qualified) interface type +name <code>E</code> in place of a method specification. This is called +<i>embedding</i> interface <code>E</code> in <code>T</code>; it adds +all (exported and non-exported) methods of <code>E</code> to the interface +<code>T</code>. </p> <pre> -type ReadWrite interface { +type ReadWriter interface { Read(b Buffer) bool Write(b Buffer) bool } type File interface { - ReadWrite // same as enumerating the methods in ReadWrite - Lock // same as enumerating the methods in Lock + ReadWriter // same as adding the methods of ReadWriter + Locker // same as adding the methods of Locker Close() } + +type LockedFile interface { + Locker + File // illegal: Lock, Unlock not unique + Lock() // illegal: Lock not unique +} </pre> <p> @@ -1443,7 +1509,7 @@ is different from <code>[]string</code>. <h3 id="Assignability">Assignability</h3> <p> -A value <code>x</code> is <i>assignable</i> to a variable of type <code>T</code> +A value <code>x</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code> ("<code>x</code> is assignable to <code>T</code>") in any of these cases: </p> @@ -1875,9 +1941,10 @@ func (tz TimeZone) String() string { <h3 id="Variable_declarations">Variable declarations</h3> <p> -A variable declaration creates a variable, binds an identifier to it and -gives it a type and optionally an initial value. +A variable declaration creates one or more variables, binds corresponding +identifiers to them, and gives each a type and an initial value. </p> + <pre class="ebnf"> VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) . VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) . @@ -1898,22 +1965,27 @@ var _, found = entries[name] // map lookup; only interested in "found" <p> If a list of expressions is given, the variables are initialized -by <a href="#Assignments">assigning</a> the expressions to the variables -in order; all expressions must be consumed and all variables initialized from them. +with the expressions following the rules for <a href="#Assignments">assignments</a>. Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>. </p> <p> -If the type is present, each variable is given that type. -Otherwise, the types are deduced from the assignment -of the expression list. +If a type is present, each variable is given that type. +Otherwise, each variable is given the type of the corresponding +initialization value in the assignment. +If that value is an untyped constant, it is first +<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>; +if it is an untyped boolean value, it is first converted to type <code>bool</code>. +The predeclared value <code>nil</code> cannot be used to initialize a variable +with no explicit type. </p> -<p> -If the type is absent and the corresponding expression evaluates to an -untyped <a href="#Constants">constant</a>, the type of the declared variable -is as described in §<a href="#Assignments">Assignments</a>. -</p> +<pre> +var d = math.Sin(0.5) // d is int64 +var i = 42 // i is int +var t, ok = x.(T) // t is T, ok is bool +var n = nil // illegal +</pre> <p> Implementation restriction: A compiler may make it illegal to declare a variable @@ -2029,13 +2101,14 @@ and associates the method with the receiver's <i>base type</i>. <pre class="ebnf"> MethodDecl = "func" Receiver MethodName ( Function | Signature ) . -Receiver = "(" [ identifier ] [ "*" ] BaseTypeName ")" . -BaseTypeName = identifier . +Receiver = Parameters . </pre> <p> -The receiver type must be of the form <code>T</code> or <code>*T</code> where -<code>T</code> is a type name. The type denoted by <code>T</code> is called +The receiver is specified via an extra parameter section preceeding the method +name. That parameter section must declare a single parameter, the receiver. +Its type must be of the form <code>T</code> or <code>*T</code> (possibly using +parentheses) where <code>T</code> is a type name. The type denoted by <code>T</code> is called the receiver <i>base type</i>; it must not be a pointer or interface type and it must be declared in the same package as the method. The method is said to be <i>bound</i> to the base type and the method name @@ -2117,9 +2190,9 @@ operand only on the left-hand side of an <a href="#Assignments">assignment</a>. </p> <pre class="ebnf"> -Operand = Literal | OperandName | MethodExpr | "(" Expression ")" . -Literal = BasicLit | CompositeLit | FunctionLit . -BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . +Operand = Literal | OperandName | MethodExpr | "(" Expression ")" . +Literal = BasicLit | CompositeLit | FunctionLit . +BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . OperandName = identifier | QualifiedIdent. </pre> @@ -2241,7 +2314,8 @@ For array and slice literals the following rules apply: <p> <a href="#Address_operators">Taking the address</a> of a composite literal -generates a pointer to a unique instance of the literal's value. +generates a pointer to a unique <a href="#Variables">variable</a> initialized +with the literal's value. </p> <pre> var pointer *Point3D = &Point3D{y: 1000} @@ -2375,12 +2449,11 @@ Primary expressions are the operands for unary and binary expressions. PrimaryExpr = Operand | Conversion | - BuiltinCall | PrimaryExpr Selector | PrimaryExpr Index | PrimaryExpr Slice | PrimaryExpr TypeAssertion | - PrimaryExpr Call . + PrimaryExpr Arguments . Selector = "." identifier . Index = "[" Expression "]" . @@ -2388,8 +2461,7 @@ Slice = "[" ( [ Expression ] ":" [ Expression ] ) | ( [ Expression ] ":" Expression ":" Expression ) "]" . TypeAssertion = "." "(" Type ")" . -Call = "(" [ ArgumentList [ "," ] ] ")" . -ArgumentList = ExpressionList [ "..." ] . +Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" . </pre> @@ -2449,30 +2521,40 @@ The following rules apply to selectors: <ol> <li> For a value <code>x</code> of type <code>T</code> or <code>*T</code> -where <code>T</code> is not an interface type, +where <code>T</code> is not a pointer or interface type, <code>x.f</code> denotes the field or method at the shallowest depth in <code>T</code> where there is such an <code>f</code>. If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a> with shallowest depth, the selector expression is illegal. </li> + <li> -For a variable <code>x</code> of type <code>I</code> where <code>I</code> +For a value <code>x</code> of type <code>I</code> where <code>I</code> is an interface type, <code>x.f</code> denotes the actual method with name -<code>f</code> of the value assigned to <code>x</code>. +<code>f</code> of the dynamic value of <code>x</code>. If there is no method with name <code>f</code> in the <a href="#Method_sets">method set</a> of <code>I</code>, the selector expression is illegal. </li> + +<li> +As an exception, if the type of <code>x</code> is a named pointer type +and <code>(*x).f</code> is a valid selector expression denoting a field +(but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>. +</li> + <li> In all other cases, <code>x.f</code> is illegal. </li> + <li> If <code>x</code> is of pointer type and has the value <code>nil</code> and <code>x.f</code> denotes a struct field, assigning to or evaluating <code>x.f</code> causes a <a href="#Run_time_panics">run-time panic</a>. </li> + <li> If <code>x</code> is of interface type and has the value <code>nil</code>, <a href="#Calls">calling</a> or @@ -2482,18 +2564,6 @@ causes a <a href="#Run_time_panics">run-time panic</a>. </ol> <p> -Selectors automatically <a href="#Address_operators">dereference</a> -pointers to structs. -If <code>x</code> is a pointer to a struct, <code>x.y</code> -is shorthand for <code>(*x).y</code>; if the field <code>y</code> -is also a pointer to a struct, <code>x.y.z</code> is shorthand -for <code>(*(*x).y).z</code>, and so on. -If <code>x</code> contains an anonymous field of type <code>*A</code>, -where <code>A</code> is also a struct type, -<code>x.f</code> is shorthand for <code>(*x.A).f</code>. -</p> - -<p> For example, given the declarations: </p> @@ -2502,13 +2572,13 @@ type T0 struct { x int } -func (recv *T0) M0() +func (*T0) M0() type T1 struct { y int } -func (recv T1) M1() +func (T1) M1() type T2 struct { z int @@ -2516,9 +2586,13 @@ type T2 struct { *T0 } -func (recv *T2) M2() +func (*T2) M2() + +type Q *T2 -var p *T2 // with p != nil and p.T0 != nil +var t T2 // with t.T0 != nil +var p *T2 // with p != nil and (*p).T0 != nil +var q Q = p </pre> <p> @@ -2526,13 +2600,254 @@ one may write: </p> <pre> -p.z // (*p).z -p.y // ((*p).T1).y -p.x // (*(*p).T0).x +t.z // t.z +t.y // t.T1.y +t.x // (*t.TO).x + +p.z // (*p).z +p.y // (*p).T1.y +p.x // (*(*p).T0).x + +q.x // (*(*q).T0).x (*q).x is a valid field selector + +p.M2() // p.M2() M2 expects *T2 receiver +p.M1() // ((*p).T1).M1() M1 expects T1 receiver +p.M0() // ((&(*p).T0)).M0() M0 expects *T0 receiver, see section on Calls +</pre> + +<p> +but the following is invalid: +</p> + +<pre> +q.M0() // (*q).M0 is valid but not a field selector +</pre> + + +<h3 id="Method_expressions">Method expressions</h3> + +<p> +If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, +<code>T.M</code> is a function that is callable as a regular function +with the same arguments as <code>M</code> prefixed by an additional +argument that is the receiver of the method. +</p> + +<pre class="ebnf"> +MethodExpr = ReceiverType "." MethodName . +ReceiverType = TypeName | "(" "*" TypeName ")" | "(" ReceiverType ")" . +</pre> + +<p> +Consider a struct type <code>T</code> with two methods, +<code>Mv</code>, whose receiver is of type <code>T</code>, and +<code>Mp</code>, whose receiver is of type <code>*T</code>. +</p> + +<pre> +type T struct { + a int +} +func (tv T) Mv(a int) int { return 0 } // value receiver +func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver + +var t T +</pre> + +<p> +The expression +</p> + +<pre> +T.Mv +</pre> + +<p> +yields a function equivalent to <code>Mv</code> but +with an explicit receiver as its first argument; it has signature +</p> + +<pre> +func(tv T, a int) int +</pre> + +<p> +That function may be called normally with an explicit receiver, so +these five invocations are equivalent: +</p> + +<pre> +t.Mv(7) +T.Mv(t, 7) +(T).Mv(t, 7) +f1 := T.Mv; f1(t, 7) +f2 := (T).Mv; f2(t, 7) +</pre> + +<p> +Similarly, the expression +</p> + +<pre> +(*T).Mp +</pre> + +<p> +yields a function value representing <code>Mp</code> with signature +</p> + +<pre> +func(tp *T, f float32) float32 +</pre> + +<p> +For a method with a value receiver, one can derive a function +with an explicit pointer receiver, so +</p> + +<pre> +(*T).Mv +</pre> + +<p> +yields a function value representing <code>Mv</code> with signature +</p> + +<pre> +func(tv *T, a int) int +</pre> + +<p> +Such a function indirects through the receiver to create a value +to pass as the receiver to the underlying method; +the method does not overwrite the value whose address is passed in +the function call. +</p> + +<p> +The final case, a value-receiver function for a pointer-receiver method, +is illegal because pointer-receiver methods are not in the method set +of the value type. +</p> + +<p> +Function values derived from methods are called with function call syntax; +the receiver is provided as the first argument to the call. +That is, given <code>f := T.Mv</code>, <code>f</code> is invoked +as <code>f(t, 7)</code> not <code>t.f(7)</code>. +To construct a function that binds the receiver, use a +<a href="#Function_literals">function literal</a> or +<a href="#Method_values">method value</a>. +</p> + +<p> +It is legal to derive a function value from a method of an interface type. +The resulting function takes an explicit receiver of that interface type. +</p> + +<h3 id="Method_values">Method values</h3> + +<p> +If the expression <code>x</code> has static type <code>T</code> and +<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, +<code>x.M</code> is called a <i>method value</i>. +The method value <code>x.M</code> is a function value that is callable +with the same arguments as a method call of <code>x.M</code>. +The expression <code>x</code> is evaluated and saved during the evaluation of the +method value; the saved copy is then used as the receiver in any calls, +which may be executed later. +</p> + +<p> +The type <code>T</code> may be an interface or non-interface type. +</p> + +<p> +As in the discussion of <a href="#Method_expressions">method expressions</a> above, +consider a struct type <code>T</code> with two methods, +<code>Mv</code>, whose receiver is of type <code>T</code>, and +<code>Mp</code>, whose receiver is of type <code>*T</code>. +</p> + +<pre> +type T struct { + a int +} +func (tv T) Mv(a int) int { return 0 } // value receiver +func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver + +var t T +var pt *T +func makeT() T +</pre> + +<p> +The expression +</p> + +<pre> +t.Mv +</pre> + +<p> +yields a function value of type +</p> + +<pre> +func(int) int +</pre> + +<p> +These two invocations are equivalent: +</p> + +<pre> +t.Mv(7) +f := t.Mv; f(7) +</pre> + +<p> +Similarly, the expression +</p> + +<pre> +pt.Mp +</pre> + +<p> +yields a function value of type +</p> + +<pre> +func(float32) float32 +</pre> + +<p> +As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver +using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. +</p> + +<p> +As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver +using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. +</p> + +<pre> +f := t.Mv; f(7) // like t.Mv(7) +f := pt.Mp; f(7) // like pt.Mp(7) +f := pt.Mv; f(7) // like (*pt).Mv(7) +f := t.Mp; f(7) // like (&t).Mp(7) +f := makeT().Mp // invalid: result of makeT() is not addressable +</pre> + +<p> +Although the examples above use non-interface types, it is also legal to create a method value +from a value of interface type. +</p> -p.M2() // (*p).M2() -p.M1() // ((*p).T1).M1() -p.M0() // ((*p).T0).M0() +<pre> +var i interface { M(int) } = myVal +f := i.M; f(7) // like i.M(7) </pre> @@ -2625,7 +2940,7 @@ Otherwise <code>a[x]</code> is illegal. <p> An index expression on a map <code>a</code> of type <code>map[K]V</code> -may be used in an assignment or initialization of the special form +used in an <a href="#Assignments">assignment</a> or initialization of the special form </p> <pre> @@ -2635,11 +2950,9 @@ var v, ok = a[x] </pre> <p> -where the result of the index expression is a pair of values with types -<code>(V, bool)</code>. In this form, the value of <code>ok</code> is +yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> if the key <code>x</code> is present in the map, and -<code>false</code> otherwise. The value of <code>v</code> is the value -<code>a[x]</code> as in the single-result form. +<code>false</code> otherwise. </p> <p> @@ -2824,7 +3137,7 @@ r := y.(io.Reader) // r has type io.Reader and y must implement both I and i </pre> <p> -If a type assertion is used in an <a href="#Assignments">assignment</a> or initialization of the form +A type assertion used in an <a href="#Assignments">assignment</a> or initialization of the special form </p> <pre> @@ -2834,13 +3147,10 @@ var v, ok = x.(T) </pre> <p> -the result of the assertion is a pair of values with types <code>(T, bool)</code>. -If the assertion holds, the expression returns the pair <code>(x.(T), true)</code>; -otherwise, the expression returns <code>(Z, false)</code> where <code>Z</code> -is the <a href="#The_zero_value">zero value</a> for type <code>T</code>. +yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> +if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is +the <a href="#The_zero_value">zero value</a> for type <code>T</code>. No run-time panic occurs in this case. -The type assertion in this construct thus acts like a function call -returning a value and a boolean indicating success. </p> @@ -2870,7 +3180,7 @@ the method. <pre> math.Atan2(x, y) // function call var pt *Point -pt.Scale(3.5) // method call with receiver pt +pt.Scale(3.5) // method call with receiver pt </pre> <p> @@ -3375,13 +3685,13 @@ or an array indexing operation of an addressable array. As an exception to the addressability requirement, <code>x</code> may also be a (possibly parenthesized) <a href="#Composite_literals">composite literal</a>. -If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>, +If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>, then the evaluation of <code>&x</code> does too. </p> <p> For an operand <code>x</code> of pointer type <code>*T</code>, the pointer -indirection <code>*x</code> denotes the value of type <code>T</code> pointed +indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed to by <code>x</code>. If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code> will cause a <a href="#Run_time_panics">run-time panic</a>. @@ -3422,7 +3732,7 @@ f(<-ch) </pre> <p> -A receive expression used in an assignment or initialization of the form +A receive expression used in an <a href="#Assignments">assignment</a> or initialization of the special form </p> <pre> @@ -3432,7 +3742,7 @@ var x, ok = <-ch </pre> <p> -yields an additional result of type <code>bool</code> reporting whether the +yields an additional untyped boolean result reporting whether the communication succeeded. The value of <code>ok</code> is <code>true</code> if the value received was delivered by a successful send operation to the channel, or <code>false</code> if it is a zero value generated because the @@ -3440,232 +3750,6 @@ channel is closed and empty. </p> -<h3 id="Method_expressions">Method expressions</h3> - -<p> -If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, -<code>T.M</code> is a function that is callable as a regular function -with the same arguments as <code>M</code> prefixed by an additional -argument that is the receiver of the method. -</p> - -<pre class="ebnf"> -MethodExpr = ReceiverType "." MethodName . -ReceiverType = TypeName | "(" "*" TypeName ")" | "(" ReceiverType ")" . -</pre> - -<p> -Consider a struct type <code>T</code> with two methods, -<code>Mv</code>, whose receiver is of type <code>T</code>, and -<code>Mp</code>, whose receiver is of type <code>*T</code>. -</p> - -<pre> -type T struct { - a int -} -func (tv T) Mv(a int) int { return 0 } // value receiver -func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver - -var t T -</pre> - -<p> -The expression -</p> - -<pre> -T.Mv -</pre> - -<p> -yields a function equivalent to <code>Mv</code> but -with an explicit receiver as its first argument; it has signature -</p> - -<pre> -func(tv T, a int) int -</pre> - -<p> -That function may be called normally with an explicit receiver, so -these five invocations are equivalent: -</p> - -<pre> -t.Mv(7) -T.Mv(t, 7) -(T).Mv(t, 7) -f1 := T.Mv; f1(t, 7) -f2 := (T).Mv; f2(t, 7) -</pre> - -<p> -Similarly, the expression -</p> - -<pre> -(*T).Mp -</pre> - -<p> -yields a function value representing <code>Mp</code> with signature -</p> - -<pre> -func(tp *T, f float32) float32 -</pre> - -<p> -For a method with a value receiver, one can derive a function -with an explicit pointer receiver, so -</p> - -<pre> -(*T).Mv -</pre> - -<p> -yields a function value representing <code>Mv</code> with signature -</p> - -<pre> -func(tv *T, a int) int -</pre> - -<p> -Such a function indirects through the receiver to create a value -to pass as the receiver to the underlying method; -the method does not overwrite the value whose address is passed in -the function call. -</p> - -<p> -The final case, a value-receiver function for a pointer-receiver method, -is illegal because pointer-receiver methods are not in the method set -of the value type. -</p> - -<p> -Function values derived from methods are called with function call syntax; -the receiver is provided as the first argument to the call. -That is, given <code>f := T.Mv</code>, <code>f</code> is invoked -as <code>f(t, 7)</code> not <code>t.f(7)</code>. -To construct a function that binds the receiver, use a -<a href="#Function_literals">function literal</a> or -<a href="#Method_values">method value</a>. -</p> - -<p> -It is legal to derive a function value from a method of an interface type. -The resulting function takes an explicit receiver of that interface type. -</p> - -<h3 id="Method_values">Method values</h3> - -<p> -If the expression <code>x</code> has static type <code>T</code> and -<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, -<code>x.M</code> is called a <i>method value</i>. -The method value <code>x.M</code> is a function value that is callable -with the same arguments as a method call of <code>x.M</code>. -The expression <code>x</code> is evaluated and saved during the evaluation of the -method value; the saved copy is then used as the receiver in any calls, -which may be executed later. -</p> - -<p> -The type <code>T</code> may be an interface or non-interface type. -</p> - -<p> -As in the discussion of <a href="#Method_expressions">method expressions</a> above, -consider a struct type <code>T</code> with two methods, -<code>Mv</code>, whose receiver is of type <code>T</code>, and -<code>Mp</code>, whose receiver is of type <code>*T</code>. -</p> - -<pre> -type T struct { - a int -} -func (tv T) Mv(a int) int { return 0 } // value receiver -func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver - -var t T -var pt *T -func makeT() T -</pre> - -<p> -The expression -</p> - -<pre> -t.Mv -</pre> - -<p> -yields a function value of type -</p> - -<pre> -func(int) int -</pre> - -<p> -These two invocations are equivalent: -</p> - -<pre> -t.Mv(7) -f := t.Mv; f(7) -</pre> - -<p> -Similarly, the expression -</p> - -<pre> -pt.Mp -</pre> - -<p> -yields a function value of type -</p> - -<pre> -func(float32) float32 -</pre> - -<p> -As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver -using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. -</p> - -<p> -As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver -using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. -</p> - -<pre> -f := t.Mv; f(7) // like t.Mv(7) -f := pt.Mp; f(7) // like pt.Mp(7) -f := pt.Mv; f(7) // like (*pt).Mv(7) -f := t.Mp; f(7) // like (&t).Mp(7) -f := makeT().Mp // invalid: result of makeT() is not addressable -</pre> - -<p> -Although the examples above use non-interface types, it is also legal to create a method value -from a value of interface type. -</p> - -<pre> -var i interface { M(int) } = myVal -f := i.M; f(7) // like i.M(7) -</pre> - <h3 id="Conversions">Conversions</h3> <p> @@ -4055,7 +4139,7 @@ n := map[int]int{a: f()} // n may be {2: 3} or {3: 3}: evaluation order bet <p> At package level, initialization dependencies override the left-to-right rule for individual initialization expressions, but not for operands within each -expression: +expression: </p> <pre> @@ -4314,7 +4398,7 @@ a[i] = 23 <p> An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code> -<code>y</code> where <i>op</i> is a binary arithmetic operation equivalent +<code>y</code> where <i>op</i> is a binary arithmetic operation is equivalent to <code>x</code> <code>=</code> <code>x</code> <i>op</i> <code>y</code> but evaluates <code>x</code> only once. The <i>op</i><code>=</code> construct is a single token. @@ -4332,8 +4416,8 @@ i &^= 1<<n A tuple assignment assigns the individual elements of a multi-valued operation to a list of variables. There are two forms. In the first, the right hand operand is a single multi-valued expression -such as a function evaluation or <a href="#Channel_types">channel</a> or -<a href="#Map_types">map</a> operation or a <a href="#Type_assertions">type assertion</a>. +such as a function call, a <a href="#Channel_types">channel</a> or +<a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>. The number of operands on the left hand side must match the number of values. For instance, if <code>f</code> is a function returning two values, @@ -4407,23 +4491,21 @@ to the type of the operand to which it is assigned, with the following special c </p> <ol> -<li><p> - If an untyped <a href="#Constants">constant</a> +<li> + Any typed value may be assigned to the blank identifier. +</li> + +<li> + If an untyped constant is assigned to a variable of interface type or the blank identifier, - the constant is first <a href="#Conversions">converted</a> to type - <code>bool</code>, <code>rune</code>, <code>int</code>, <code>float64</code>, - <code>complex128</code> or <code>string</code> respectively, depending on - whether the value is a boolean, rune, integer, floating-point, complex, or - string constant. -</p></li> - -<li><p> - <!-- Note that the result of a comparison is an untyped bool that may not be constant. --> - If a left-hand side is the blank identifier, any typed or non-constant - value except for the predeclared identifier - <a href="#Predeclared_identifiers"><code>nil</code></a> - may be assigned to it. -</p></li> + the constant is first <a href="#Conversions">converted</a> to its + <a href="#Constants">default type</a>. +</li> + +<li> + If an untyped boolean value is assigned to a variable of interface type or + the blank identifier, it is first converted to type <code>bool</code>. +</li> </ol> <h3 id="If_statements">If statements</h3> @@ -4678,6 +4760,7 @@ additionally it may specify an <i>init</i> and a <i>post</i> statement, such as an assignment, an increment or decrement statement. The init statement may be a <a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not. +Variables declared by the init statement are re-used in each iteration. </p> <pre class="ebnf"> @@ -4713,41 +4796,42 @@ for { S() } is the same as for true { S() } A "for" statement with a "range" clause iterates through all entries of an array, slice, string or map, or values received on a channel. For each entry it assigns <i>iteration values</i> -to corresponding <i>iteration variables</i> and then executes the block. +to corresponding <i>iteration variables</i> if present and then executes the block. </p> <pre class="ebnf"> -RangeClause = ( ExpressionList "=" | IdentifierList ":=" ) "range" Expression . +RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression . </pre> <p> The expression on the right in the "range" clause is called the <i>range expression</i>, which may be an array, pointer to an array, slice, string, map, or channel permitting <a href="#Receive_operator">receive operations</a>. -As with an assignment, the operands on the left must be +As with an assignment, if present the operands on the left must be <a href="#Address_operators">addressable</a> or map index expressions; they -denote the iteration variables. If the range expression is a channel, only -one iteration variable is permitted, otherwise there may be one or two. In the latter case, -if the second iteration variable is the <a href="#Blank_identifier">blank identifier</a>, -the range clause is equivalent to the same clause with only the first variable present. +denote the iteration variables. If the range expression is a channel, at most +one iteration variable is permitted, otherwise there may be up to two. +If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>, +the range clause is equivalent to the same clause without that identifier. </p> <p> The range expression is evaluated once before beginning the loop, -with one exception. If the range expression is an array or a pointer to an array -and only the first iteration value is present, only the range expression's -length is evaluated; if that length is constant -<a href="#Length_and_capacity">by definition</a>, +with one exception: if the range expression is an array or a pointer to an array +and at most one iteration variable is present, only the range expression's +length is evaluated; if that length is constant, +<a href="#Length_and_capacity">by definition</a> the range expression itself will not be evaluated. </p> <p> Function calls on the left are evaluated once per iteration. -For each iteration, iteration values are produced as follows: +For each iteration, iteration values are produced as follows +if the respective iteration variables are present: </p> <pre class="grammar"> -Range expression 1st value 2nd value (if 2nd variable is present) +Range expression 1st value 2nd value array or slice a [n]E, *[n]E, or []E index i int a[i] E string s string type index i int see below rune @@ -4759,7 +4843,7 @@ channel c chan E, <-chan E element e E <li> For an array, pointer to array, or slice value <code>a</code>, the index iteration values are produced in increasing order, starting at element index 0. -If only the first iteration variable is present, the range loop produces +If at most one iteration variable is present, the range loop produces iteration values from 0 up to <code>len(a)-1</code> and does not index into the array or slice itself. For a <code>nil</code> slice, the number of iterations is 0. </li> @@ -4803,7 +4887,7 @@ The iteration variables may be declared by the "range" clause using a form of <a href="#Short_variable_declarations">short variable declaration</a> (<code>:=</code>). In this case their types are set to the types of the respective iteration values -and their <a href="#Declarations_and_scope">scope</a> ends at the end of the "for" +and their <a href="#Declarations_and_scope">scope</a> is the block of the "for" statement; they are re-used in each iteration. If the iteration variables are declared outside the "for" statement, after execution their values will be those of the last iteration. @@ -4840,6 +4924,9 @@ var ch chan Work = producer() for w := range ch { doWork(w) } + +// empty a channel +for range ch {} </pre> @@ -5242,13 +5329,16 @@ Calls of built-in functions are restricted as for </p> <p> -Each time the "defer" statement +Each time a "defer" statement executes, the function value and parameters to the call are <a href="#Calls">evaluated as usual</a> -and saved anew but the actual function body is not executed. -Instead, deferred functions are executed immediately before +and saved anew but the actual function is not invoked. +Instead, deferred functions are invoked immediately before the surrounding function returns, in the reverse order they were deferred. +If a deferred function value evaluates +to <code>nil</code>, execution <a href="#Handling_panics">panics</a> +when the function is invoked, not when the "defer" statement is executed. </p> <p> @@ -5295,11 +5385,6 @@ so they can only appear in <a href="#Calls">call expressions</a>; they cannot be used as function values. </p> -<pre class="ebnf"> -BuiltinCall = identifier "(" [ BuiltinArgs [ "," ] ] ")" . -BuiltinArgs = Type [ "," ArgumentList ] | ArgumentList . -</pre> - <h3 id="Close">Close</h3> <p> @@ -5378,9 +5463,11 @@ var z complex128 <h3 id="Allocation">Allocation</h3> <p> -The built-in function <code>new</code> takes a type <code>T</code> and -returns a value of type <code>*T</code>. -The memory is initialized as described in the section on +The built-in function <code>new</code> takes a type <code>T</code>, +allocates storage for a <a href="#Variables">variable</a> of that type +at run time, and returns a value of type <code>*T</code> +<a href="#Pointer_types">pointing</a> to it. +The variable is initialized as described in the section on <a href="#The_zero_value">initial values</a>. </p> @@ -5398,10 +5485,10 @@ new(S) </pre> <p> -dynamically allocates memory for a variable of type <code>S</code>, +allocates storage for a variable of type <code>S</code>, initializes it (<code>a=0</code>, <code>b=0.0</code>), and returns a value of type <code>*S</code> containing the address -of the memory. +of the location. </p> <h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3> @@ -5868,10 +5955,12 @@ func main() { <h3 id="The_zero_value">The zero value</h3> <p> -When memory is allocated to store a value, either through a declaration -or a call of <code>make</code> or <code>new</code>, -and no explicit initialization is provided, the memory is -given a default initialization. Each element of such a value is +When storage is allocated for a <a href="#Variables">variable</a>, +either through a declaration or a call of <code>new</code>, or when +a new value is created, either through a composite literal or a call +of <code>make</code>, +and no explicit initialization is provided, the variable or value is +given a default value. Each element of such a variable or value is set to the <i>zero value</i> for its type: <code>false</code> for booleans, <code>0</code> for integers, <code>0.0</code> for floats, <code>""</code> for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps. @@ -5915,20 +6004,42 @@ var t T </pre> <h3 id="Package_initialization">Package initialization</h3> + <p> -Within a package, package-level variables are initialized according -to their <i>dependencies</i>: if a variable <code>x</code> depends on -a variable <code>y</code>, <code>x</code> will be initialized after -<code>y</code>. +Within a package, package-level variables are initialized in +<i>declaration order</i> but after any of the variables +they <i>depend</i> on. +</p> + +<p> +More precisely, a package-level variable is considered <i>ready for +initialization</i> if it is not yet initialized and either has +no <a href="#Variable_declarations">initialization expression</a> or +its initialization expression has no dependencies on uninitialized variables. +Initialization proceeds by repeatedly initializing the next package-level +variable that is earliest in declaration order and ready for initialization, +until there are no variables ready for initialization. +</p> + +<p> +If any variables are still uninitialized when this +process ends, those variables are part of one or more initialization cycles, +and the program is not valid. +</p> + +<p> +The declaration order of variables declared in multiple files is determined +by the order in which the files are presented to the compiler: Variables +declared in the first file are declared before any of the variables declared +in the second file, and so on. </p> <p> Dependency analysis does not rely on the actual values of the variables, only on lexical <i>references</i> to them in the source, -analyzed transitively. For instance, a variable <code>x</code>'s -<a href="#Variable_declarations">initialization expression</a> -may refer to a function whose body refers to variable <code>y</code>; -if so, <code>x</code> depends on <code>y</code>. +analyzed transitively. For instance, if a variable <code>x</code>'s +initialization expression refers to a function whose body refers to +variable <code>y</code> then <code>x</code> depends on <code>y</code>. Specifically: </p> @@ -5941,7 +6052,7 @@ variable or function. <li> A reference to a method <code>m</code> is a <a href="#Method_values">method value</a> or -<a href="#Method_expressions">method expression</a> of the form +<a href="#Method_expressions">method expression</a> of the form <code>t.m</code>, where the (static) type of <code>t</code> is not an interface type, and the method <code>m</code> is in the <a href="#Method_sets">method set</a> of <code>t</code>. @@ -5950,7 +6061,7 @@ It is immaterial whether the resulting function value </li> <li> -A variable, function, or method <code>x</code> depends on a variable +A variable, function, or method <code>x</code> depends on a variable <code>y</code> if <code>x</code>'s initialization expression or body (for functions and methods) contains a reference to <code>y</code> or to a function or method that depends on <code>y</code>. @@ -5961,11 +6072,6 @@ or to a function or method that depends on <code>y</code>. Dependency analysis is performed per package; only references referring to variables, functions, and methods declared in the current package are considered. -It is an error if variable dependencies form a cycle -(but dependency cycles containing no variables are permitted). -If two variables are independent of each other, -they are initialized in the order they are declared -in the source, possibly in multiple files, as presented to the compiler. </p> <p> @@ -5988,8 +6094,6 @@ func f() int { <p> the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>. -Since <code>b</code> and <code>c</code> are independent of each other, they are -initialized in declaration order (<code>b</code> before <code>c</code>). </p> <p> @@ -6002,7 +6106,7 @@ func init() { … } </pre> <p> -Multiple such functions may be defined, even within a single +Multiple such functions may be defined, even within a single source file. The <code>init</code> identifier is not <a href="#Declarations_and_scope">declared</a> and thus <code>init</code> functions cannot be referred to from anywhere @@ -6032,6 +6136,12 @@ the <code>init</code> functions: it will not invoke the next one until the previous one has returned. </p> +<p> +To ensure reproducible initialization behavior, build systems are encouraged +to present multiple files belonging to the same package in lexical file name +order to a compiler. +</p> + <h3 id="Program_execution">Program execution</h3> <p> @@ -6106,8 +6216,8 @@ type Error interface { The built-in package <code>unsafe</code>, known to the compiler, provides facilities for low-level programming including operations that violate the type system. A package using <code>unsafe</code> -must be vetted manually for type safety. The package provides the -following interface: +must be vetted manually for type safety and may not be portable. +The package provides the following interface: </p> <pre class="grammar"> @@ -6122,10 +6232,11 @@ func Sizeof(variable ArbitraryType) uintptr </pre> <p> -Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to -a <code>Pointer</code> type and vice versa. A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code> value may not be <a href="#Address_operators">dereferenced</a>. +Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to +a <code>Pointer</code> type and vice versa. +The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined. </p> <pre> diff --git a/doc/gopher/biplane.jpg b/doc/gopher/biplane.jpg Binary files differnew file mode 100644 index 000000000..d5e666f96 --- /dev/null +++ b/doc/gopher/biplane.jpg diff --git a/doc/gopher/fiveyears.jpg b/doc/gopher/fiveyears.jpg Binary files differnew file mode 100644 index 000000000..df1064868 --- /dev/null +++ b/doc/gopher/fiveyears.jpg diff --git a/doc/help.html b/doc/help.html index a307b2aad..2cc47806c 100644 --- a/doc/help.html +++ b/doc/help.html @@ -24,7 +24,7 @@ Need help with Go? Try these resources. <p> Search the <a href="//groups.google.com/group/golang-nuts">golang-nuts</a> archives and consult the <a href="/doc/go_faq.html">FAQ</a> and -<a href="//code.google.com/p/go-wiki/wiki">wiki</a> before posting. +<a href="//golang.org/wiki">wiki</a> before posting. </p> <h3 id="irc"><a href="irc:irc.freenode.net/go-nuts">Go IRC Channel</a></h3> diff --git a/doc/install-source.html b/doc/install-source.html index 82859b50f..f53deb404 100644 --- a/doc/install-source.html +++ b/doc/install-source.html @@ -241,12 +241,12 @@ provides <b>essential setup instructions</b> for using the Go tools. <p> The source code for several Go tools (including <a href="/cmd/godoc/">godoc</a>) -is kept in <a href="https://code.google.com/p/go.tools">the go.tools repository</a>. +is kept in <a href="https://golang.org/x/tools">the go.tools repository</a>. To install all of them, run the <code>go</code> <code>get</code> command: </p> <pre> -$ go get code.google.com/p/go.tools/cmd/... +$ go get golang.org/x/tools/cmd/... </pre> <p> @@ -254,7 +254,7 @@ Or if you just want to install a specific command (<code>godoc</code> in this ca </p> <pre> -$ go get code.google.com/p/go.tools/cmd/godoc +$ go get golang.org/x/tools/cmd/godoc </pre> <p> diff --git a/doc/install.html b/doc/install.html index 2de04471c..9561fdde2 100644 --- a/doc/install.html +++ b/doc/install.html @@ -6,14 +6,14 @@ <h2 id="download">Download the Go distribution</h2> <p> -<a href="/dl/" id="start" class="download" target="_blank"> +<a href="https://golang.org/dl/" id="start" class="download" target="_blank"> <span class="big">Download Go</span> <span class="desc">Click here to visit the downloads page</span> </a> </p> <p> -<a href="https://code.google.com/p/go/wiki/Downloads?tm=2" target="_blank">Official binary +<a href="https://golang.org/dl/" target="_blank">Official binary distributions</a> are available for the FreeBSD (release 8 and above), Linux, Mac OS X (Snow Leopard and above), and Windows operating systems and the 32-bit (<code>386</code>) and 64-bit (<code>amd64</code>) x86 processor architectures. @@ -47,7 +47,7 @@ proceeding. If your OS or architecture is not on the list, it's possible that <tr><td>FreeBSD 8 or later</td> <td>amd64, 386, arm</td> <td>Debian GNU/kFreeBSD not supported; FreeBSD/ARM needs FreeBSD 10 or later</td></tr> <tr><td>Linux 2.6.23 or later with glibc</td> <td>amd64, 386, arm</td> <td>CentOS/RHEL 5.x not supported; no binary distribution for ARM yet</td></tr> <tr><td>Mac OS X 10.6 or later</td> <td>amd64, 386</td> <td>use the gcc<sup>†</sup> that comes with Xcode<sup>‡</sup></td></tr> -<tr><td>Windows XP or later</td> <td>amd64, 386</td> <td>use MinGW gcc<sup>†</sup>. No need for cgywin or msys.</td></tr> +<tr><td>Windows XP or later</td> <td>amd64, 386</td> <td>use MinGW gcc<sup>†</sup>. No need for cygwin or msys.</td></tr> </table> <p> @@ -70,7 +70,7 @@ first <a href="#uninstall">remove the existing version</a>. <h3 id="tarball">Linux, Mac OS X, and FreeBSD tarballs</h3> <p> -<a href="https://code.google.com/p/go/wiki/Downloads?tm=2">Download the archive</a> +<a href="https://golang.org/dl/">Download the archive</a> and extract it into <code>/usr/local</code>, creating a Go tree in <code>/usr/local/go</code>. For example: </p> @@ -127,7 +127,7 @@ location. <h3 id="osx">Mac OS X package installer</h3> <p> -<a href="https://code.google.com/p/go/wiki/Downloads?tm=2">Download the package file</a>, +<a href="https://golang.org/dl/">Download the package file</a>, open it, and follow the prompts to install the Go tools. The package installs the Go distribution to <code>/usr/local/go</code>. </p> @@ -150,7 +150,7 @@ MSI installer that configures your installation automatically. <h4 id="windows_msi">MSI installer</h4> <p> -Open the <a href="https://code.google.com/p/go/wiki/Downloads?tm=2">MSI file</a> +Open the <a href="https://golang.org/dl/">MSI file</a> and follow the prompts to install the Go tools. By default, the installer puts the Go distribution in <code>c:\Go</code>. </p> @@ -164,7 +164,7 @@ command prompts for the change to take effect. <h4 id="windows_zip">Zip archive</h4> <p> -<a href="https://code.google.com/p/go/wiki/Downloads?tm=2">Download the zip file</a> and extract it into the directory of your choice (we suggest <code>c:\Go</code>). +<a href="https://golang.org/dl/">Download the zip file</a> and extract it into the directory of your choice (we suggest <code>c:\Go</code>). </p> <p> @@ -224,19 +224,12 @@ If you see the "hello, world" message then your Go installation is working. <p> You're almost done. -You just need to do a little more setup. +You just need to set up your environment. </p> <p> -<a href="/doc/code.html" class="download" id="writing"> -<span class="big">How to Write Go Code</span> -<span class="desc">Learn how to set up and use the Go tools</span> -</a> -</p> - -<p> -The <a href="/doc/code.html">How to Write Go Code</a> document -provides <b>essential setup instructions</b> for using the Go tools. +Read the <a href="/doc/code.html">How to Write Go Code</a> document, +which provides <b>essential setup instructions</b> for using the Go tools. </p> @@ -277,5 +270,3 @@ The official mailing list for discussion of the Go language is Report bugs using the <a href="//golang.org/issue">Go issue tracker</a>. </p> - - |
