Introduction to Go 1

For a full explanation of the motivation and design of Go 1, see XXX. Here follows a summary.

Go 1 is intended to be a stable language and core library set that will form a reliable foundation for people and organizations that want to make a long-term commitment to developing in the Go programming language. Go will continue to develop, but in a way that guarantees code written to the Go 1 specification will continue to work. For instance, Go 1 will be a supported platform on Google App Engine for the next few years. Incompatible changes to the environment, should they arise, will be done in a distinct version.

This document describes the changes in the language and libraries in Go 1, relative to the previous release, r60 (at the time of writing, tagged as r60.3). It also explains how to update code at r60 to compile and run under Go 1. Finally, it outlines the new go command for building Go programs and the new binary release process being introduced. Most of these topics have more thorough presentations elsewhere; such documents are linked below.

Changes to the language

Append

The append built-in function is variadic, so one can append to a byte slice using the ... syntax in the call.

By analogy with the similar property of copy, Go 1 permits a string to be appended (byte-wise) directly to a byte slice; the conversion is no longer necessary:

Updating: This is a new feature, so existing code needs no changes.

Close

The close built-in function lets a sender tell a receiver that no more data will be transmitted on the channel. In Go 1 the type system enforces the directionality when possible: it is illegal to call close on a receive-only channel:

    var c chan int
    var csend chan<- int = c
    var crecv <-chan int = c
    close(c)     // legal
    close(csend) // legal
    close(crecv) // illegal

Updating: Existing code that attempts to close a receive-only channel was erroneous even before Go 1 and should be fixed. The compiler will now reject such code.

Composite literals

In Go 1, a composite literal of array, slice, or map type can elide the type specification for the elements' initializers if they are of pointer type. All four of the initializations in this example are legal; the last one was illegal before Go 1.

Updating: This change has no effect on existing code, but the command gofmt -s applied to existing source will, among other things, elide explicit element types wherever permitted.

Goroutines during init

Go 1 allows goroutines to be created and run during initialization. (They used to be created but were not run until after initialization completed.) Code that uses goroutines can now be called from init routines and global initialization expressions without introducing a deadlock.

Updating: This is a new feature, so existing code needs no changes, although it's possible that code that depends on goroutines not starting before main will break. There was no such code in the standard repository.

The rune type

Go 1 introduces a new basic type, rune, to be used to represent individual Unicode code points. It is an alias for int32, analogous to byte as an alias for uint8.

Character literals such as 'a', '語', and '\u0345' now have default type rune, analogous to 1.0 having default type float64. A variable initialized to a character constant will therefore have type rune unless otherwise specified.

Libraries have been updated to use rune rather than int when appropriate. For instance, the functions unicode.ToLower and relatives now take and return a rune.

Updating: Most source code will be unaffected by this because the type inference from := initializers introduces the new type silently, and it propagates from there. Some code may get type errors that a trivial conversion will resolve.

The error type

Go 1 introduces a new built-in type, error, which has the following definition:

    type error interface {
        Error() string
    }

Since the consequences of this type are all in the package library, it is discussed below.

Deleting from maps

The original syntax for deleting an element in a map was:

    m[k] = ignored, false

In Go 1, that syntax has gone; instead there is a new built-in function, delete. The call

will delete the map entry retrieved by the expression m[k]. There is no return value. Deleting a non-existent entry is a no-op.

Updating: Running go fix will convert expressions of the form m[k] = ignored, false into delete(m, k) when it is clear that the ignored value can be safely discarded from the program and false refers to the predefined boolean constant. The fix tool will flag other uses of the syntax for inspection by the programmer.

Iterating in maps

In Go 1, the order in which elements are visited when iterating over a map using a for range statement is defined to be unpredictable, even if the same loop is run multiple times with the same map. Code should not assume that the elements are visited in any particular order.

Updating: This is one change where tools cannot help. Most existing code will be unaffected, but some programs may break or misbehave; we recommend manual checking of all range statements over maps to verify they do not depend on iteration order. There were a few such examples in the standard repository; they have been fixed. Note that it was already incorrect to depend on the iteration order, which was unspecified. This change codifies the unpredictability.

Multiple assignment

