go1.tmpl 69.3 KB
Newer Older
1 2 3
<!--{
	"Title": "Go 1 Release Notes"
}-->
4
{{donotedit}}
5 6 7 8

<h2 id="introduction">Introduction to Go 1</h2>

<p>
Rob Pike's avatar
Rob Pike committed
9 10 11
Go version 1, Go 1 for short, defines a language and a set of core libraries
that provide a stable foundation for creating reliable products, projects, and
publications.
12 13 14
</p>

<p>
Rob Pike's avatar
Rob Pike committed
15 16 17 18 19 20
The driving motivation for Go 1 is stability for its users. People should be able to
write Go programs and expect that they will continue to compile and run without
change, on a time scale of years, including in production environments such as
Google App Engine. Similarly, people should be able to write books about Go, be
able to say which version of Go the book is describing, and have that version
number still be meaningful much later.
21 22 23
</p>

<p>
Rob Pike's avatar
Rob Pike committed
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
Code that compiles in Go 1 should, with few exceptions, continue to compile and
run throughout the lifetime of that version, even as we issue updates and bug
fixes such as Go version 1.1, 1.2, and so on. Other than critical fixes, changes
made to the language and library for subsequent releases of Go 1 may
add functionality but will not break existing Go 1 programs.
<a href="go1compat.html">The Go 1 compatibility document</a>
explains the compatibility guidelines in more detail.
</p>

<p>
Go 1 is a representation of Go as it used today, not a wholesale rethinking of
the language. We avoided designing new features and instead focused on cleaning
up problems and inconsistencies and improving portability. There are a number
changes to the Go language and packages that we had considered for some time and
prototyped but not released primarily because they are significant and
backwards-incompatible. Go 1 was an opportunity to get them out, which is
helpful for the long term, but also means that Go 1 introduces incompatibilities
for old programs. Fortunately, the <code>go</code> <code>fix</code> tool can
automate much of the work needed to bring programs up to the Go 1 standard.
</p>

<p>
This document outlines the major changes in Go 1 that will affect programmers
updating existing code; its reference point is the prior release, r60 (tagged as
r60.3). It also explains how to update code from r60 to run under Go 1.
49
</p>
50 51 52 53 54

<h2 id="language">Changes to the language</h2>

<h3 id="append">Append</h3>

55
<p>
56 57 58 59 60
The <code>append</code> predeclared variadic function makes it easy to grow a slice
by adding elements to the end.
A common use is to add bytes to the end of a byte slice when generating output.
However, <code>append</code> did not provide a way to append a string to a <code>[]byte</code>,
which is another common case.
61 62 63 64 65 66 67
</p>

{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}

<p>
By analogy with the similar property of <code>copy</code>, Go 1
permits a string to be appended (byte-wise) directly to a byte
68 69
slice, reducing the friction between strings and byte slices.
The conversion is no longer necessary:
70 71 72 73 74 75 76 77 78
</p>

{{code "progs/go1.go" `/append.*world/`}}

<p>
<em>Updating</em>:
This is a new feature, so existing code needs no changes.
</p>

79 80
<h3 id="close">Close</h3>

81
<p>
82 83 84 85 86 87 88 89 90 91 92 93 94 95
The <code>close</code> predeclared function provides a mechanism
for a sender to signal that no more values will be sent.
It is important to the implementation of <code>for</code> <code>range</code>
loops over channels and is helpful in other situations.
Partly by design and partly because of race conditions that can occur otherwise,
it is intended for use only by the goroutine sending on the channel,
not by the goroutine receiving data.
However, before Go 1 there was no compile-time checking that <code>close</code>
was being used correctly.
</p>

<p>
To close this gap, at least in part, Go 1 disallows <code>close</code> on receive-only channels.
Attempting to close such a channel is a compile-time error.
96 97 98 99
</p>

<pre>
    var c chan int
Robert Hencke's avatar
Robert Hencke committed
100 101
    var csend chan&lt;- int = c
    var crecv &lt;-chan int = c
102 103 104 105 106 107 108 109 110 111 112 113
    close(c)     // legal
    close(csend) // legal
    close(crecv) // illegal
</pre>

<p>
<em>Updating</em>:
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.
</p>

114
<h3 id="literals">Composite literals</h3>
115

116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
<p>
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.
</p>

{{code "progs/go1.go" `/type Date struct/` `/STOP/`}}

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


132
<h3 id="init">Goroutines during init</h3>
133

134
<p>
135 136 137 138 139 140 141 142 143 144 145 146
The old language defined that <code>go</code> statements executed during initialization created goroutines but that they did not begin to run until initialization of the entire program was complete.
This introduced clumsiness in many places and, in effect, limited the utility
of the <code>init</code> construct:
if it was possible for another package to use the library during initialization, the library
was forced to avoid goroutines.
This design was done for reasons of simplicity and safety but,
as our confidence in the language grew, it seemed unnecessary.
Running goroutines during initialization is no more complex or unsafe than running them during normal execution.
</p>

<p>
In Go 1, code that uses goroutines can be called from
147 148 149 150 151 152 153 154 155 156 157 158 159
<code>init</code> routines and global initialization expressions
without introducing a deadlock.
</p>

{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}}

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

160 161
<h3 id="rune">The rune type</h3>

162
<p>
163 164 165 166 167 168 169 170 171 172
The language spec allows the <code>int</code> type to be 32 or 64 bits wide, but current implementations set <code>int</code> to 32 bits even on 64-bit platforms.
It would be preferable to have <code>int</code> be 64 bits on 64-bit platforms.
(There are important consequences for indexing large slices.)
However, this change would waste space when processing Unicode characters with
the old language because the <code>int</code> type was also used to hold Unicode code points: each code point would waste an extra 32 bits of storage if <code>int</code> grew from 32 bits to 64.
</p>

<p>
To make changing to 64-bit <code>int</code> feasible,
Go 1 introduces a new basic type, <code>rune</code>, to represent
173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
individual Unicode code points.
It is an alias for <code>int32</code>, analogous to <code>byte</code>
as an alias for <code>uint8</code>.
</p>

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

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

{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}

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

<h3 id="error">The error type</h3>

<p>
Go 1 introduces a new built-in type, <code>error</code>, which has the following definition:
</p>

<pre>
    type error interface {
        Error() string
    }
</pre>

<p>
Since the consequences of this type are all in the package library,
216
it is discussed <a href="#errors">below</a>.
217 218
</p>

219
<h3 id="delete">Deleting from maps</h3>
Rob Pike's avatar
Rob Pike committed
220 221

<p>
222
In the old language, to delete the entry with key <code>k</code> from map <code>m</code>, one wrote the statement,
Rob Pike's avatar
Rob Pike committed
223 224 225
</p>

<pre>
226
    m[k] = value, false
Rob Pike's avatar
Rob Pike committed
227 228
</pre>

229 230 231 232 233 234 235
<p>
This syntax was a peculiar special case, the only two-to-one assignment.
It required passing a value (usually ignored) that is evaluated but discarded,
plus a boolean that was nearly always the constant <code>false</code>.
It did the job but was odd and a point of contention.
</p>

Rob Pike's avatar
Rob Pike committed
236
<p>
237
In Go 1, that syntax has gone; instead there is a new built-in
Rob Pike's avatar
Rob Pike committed
238 239 240 241 242 243 244 245 246 247 248 249
function, <code>delete</code>.  The call
</p>

{{code "progs/go1.go" `/delete\(m, k\)/`}}

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

<p>
<em>Updating</em>:
250
Running <code>go</code> <code>fix</code> will convert expressions of the form <code>m[k] = value,
Rob Pike's avatar
Rob Pike committed
251 252
false</code> into <code>delete(m, k)</code> when it is clear that
the ignored value can be safely discarded from the program and
253 254
<code>false</code> refers to the predefined boolean constant.
The fix tool
Rob Pike's avatar
Rob Pike committed
255 256 257
will flag other uses of the syntax for inspection by the programmer.
</p>

258 259
<h3 id="iteration">Iterating in maps</h3>

260 261 262 263 264 265 266
<p>
The old language specification did not define the order of iteration for maps,
and in practice it differed across hardware platforms.
This caused tests that iterated over maps to be fragile and non-portable, with the
unpleasant property that a test might always pass on one machine but break on another.
</p>

267 268 269 270 271 272 273 274
<p>
In Go 1, the order in which elements are visited when iterating
over a map using a <code>for</code> <code>range</code> 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.
</p>

275 276 277 278 279
<p>
This change means that code that depends on iteration order is very likely to break early and be fixed long before it becomes a problem.
Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a map.
</p>

280 281 282 283 284 285 286 287 288 289 290 291
{{code "progs/go1.go" `/Sunday/` `/^	}/`}}

<p>
<em>Updating</em>:
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.
</p>
292 293 294

<h3 id="multiple_assignment">Multiple assignment</h3>

295
<p>
296
The language specification has long guaranteed that in assignments
297 298 299 300 301 302 303
the right-hand-side expressions are all evaluated before any left-hand-side expressions are assigned.
To guarantee predictable behavior,
Go 1 refines the specification further.
</p>

