-
Notifications
You must be signed in to change notification settings - Fork 17.5k
/
go1.13.html
1078 lines (895 loc) · 45.2 KB
/
go1.13.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
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
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
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
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
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
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
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
660
661
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
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
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
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
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
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!--{
"Title": "Go 1.13 Release Notes",
"Path": "/doc/go1.13",
"Template": true
}-->
<!--
NOTE: In this document and others in this directory, the convention is to
set fixed-width phrases with non-fixed-width spaces, as in
<code>hello</code> <code>world</code>.
Do not send CLs removing the interior tags from such phrases.
-->
<style>
main ul li { margin: 0.5em 0; }
</style>
<h2 id="introduction">Introduction to Go 1.13</h2>
<p>
The latest Go release, version 1.13, arrives six months after <a href="go1.12">Go 1.12</a>.
Most of its changes are in the implementation of the toolchain, runtime, and libraries.
As always, the release maintains the Go 1 <a href="/doc/go1compat.html">promise of compatibility</a>.
We expect almost all Go programs to continue to compile and run as before.
</p>
<p>
As of Go 1.13, the go command by default downloads and authenticates
modules using the Go module mirror and Go checksum database run by Google. See
<a href="https://proxy.golang.org/privacy">https://proxy.golang.org/privacy</a>
for privacy information about these services and the
<a href="/cmd/go/#hdr-Module_downloading_and_verification">go command documentation</a>
for configuration details including how to disable the use of these servers or use
different ones. If you depend on non-public modules, see the
<a href="/cmd/go/#hdr-Module_configuration_for_non_public_modules">documentation for configuring your environment</a>.
</p>
<h2 id="language">Changes to the language</h2>
<p>
Per the <a href="https://github.com/golang/proposal/blob/master/design/19308-number-literals.md">number literal proposal</a>,
Go 1.13 supports a more uniform and modernized set of number literal prefixes.
<ul>
<li>
<a href="/ref/spec#Integer_literals">Binary integer literals</a>:
The prefix <code>0b</code> or <code>0B</code> indicates a binary integer literal
such as <code>0b1011</code>.
</li>
<li>
<a href="/ref/spec#Integer_literals">Octal integer literals</a>:
The prefix <code>0o</code> or <code>0O</code> indicates an octal integer literal
such as <code>0o660</code>.
The existing octal notation indicated by a leading <code>0</code> followed by
octal digits remains valid.
</li>
<li>
<a href="/ref/spec#Floating-point_literals">Hexadecimal floating point literals</a>:
The prefix <code>0x</code> or <code>0X</code> may now be used to express the mantissa of a
floating-point number in hexadecimal format such as <code>0x1.0p-1021</code>.
A hexadecimal floating-point number must always have an exponent, written as the letter
<code>p</code> or <code>P</code> followed by an exponent in decimal. The exponent scales
the mantissa by 2 to the power of the exponent.
</li>
<li>
<a href="/ref/spec#Imaginary_literals">Imaginary literals</a>:
The imaginary suffix <code>i</code> may now be used with any (binary, decimal, hexadecimal)
integer or floating-point literal.
</li>
<li>
Digit separators:
The digits of any number literal may now be separated (grouped) using underscores, such as
in <code>1_000_000</code>, <code>0b_1010_0110</code>, or <code>3.1415_9265</code>.
An underscore may appear between any two digits or the literal prefix and the first digit.
</li>
</ul>
</p>
<p>
Per the <a href="https://github.com/golang/proposal/blob/master/design/19113-signed-shift-counts.md">signed shift counts proposal</a>
Go 1.13 removes the restriction that a <a href="/ref/spec#Operators">shift count</a>
must be unsigned. This change eliminates the need for many artificial <code>uint</code> conversions,
solely introduced to satisfy this (now removed) restriction of the <code><<</code> and <code>>></code> operators.
</p>
<p>
These language changes were implemented by changes to the compiler, and corresponding internal changes to the library
packages <code><a href="#go/scanner">go/scanner</a></code> and
<code><a href="#text/scanner">text/scanner</a></code> (number literals),
and <code><a href="#go/types">go/types</a></code> (signed shift counts).
</p>
<p>
If your code uses modules and your <code>go.mod</code> files specifies a language version, be sure
it is set to at least <code>1.13</code> to get access to these language changes.
You can do this by editing the <code>go.mod</code> file directly, or you can run
<code>go mod edit -go=1.13</code>.
</p>
<h2 id="ports">Ports</h2>
<p>
Go 1.13 is the last release that will run on Native Client (NaCl).
</p>
<p><!-- CL 170119, CL 168882 -->
For <code>GOARCH=wasm</code>, the new environment variable <code>GOWASM</code> takes a comma-separated list of experimental features that the binary gets compiled with.
The valid values are documented <a href="/cmd/go/#hdr-Environment_variables">here</a>.
</p>
<h3 id="aix">AIX</h3>
<p><!-- CL 164003, CL 169120 -->
AIX on PPC64 (<code>aix/ppc64</code>) now supports cgo, external
linking, and the <code>c-archive</code> and <code>pie</code> build
modes.
</p>
<h3 id="android">Android</h3>
<p><!-- CL 170127 -->
Go programs are now compatible with Android 10.
</p>
<h3 id="darwin">Darwin</h3>
<p>
As <a href="go1.12#darwin">announced</a> in the Go 1.12 release notes,
Go 1.13 now requires macOS 10.11 El Capitan or later;
support for previous versions has been discontinued.
</p>
<h3 id="freebsd">FreeBSD</h3>
<p>
As <a href="go1.12#freebsd">announced</a> in the Go 1.12 release notes,
Go 1.13 now requires FreeBSD 11.2 or later;
support for previous versions has been discontinued.
FreeBSD 12.0 or later requires a kernel with the <code>COMPAT_FREEBSD11</code>
option set (this is the default).
</p>
<h3 id="illumos">Illumos</h3>
<p><!-- CL 174457 -->
Go now supports Illumos with <code>GOOS=illumos</code>.
The <code>illumos</code> build tag implies the <code>solaris</code>
build tag.
</p>
<h3 id="netbsd">NetBSD</h3>
<p><!--CL 155739 -->
Go now supports NetBSD on arm64.
</p>
<h3 id="openbsd">OpenBSD</h3>
<p><!--CL 174125 -->
Go now supports OpenBSD on arm64.
</p>
<h3 id="windows">Windows</h3>
<p><!-- CL 178977 -->
The Windows version specified by internally-linked Windows binaries
is now Windows 7 rather than NT 4.0. This was already the minimum
required version for Go, but can affect the behavior of system calls
that have a backwards-compatibility mode. These will now behave as
documented. Externally-linked binaries (any program using cgo) have
always specified a more recent Windows version.
</p>
<h2 id="tools">Tools</h2>
<h3 id="modules">Modules</h3>
<h4 id="proxy-vars">Environment variables</h4>
<p><!-- CL 176580 -->
The <a href="/cmd/go/#hdr-Module_support"><code>GO111MODULE</code></a>
environment variable continues to default to <code>auto</code>, but
the <code>auto</code> setting now activates the module-aware mode of
the <code>go</code> command whenever the current working directory contains,
or is below a directory containing, a <code>go.mod</code> file — even if the
current directory is within <code>GOPATH/src</code>. This change simplifies
the migration of existing code within <code>GOPATH/src</code> and the ongoing
maintenance of module-aware packages alongside non-module-aware importers.
</p>
<p><!-- CL 181719 -->
The new
<a href="/cmd/go/#hdr-Module_configuration_for_non_public_modules"><code>GOPRIVATE</code></a>
environment variable indicates module paths that are not publicly available.
It serves as the default value for the lower-level <code>GONOPROXY</code>
and <code>GONOSUMDB</code> variables, which provide finer-grained control over
which modules are fetched via proxy and verified using the checksum database.
</p>
<p><!-- CL 173441, CL 177958 -->
The <a href="/cmd/go/#hdr-Module_downloading_and_verification"><code>GOPROXY</code>
environment variable</a> may now be set to a comma-separated list of proxy
URLs or the special token <code>direct</code>, and
its <a href="#introduction">default value</a> is
now <code>https://proxy.golang.org,direct</code>. When resolving a package
path to its containing module, the <code>go</code> command will try all
candidate module paths on each proxy in the list in succession. An unreachable
proxy or HTTP status code other than 404 or 410 terminates the search without
consulting the remaining proxies.
</p>
<p>
The new
<a href="/cmd/go/#hdr-Module_authentication_failures"><code>GOSUMDB</code></a>
environment variable identifies the name, and optionally the public key and
server URL, of the database to consult for checksums of modules that are not
yet listed in the main module's <code>go.sum</code> file.
If <code>GOSUMDB</code> does not include an explicit URL, the URL is chosen by
probing the <code>GOPROXY</code> URLs for an endpoint indicating support for
the checksum database, falling back to a direct connection to the named
database if it is not supported by any proxy. If <code>GOSUMDB</code> is set
to <code>off</code>, the checksum database is not consulted and only the
existing checksums in the <code>go.sum</code> file are verified.
</p>
<p>
Users who cannot reach the default proxy and checksum database (for example,
due to a firewalled or sandboxed configuration) may disable their use by
setting <code>GOPROXY</code> to <code>direct</code>, and/or
<code>GOSUMDB</code> to <code>off</code>.
<a href="#go-env-w"><code>go</code> <code>env</code> <code>-w</code></a>
can be used to set the default values for these variables independent of
platform:
</p>
<pre>
go env -w GOPROXY=direct
go env -w GOSUMDB=off
</pre>
<h4 id="go-get"><code>go</code> <code>get</code></h4>
<p><!-- CL 174099 -->
In module-aware mode,
<a href="/cmd/go/#hdr-Add_dependencies_to_current_module_and_install_them"><code>go</code> <code>get</code></a>
with the <code>-u</code> flag now updates a smaller set of modules that is
more consistent with the set of packages updated by
<code>go</code> <code>get</code> <code>-u</code> in GOPATH mode.
<code>go</code> <code>get</code> <code>-u</code> continues to update the
modules and packages named on the command line, but additionally updates only
the modules containing the packages <em>imported by</em> the named packages,
rather than the transitive module requirements of the modules containing the
named packages.
</p>
<p>
Note in particular that <code>go</code> <code>get</code> <code>-u</code>
(without additional arguments) now updates only the transitive imports of the
package in the current directory. To instead update all of the packages
transitively imported by the main module (including test dependencies), use
<code>go</code> <code>get</code> <code>-u</code> <code>all</code>.
</p>
<p><!-- CL 177879 -->
As a result of the above changes to
<code>go</code> <code>get</code> <code>-u</code>, the
<code>go</code> <code>get</code> subcommand no longer supports
the <code>-m</code> flag, which caused <code>go</code> <code>get</code> to
stop before loading packages. The <code>-d</code> flag remains supported, and
continues to cause <code>go</code> <code>get</code> to stop after downloading
the source code needed to build dependencies of the named packages.
</p>
<p><!-- CL 177677 -->
By default, <code>go</code> <code>get</code> <code>-u</code> in module mode
upgrades only non-test dependencies, as in GOPATH mode. It now also accepts
the <code>-t</code> flag, which (as in GOPATH mode)
causes <code>go</code> <code>get</code> to include the packages imported
by <em>tests of</em> the packages named on the command line.
</p>
<p><!-- CL 167747 -->
In module-aware mode, the <code>go</code> <code>get</code> subcommand now
supports the version suffix <code>@patch</code>. The <code>@patch</code>
suffix indicates that the named module, or module containing the named
package, should be updated to the highest patch release with the same
major and minor versions as the version found in the build list.
</p>
<p><!-- CL 184440 -->
If a module passed as an argument to <code>go</code> <code>get</code>
without a version suffix is already required at a newer version than the
latest released version, it will remain at the newer version. This is
consistent with the behavior of the <code>-u</code> flag for module
dependencies. This prevents unexpected downgrades from pre-release versions.
The new version suffix <code>@upgrade</code> explicitly requests this
behavior. <code>@latest</code> explicitly requests the latest version
regardless of the current version.
</p>
<h4 id="version-validation">Version validation</h4><!-- CL 181881 -->
<p>
When extracting a module from a version control system, the <code>go</code>
command now performs additional validation on the requested version string.
</p>
<p>
The <code>+incompatible</code> version annotation bypasses the requirement
of <a href="/cmd/go/#hdr-Module_compatibility_and_semantic_versioning">semantic
import versioning</a> for repositories that predate the introduction of
modules. The <code>go</code> command now verifies that such a version does not
include an explicit <code>go.mod</code> file.
</p>
<p>
The <code>go</code> command now verifies the mapping
between <a href="/cmd/go/#hdr-Pseudo_versions">pseudo-versions</a> and
version-control metadata. Specifically:
<ul>
<li>The version prefix must be of the form <code>vX.0.0</code>, or derived
from a tag on an ancestor of the named revision, or derived from a tag that
includes <a href="https://semver.org/#spec-item-10">build metadata</a> on
the named revision itself.</li>
<li>The date string must match the UTC timestamp of the revision.</li>
<li>The short name of the revision must use the same number of characters as
what the <code>go</code> command would generate. (For SHA-1 hashes as used
by <code>git</code>, a 12-digit prefix.)</li>
</ul>
</p>
<p>
If a <code>require</code> directive in the
<a href="/cmd/go/#hdr-The_main_module_and_the_build_list">main module</a> uses
an invalid pseudo-version, it can usually be corrected by redacting the
version to just the commit hash and re-running a <code>go</code> command, such
as <code>go</code> <code>list</code> <code>-m</code> <code>all</code>
or <code>go</code> <code>mod</code> <code>tidy</code>. For example,
</p>
<pre>require github.com/docker/docker v1.14.0-0.20190319215453-e7b5f7dbe98c</pre>
<p>can be redacted to</p>
<pre>require github.com/docker/docker e7b5f7dbe98c</pre>
<p>which currently resolves to</p>
<pre>require github.com/docker/docker v0.7.3-0.20190319215453-e7b5f7dbe98c</pre>
<p>
If one of the transitive dependencies of the main module requires an invalid
version or pseudo-version, the invalid version can be replaced with a valid
one using a
<a href="/cmd/go/#hdr-The_go_mod_file"><code>replace</code> directive</a> in
the <code>go.mod</code> file of the main module. If the replacement is a
commit hash, it will be resolved to the appropriate pseudo-version as above.
For example,
</p>
<pre>replace github.com/docker/docker v1.14.0-0.20190319215453-e7b5f7dbe98c => github.com/docker/docker e7b5f7dbe98c</pre>
<p>currently resolves to</p>
<pre>replace github.com/docker/docker v1.14.0-0.20190319215453-e7b5f7dbe98c => github.com/docker/docker v0.7.3-0.20190319215453-e7b5f7dbe98c</pre>
<h3 id="go-command">Go command</h3>
<p id="go-env-w"><!-- CL 171137 -->
The <a href="/cmd/go/#hdr-Environment_variables"><code>go</code> <code>env</code></a>
command now accepts a <code>-w</code> flag to set the per-user default value
of an environment variable recognized by the
<code>go</code> command, and a corresponding <code>-u</code> flag to unset a
previously-set default. Defaults set via
<code>go</code> <code>env</code> <code>-w</code> are stored in the
<code>go/env</code> file within
<a href="/pkg/os/#UserConfigDir"><code>os.UserConfigDir()</code></a>.
</p>
<p id="go-version-exe"><!-- CL 173343 -->
The <a href="/cmd/go/#hdr-Print_Go_version">
<code>go</code> <code>version</code></a> command now accepts arguments naming
executables and directories. When invoked on an executable,
<code>go</code> <code>version</code> prints the version of Go used to build
the executable. If the <code>-m</code> flag is used,
<code>go</code> <code>version</code> prints the executable's embedded module
version information, if available. When invoked on a directory,
<code>go</code> <code>version</code> prints information about executables
contained in the directory and its subdirectories.
</p>
<p id="trimpath"><!-- CL 173345 -->
The new <a href="/cmd/go/#hdr-Compile_packages_and_dependencies"><code>go</code>
<code>build</code> flag</a> <code>-trimpath</code> removes all file system paths
from the compiled executable, to improve build reproducibility.
</p>
<p id="o-dir"><!-- CL 167679 -->
If the <code>-o</code> flag passed to <code>go</code> <code>build</code>
refers to an existing directory, <code>go</code> <code>build</code> will now
write executable files within that directory for <code>main</code> packages
matching its package arguments.
</p>
<p id="comma-separated-tags"><!-- CL 173438 -->
The <code>go</code> <code>build</code> flag <code>-tags</code> now takes a
comma-separated list of build tags, to allow for multiple tags in
<a href="/cmd/go/#hdr-Environment_variables"><code>GOFLAGS</code></a>. The
space-separated form is deprecated but still recognized and will be maintained.
</p>
<p id="go-generate-tag"><!-- CL 175983 -->
<a href="/cmd/go/#hdr-Generate_Go_files_by_processing_source"><code>go</code>
<code>generate</code></a> now sets the <code>generate</code> build tag so that
files may be searched for directives but ignored during build.
</p>
<p id="binary-only"><!-- CL 165746 -->
As <a href="/doc/go1.12#binary-only">announced</a> in the Go 1.12 release
notes, binary-only packages are no longer supported. Building a binary-only
package (marked with a <code>//go:binary-only-package</code> comment) now
results in an error.
</p>
<h3 id="compiler">Compiler toolchain</h3>
<p><!-- CL 170448 -->
The compiler has a new implementation of escape analysis that is
more precise. For most Go code should be an improvement (in other
words, more Go variables and expressions allocated on the stack
instead of heap). However, this increased precision may also break
invalid code that happened to work before (for example, code that
violates
the <a href="/pkg/unsafe/#Pointer"><code>unsafe.Pointer</code>
safety rules</a>). If you notice any regressions that appear
related, the old escape analysis pass can be re-enabled
with <code>go</code> <code>build</code> <code>-gcflags=all=-newescape=false</code>.
The option to use the old escape analysis will be removed in a
future release.
</p>
<p><!-- CL 161904 -->
The compiler no longer emits floating point or complex constants
to <code>go_asm.h</code> files. These have always been emitted in a
form that could not be used as numeric constant in assembly code.
</p>
<h3 id="assembler">Assembler</h3>
<p><!-- CL 157001 -->
The assembler now supports many of the atomic instructions
introduced in ARM v8.1.
</p>
<h3 id="gofmt">gofmt</h3>
<p>
<code>gofmt</code> (and with that <code>go fmt</code>) now canonicalizes
number literal prefixes and exponents to use lower-case letters, but
leaves hexadecimal digits alone. This improves readability when using the new octal prefix
(<code>0O</code> becomes <code>0o</code>), and the rewrite is applied consistently.
<code>gofmt</code> now also removes unnecessary leading zeroes from a decimal integer
imaginary literal. (For backwards-compatibility, an integer imaginary literal
starting with <code>0</code> is considered a decimal, not an octal number.
Removing superfluous leading zeroes avoids potential confusion.)
For instance, <code>0B1010</code>, <code>0XabcDEF</code>, <code>0O660</code>,
<code>1.2E3</code>, and <code>01i</code> become <code>0b1010</code>, <code>0xabcDEF</code>,
<code>0o660</code>, <code>1.2e3</code>, and <code>1i</code> after applying <code>gofmt</code>.
</p>
<h3 id="godoc"><code>godoc</code> and <code>go</code> <code>doc</code></h3>
<p><!-- CL 174322 -->
The <code>godoc</code> webserver is no longer included in the main binary distribution.
To run the <code>godoc</code> webserver locally, manually install it first:
<pre>
go get golang.org/x/tools/cmd/godoc
godoc
</pre>
</p>
<p><!-- CL 177797 -->
The
<a href="/cmd/go/#hdr-Show_documentation_for_package_or_symbol"><code>go</code> <code>doc</code></a>
command now always includes the package clause in its output, except for
commands. This replaces the previous behavior where a heuristic was used,
causing the package clause to be omitted under certain conditions.
</p>
<h2 id="runtime">Runtime</h2>
<p><!-- CL 161477 -->
Out of range panic messages now include the index that was out of
bounds and the length (or capacity) of the slice. For
example, <code>s[3]</code> on a slice of length 1 will panic with
"runtime error: index out of range [3] with length 1".
</p>
<p><!-- CL 171758 -->
This release improves performance of most uses of <code>defer</code>
by 30%.
</p>
<p><!-- CL 142960 -->
The runtime is now more aggressive at returning memory to the
operating system to make it available to co-tenant applications.
Previously, the runtime could retain memory for five or more minutes
following a spike in the heap size. It will now begin returning it
promptly after the heap shrinks. However, on many OSes, including
Linux, the OS itself reclaims memory lazily, so process RSS will not
decrease until the system is under memory pressure.
</p>
<h2 id="library">Core library</h2>
<h3 id="tls_1_3">TLS 1.3</h3>
<p>
As announced in Go 1.12, Go 1.13 enables support for TLS 1.3 in the
<code>crypto/tls</code> package by default. It can be disabled by adding the
value <code>tls13=0</code> to the <code>GODEBUG</code>
environment variable. The opt-out will be removed in Go 1.14.
</p>
<p>
See <a href="/doc/go1.12#tls_1_3">the Go 1.12 release notes</a> for important
compatibility information.
</p>
<h3 id="crypto/ed25519"><a href="/pkg/crypto/ed25519/">crypto/ed25519</a></h3>
<p><!-- CL 174945, 182698 -->
The new <a href="/pkg/crypto/ed25519/"><code>crypto/ed25519</code></a>
package implements the Ed25519 signature
scheme. This functionality was previously provided by the
<a href="https://godoc.org/golang.org/x/crypto/ed25519"><code>golang.org/x/crypto/ed25519</code></a>
package, which becomes a wrapper for
<code>crypto/ed25519</code> when used with Go 1.13+.
</p>
<h3 id="error_wrapping">Error wrapping</h3>
<p><!-- CL 163558, 176998 -->
Go 1.13 contains support for error wrapping, as first proposed in
the <a href="https://go.googlesource.com/proposal/+/master/design/29934-error-values.md">
Error Values proposal</a> and discussed on <a href="https://golang.org/issue/29934">the
associated issue</a>.
</p>
<p>
An error <code>e</code> can <em>wrap</em> another error <code>w</code> by providing
an <code>Unwrap</code> method that returns <code>w</code>. Both <code>e</code>
and <code>w</code> are available to programs, allowing <code>e</code> to provide
additional context to <code>w</code> or to reinterpret it while still allowing
programs to make decisions based on <code>w</code>.
</p>
<p>
To support wrapping, <a href="#fmt"><code>fmt.Errorf</code></a> now has a <code>%w</code>
verb for creating wrapped errors, and three new functions in
the <a href="#errors"><code>errors</code></a> package (
<a href="/pkg/errors/#Unwrap"><code>errors.Unwrap</code></a>,
<a href="/pkg/errors/#Is"><code>errors.Is</code></a> and
<a href="/pkg/errors/#As"><code>errors.As</code></a>) simplify unwrapping
and inspecting wrapped errors.
</p>
<p>
For more information, read the <a href="/pkg/errors/"><code>errors</code> package
documentation</a>, or see
the <a href="https://golang.org/wiki/ErrorValueFAQ">Error Value FAQ</a>.
There will soon be a blog post as well.
</p>
<h3 id="minor_library_changes">Minor changes to the library</h3>
<p>
As always, there are various minor changes and updates to the library,
made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>
in mind.
</p>
<dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>
<dd>
<p>
The new <a href="/pkg/bytes/#ToValidUTF8"><code>ToValidUTF8</code></a> function returns a
copy of a given byte slice with each run of invalid UTF-8 byte sequences replaced by a given slice.
</p>
</dl><!-- bytes -->
<dl id="context"><dt><a href="/pkg/context/">context</a></dt>
<dd>
<p><!-- CL 169080 -->
The formatting of contexts returned by <a href="/pkg/context/#WithValue"><code>WithValue</code></a> no longer depends on <code>fmt</code> and will not stringify in the same way. Code that depends on the exact previous stringification might be affected.
</p>
</dl><!-- context -->
<dl id="crypto/tls"><dt><a href="/pkg/crypto/tls/">crypto/tls</a></dt>
<dd>
<p>
Support for SSL version 3.0 (SSLv3) <a href="https://golang.org/issue/32716">
is now deprecated and will be removed in Go 1.14</a>. Note that SSLv3 is the
<a href="https://tools.ietf.org/html/rfc7568">cryptographically broken</a>
protocol predating TLS.
</p>
<p>
SSLv3 was always disabled by default, other than in Go 1.12, when it was
mistakenly enabled by default server-side. It is now again disabled by
default. (SSLv3 was never supported client-side.)
</p>
<p><!-- CL 177698 -->
Ed25519 certificates are now supported in TLS versions 1.2 and 1.3.
</p>
</dl><!-- crypto/tls -->
<dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>
<dd>
<p><!-- CL 175478 -->
Ed25519 keys are now supported in certificates and certificate requests
according to <a href="https://www.rfc-editor.org/info/rfc8410">RFC 8410</a>, as well as by the
<a href="/pkg/crypto/x509/#ParsePKCS8PrivateKey"><code>ParsePKCS8PrivateKey</code></a>,
<a href="/pkg/crypto/x509/#MarshalPKCS8PrivateKey"><code>MarshalPKCS8PrivateKey</code></a>,
and <a href="/pkg/crypto/x509/#ParsePKIXPublicKey"><code>ParsePKIXPublicKey</code></a> functions.
</p>
<p><!-- CL 169238 -->
The paths searched for system roots now include <code>/etc/ssl/cert.pem</code>
to support the default location in Alpine Linux 3.7+.
</p>
</dl><!-- crypto/x509 -->
<dl id="database/sql"><dt><a href="/pkg/database/sql/">database/sql</a></dt>
<dd>
<p><!-- CL 170699 -->
The new <a href="/pkg/database/sql/#NullTime"><code>NullTime</code></a> type represents a <code>time.Time</code> that may be null.
</p>
<p><!-- CL 174178 -->
The new <a href="/pkg/database/sql/#NullInt32"><code>NullInt32</code></a> type represents an <code>int32</code> that may be null.
</p>
</dl><!-- database/sql -->
<dl id="debug/dwarf"><dt><a href="/pkg/debug/dwarf/">debug/dwarf</a></dt>
<dd>
<p><!-- CL 158797 -->
The <a href="/pkg/debug/dwarf/#Data.Type"><code>Data.Type</code></a>
method no longer panics if it encounters an unknown DWARF tag in
the type graph. Instead, it represents that component of the
type with
an <a href="/pkg/debug/dwarf/#UnsupportedType"><code>UnsupportedType</code></a>
object.
</p>
</dl><!-- debug/dwarf -->
<dl id="errors"><dt><a href="/pkg/errors/">errors</a></dt>
<dd>
<!-- CL 163558 -->
<p>
The new function <a href="/pkg/errors/#As"><code>As</code></a> finds the first
error in a given error’s chain (sequence of wrapped errors)
that matches a given target’s type, and if so, sets the target to that error value.
</p>
<p>
The new function <a href="/pkg/errors/#Is"><code>Is</code></a> reports whether a given error value matches an
error in another’s chain.
</p>
<p>
The new function <a href="/pkg/errors/#Unwrap"><code>Unwrap</code></a> returns the result of calling
<code>Unwrap</code> on a given error, if one exists.
</p>
</dl><!-- errors -->
<dl id="fmt"><dt><a href="/pkg/fmt/">fmt</a></dt>
<dd>
<!-- CL 160245 -->
<p>
The printing verbs <code>%x</code> and <code>%X</code> now format floating-point and
complex numbers in hexadecimal notation, in lower-case and upper-case respectively.
</p>
<!-- CL 160246 -->
<p>
The new printing verb <code>%O</code> formats integers in base 8, emitting the <code>0o</code> prefix.
</p>
<!-- CL 160247 -->
<p>
The scanner now accepts hexadecimal floating-point values, digit-separating underscores
and leading <code>0b</code> and <code>0o</code> prefixes.
See the <a href="#language">Changes to the language</a> for details.
</p>
<!-- CL 176998 -->
<p>The <a href="/pkg/fmt/#Errorf"><code>Errorf</code></a> function
has a new verb, <code>%w</code>, whose operand must be an error.
The error returned from <code>Errorf</code> will have an
<code>Unwrap</code> method which returns the operand of <code>%w</code>.
</p>
</dl><!-- fmt -->
<dl id="go/scanner"><dt><a href="/pkg/go/scanner/">go/scanner</a></dt>
<dd>
<p><!-- CL 175218 -->
The scanner has been updated to recognize the new Go number literals, specifically
binary literals with <code>0b</code>/<code>0B</code> prefix, octal literals with <code>0o</code>/<code>0O</code> prefix,
and floating-point numbers with hexadecimal mantissa. The imaginary suffix <code>i</code> may now be used with any number
literal, and underscores may used as digit separators for grouping.
See the <a href="#language">Changes to the language</a> for details.
</p>
</dl><!-- go/scanner -->
<dl id="go/types"><dt><a href="/pkg/go/types/">go/types</a></dt>
<dd>
<p>
The type-checker has been updated to follow the new rules for integer shifts.
See the <a href="#language">Changes to the language</a> for details.
</p>
</dl><!-- go/types -->
<dl id="html/template"><dt><a href="/pkg/html/template/">html/template</a></dt>
<dd>
<p><!-- CL 175218 -->
When using a <code><script></code> tag with "module" set as the
type attribute, code will now be interpreted as <a href="https://html.spec.whatwg.org/multipage/scripting.html#the-script-element:module-script-2">JavaScript module script</a>.
</p>
</dl><!-- html/template -->
<dl id="log"><dt><a href="/pkg/log/">log</a></dt>
<dd>
<p><!-- CL 168920 -->
The new <a href="/pkg/log/#Writer"><code>Writer</code></a> function returns the output destination for the standard logger.
</p>
</dl><!-- log -->
<dl id="math/big"><dt><a href="/pkg/math/big/">math/big</a></dt>
<dd>
<p><!-- CL 160682 -->
The new <a href="/pkg/math/big/#Rat.SetUint64"><code>Rat.SetUint64</code></a> method sets the <code>Rat</code> to a <code>uint64</code> value.
</p>
<p><!-- CL 166157 -->
For <a href="/pkg/math/big/#Float.Parse"><code>Float.Parse</code></a>, if base is 0, underscores
may be used between digits for readability.
See the <a href="#language">Changes to the language</a> for details.
</p>
<p><!-- CL 166157 -->
For <a href="/pkg/math/big/#Int.SetString"><code>Int.SetString</code></a>, if base is 0, underscores
may be used between digits for readability.
See the <a href="#language">Changes to the language</a> for details.
</p>
<p><!-- CL 168237 -->
<a href="/pkg/math/big/#Rat.SetString"><code>Rat.SetString</code></a> now accepts non-decimal floating point representations.
</p>
</dl><!-- math/big -->
<dl id="math/bits"><dt><a href="/pkg/math/bits/">math/bits</a></dt>
<dd>
<p><!-- CL 178177 -->
The execution time of <a href="/pkg/math/bits/#Add"><code>Add</code></a>,
<a href="/pkg/math/bits/#Sub"><code>Sub</code></a>,
<a href="/pkg/math/bits/#Mul"><code>Mul</code></a>,
<a href="/pkg/math/bits/#RotateLeft"><code>RotateLeft</code></a>, and
<a href="/pkg/math/bits/#ReverseBytes"><code>ReverseBytes</code></a> is now
guaranteed to be independent of the inputs.
</p>
</dl><!-- math/bits -->
<dl id="net"><dt><a href="/pkg/net/">net</a></dt>
<dd>
<p><!-- CL 156366 -->
On Unix systems where <code>use-vc</code> is set in <code>resolv.conf</code>, TCP is used for DNS resolution.
</p>
<p><!-- CL 170678 -->
The new field <a href="/pkg/net/#ListenConfig.KeepAlive"><code>ListenConfig.KeepAlive</code></a>
specifies the keep-alive period for network connections accepted by the listener.
If this field is 0 (the default) TCP keep-alives will be enabled.
To disable them, set it to a negative value.
</p>
<p>
Note that the error returned from I/O on a connection that was
closed by a keep-alive timeout will have a
<code>Timeout</code> method that returns <code>true</code> if called.
This can make a keep-alive error difficult to distinguish from
an error returned due to a missed deadline as set by the
<a href="/pkg/net/#Conn"><code>SetDeadline</code></a>
method and similar methods.
Code that uses deadlines and checks for them with
the <code>Timeout</code> method or
with <a href="/pkg/os/#IsTimeout"><code>os.IsTimeout</code></a>
may want to disable keep-alives, or
use <code>errors.Is(syscall.ETIMEDOUT)</code> (on Unix systems)
which will return true for a keep-alive timeout and false for a
deadline timeout.
</p>
</dl><!-- net -->
<dl id="net/http"><dt><a href="/pkg/net/http/">net/http</a></dt>
<dd>
<p><!-- CL 76410 -->
The new fields <a href="/pkg/net/http/#Transport.WriteBufferSize"><code>Transport.WriteBufferSize</code></a>
and <a href="/pkg/net/http/#Transport.ReadBufferSize"><code>Transport.ReadBufferSize</code></a>
allow one to specify the sizes of the write and read buffers for a <a href="/pkg/net/http/#Transport"><code>Transport</code></a>.
If either field is zero, a default size of 4KB is used.
</p>
<p><!-- CL 130256 -->
The new field <a href="/pkg/net/http/#Transport.ForceAttemptHTTP2"><code>Transport.ForceAttemptHTTP2</code></a>
controls whether HTTP/2 is enabled when a non-zero <code>Dial</code>, <code>DialTLS</code>, or <code>DialContext</code>
func or <code>TLSClientConfig</code> is provided.
</p>
<p><!-- CL 140357 -->
<a href="/pkg/net/http/#Transport.MaxConnsPerHost"><code>Transport.MaxConnsPerHost</code></a> now works
properly with HTTP/2.
</p>
<p><!-- CL 154383 -->
<a href="/pkg/net/http/#TimeoutHandler"><code>TimeoutHandler</code></a>'s
<a href="/pkg/net/http/#ResponseWriter"><code>ResponseWriter</code></a> now implements the
<a href="/pkg/net/http/#Pusher"><code>Pusher</code></a> and <a href="/pkg/net/http/#Flusher"><code>Flusher</code></a> interfaces.
</p>
<p><!-- CL 157339 -->
The <code>StatusCode</code> <code>103</code> <code>"Early Hints"</code> has been added.
</p>
<p><!-- CL 163599 -->
<a href="/pkg/net/http/#Transport"><code>Transport</code></a> now uses the <a href="/pkg/net/http/#Request.Body"><code>Request.Body</code></a>'s
<a href="/pkg/io/#ReaderFrom"><code>io.ReaderFrom</code></a> implementation if available, to optimize writing the body.
</p>
<p><!-- CL 167017 -->
On encountering unsupported transfer-encodings, <a href="/pkg/net/http/#Server"><code>http.Server</code></a> now
returns a "501 Unimplemented" status as mandated by the HTTP specification <a href="https://tools.ietf.org/html/rfc7230#section-3.3.1">RFC 7230 Section 3.3.1</a>.
</p>
<p><!-- CL 167681 -->
The new <a href="/pkg/net/http/#Server"><code>Server</code></a> fields
<a href="/pkg/net/http/#Server.BaseContext"><code>BaseContext</code></a> and
<a href="/pkg/net/http/#Server.ConnContext"><code>ConnContext</code></a>
allow finer control over the <a href="/pkg/context/#Context"><code>Context</code></a> values provided to requests and connections.
</p>
<p><!-- CL 167781 -->
<a href="/pkg/net/http/#DetectContentType"><code>http.DetectContentType</code></a> now correctly detects RAR signatures, and can now also detect RAR v5 signatures.
</p>
<p><!-- CL 173658 -->
The new <a href="/pkg/net/http/#Header"><code>Header</code></a> method
<a href="/pkg/net/http/#Header.Clone"><code>Clone</code></a> returns a copy of the receiver.
</p>
<p><!-- CL 174324 -->
A new function <a href="/pkg/net/http/#NewRequestWithContext"><code>NewRequestWithContext</code></a> has been added and it
accepts a <a href="/pkg/context/#Context"><code>Context</code></a> that controls the entire lifetime of
the created outgoing <a href="/pkg/net/http/#Request"><code>Request</code></a>, suitable for use with
<a href="/pkg/net/http/#Client.Do"><code>Client.Do</code></a> and <a href="/pkg/net/http/#Transport.RoundTrip"><code>Transport.RoundTrip</code></a>.
</p>
<p><!-- CL 179457 -->
The <a href="/pkg/net/http/#Transport"><code>Transport</code></a> no longer logs errors when servers
gracefully shut down idle connections using a <code>"408 Request Timeout"</code> response.
</p>
</dl><!-- net/http -->
<dl id="os"><dt><a href="/pkg/os/">os</a></dt>
<dd>
<p><!-- CL 160877 -->
The new <a href="/pkg/os/#UserConfigDir"><code>UserConfigDir</code></a> function
returns the default directory to use for user-specific configuration data.
</p>
<p><!-- CL 166578 -->
If a <a href="/pkg/os/#File"><code>File</code></a> is opened using the O_APPEND flag, its
<a href="/pkg/os/#File.WriteAt"><code>WriteAt</code></a> method will always return an error.
</p>
</dl><!-- os -->
<dl id="os/exec"><dt><a href="/pkg/os/exec/">os/exec</a></dt>
<dd>
<p><!-- CL 174318 -->
On Windows, the environment for a <a href="/pkg/os/exec/#Cmd"><code>Cmd</code></a> always inherits the
<code>%SYSTEMROOT%</code> value of the parent process unless the
<a href="/pkg/os/exec/#Cmd.Env"><code>Cmd.Env</code></a> field includes an explicit value for it.
</p>
</dl><!-- os/exec -->
<dl id="reflect"><dt><a href="/pkg/reflect/">reflect</a></dt>
<dd>
<p><!-- CL 171337 -->
The new <a href="/pkg/reflect/#Value.IsZero"><code>Value.IsZero</code></a> method reports whether a <code>Value</code> is the zero value for its type.
</p>
<p><!-- CL 174531 -->
The <a href="/pkg/reflect/#MakeFunc"><code>MakeFunc</code></a> function now allows assignment conversions on returned values, instead of requiring exact type match. This is particularly useful when the type being returned is an interface type, but the value actually returned is a concrete value implementing that type.
</p>
</dl><!-- reflect -->
<dl id="runtime"><dt><a href="/pkg/runtime/">runtime</a></dt>
<dd>
<p> <!-- CL 167780 -->
Tracebacks, <a href="/pkg/runtime/#Caller"><code>runtime.Caller</code></a>,
and <a href="/pkg/runtime/#Callers"><code>runtime.Callers</code></a> now refer to the function that
initializes the global variables of <code>PKG</code>
as <code>PKG.init</code> instead of <code>PKG.init.ializers</code>.
</p>
</dl><!-- runtime -->
<dl id="strconv"><dt><a href="/pkg/strconv/">strconv</a></dt>
<dd>
<p><!-- CL 160243 -->
For <a href="/pkg/strconv/#ParseFloat"><code>strconv.ParseFloat</code></a>,
<a href="/pkg/strconv/#ParseInt"><code>strconv.ParseInt</code></a>
and <a href="/pkg/strconv/#ParseUint"><code>strconv.ParseUint</code></a>,
if base is 0, underscores may be used between digits for readability.
See the <a href="#language">Changes to the language</a> for details.
</p>
</dl><!-- strconv -->
<dl id="strings"><dt><a href="/pkg/strings/">strings</a></dt>
<dd>
<p><!-- CL 142003 -->
The new <a href="/pkg/strings/#ToValidUTF8"><code>ToValidUTF8</code></a> function returns a
copy of a given string with each run of invalid UTF-8 byte sequences replaced by a given string.
</p>
</dl><!-- strings -->
<dl id="sync"><dt><a href="/pkg/sync/">sync</a></dt>
<dd>
<p><!-- CL 148958, CL 148959, CL 152697, CL 152698 -->
The fast paths of <a href="/pkg/sync/#Mutex.Lock"><code>Mutex.Lock</code></a>, <a href="/pkg/sync/#Mutex.Unlock"><code>Mutex.Unlock</code></a>,
<a href="/pkg/sync/#RWMutex.Lock"><code>RWMutex.Lock</code></a>, <a href="/pkg/sync/#Mutex.RUnlock"><code>RWMutex.RUnlock</code></a>, and
<a href="/pkg/sync/#Once.Do"><code>Once.Do</code></a> are now inlined in their callers.
For the uncontended cases on amd64, these changes make <a href="/pkg/sync/#Once.Do"><code>Once.Do</code></a> twice as fast, and the
<a href="/pkg/sync/#Mutex"><code>Mutex</code></a>/<a href="/pkg/sync/#RWMutex"><code>RWMutex</code></a> methods up to 10% faster.
</p>
<p><!-- CL 166960 -->
Large <a href="/pkg/sync/#Pool"><code>Pool</code></a> no longer increase stop-the-world pause times.
</p>
<p><!-- CL 166961 -->
<code>Pool</code> no longer needs to be completely repopulated after every GC. It now retains some objects across GCs,
as opposed to releasing all objects, reducing load spikes for heavy users of <code>Pool</code>.
</p>
</dl><!-- sync -->
<dl id="syscall"><dt><a href="/pkg/syscall/">syscall</a></dt>
<dd>
<p><!-- CL 168479 -->
Uses of <code>_getdirentries64</code> have been removed from
Darwin builds, to allow Go binaries to be uploaded to the macOS
App Store.
</p>
<p><!-- CL 174197 -->
The new <code>ProcessAttributes</code> and <code>ThreadAttributes</code> fields in
<a href="/pkg/syscall/?GOOS=windows#SysProcAttr"><code>SysProcAttr</code></a> have been introduced for Windows,
exposing security settings when creating new processes.
</p>
<p><!-- CL 174320 -->
<code>EINVAL</code> is no longer returned in zero
<a href="/pkg/syscall/?GOOS=windows#Chmod"><code>Chmod</code></a> mode on Windows.
</p>
<p><!-- CL 191337 -->
Values of type <code>Errno</code> can be tested against error values in
the <code>os</code> package,
like <a href="/pkg/os/#ErrExist"><code>ErrExist</code></a>, using
<a href="/pkg/errors/#Is"><code>errors.Is</code></a>.
</p>
</dl><!-- syscall -->
<dl id="syscall/js"><dt><a href="/pkg/syscall/js/">syscall/js</a></dt>