Go 1 fully specifies the evaluation order in multiple assignment statements. In particular, if the left-hand side of the assignment statement contains expressions that require evaluation, such as function calls or array indexing operations, these will all be done using the usual left-to-right rule before any variables are assigned their value. Once everything is evaluated, the actual assignments proceed in left-to-right order.

These examples illustrate the behavior.

Updating: This is one change where tools cannot help, but breakage is unlikely. No code in the standard repository was broken by this change, and code that depended on the previous unspecified behavior was already incorrect.

Returns and shadowed variables

A shadowed variable is one that has the same name as another variable in an inner scope. In functions with named return values, the Go 1 compilers disallow return statements without arguments if any of the named return values is shadowed at the point of the return statement. (It isn't part of the specification, because this is one area we are still exploring; the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.)

This function implicitly returns a shadowed return value and will be rejected by the compiler:

    func Bug() (i, j, k int) {
        for i = 0; i < 5; i++ {
            for j := 0; j < 5; j++ { // Redeclares j.
                k += i*j
                if k > 100 {
                    return // Rejected: j is shadowed here.
                }
            }
        }
        return // OK: j is not shadowed here.
    }

Updating: Code that shadows return values in this way will be rejected by the compiler and will need to be fixed by hand. The few cases that arose in the standard repository were mostly bugs.

Copying structs with unexported fields

Go 1 relaxes the rules about accessing structs with unexported (lower-case) fields, permitting a client package to assign (and therefore copy) such a struct. Of course, the client package still cannot access such fields individually.

As an example, if package p includes the definitions,

    type Struct struct {
        Public int
        secret int
    }
    func NewStruct(a int) Struct {  // Note: not a pointer.
        return Struct{a, f(a)}
    }
    func (s Struct) String() string {
        return fmt.Sprintf("{%d (secret %d)}", s.Public, s.secret)
    }

a package that imports p can assign and copy values of type p.Struct at will. Behind the scenes the unexported fields will be assigned and copied just as if they were exported, but the client code will never be aware of them. The code

    import "p"

    myStruct := p.NewStruct(23)
    copyOfMyStruct := myStruct
    fmt.Println(myStruct, copyOfMyStruct)

will show that the secret field of the struct has been copied to the new value.

Updating: This is a new feature, so existing code needs no changes.

Equality of structs and arrays

Go 1 defines equality and inequality (== and !=) for struct and array values, respectively, provided the elements of the data structures can themselves be compared. That is, if equality is defined for all the fields of a struct (or an array element), then it is defined for the struct (or array).

As a result, structs and arrays can now be used as map keys:

Note that equality is still undefined for slices, for which the calculation is in general infeasible. Also note that the ordered comparison operators (< <= > >=) are still undefined for structs and arrays.

Updating: This is a new feature, so existing code needs no changes.

Function and map equality

Go 1 disallows checking for equality of functions and maps, respectively, except to compare them directly to nil.

Updating: Existing code that depends on function or map equality will be rejected by the compiler and will need to be fixed by hand. Few programs will be affected, but the fix may require some redesign.

The package hierarchy

This section describes how the packages have been rearranged in Go 1. Some have moved, some have been renamed, some have been deleted. New packages are described in later sections.

The package hierarchy

Go 1 has a rearranged package hierarchy that groups related items into subdirectories. For instance, utf8 and utf16 now occupy subdirectories of unicode. Also, some packages have moved into subrepositories of code.google.com/p/go while others have been deleted outright.

Note that the package names for the old cmath and exp/template/html packages have changed to cmplx and template.

Updating: Running go fix will update all imports and package renames for packages that remain inside the standard repository. Programs that import packages that are no longer in the standard repository will need to be edited by hand.
TODO: go fix should warn about deletions.

The package tree exp

Because they are not standardized, the packages under the exp directory will not be available in the standard Go 1 release distributions, although they will be available in source code form in the repository for developers who wish to use them.

Several packages have moved under exp at the time of Go 1's release:

• ebnf
• go/types
• os/signal

All these packages are available under the same names, with the prefix exp/: exp/ebnf etc.

Also, the utf8.String type has been moved to its own package, exp/utf8string.

Finally, the gotype command now resides in exp/gotype, while ebnflint is now in exp/ebnflint. If they are installed, they now reside in $GOROOT/bin/tool.

Updating: Code that uses packages in exp will need to be updated by hand, or else compiled from an installation that has exp available. The go fix tool or the compiler will complain about such uses.
TODO: go fix should warn about such uses.

The package tree old

Because they are deprecated, the packages under the old directory will not be available in the standard Go 1 release distributions, although they will be available in source code form for developers who wish to use them.

The packages in their new locations are:

• old/netchan
• old/regexp
• old/template

Updating: Code that uses packages now in old will need to be updated by hand, or else compiled from an installation that has old available. The go fix tool will warn about such uses.
TODO: go fix should warn about such uses.

Deleted packages

Go 1 deletes several packages outright:

• container/vector
• exp/datafmt
• go/typechecker
• try

and also the command gotry.

Updating: Code that uses container/vector should be updated to use slices directly. See the Go Language Community Wiki for some suggestions. Code that uses the other packages (there should be almost zero) will need to be rethought.
TODO: go fix should warn such uses.

Packages moving to subrepositories

Go 1 has moved a number of packages into sub-repositories of the main Go repository. This table lists the old and new import paths:

Old	New
crypto/bcrypt	code.google.com/p/go.crypto/bcrypt
crypto/blowfish	code.google.com/p/go.crypto/blowfish
crypto/cast5	code.google.com/p/go.crypto/cast5
crypto/md4	code.google.com/p/go.crypto/md4
crypto/ocsp	code.google.com/p/go.crypto/ocsp
crypto/openpgp	code.google.com/p/go.crypto/openpgp
crypto/openpgp/armor	code.google.com/p/go.crypto/openpgp/armor
crypto/openpgp/elgamal	code.google.com/p/go.crypto/openpgp/elgamal
crypto/openpgp/errors	code.google.com/p/go.crypto/openpgp/errors
crypto/openpgp/packet	code.google.com/p/go.crypto/openpgp/packet
crypto/openpgp/s2k	code.google.com/p/go.crypto/openpgp/s2k
crypto/ripemd160	code.google.com/p/go.crypto/ripemd160
crypto/twofish	code.google.com/p/go.crypto/twofish
crypto/xtea	code.google.com/p/go.crypto/xtea
exp/ssh	code.google.com/p/go.crypto/ssh
image/bmp	code.google.com/p/go.image/bmp
image/tiff	code.google.com/p/go.image/tiff
net/dict	code.google.com/p/go.net/dict
net/websocket	code.google.com/p/go.net/websocket
exp/spdy	code.google.com/p/go.net/spdy
encoding/git85	code.google.com/p/go.codereview/git85
patch	code.google.com/p/go.codereview/patch

Updating: Running go fix will update imports of these packages to use the new import paths. Installations that depend on these packages will need to install them using a go install command.

Major changes to the library

This section describes significant changes to the core libraries, the ones that affect the most programs.

The error type and errors package

As mentioned above, Go 1 introduces a new built-in interface type called error. Its intent is to replace the old os.Error type with a more central concept. So the widely-used String method does not cause accidental satisfaction of the error interface, the error interface uses instead the name Error for that method:

    type error interface {
        Error() string
    }

The fmt library automatically invokes Error, as it already does for String, for easy printing of error values.

All standard packages have been updated to use the new interface; the old os.Error is gone.

A new package, errors, contains the function

func New(text string) error

to turn a string into an error. It replaces the old os.NewError.

Updating: Running go fix will update almost all code affected by the change. Code that defines error types with a String method will need to be updated by hand to rename the methods to Error.

System call errors

In Go 1, the syscall package returns an error for system call errors, rather than plain integer errno values. On Unix, the implementation is done by a syscall.Errno type that satisfies error and replaces the old os.Errno.

Updating: Running go fix will update almost all code affected by the change. Regardless, most code should use the os package rather than syscall and so will be unaffected.

Time

One of the most sweeping changes in the Go 1 library is the complete redesign of the time package. Instead of an integer number of nanoseconds as an int64, and a separate *time.Time type to deal with human units such as hours and years, there are now two fundamental types: time.Time (a value, so the * is gone), which represents a moment in time; and time.Duration, which represents an interval. Both have nanosecond resolution. A Time can represent any time into the ancient past and remote future, while a Duration can span plus or minus only about 290 years. There are methods on these types, plus a number of helpful predefined constant durations such as time.Second.

Among the new methods are things like Time.Add, which adds a Duration to a Time, and Time.Sub, which subtracts two Times to yield a Duration.

The most important semantic change is that the Unix epoch (Jan 1, 1970) is now relevant only for those functions and methods that mention Unix: time.Unix and the Unix and UnixNano methods of the Time type. In particular, time.Now returns a time.Time value rather than, in the old API, an integer nanosecond count since the Unix epoch.

The new types, methods, and constants have been propagated through all the standard packages that use time, such as os and its representation of file time stamps.

Updating: The go fix tool will update many uses of the old time package to use the new types and methods, although it does not replace values such as 1e9 representing nanoseconds per second. Also, because of type changes in some of the values that arise, some of the expressions rewritten by the fix tool may require further hand editing; in such cases the rewrite will include the correct function or method for the old functionality, but may have the wrong type or require further analysis.

Minor changes to the library

This section describes smaller changes, such as those to less commonly used packages or that affect few programs beyond the need to run go fix. This category includes packages that are new in Go 1.

The crypto/elliptic package

In Go 1, elliptic.Curve has been made an interface to permit alternative implementations. The curve parameters have been moved to the elliptic.CurveParams structure.

Updating: Existing users of *elliptic.Curve will need to change to simply elliptic.Curve. Calls to Marshal, Unmarshal and GenerateKey are now functions in crypto/elliptic that take an elliptic.Curve as their first argument.

The crypto/hmac package

In Go 1, the hash-specific functions, such as hmac.NewMD5, have been removed from crypto/hmac. Instead, hmac.New takes a function that returns a hash.Hash, such as md5.New.

Updating: Running go fix will perform the needed changes.

The crypto/x509 package

In Go 1, the CreateCertificate and CreateCRL functions in crypto/x509 have been altered to take an interface{} where they previously took a *rsa.PublicKey or *rsa.PrivateKey. This will allow other public key algorithms to be implemented in the future.

Updating: No changes will be needed.

The expvar package

In Go 1, the RemoveAll function has been removed. The Iter function and Iter method on *Map have been replaced by Do and (*Map).Do.

Updating: Most code using expvar will not need changing. The rare code that used Iter can be updated to pass a closure to Do to achieve the same effect.

The flag package

In Go 1, the interface flag.Value has changed slightly. The Set method now returns an error instead of a bool to indicate success or failure.

There is also a new kind of flag, Duration, to support argument values specifying time intervals. Values for such flags must be given units, just as time.Duration formats them: 10s, 1h30m, etc.

Updating: Programs that implement their own flags will need minor manual fixes to update their Set methods. The Duration flag is new and affects no existing code.

The go/* packages

Several packages under go have slightly revised APIs.

The modes AllowIllegalChars and InsertSemis have been removed from the go/scanner package. They were mostly useful for scanning text other then Go source files. Instead, the text/scanner package should be used for that purpose.

The set of parse functions provided by the go/parser package has been reduced to the primary parse function ParseFile, and a couple of convenience functions ParseDir and ParseExpr.

The type names of the go/doc package have been streamlined by removing the Doc suffix: PackageDoc is now Package, ValueDoc is Value, etc. Also, all types now consistently have a Name field (or Names, in the case of type Value) and Type.Factories has become Type.Funcs. Instead of calling doc.NewPackageDoc(pkg, importpath), documentation for a package is created with:

    doc.New(pkg, importpath, mode)

where the new mode parameter specifies the operation mode: if set to AllDecls, all declarations (not just exported ones) are considered. The function NewFileDoc was removed, and the function CommentText has become the method Text of ast.CommentGroup.

In package go/token, the token.FileSet method Files (which originally returned a channel of *token.Files) has been replaced with the iterator Iterate that accepts a function argument instead.

Updating: Code that uses packages in go will have to be updated by hand; the compiler will reject incorrect uses. Templates used in conjuction with any of the go/doc types may need manual fixes; the renamed fields will lead to run-time errors.

The hash package

In Go 1, the definition of hash.Hash includes a new method, BlockSize. This new method is used primarily in the cryptographic libraries.

The Sum method of the hash.Hash interface now takes a []byte argument, to which the hash value will be appended. The previous behavior can be recreated by adding a nil argument to the call.

Updating: Existing implementations of hash.Hash will need to add a BlockSize method. Hashes that process the input one byte at a time can implement BlockSize to return 1. Running go fix will update calls to the Sum methods of the various implementations of hash.Hash.

Updating: Since the package's functionality is new, no updating is necessary.

The http package

In Go 1 the http package is refactored, putting some of the utilities into a httputil subdirectory. These pieces are only rarely needed by HTTP clients. The affected items are:

• ClientConn
• DumpRequest
• DumpRequest
• DumpRequestOut
• DumpResponse
• NewChunkedReader
• NewChunkedWriter
• NewClientConn
• NewProxyClientConn
• NewServerConn
• NewSingleHostReverseProxy
• ReverseProxy
• ServerConn

Also, the Request.RawURL field has been removed; it was a historical artifact.

Updating: Running go fix will update the few programs that are affected except for uses of RawURL, which must be fixed by hand.

The image package

The image package has had a number of minor changes, rearrangements and renamings.

Most of the color handling code has been moved into its own package, image/color. For the elements that moved, a symmetry arises; for instance, each pixel of an image.RGBA is a color.RGBA.

The old image/ycbcr package has been folded, with some renamings, into the image and image/color packages.

The old image.ColorImage type is still in the image package but has been renamed image.Uniform, while image.Tiled has been renamed image.Repeated.

This table lists the renamings.

The image package's New functions (NewRGBA, NewRGBA64, etc.) take an image.Rectangle as an argument instead of four integers.

Finally, there are new predefined color.Color variables color.Black, color.White, color.Opaque and color.Transparent.

Updating: Running go fix will update almost all code affected by the change.

The mime package

In Go 1, the FormatMediaType function of the mime package has been simplified to make it consistent with ParseMediaType. It now takes "text/html" rather than "text" and "html".

Updating: What little code is affected will be caught by the compiler and must be updated by hand.

The net package

In Go 1, the various SetTimeout, SetReadTimeout, and SetWriteTimeout methods have been replaced with SetDeadline, SetReadDeadline, and SetWriteDeadline, respectively. Rather than taking a timeout value in nanoseconds that apply to any activity on the connection, the new methods set an absolute deadline (as a time.Time value) after which reads and writes will time out and no longer block.

There are also new functions net.DialTimeout to simplify timing out dialing a network address and net.ListenMulticastUDP to allow multicast UDP to listen concurrently across multiple listeners. The net.ListenMulticastUDP function replaces the old JoinGroup and LeaveGroup methods.

Updating: Code that uses the old methods will fail to compile and must be updated by hand. The semantic change makes it difficult for the fix tool to update automatically.

The os.FileInfo type

Go 1 redefines the os.FileInfo type, changing it from a struct to an interface:

    type FileInfo interface {
        Name() string       // base name of the file
        Size() int64        // length in bytes
        Mode() FileMode     // file mode bits
        ModTime() time.Time // modification time
        IsDir() bool        // abbreviation for Mode().IsDir()
    }

The file mode information has been moved into a subtype called os.FileMode, a simple integer type with IsDir, Perm, and String methods.

The system-specific details of file modes and properties such as (on Unix) i-number have been removed from FileInfo altogether. Instead, each operating system's os package provides an implementation of the FileInfo interface, *os.FileStat, which in turn contains a Sys field that stores the system-specific representation of file metadata. For instance, to discover the i-number of a file on a Unix system, unpack the FileInfo like this:

    fi, err := os.Stat("hello.go")
    if err != nil {
        log.Fatal(err)
    }
    // Make sure it's an implementation known to package os.
    fileStat, ok := fi.(*os.FileStat)
    if !ok {
        log.Fatal("hello.go: not an os File")
    }
    // Now check that it's a Unix file.
    unixStat, ok := fileStat.Sys.(*syscall.Stat_t)
    if !ok {
        log.Fatal("hello.go: not a Unix file")
    }
    fmt.Printf("file i-number: %d\n", unixStat.Ino)

Assuming (which is unwise) that "hello.go" is a Unix file, the i-number expression could be contracted to

    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino

The vast majority of uses of FileInfo need only the methods of the standard interface.

Updating: Running go fix will update code that uses the old equivalent of the current os.FileInfo and os.FileMode API. Code that needs system-specific file details will need to be updated by hand.

The path/filepath package

In Go 1, the Walk function of the path/filepath package has been changed to take a function value of type WalkFunc instead of a Visitor interface value. WalkFunc unifies the handling of both files and directories.

    type WalkFunc func(path string, info *os.FileInfo, err os.Error) os.Error

The WalkFunc function will be called even for files or directories that could not be opened; in such cases the error argument will describe the failure. If a directory's contents are to be skipped, the function should return the value SkipDir.

TODO: add an example?

Updating: The change simplifies most code but has subtle consequences, so affected programs will need to be updated by hand. The compiler will catch code using the old interface.

The runtime package

The runtime package in Go 1 includes a new niladic function, runtime.NumCPU, that returns the number of CPUs available for parallel execution, as reported by the operating system kernel. Its value can inform the setting of GOMAXPROCS.

Updating: No existing code is affected.

The strconv package

In Go 1, the strconv package has been significantly reworked to make it more Go-like and less C-like, although Atoi lives on (it's similar to int(ParseInt(x, 10, 0)), as does Itoa(x) (FormatInt(int64(x), 10)). There are also new variants of some of the functions that append to byte slices rather than return strings, to allow control over allocation.

This table summarizes the renamings; see the package documentation for full details.

Updating: Running go fix will update almost all code affected by the change.
§ Atoi persists but Atoui and Atof32 do not, so they may require a cast that must be added by hand; the go fix tool will warn about it.

The testing package

The testing package has a type, B, passed as an argument to benchmark functions. In Go 1, B has new methods, analogous to those of T, enabling logging and failure reporting.

Updating: Existing code is unaffected, although benchmarks that use println or panic should be updated to use the new methods.

The url package

In Go 1 several fields from the url.URL type were removed or replaced.

The String method now predictably rebuilds an encoded URL string using all of URL's fields as necessary. The resulting string will also no longer have passwords escaped.

The Raw field has been removed. In most cases the String method may be used in its place.

The old RawUserinfo field is replaced by the User field, of type *net.Userinfo. Values of this type may be created using the new net.User and net.UserPassword functions. The EscapeUserinfo and UnescapeUserinfo functions are also gone.

The RawAuthority field has been removed. The same information is available in the Host and User fields.

The RawPath field and the EncodedPath method have been removed. The path information in rooted URLs (with a slash following the schema) is now available only in decoded form in the Path field. Occasionally, the encoded data may be required to obtain information that was lost in the decoding process. These cases must be handled by accessing the data the URL was built from.

URLs with non-rooted paths, such as "mailto:dev@golang.org?subject=Hi", are also handled differently. The OpaquePath boolean field has been removed and a new Opaque string field introduced to hold the encoded path for such URLs. In Go 1, the cited URL parses as:

    URL{
        Scheme: "mailto",
        Opaque: "dev@golang.org",
        RawQuery: "subject=Hi",
    }

A new RequestURI method was added to URL.

Updating: Code that uses the old fields will fail to compile and must be updated by hand. The semantic changes make it difficult for the fix tool to update automatically.

The xml package

In Go 1, the xml package has been brought closer in design to the other marshaling packages such as encoding/gob.

The old Parser type is renamed Decoder and has a new Decode method. An Encoder type was also introduced.

The functions Marshal and Unmarshal work with []byte values now. To work with streams, use the new Encoder and Decoder types.

When marshaling or unmarshaling values, the format of supported flags in field tags has changed to be closer to the json package (`xml:"name,flag"`). The matching done between field tags, field names, and the XML attribute and element names is now case-sensitive. The XMLName field tag, if present, must also match the name of the XML element being marshaled.

Updating: Running go fix will update most uses of the package except for some calls to Unmarshal. Special care must be taken with field tags, since the fix tool will not update them and if not fixed by hand they will misbehave silently in some cases. For example, the old "attr" is now written ",attr" while plain "attr" remains valid but with a different meaning.

The go command

Packaged releases