<p>
If the left-hand side of the assignment
304 305 306 307 308 309 310 311 312 313 314 315 316
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.
</p>

<p>
These examples illustrate the behavior.
</p>

{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}

317
<p>
318 319 320 321 322 323
<em>Updating</em>:
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.
</p>

324 325
<h3 id="shadowing">Returns and shadowed variables</h3>

326
<p>
327 328 329 330 331
A common mistake is to use <code>return</code> (without arguments) after an assignment to a variable that has the same name as a result variable but is not the same variable.
This situation is called <em>shadowing</em>: the result variable has been shadowed by another variable with the same name declared in an inner scope.
</p>

<p>
332 333 334 335 336 337 338 339 340 341 342 343
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.)
</p>

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

<pre>
    func Bug() (i, j, k int) {
Robert Hencke's avatar
Robert Hencke committed
344 345
        for i = 0; i &lt; 5; i++ {
            for j := 0; j &lt; 5; j++ { // Redeclares j.
346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363
                k += i*j
                if k > 100 {
                    return // Rejected: j is shadowed here.
                }
            }
        }
        return // OK: j is not shadowed here.
    }
</pre>

<p>
<em>Updating</em>:
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.
</p>

<h3 id="unexported">Copying structs with unexported fields</h3>

364
<p>
365 366 367 368 369 370 371 372 373 374 375
The old language did not allow a package to make a copy of a struct value containing unexported fields belonging to a different package.
There was, however, a required exception for a method receiver;
also, the implementations of <code>copy</code> and <code>append</code> have never honored the restriction.
</p>

<p>
Go 1 will allow packages to copy struct values containing unexported fields from other packages.
Besides resolving the inconsistency,
this change admits a new kind of API: a package can return an opaque value without resorting to a pointer or interface.
The new implementations of <code>time.Time</code> and
<code>reflect.Value</code> are examples of types taking advantage of this new property.
376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419
</p>

<p>
As an example, if package <code>p</code> includes the definitions,
</p>

<pre>
    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)
    }
</pre>

<p>
a package that imports <code>p</code> can assign and copy values of type
<code>p.Struct</code> 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
</p>

<pre>
    import "p"

    myStruct := p.NewStruct(23)
    copyOfMyStruct := myStruct
    fmt.Println(myStruct, copyOfMyStruct)
</pre>

<p>
will show that the secret field of the struct has been copied to the new value.
</p>

<p>
<em>Updating</em>:
This is a new feature, so existing code needs no changes.
</p>

420
<h3 id="equality">Equality</h3>
421

422
<p>
423 424 425 426 427 428 429 430
Before Go 1, the language did not define equality on struct and array values.
This meant,
among other things, that structs and arrays could not be used as map keys.
On the other hand, Go did define equality on function and map values.
Function equality was problematic in the presence of closures
(when are two closures equal?)
while map equality compared pointers, not the maps' content, which was usually
not what the user would want.
431 432 433
</p>

<p>
434 435 436 437 438 439
Go 1 addressed these issues.
First, structs and arrays can be compared for equality and inequality
(<code>==</code> and <code>!=</code>),
and therefore be used as map keys,
provided they are composed from elements for which equality is also defined,
using element-wise comparison.
440 441 442 443
</p>

{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}

444 445 446
<p>
Second, Go 1 removes the definition of equality for function values,
except for comparison with <code>nil</code>.
447
Finally, map equality is gone too, also except for comparison with <code>nil</code>.
448 449
</p>

450 451 452 453 454 455 456 457 458
<p>
Note that equality is still undefined for slices, for which the
calculation is in general infeasible.  Also note that the ordered
comparison operators (<code>&lt;</code> <code>&lt;=</code>
<code>&gt;</code> <code>&gt;=</code>) are still undefined for
structs and arrays.

<p>
<em>Updating</em>:
459
Struct and array equality is a new feature, so existing code needs no changes.
460 461 462 463 464 465
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.
</p>

466 467
<h2 id="packages">The package hierarchy</h2>

468 469 470 471 472 473
<p>
Go 1 addresses many deficiencies in the old standard library and
cleans up a number of packages, making them more internally consistent
and portable.
</p>

474 475 476 477 478
<p>
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.
</p>
479

480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498
<h3 id="hierarchy">The package hierarchy</h3>

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

<table class="codetable" frame="border" summary="Moved packages">
<colgroup align="left" width="60%"></colgroup>
<colgroup align="left" width="40%"></colgroup>
<tr>
<th align="left">Old path</th>
<th align="left">New path</th>
</tr>
Rob Pike's avatar
Rob Pike committed
499 500 501
<tr>
<td colspan="2"><hr></td>
</tr>
502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555
<tr><td>asn1</td> <td>encoding/asn1</td></tr>
<tr><td>csv</td> <td>encoding/csv</td></tr>
<tr><td>gob</td> <td>encoding/gob</td></tr>
<tr><td>json</td> <td>encoding/json</td></tr>
<tr><td>xml</td> <td>encoding/xml</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>exp/template/html</td> <td>html/template</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>big</td> <td>math/big</td></tr>
<tr><td>cmath</td> <td>math/cmplx</td></tr>
<tr><td>rand</td> <td>math/rand</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>http</td> <td>net/http</td></tr>
<tr><td>http/cgi</td> <td>net/http/cgi</td></tr>
<tr><td>http/fcgi</td> <td>net/http/fcgi</td></tr>
<tr><td>http/httptest</td> <td>net/http/httptest</td></tr>
<tr><td>http/pprof</td> <td>net/http/pprof</td></tr>
<tr><td>mail</td> <td>net/mail</td></tr>
<tr><td>rpc</td> <td>net/rpc</td></tr>
<tr><td>rpc/jsonrpc</td> <td>net/rpc/jsonrpc</td></tr>
<tr><td>smtp</td> <td>net/smtp</td></tr>
<tr><td>url</td> <td>net/url</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>exec</td> <td>os/exec</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>scanner</td> <td>text/scanner</td></tr>
<tr><td>tabwriter</td> <td>text/tabwriter</td></tr>
<tr><td>template</td> <td>text/template</td></tr>
<tr><td>template/parse</td> <td>text/template/parse</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>utf8</td> <td>unicode/utf8</td></tr>
<tr><td>utf16</td> <td>unicode/utf16</td></tr>
</table>

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

<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
556
Running <code>go</code> <code>fix</code> will update all imports and package renames for packages that
557 558 559 560
remain inside the standard repository.  Programs that import packages
that are no longer in the standard repository will need to be edited
by hand.
</p>
561

562 563 564 565 566 567 568 569 570 571 572 573 574 575 576
<h3 id="exp">The package tree exp</h3>

<p>
Because they are not standardized, the packages under the <code>exp</code> directory will not be available in the
standard Go 1 release distributions, although they will be available in source code form
in <a href="http://code.google.com/p/go/">the repository</a> for
developers who wish to use them.
</p>

<p>
Several packages have moved under <code>exp</code> at the time of Go 1's release:
</p>

<ul>
<li><code>ebnf</code></li>
Shenghou Ma's avatar
Shenghou Ma committed
577
<li><code>html</code><sup>&#8224;</sup></li>
578 579 580
<li><code>go/types</code></li>
</ul>

581
<p>
Shenghou Ma's avatar
Shenghou Ma committed
582
(<sup>&#8224;</sup>The <code>EscapeString</code> and <code>UnescapeString</code> types remain
583 584 585
in package <code>html</code>.)
</p>

586
<p>
Rob Pike's avatar
Rob Pike committed
587
All these packages are available under the same names, with the prefix <code>exp/</code>: <code>exp/ebnf</code> etc.
588 589 590
</p>

<p>
Rob Pike's avatar
Rob Pike committed
591
Also, the <code>utf8.String</code> type has been moved to its own package, <code>exp/utf8string</code>.
592 593 594
</p>

<p>
Rob Pike's avatar
Rob Pike committed
595
Finally, the <code>gotype</code> command now resides in <code>exp/gotype</code>, while
596 597
<code>ebnflint</code> is now in <code>exp/ebnflint</code>.
If they are installed, they now reside in <code>$GOROOT/bin/tool</code>.
598 599 600 601 602 603
</p>

<p>
<em>Updating</em>:
Code that uses packages in <code>exp</code> will need to be updated by hand,
or else compiled from an installation that has <code>exp</code> available.
Rob Pike's avatar
Rob Pike committed
604
The <code>go</code> <code>fix</code> tool or the compiler will complain about such uses.
605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628
</p>

<h3 id="old">The package tree old</h3>

<p>
Because they are deprecated, the packages under the <code>old</code> 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.
</p>

<p>
The packages in their new locations are:
</p>

<ul>
<li><code>old/netchan</code></li>
<li><code>old/regexp</code></li>
<li><code>old/template</code></li>
</ul>

<p>
<em>Updating</em>:
Code that uses packages now in <code>old</code> will need to be updated by hand,
or else compiled from an installation that has <code>old</code> available.
Rob Pike's avatar
Rob Pike committed
629
The <code>go</code> <code>fix</code> tool will warn about such uses.
630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659
</p>

<h3 id="deleted">Deleted packages</h3>

<p>
Go 1 deletes several packages outright:
</p>

<ul>
<li><code>container/vector</code></li>
<li><code>exp/datafmt</code></li>
<li><code>go/typechecker</code></li>
<li><code>try</code></li>
</ul>

<p>
and also the command <code>gotry</code>.
</p>

<p>
<em>Updating</em>:
Code that uses <code>container/vector</code> should be updated to use
slices directly.  See
<a href="http://code.google.com/p/go-wiki/wiki/SliceTricks">the Go
Language Community Wiki</a> for some suggestions.
Code that uses the other packages (there should be almost zero) will need to be rethought.
</p>

<h3 id="subrepo">Packages moving to subrepositories</h3>

Rob Pike's avatar
Rob Pike committed
660
<p>
661
Go 1 has moved a number of packages into other repositories, usually sub-repositories of
Rob Pike's avatar
Rob Pike committed
662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692
<a href="http://code.google.com/p/go/">the main Go repository</a>.
This table lists the old and new import paths:

<table class="codetable" frame="border" summary="Sub-repositories">
<colgroup align="left" width="40%"></colgroup>
<colgroup align="left" width="60%"></colgroup>
<tr>
<th align="left">Old</th>
<th align="left">New</th>
</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>crypto/bcrypt</td> <td>code.google.com/p/go.crypto/bcrypt</tr>
<tr><td>crypto/blowfish</td> <td>code.google.com/p/go.crypto/blowfish</tr>
<tr><td>crypto/cast5</td> <td>code.google.com/p/go.crypto/cast5</tr>
<tr><td>crypto/md4</td> <td>code.google.com/p/go.crypto/md4</tr>
<tr><td>crypto/ocsp</td> <td>code.google.com/p/go.crypto/ocsp</tr>
<tr><td>crypto/openpgp</td> <td>code.google.com/p/go.crypto/openpgp</tr>
<tr><td>crypto/openpgp/armor</td> <td>code.google.com/p/go.crypto/openpgp/armor</tr>
<tr><td>crypto/openpgp/elgamal</td> <td>code.google.com/p/go.crypto/openpgp/elgamal</tr>
<tr><td>crypto/openpgp/errors</td> <td>code.google.com/p/go.crypto/openpgp/errors</tr>
<tr><td>crypto/openpgp/packet</td> <td>code.google.com/p/go.crypto/openpgp/packet</tr>
<tr><td>crypto/openpgp/s2k</td> <td>code.google.com/p/go.crypto/openpgp/s2k</tr>
<tr><td>crypto/ripemd160</td> <td>code.google.com/p/go.crypto/ripemd160</tr>
<tr><td>crypto/twofish</td> <td>code.google.com/p/go.crypto/twofish</tr>
<tr><td>crypto/xtea</td> <td>code.google.com/p/go.crypto/xtea</tr>
<tr><td>exp/ssh</td> <td>code.google.com/p/go.crypto/ssh</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
693 694 695 696 697
<tr><td>image/bmp</td> <td>code.google.com/p/go.image/bmp</tr>
<tr><td>image/tiff</td> <td>code.google.com/p/go.image/tiff</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
Rob Pike's avatar
Rob Pike committed
698 699 700 701 702 703 704 705
<tr><td>net/dict</td> <td>code.google.com/p/go.net/dict</tr>
<tr><td>net/websocket</td> <td>code.google.com/p/go.net/websocket</tr>
<tr><td>exp/spdy</td> <td>code.google.com/p/go.net/spdy</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>encoding/git85</td> <td>code.google.com/p/go.codereview/git85</tr>
<tr><td>patch</td> <td>code.google.com/p/go.codereview/patch</tr>
706 707 708 709
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>exp/wingui</td> <td>code.google.com/p/gowingui</tr>
Rob Pike's avatar
Rob Pike committed
710 711 712 713
</table>

<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
714
Running <code>go</code> <code>fix</code> will update imports of these packages to use the new import paths.
Rob Pike's avatar
Rob Pike committed
715 716 717
Installations that depend on these packages will need to install them using
a <code>go install</code> command.
</p>
718 719 720 721 722 723 724 725

<h2 id="major">Major changes to the library</h2>

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

Rob Pike's avatar
Rob Pike committed
726
<h3 id="errors">The error type and errors package</h3>
727

728
<p>
729 730 731 732 733 734 735 736 737 738 739 740 741
The placement of <code>os.Error</code> in package <code>os</code> is mostly historical: errors first came up when implementing package <code>os</code>, and they seemed system-related at the time.
Since then it has become clear that errors are more fundamental than the operating system.  For example, it would be nice to use <code>Errors</code> in packages that <code>os</code> depends on, like <code>syscall</code>.
Also, having <code>Error</code> in <code>os</code> introduces many dependencies on <code>os</code> that would otherwise not exist.
</p>

<p>
Go 1 solves these problems by introducing a built-in <code>error</code> interface type and a separate <code>errors</code> package (analogous to <code>bytes</code> and <code>strings</code>) that contains utility functions.
It replaces <code>os.NewError</code> with
<a href="/pkg/errors/#New"><code>errors.New</code></a>,
giving errors a more central place in the environment.
</p>

<p>
742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779
So the widely-used <code>String</code> method does not cause accidental satisfaction
of the <code>error</code> interface, the <code>error</code> interface uses instead
the name <code>Error</code> for that method:
</p>

<pre>
    type error interface {
        Error() string
    }
</pre>

<p>
The <code>fmt</code> library automatically invokes <code>Error</code>, as it already
does for <code>String</code>, for easy printing of error values.
</p>

{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}

<p>
All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
</p>

<p>
A new package, <a href="/pkg/errors/"><code>errors</code></a>, contains the function
</p>

<pre>
func New(text string) error
</pre>

<p>
to turn a string into an error. It replaces the old <code>os.NewError</code>.
</p>

{{code "progs/go1.go" `/ErrSyntax/`}}
		
<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
780
Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
781 782 783 784
Code that defines error types with a <code>String</code> method will need to be updated
by hand to rename the methods to <code>Error</code>.
</p>

785
<h3 id="errno">System call errors</h3>
786

787 788 789 790 791 792 793 794 795
<p>
The old <code>syscall</code> package, which predated <code>os.Error</code>
(and just about everything else),
returned errors as <code>int</code> values.
In turn, the <code>os</code> package forwarded many of these errors, such
as <code>EINVAL</code>, but using a different set of errors on each platform.
This behavior was unpleasant and unportable.
</p>

Rob Pike's avatar
Rob Pike committed
796 797
<p>
In Go 1, the
798
<a href="/pkg/syscall/"><code>syscall</code></a>
799
package instead returns an <code>error</code> for system call errors.
800
On Unix, the implementation is done by a
801
<a href="/pkg/syscall/#Errno"><code>syscall.Errno</code></a> type
Rob Pike's avatar
Rob Pike committed
802 803 804
that satisfies <code>error</code> and replaces the old <code>os.Errno</code>.
</p>

805 806 807 808
<p>
The changes affecting <code>os.EINVAL</code> and relatives are
described <a href="#os">elsewhere</a>.

Rob Pike's avatar
Rob Pike committed
809 810
<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
811
Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
Rob Pike's avatar
Rob Pike committed
812 813 814 815
Regardless, most code should use the <code>os</code> package
rather than <code>syscall</code> and so will be unaffected.
</p>

816 817
<h3 id="time">Time</h3>

Rob Pike's avatar
Rob Pike committed
818
<p>
819 820 821 822 823 824 825 826
Time is always a challenge to support well in a programming language.
The old Go <code>time</code> package had <code>int64</code> units, no
real type safety,
and no distinction between absolute times and durations.
</p>

<p>
One of the most sweeping changes in the Go 1 library is therefore a
827
complete redesign of the
Rob Pike's avatar
Rob Pike committed
828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875
<a href="/pkg/time/"><code>time</code></a> package.
Instead of an integer number of nanoseconds as an <code>int64</code>,
and a separate <code>*time.Time</code> type to deal with human
units such as hours and years,
there are now two fundamental types:
<a href="/pkg/time/#Time"><code>time.Time</code></a>
(a value, so the <code>*</code> is gone), which represents a moment in time;
and <a href="/pkg/time/#Duration"><code>time.Duration</code></a>,
which represents an interval.
Both have nanosecond resolution.
A <code>Time</code> can represent any time into the ancient
past and remote future, while a <code>Duration</code> 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 <code>time.Second</code>.
</p>

<p>
Among the new methods are things like
<a href="/pkg/time/#Time.Add"><code>Time.Add</code></a>,
which adds a <code>Duration</code> to a <code>Time</code>, and
<a href="/pkg/time/#Time.Sub"><code>Time.Sub</code></a>,
which subtracts two <code>Times</code> to yield a <code>Duration</code>.
</p>

<p>
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:
<a href="/pkg/time/#Unix"><code>time.Unix</code></a>
and the <a href="/pkg/time/#Time.Unix"><code>Unix</code></a>
and <a href="/pkg/time/#Time.UnixNano"><code>UnixNano</code></a> methods
of the <code>Time</code> type.
In particular,
<a href="/pkg/time/#Now"><code>time.Now</code></a>
returns a <code>time.Time</code> value rather than, in the old
API, an integer nanosecond count since the Unix epoch.
</p>

{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}

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

<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
876
The <code>go</code> <code>fix</code> tool will update many uses of the old <code>time</code> package to use the new
Rob Pike's avatar
Rob Pike committed
877 878 879
types and methods, although it does not replace values such as <code>1e9</code>
representing nanoseconds per second.
Also, because of type changes in some of the values that arise,
880
some of the expressions rewritten by the fix tool may require
Rob Pike's avatar
Rob Pike committed
881 882 883 884 885
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.
</p>

886 887 888 889 890
<h2 id="minor">Minor changes to the library</h2>

<p>
This section describes smaller changes, such as those to less commonly
used packages or that affect
Rob Pike's avatar
Rob Pike committed
891
few programs beyond the need to run <code>go</code> <code>fix</code>.
892
This category includes packages that are new in Go 1.
893 894
Collectively they improve portability, regularize behavior, and
make the interfaces more modern and Go-like.
895 896
</p>

897 898 899 900 901 902 903 904
<h3 id="archive_zip">The archive/zip package</h3>

<p>
In Go 1, <a href="/pkg/archive/zip/#Writer"><code>*zip.Writer</code></a> no
longer has a <code>Write</code> method. Its presence was a mistake.
</p>

<p>
905 906
<em>Updating</em>:
What little code is affected will be caught by the compiler and must be updated by hand.
907 908
</p>

Adam Langley's avatar
Adam Langley committed
909 910 911 912 913 914 915 916 917 918 919 920
<h3 id="bufio">The bufio package</h3>

<p>
In Go 1, <a href="/pkg/bufio/#NewReaderSize"><code>bufio.NewReaderSize</code></a>
and
<a href="/pkg/bufio/#NewWriterSize"><code>bufio.NewWriterSize</code></a>
functions no longer return an error for invalid sizes.
If the argument size is too small or invalid, it is adjusted.
</p>

<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
921
Running <code>go</code> <code>fix</code> will update calls that assign the error to _.
922
Calls that aren't fixed will be caught by the compiler and must be updated by hand.
Adam Langley's avatar
Adam Langley committed
923 924
</p>

925
<h3 id="compress">The compress/flate, compress/gzip and compress/zlib packages</h3>
Adam Langley's avatar
Adam Langley committed
926 927 928 929 930 931 932 933 934 935 936 937 938 939 940

<p>
In Go 1, the <code>NewWriterXxx</code> functions in
<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>
all return <code>(*Writer, error)</code> if they take a compression level,
and <code>*Writer</code> otherwise. Package <code>gzip</code>'s
<code>Compressor</code> and <code>Decompressor</code> types have been renamed
to <code>Writer</code> and <code>Reader</code>. Package <code>flate</code>'s
<code>WrongValueError</code> type has been removed.
</p>

<p>
<em>Updating</em>
Rob Pike's avatar
Rob Pike committed
941
Running <code>go</code> <code>fix</code> will update old names and calls that assign the error to _.
942
Calls that aren't fixed will be caught by the compiler and must be updated by hand.
Adam Langley's avatar
Adam Langley committed
943 944
</p>

945
<h3 id="crypto_aes_des">The crypto/aes and crypto/des packages</h3>
946 947

<p>
948 949
In Go 1, the <code>Reset</code> method has been removed. Go does not guarantee
that memory is not copied and therefore this method was misleading.
950 951 952
</p>

<p>
953 954 955
The cipher-specific types <code>*aes.Cipher</code>, <code>*des.Cipher</code>,
and <code>*des.TripleDESCipher</code> have been removed in favor of
<code>cipher.Block</code>.
956 957 958 959
</p>

<p>
<em>Updating</em>:
960 961
Remove the calls to Reset. Replace uses of the specific cipher types with
cipher.Block.
962 963
</p>

964
<h3 id="crypto_elliptic">The crypto/elliptic package</h3>
965 966 967 968 969 970 971 972 973 974 975 976 977 978

<p>
In Go 1, <a href="/pkg/crypto/elliptic/#Curve"><code>elliptic.Curve</code></a>
has been made an interface to permit alternative implementations. The curve
parameters have been moved to the
<a href="/pkg/crypto/elliptic/#CurveParams"><code>elliptic.CurveParams</code></a>
structure.
</p>

<p>
<em>Updating</em>:
Existing users of <code>*elliptic.Curve</code> will need to change to
simply <code>elliptic.Curve</code>. Calls to <code>Marshal</code>,
<code>Unmarshal</code> and <code>GenerateKey</code> are now functions
979
in <code>crypto/elliptic</code> that take an <code>elliptic.Curve</code>
980 981 982
as their first argument.
</p>

983
<h3 id="crypto_hmac">The crypto/hmac package</h3>
984 985 986 987 988 989 990 991 992

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

<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
993
Running <code>go</code> <code>fix</code> will perform the needed changes.
994 995
</p>

996
<h3 id="crypto_x509">The crypto/x509 package</h3>
997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013

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

<p>
<em>Updating</em>:
No changes will be needed.
</p>

1014
<h3 id="encoding_binary">The encoding/binary package</h3>
Adam Langley's avatar
Adam Langley committed
1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039

<p>
In Go 1, the <code>binary.TotalSize</code> function has been replaced by
<a href="/pkg/encoding/binary/#Size"><code>Size</code></a>,
which takes an <code>interface{}</code> argument rather than
a <code>reflect.Value</code>.
</p>

<p>
<em>Updating</em>:
What little code is affected will be caught by the compiler and must be updated by hand.
</p>

<h3 id="encoding_xml">The encoding/xml package</h3>

<p>
In Go 1, the <a href="/pkg/encoding/xml/"><code>xml</code></a> package
has been brought closer in design to the other marshaling packages such
as <a href="/pkg/encoding/gob/"><code>encoding/gob</code></a>.
</p>

<p>
The old <code>Parser</code> type is renamed
<a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> and has a new
<a href="/pkg/encoding/xml/#Decoder.Decode"><code>Decode</code></a> method. An
1040
<a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a> type was also introduced.
Adam Langley's avatar
Adam Langley committed
1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062
</p>

<p>
The functions <a href="/pkg/encoding/xml/#Marshal"><code>Marshal</code></a>
and <a href="/pkg/encoding/xml/#Unmarshal"><code>Unmarshal</code></a>
work with <code>[]byte</code> values now. To work with streams,
use the new <a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>
and <a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> types.
</p>

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

<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
1063
Running <code>go</code> <code>fix</code> will update most uses of the package except for some calls to
Adam Langley's avatar
Adam Langley committed
1064 1065 1066 1067 1068 1069 1070
<code>Unmarshal</code>. 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
<code>"attr"</code> is now written <code>",attr"</code> while plain
<code>"attr"</code> remains valid but with a different meaning.
</p>

David Symonds's avatar
David Symonds committed
1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084
<h3 id="expvar">The expvar package</h3>

<p>
In Go 1, the <code>RemoveAll</code> function has been removed.
The <code>Iter</code> function and Iter method on <code>*Map</code> have
been replaced by
<a href="/pkg/expvar/#Do"><code>Do</code></a>
and
<a href="/pkg/expvar/#Map.Do"><code>(*Map).Do</code></a>.
</p>

<p>
<em>Updating</em>:
Most code using <code>expvar</code> will not need changing. The rare code that used
1085
<code>Iter</code> can be updated to pass a closure to <code>Do</code> to achieve the same effect.
David Symonds's avatar
David Symonds committed
1086 1087
</p>

Rob Pike's avatar
Rob Pike committed
1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112
<h3 id="flag">The flag package</h3>

<p>
In Go 1, the interface <a href="/pkg/flag/#Value"><code>flag.Value</code></a> has changed slightly.
The <code>Set</code> method now returns an <code>error</code> instead of
a <code>bool</code> to indicate success or failure.
</p>

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

{{code "progs/go1.go" `/timeout/`}}

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


1113 1114 1115 1116 1117 1118
<h3 id="go">The go/* packages</h3>

<p>
Several packages under <code>go</code> have slightly revised APIs.
</p>

Adam Langley's avatar
Adam Langley committed
1119 1120 1121 1122 1123 1124 1125 1126 1127
<p>
A concrete <code>Mode</code> type was introduced for configuration mode flags
in the packages
<a href="/pkg/go/scanner/"><code>go/scanner</code></a>,
<a href="/pkg/go/parser/"><code>go/parser</code></a>,
<a href="/pkg/go/printer/"><code>go/printer</code></a>, and
<a href="/pkg/go/doc/"><code>go/doc</code></a>.
</p>

1128 1129 1130 1131 1132 1133 1134 1135
<p>
The modes <code>AllowIllegalChars</code> and <code>InsertSemis</code> have been removed
from the <a href="/pkg/go/scanner/"><code>go/scanner</code></a> package. They were mostly
useful for scanning text other then Go source files. Instead, the
<a href="/pkg/text/scanner/"><code>text/scanner</code></a> package should be used
for that purpose.
</p>

Adam Langley's avatar
Adam Langley committed
1136 1137 1138 1139 1140 1141 1142 1143 1144 1145
<p>
The <a href="/pkg/go/scanner/#ErrorHandler"><code>ErrorHandler</code></a> provided
to the scanner's <a href="/pkg/go/scanner/#Scanner.Init"><code>Init</code></a> method is
now simply a function rather than an interface. The <code>ErrorVector</code> type has
been removed in favor of the (existing) <a href="/pkg/go/scanner/#ErrorList"><code>ErrorList</code></a>
type, and the <code>ErrorVector</code> methods have been migrated. Instead of embedding
an <code>ErrorVector</code> in a client of the scanner, now a client should maintain
an <code>ErrorList</code>.
</p>

1146 1147 1148
<p>
The set of parse functions provided by the <a href="/pkg/go/parser/"><code>go/parser</code></a>
package has been reduced to the primary parse function
Gustavo Niemeyer's avatar
Gustavo Niemeyer committed
1149 1150 1151
<a href="/pkg/go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of
convenience functions <a href="/pkg/go/parser/#ParseDir"><code>ParseDir</code></a>
and <a href="/pkg/go/parser/#ParseExpr"><code>ParseExpr</code></a>.
1152 1153
</p>

Adam Langley's avatar
Adam Langley committed
1154 1155 1156 1157 1158
<p>
The <a href="/pkg/go/printer/"><code>go/printer</code></a> package supports an additional
configuration mode <a href="/pkg/go/printer/#Mode"><code>SourcePos</code></a>;
if set, the printer will emit <code>//line</code> comments such that the generated
output contains the original source code position information. The new type
1159
<a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be
Adam Langley's avatar
Adam Langley committed
1160 1161 1162 1163 1164
used to provide comments associated with an arbitrary
<a href="/pkg/go/ast/#Node"><code>ast.Node</code></a> (until now only
<a href="/pkg/go/ast/#File"><code>ast.File</code></a> carried comment information).
</p>

1165
<p>
Gustavo Niemeyer's avatar
Gustavo Niemeyer committed
1166
The type names of the <a href="/pkg/go/doc/"><code>go/doc</code></a> package have been
1167 1168 1169
streamlined by removing the <code>Doc</code> suffix: <code>PackageDoc</code>
is now <code>Package</code>, <code>ValueDoc</code> is <code>Value</code>, etc.
Also, all types now consistently have a <code>Name</code> field (or <code>Names</code>,
1170 1171
in the case of type <code>Value</code>) and <code>Type.Factories</code> has become
<code>Type.Funcs</code>.
1172 1173 1174 1175 1176 1177 1178 1179 1180 1181
Instead of calling <code>doc.NewPackageDoc(pkg, importpath)</code>,
documentation for a package is created with:
</p>

<pre>
    doc.New(pkg, importpath, mode)
</pre>

<p>
where the new <code>mode</code> parameter specifies the operation mode:
Gustavo Niemeyer's avatar
Gustavo Niemeyer committed
1182
if set to <a href="/pkg/go/doc/#AllDecls"><code>AllDecls</code></a>, all declarations
1183 1184 1185
(not just exported ones) are considered.
The function <code>NewFileDoc</code> was removed, and the function
<code>CommentText</code> has become the method
Gustavo Niemeyer's avatar
Gustavo Niemeyer committed
1186 1187
<a href="/pkg/go/ast/#Text"><code>Text</code></a> of
<a href="/pkg/go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>.
1188 1189 1190
</p>

<p>
Gustavo Niemeyer's avatar
Gustavo Niemeyer committed
1191 1192
In package <a href="/pkg/go/token/"><code>go/token</code></a>, the
<a href="/pkg/go/token/#FileSet"><code>token.FileSet</code></a> method <code>Files</code>
1193
(which originally returned a channel of <code>*token.File</code>s) has been replaced
Gustavo Niemeyer's avatar
Gustavo Niemeyer committed
1194
with the iterator <a href="/pkg/go/token/#FileSet.Iterate"><code>Iterate</code></a> that
1195 1196 1197
accepts a function argument instead.
</p>

1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213
<p>
In package <a href="/pkg/go/build/"><code>go/build</code></a>, the API
has been nearly completely replaced.
The package still computes Go package information
but it does not run the build: the <code>Cmd</code> and <code>Script</code>
types are gone.
(To build code, use the new
<a href="/cmd/go/"><code>go</code></a> command instead.)
The <code>DirInfo</code> type is now named
<a href="/pkg/go/build/#Package"><code>Package</code></a>.
<code>FindTree</code> and <code>ScanDir</code> are replaced by
<a href="/pkg/go/build/#Import"><code>Import</code></a>
and
<a href="/pkg/go/build/#ImportDir"><code>ImportDir</code></a>.
</p>

1214 1215 1216
<p>
<em>Updating</em>:
Code that uses packages in <code>go</code> will have to be updated by hand; the
1217
compiler will reject incorrect uses. Templates used in conjunction with any of the
1218 1219 1220 1221
<code>go/doc</code> types may need manual fixes; the renamed fields will lead
to run-time errors.
</p>

1222 1223 1224 1225
<h3 id="hash">The hash package</h3>

<p>
In Go 1, the definition of <a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> includes
1226
a new method, <code>BlockSize</code>.  This new method is used primarily in the
1227 1228 1229
cryptographic libraries.
</p>

1230 1231 1232 1233 1234 1235 1236
<p>
The <code>Sum</code> method of the
<a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> interface now takes a
<code>[]byte</code> argument, to which the hash value will be appended.
The previous behavior can be recreated by adding a <code>nil</code> argument to the call.
</p>

1237 1238 1239 1240 1241
<p>
<em>Updating</em>:
Existing implementations of <code>hash.Hash</code> will need to add a
<code>BlockSize</code> method.  Hashes that process the input one byte at
a time can implement <code>BlockSize</code> to return 1.
Rob Pike's avatar
Rob Pike committed
1242
Running <code>go</code> <code>fix</code> will update calls to the <code>Sum</code> methods of the various
1243
implementations of <code>hash.Hash</code>.
Rob Pike's avatar
Rob Pike committed
1244 1245 1246 1247 1248 1249 1250
</p>

<p>
<em>Updating</em>:
Since the package's functionality is new, no updating is necessary.
</p>

1251 1252
<h3 id="http">The http package</h3>

Rob Pike's avatar
Rob Pike committed
1253
<p>
1254
In Go 1 the <a href="/pkg/net/http/"><code>http</code></a> package is refactored,
Rob Pike's avatar
Rob Pike committed
1255
putting some of the utilities into a
1256
<a href="/pkg/net/httputil/"><code>httputil</code></a> subdirectory.
Rob Pike's avatar
Rob Pike committed
1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277
These pieces are only rarely needed by HTTP clients.
The affected items are:
</p>

<ul>
<li>ClientConn</li>
<li>DumpRequest</li>
<li>DumpRequest</li>
<li>DumpRequestOut</li>
<li>DumpResponse</li>
<li>NewChunkedReader</li>
<li>NewChunkedWriter</li>
<li>NewClientConn</li>
<li>NewProxyClientConn</li>
<li>NewServerConn</li>
<li>NewSingleHostReverseProxy</li>
<li>ReverseProxy</li>
<li>ServerConn</li>
</ul>

<p>
Adam Langley's avatar
Adam Langley committed
1278
The <code>Request.RawURL</code> field has been removed; it was a
Rob Pike's avatar
Rob Pike committed
1279 1280 1281
historical artifact.
</p>

Adam Langley's avatar
Adam Langley committed
1282 1283 1284 1285 1286 1287
<p>
The <code>Handle</code> and <code>HandleFunc</code>
functions, and the similarly-named methods of <code>ServeMux</code>,
now panic if an attempt is made to register the same pattern twice.
</p>

Rob Pike's avatar
Rob Pike committed
1288 1289
<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
1290
Running <code>go</code> <code>fix</code> will update the few programs that are affected except for
Rob Pike's avatar
Rob Pike committed
1291 1292 1293
uses of <code>RawURL</code>, which must be fixed by hand.
</p>

Rob Pike's avatar
Rob Pike committed
1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323
<h3 id="image">The image package</h3>

<p>
The <a href="/pkg/image/"><code>image</code></a> package has had a number of
minor changes, rearrangements and renamings.
</p>

<p>
Most of the color handling code has been moved into its own package,
<a href="/pkg/image/color/"><code>image/color</code></a>.
For the elements that moved, a symmetry arises; for instance,
each pixel of an
<a href="/pkg/image/#RGBA"><code>image.RGBA</code></a>
is a
<a href="/pkg/image/color/#RGBA"><code>color.RGBA</code></a>.
</p>

<p>
The old <code>image/ycbcr</code> package has been folded, with some
renamings, into the
<a href="/pkg/image/"><code>image</code></a>
and
<a href="/pkg/image/color/"><code>image/color</code></a>
packages.
</p>

<p>
The old <code>image.ColorImage</code> type is still in the <code>image</code>
package but has been renamed
<a href="/pkg/image/#Uniform"><code>image.Uniform</code></a>,
Adam Langley's avatar
Adam Langley committed
1324
while <code>image.Tiled</code> has been removed.
Rob Pike's avatar
Rob Pike committed
1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405
</p>

<p>
This table lists the renamings.
</p>

<table class="codetable" frame="border" summary="image renames">
<colgroup align="left" width="50%"></colgroup>
<colgroup align="left" width="50%"></colgroup>
<tr>
<th align="left">Old</th>
<th align="left">New</th>
</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>image.Color</td> <td>color.Color</td></tr>
<tr><td>image.ColorModel</td> <td>color.Model</td></tr>
<tr><td>image.ColorModelFunc</td> <td>color.ModelFunc</td></tr>
<tr><td>image.PalettedColorModel</td> <td>color.Palette</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>image.RGBAColor</td> <td>color.RGBA</td></tr>
<tr><td>image.RGBA64Color</td> <td>color.RGBA64</td></tr>
<tr><td>image.NRGBAColor</td> <td>color.NRGBA</td></tr>
<tr><td>image.NRGBA64Color</td> <td>color.NRGBA64</td></tr>
<tr><td>image.AlphaColor</td> <td>color.Alpha</td></tr>
<tr><td>image.Alpha16Color</td> <td>color.Alpha16</td></tr>
<tr><td>image.GrayColor</td> <td>color.Gray</td></tr>
<tr><td>image.Gray16Color</td> <td>color.Gray16</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>image.RGBAColorModel</td> <td>color.RGBAModel</td></tr>
<tr><td>image.RGBA64ColorModel</td> <td>color.RGBA64Model</td></tr>
<tr><td>image.NRGBAColorModel</td> <td>color.NRGBAModel</td></tr>
<tr><td>image.NRGBA64ColorModel</td> <td>color.NRGBA64Model</td></tr>
<tr><td>image.AlphaColorModel</td> <td>color.AlphaModel</td></tr>
<tr><td>image.Alpha16ColorModel</td> <td>color.Alpha16Model</td></tr>
<tr><td>image.GrayColorModel</td> <td>color.GrayModel</td></tr>
<tr><td>image.Gray16ColorModel</td> <td>color.Gray16Model</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>ycbcr.RGBToYCbCr</td> <td>color.RGBToYCbCr</td></tr>
<tr><td>ycbcr.YCbCrToRGB</td> <td>color.YCbCrToRGB</td></tr>
<tr><td>ycbcr.YCbCrColorModel</td> <td>color.YCbCrModel</td></tr>
<tr><td>ycbcr.YCbCrColor</td> <td>color.YCbCr</td></tr>
<tr><td>ycbcr.YCbCr</td> <td>image.YCbCr</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>ycbcr.SubsampleRatio444</td> <td>image.YCbCrSubsampleRatio444</td></tr>
<tr><td>ycbcr.SubsampleRatio422</td> <td>image.YCbCrSubsampleRatio422</td></tr>
<tr><td>ycbcr.SubsampleRatio420</td> <td>image.YCbCrSubsampleRatio420</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>image.ColorImage</td> <td>image.Uniform</td></tr>
</table>

<p>
The image package's <code>New</code> functions
(<a href="/pkg/image/#NewRGBA"><code>NewRGBA</code></a>,
<a href="/pkg/image/#NewRGBA64"><code>NewRGBA64</code></a>, etc.)
take an <a href="/pkg/image/#Rectangle"><code>image.Rectangle</code></a> as an argument
instead of four integers.
</p>

<p>
Finally, there are new predefined <code>color.Color</code> variables
<a href="/pkg/image/color/#Black"><code>color.Black</code></a>,
<a href="/pkg/image/color/#White"><code>color.White</code></a>,
<a href="/pkg/image/color/#Opaque"><code>color.Opaque</code></a>
and
<a href="/pkg/image/color/#Transparent"><code>color.Transparent</code></a>.
</p>

<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
1406
Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
Rob Pike's avatar
Rob Pike committed
1407 1408
</p>

Adam Langley's avatar
Adam Langley committed
1409 1410 1411
<h3 id="log_syslog">The log/syslog package</h3>

<p>
1412
In Go 1, the <a href="/pkg/log/syslog/#NewLogger"><code>syslog.NewLogger</code></a>
Adam Langley's avatar
Adam Langley committed
1413 1414 1415 1416 1417 1418 1419 1420
function returns an error as well as a <code>log.Logger</code>.
</p>

<p>
<em>Updating</em>:
What little code is affected will be caught by the compiler and must be updated by hand.
</p>

Rob Pike's avatar
Rob Pike committed
1421 1422 1423 1424 1425 1426
<h3 id="mime">The mime package</h3>

<p>
In Go 1, the <a href="/pkg/mime/#FormatMediaType"><code>FormatMediaType</code></a> function
of the <code>mime</code> package has  been simplified to make it
consistent with
1427
<a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a>.
Rob Pike's avatar
Rob Pike committed
1428 1429 1430 1431 1432 1433 1434 1435
It now takes <code>"text/html"</code> rather than <code>"text"</code> and <code>"html"</code>.
</p>

<p>
<em>Updating</em>:
What little code is affected will be caught by the compiler and must be updated by hand.
</p>

1436 1437
<h3 id="net">The net package</h3>

1438 1439
<p>
In Go 1, the various <code>SetTimeout</code>,
1440
<code>SetReadTimeout</code>, and <code>SetWriteTimeout</code> methods
1441
have been replaced with
1442
<a href="/pkg/net/#IPConn.SetDeadline"><code>SetDeadline</code></a>,
1443
<a href="/pkg/net/#IPConn.SetReadDeadline"><code>SetReadDeadline</code></a>, and
1444
<a href="/pkg/net/#IPConn.SetWriteDeadline"><code>SetWriteDeadline</code></a>,
1445 1446 1447
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 <code>time.Time</code> value) after which
1448 1449 1450 1451
reads and writes will time out and no longer block.
</p>

<p>
1452 1453 1454 1455 1456 1457 1458
There are also new functions
<a href="/pkg/net/#DialTimeout"><code>net.DialTimeout</code></a>
to simplify timing out dialing a network address and
<a href="/pkg/net/#ListenMulticastUDP"><code>net.ListenMulticastUDP</code></a>
to allow multicast UDP to listen concurrently across multiple listeners.
The <code>net.ListenMulticastUDP</code> function replaces the old
<code>JoinGroup</code> and <code>LeaveGroup</code> methods.
1459 1460 1461 1462 1463
</p>

<p>
<em>Updating</em>:
Code that uses the old methods will fail to compile and must be updated by hand.
1464
The semantic change makes it difficult for the fix tool to update automatically.
1465
</p>
1466

Adam Langley's avatar
Adam Langley committed
1467 1468
<h3 id="os">The os package</h3>

1469 1470
<p>
The <code>Time</code> function has been removed; callers should use
Adam Langley's avatar
Adam Langley committed
1471
the <a href="/pkg/time/#Time"><code>Time</code></a> type from the
1472 1473
<code>time</code> package.
</p>
Adam Langley's avatar
Adam Langley committed
1474

1475 1476 1477 1478
<p>
The <code>Exec</code> function has been removed; callers should use
<code>Exec</code> from the <code>syscall</code> package, where available.
</p>
Adam Langley's avatar
Adam Langley committed
1479

1480 1481 1482 1483
<p>
The <code>ShellExpand</code> function has been renamed to <a
href="/pkg/os/#ExpandEnv"><code>ExpandEnv</code></a>.
</p>
Adam Langley's avatar
Adam Langley committed
1484

1485 1486
<p>
The <a href="/pkg/os/#NewFile"><code>NewFile</code></a> function
Adam Langley's avatar
Adam Langley committed
1487 1488
now takes a <code>uintptr</code> fd, instead of an <code>int</code>.
The <a href="/pkg/os/#File.Fd"><code>Fd</code></a> method on files now
1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501
also returns a <code>uintptr</code>.
</p>

<p>
There are no longer error constants such as <code>EINVAL</code>
in the <code>os</code> package, since the set of values varied with
the underlying operating system. There are new portable functions like
<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>
to test common error properties, plus a few new error values
with more Go-like names, such as
<a href="/pkg/os/#ErrPermission"><code>ErrPermission</code></a>
and
<a href="/pkg/os/#ErrNoEnv"><code>ErrNoEnv</code></a>.
Brad Fitzpatrick's avatar
Brad Fitzpatrick committed
1502
</p>
1503

Brad Fitzpatrick's avatar
Brad Fitzpatrick committed
1504 1505 1506 1507 1508 1509
<p>
The <code>Getenverror</code> function has been removed. To distinguish
between a non-existent environment variable and an empty string,
use <a href="/pkg/os/#Environ"><code>os.Environ</code></a> or
<a href="/pkg/syscall/#Getenv"><code>syscall.Getenv</code></a>.
</p>
Adam Langley's avatar
Adam Langley committed
1510

1511 1512 1513 1514 1515 1516 1517 1518 1519

<p>
The <a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a> method has
dropped its option argument and the associated constants are gone
from the package.
Also, the function <code>Wait</code> is gone; only the method of
the <code>Process</code> type persists.
</p>

Rob Pike's avatar
Rob Pike committed
1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536
<p>
The <code>Waitmsg</code> type returned by
<a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a>
has been replaced with a more portable
<a href="/pkg/os/#ProcessState"><code>ProcessState</code></a>
type with accessor methods to recover information about the
process.
Because of changes to <code>Wait</code>, the <code>ProcessState</code>
value always describes an exited process.
Portability concerns simplified the interface in other ways, but the values returned by the
<a href="/pkg/os/#ProcessState.Sys"><code>ProcessState.Sys</code></a> and
<a href="/pkg/os/#ProcessState.SysUsage"><code>ProcessState.SysUsage</code></a>
methods can be type-asserted to underlying system-specific data structures such as
<a href="/pkg/syscall/#WaitStatus"><code>syscall.WaitStatus</code></a> and
<a href="/pkg/syscall/#Rusage"><code>syscall.Rusage</code></a> on Unix.
</p>

1537 1538
<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
1539 1540
Running <code>go</code> <code>fix</code> will drop a zero argument to <code>Process.Wait</code>.
All other changes will be caught by the compiler and must be updated by hand.
1541
</p>
Adam Langley's avatar
Adam Langley committed
1542 1543

<h4 id="os_fileinfo">The os.FileInfo type</h4>
1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556

<p>
Go 1 redefines the <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> type,
changing it from a struct to an interface:
</p>

<pre>
    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()
1557
        Sys() interface{}   // underlying data source (can return nil)
1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571
    }
</pre>

<p>
The file mode information has been moved into a subtype called
<a href="/pkg/os/#FileMode"><code>os.FileMode</code></a>,
a simple integer type with <code>IsDir</code>, <code>Perm</code>, and <code>String</code>
methods.
</p>

<p>
The system-specific details of file modes and properties such as (on Unix)
i-number have been removed from <code>FileInfo</code> altogether.
Instead, each operating system's <code>os</code> package provides an
1572 1573
implementation of the <code>FileInfo</code> interface, which
has a <code>Sys</code> method that returns the
1574 1575 1576 1577 1578 1579 1580 1581 1582 1583
system-specific representation of file metadata.
For instance, to discover the i-number of a file on a Unix system, unpack
the <code>FileInfo</code> like this:
</p>

<pre>
    fi, err := os.Stat("hello.go")
    if err != nil {
        log.Fatal(err)
    }
1584 1585
    // Check that it's a Unix file.
    unixStat, ok := fi.Sys().(*syscall.Stat_t)
1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597
    if !ok {
        log.Fatal("hello.go: not a Unix file")
    }
    fmt.Printf("file i-number: %d\n", unixStat.Ino)
</pre>

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

<pre>
1598
    fi.Sys().(*syscall.Stat_t).Ino
1599 1600 1601 1602 1603 1604
</pre>

<p>
The vast majority of uses of <code>FileInfo</code> need only the methods
of the standard interface.
</p>
Rob Pike's avatar
Rob Pike committed
1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618

<p>
The <code>os</code> package no longer contains wrappers for the POSIX errors
such as <code>ENOENT</code>.
For the few programs that need to verify particular error conditions, there are
now the boolean functions
<a href="/pkg/os/#IsExist"><code>IsExist</code></a>,
<a href="/pkg/os/#IsNotExist"><code>IsNotExist</code></a>
and
<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>.
</p>

{{code "progs/go1.go" `/os\.Open/` `/}/`}}

1619 1620
<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
1621
Running <code>go</code> <code>fix</code> will update code that uses the old equivalent of the current <code>os.FileInfo</code>
1622 1623
and <code>os.FileMode</code> API.
Code that needs system-specific file details will need to be updated by hand.
Rob Pike's avatar
Rob Pike committed
1624 1625
Code that uses the old POSIX error values from the <code>os</code> package
will fail to compile and will also need to be updated by hand.
1626 1627
</p>

1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660
<h3 id="os_signal">The os/signal package</h3>

<p>
The <code>os/signal</code> package in Go 1 replaces the
<code>Incoming</code> function, which returned a channel
that received all incoming signals,
with the selective <code>Notify</code> function, which asks
for delivery of specific signals on an existing channel.
</p>

<p>
<em>Updating</em>:
Code must be updated by hand.
A literal translation of
</p>
<pre>
c := signal.Incoming()
</pre>
<p>
is
</p>
<pre>
c := make(chan os.Signal)
signal.Notify(c) // ask for all signals
</pre>
<p>
but most code should list the specific signals it wants to handle instead:
</p>
<pre>
c := make(chan os.Signal)
signal.Notify(c, syscall.SIGHUP, syscall.SIGQUIT)
</pre>

Rob Pike's avatar
Rob Pike committed
1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672
<h3 id="path_filepath">The path/filepath package</h3>

<p>
In Go 1, the <a href="/pkg/path/filepath/#Walk"><code>Walk</code></a> function of the
<code>path/filepath</code> package
has been changed to take a function value of type
<a href="/pkg/path/filepath/#WalkFunc"><code>WalkFunc</code></a>
instead of a <code>Visitor</code> interface value.
<code>WalkFunc</code> unifies the handling of both files and directories.
</p>

<pre>
1673
    type WalkFunc func(path string, info os.FileInfo, err error) error
Rob Pike's avatar
Rob Pike committed
1674 1675 1676 1677 1678 1679
</pre>

<p>
The <code>WalkFunc</code> 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,
1680
the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
Rob Pike's avatar
Rob Pike committed
1681 1682
</p>

1683
{{code "progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
Rob Pike's avatar
Rob Pike committed
1684 1685 1686 1687 1688 1689 1690 1691

<p>
<em>Updating</em>:
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.
</p>

1692
<h3 id="regexp">The regexp package</h3>
1693 1694

<p>
1695
The <a href="/pkg/regexp/"><code>regexp</code></a> package has been rewritten.
1696
It has the same interface but the specification of the regular expressions
1697
it supports has changed from the old "egrep" form to that of
Stefan Nilsson's avatar
Stefan Nilsson committed
1698
<a href="http://code.google.com/p/re2/">RE2</a>.
1699 1700 1701 1702
</p>

<p>
<em>Updating</em>:
1703
Code that uses the package should have its regular expressions checked by hand.
1704 1705
</p>

Rob Pike's avatar
Rob Pike committed
1706 1707 1708
<h3 id="runtime">The runtime package</h3>

<p>
1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732
In Go 1, much of the API exported by package
<code>runtime</code> has been removed in favor of
functionality provided by other packages.
Code using the <code>runtime.Type</code> interface
or its specific concrete type implementations should
now use package <a href="/pkg/reflect/"><code>reflect</code></a>.
Code using <code>runtime.Semacquire</code> or <code>runtime.Semrelease</code>
should use channels or the abstractions in package <a href="/pkg/sync/"><code>sync</code></a>.
The <code>runtime.Alloc</code>, <code>runtime.Free</code>,
and <code>runtime.Lookup</code> functions, an unsafe API created for
debugging the memory allocator, have no replacement.
</p>

<p>
Before, <code>runtime.MemStats</code> was a global variable holding
statistics about memory allocation, and calls to <code>runtime.UpdateMemStats</code>
ensured that it was up to date.
In Go 1, <code>runtime.MemStats</code> is a struct type, and code should use
<a href="/pkg/runtime/#ReadMemStats"><code>runtime.ReadMemStats</code></a>
to obtain the current statistics.
</p>

<p>
The package adds a new function,
Rob Pike's avatar
Rob Pike committed
1733 1734 1735
<a href="/pkg/runtime/#NumCPU"><code>runtime.NumCPU</code></a>, that returns the number of CPUs available
for parallel execution, as reported by the operating system kernel.
Its value can inform the setting of <code>GOMAXPROCS</code>.
1736 1737
The <code>runtime.Cgocalls</code> and <code>runtime.Goroutines</code> functions
have been renamed to <code>runtime.NumCgoCall</code> and <code>runtime.NumGoroutine</code>.
Rob Pike's avatar
Rob Pike committed
1738 1739 1740 1741
</p>

<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
1742
Running <code>go</code> <code>fix</code> will update code for the function renamings.
1743
Other code will need to be updated by hand.
Rob Pike's avatar
Rob Pike committed
1744 1745
</p>

1746 1747
<h3 id="strconv">The strconv package</h3>

Rob Pike's avatar
Rob Pike committed
1748 1749
<p>
In Go 1, the
1750
<a href="/pkg/strconv/"><code>strconv</code></a>
Rob Pike's avatar
Rob Pike committed
1751 1752 1753 1754 1755 1756 1757 1758 1759 1760
package has been significantly reworked to make it more Go-like and less C-like,
although <code>Atoi</code> lives on (it's similar to
<code>int(ParseInt(x, 10, 0))</code>, as does
<code>Itoa(x)</code> (<code>FormatInt(int64(x), 10)</code>).
There are also new variants of some of the functions that append to byte slices rather than
return strings, to allow control over allocation.
</p>

<p>
This table summarizes the renamings; see the
1761
<a href="/pkg/strconv/">package documentation</a>
Rob Pike's avatar
Rob Pike committed
1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804
for full details.
</p>

<table class="codetable" frame="border" summary="strconv renames">
<colgroup align="left" width="50%"></colgroup>
<colgroup align="left" width="50%"></colgroup>
<tr>
<th align="left">Old call</th>
<th align="left">New call</th>
</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Atob(x)</td> <td>ParseBool(x)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Atof32(x)</td> <td>ParseFloat(x, 32)§</td></tr>
<tr><td>Atof64(x)</td> <td>ParseFloat(x, 64)</td></tr>
<tr><td>AtofN(x, n)</td> <td>ParseFloat(x, n)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Atoi(x)</td> <td>Atoi(x)</td></tr>
<tr><td>Atoi(x)</td> <td>ParseInt(x, 10, 0)§</td></tr>
<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Atoui(x)</td> <td>ParseUint(x, 10, 0)§</td></tr>
<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Btoi64(x, b)</td> <td>ParseInt(x, b, 64)</td></tr>
<tr><td>Btoui64(x, b)</td> <td>ParseUint(x, b, 64)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Btoa(x)</td> <td>FormatBool(x)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
1805
<tr><td>Ftoa32(x, f, p)</td> <td>FormatFloat(float64(x), f, p, 32)</td></tr>
Rob Pike's avatar
Rob Pike committed
1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832
<tr><td>Ftoa64(x, f, p)</td> <td>FormatFloat(x, f, p, 64)</td></tr>
<tr><td>FtoaN(x, f, p, n)</td> <td>FormatFloat(x, f, p, n)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Itoa(x)</td> <td>Itoa(x)</td></tr>
<tr><td>Itoa(x)</td> <td>FormatInt(int64(x), 10)</td></tr>
<tr><td>Itoa64(x)</td> <td>FormatInt(x, 10)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Itob(x, b)</td> <td>FormatInt(int64(x), b)</td></tr>
<tr><td>Itob64(x, b)</td> <td>FormatInt(x, b)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Uitoa(x)</td> <td>FormatUint(uint64(x), 10)</td></tr>
<tr><td>Uitoa64(x)</td> <td>FormatUint(x, 10)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Uitob(x, b)</td> <td>FormatUint(uint64(x), b)</td></tr>
<tr><td>Uitob64(x, b)</td> <td>FormatUint(x, b)</td></tr>
</table>
		
<p>
<em>Updating</em>:
Rob Pike's avatar
Rob Pike committed
1833
Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
Rob Pike's avatar
Rob Pike committed
1834 1835 1836
<br>
§ <code>Atoi</code> persists but <code>Atoui</code> and <code>Atof32</code> do not, so
they may require
Rob Pike's avatar
Rob Pike committed
1837
a cast that must be added by hand; the <code>go</code> <code>fix</code> tool will warn about it.
Rob Pike's avatar
Rob Pike committed
1838 1839
</p>

1840

1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872
<h3 id="templates">The template packages</h3>

<p>
The <code>template</code> and <code>exp/template/html</code> packages have moved to 
<a href="/pkg/text/template/"><code>text/template</code></a> and
<a href="/pkg/html/template/"><code>html/template</code></a>.
More significant, the interface to these packages has been simplified.
The template language is the same, but the concept of "template set" is gone
and the functions and methods of the packages have changed accordingly,
often by elimination.
</p>

<p>
Instead of sets, a <code>Template</code> object
may contain multiple named template definitions,
in effect constructing
name spaces for template invocation.
A template can invoke any other template associated with it, but only those
templates associated with it.
The simplest way to associate templates is to parse them together, something
made easier with the new structure of the packages.
</p>

<p>
<em>Updating</em>:
The imports will be updated by fix tool.
Single-template uses will be otherwise be largely unaffected.
Code that uses multiple templates in concert will need to be updated by hand.
The <a href="/pkg/text/template/#examples">examples</a> in
the documentation for <code>text/template</code> can provide guidance.
</p>

Rob Pike's avatar
Rob Pike committed
1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885
<h3 id="testing">The testing package</h3>

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

{{code "progs/go1.go" `/func.*Benchmark/` `/^}/`}}

<p>
<em>Updating</em>:
Existing code is unaffected, although benchmarks that use <code>println</code>
Rob Pike's avatar
Rob Pike committed
1886
or <code>panic</code> should be updated to use the new methods.
Rob Pike's avatar
Rob Pike committed
1887 1888
</p>

Adam Langley's avatar
Adam Langley committed
1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899
<h3 id="testing_script">The testing/script package</h3>

<p>
The testing/script package has been deleted. It was a dreg.
</p>

<p>
<em>Updating</em>:
No code is likely to be affected.
</p>

1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918
<h3 id="unsafe">The unsafe package</h3>

<p>
In Go 1, the functions
<code>unsafe.Typeof</code>, <code>unsafe.Reflect</code>,
<code>unsafe.Unreflect</code>, <code>unsafe.New</code>, and
<code>unsafe.NewArray</code> have been removed;
they duplicated safer functionality provided by
package <a href="/pkg/reflect/"><code>reflect</code></a>.
</p>

<p>
<em>Updating</em>:
Code using these functions must be rewritten to use
package <a href="/pkg/reflect/"><code>reflect</code></a>.
The changes to <a href="http://code.google.com/p/go/source/detail?r=2646dc956207">encoding/gob</a> and the <a href="http://code.google.com/p/goprotobuf/source/detail?r=5340ad310031">protocol buffer library</a>
may be helpful as examples.
</p>

1919 1920 1921
<h3 id="url">The url package</h3>

<p>
1922
In Go 1 several fields from the <a href="/pkg/net/url/#URL"><code>url.URL</code></a> type
1923 1924 1925 1926
were removed or replaced.
</p>

<p>
1927
The <a href="/pkg/net/url/#URL.String"><code>String</code></a> method now
1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939
predictably rebuilds an encoded URL string using all of <code>URL</code>'s
fields as necessary. The resulting string will also no longer have
passwords escaped.
</p>

<p>
The <code>Raw</code> field has been removed. In most cases the <code>String</code>
method may be used in its place.
</p>

<p>
The old <code>RawUserinfo</code> field is replaced by the <code>User</code>
1940 1941 1942
field, of type <a href="/pkg/net/url/#Userinfo"><code>*net.Userinfo</code></a>.
Values of this type may be created using the new <a href="/pkg/net/url/#User"><code>net.User</code></a>
and <a href="/pkg/net/url/#UserPassword"><code>net.UserPassword</code></a>
1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976
functions. The <code>EscapeUserinfo</code> and <code>UnescapeUserinfo</code>
functions are also gone.
</p>

<p>
The <code>RawAuthority</code> field has been removed. The same information is
available in the <code>Host</code> and <code>User</code> fields.
</p>

<p>
The <code>RawPath</code> field and the <code>EncodedPath</code> 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 <code>Path</code> 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.
</p>

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

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

<p>
1977
A new <a href="/pkg/net/url/#URL.RequestURI"><code>RequestURI</code></a> method was
1978 1979 1980
added to <code>URL</code>.
</p>

1981 1982 1983 1984
<p>
The <code>ParseWithReference</code> function has been renamed to <code>ParseWithFragment</code>.
</p>

1985 1986 1987
<p>
<em>Updating</em>:
Code that uses the old fields will fail to compile and must be updated by hand.
1988
The semantic changes make it difficult for the fix tool to update automatically.
1989 1990
</p>

Russ Cox's avatar
Russ Cox committed
1991 1992 1993
<h2 id="cmd_go">The go command</h2>

<p>
1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012
Go 1 introduces the <a href="/cmd/go/">go command</a>, a tool for fetching,
building, and installing Go packages and commands. The <code>go</code> command
does away with makefiles, instead using Go source code to find dependencies and
determine build conditions. Most existing Go programs will no longer require
makefiles to be built.
</p>

<p>
See <a href="/doc/code.html">How to Write Go Code</a> for a primer on the
<code>go</code> command and the <a href="/cmd/go/">go command documentation</a>
for the full details.
</p>

<p>
<em>Updating</em>:
Projects that depend on the Go project's old makefile-based build
infrastructure (<code>Make.pkg</code>, <code>Make.cmd</code>, and so on) should
switch to using the <code>go</code> command for building Go code and, if
necessary, rewrite their makefiles to perform any auxiliary build tasks.
Russ Cox's avatar
Russ Cox committed
2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025
</p>

<h2 id="cmd_cgo">The cgo command</h2>

<p>
In Go 1, the <a href="/cmd/cgo">cgo command</a>
uses a different <code>_cgo_export.h</code>
file, which is generated for packages containing <code>//export</code> lines.
The <code>_cgo_export.h</code> file now begins with the C preamble comment,
so that exported function definitions can use types defined there.
This has the effect of compiling the preamble multiple times, so a
package using <code>//export</code> must not put function definitions
or variable initializations in the C preamble.
2026
</p>
2027 2028 2029

<h2 id="releases">Packaged releases</h2>