qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-11 18:21:40 -07:00
Code Releases Activity

[release-branch.go1.10] doc: sync with master

Browse Source 
A number of changes were applied to documentation in master, including
a wide rewrite of the contribution guide. Backport them all to get them
deployed on golang.org.

$ git ch master -- doc
$ git show-ref master
88756931d0 refs/heads/master

Change-Id: Ib45ff191f3b60723aa4421113992289c37d144aa
Reviewed-on: https://go-review.googlesource.com/114503
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
Run-TryBot: Andrew Bonventre <andybons@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
This commit is contained in:
Filippo Valsorda 2018-05-25 15:07:15 -04:00
parent 09fa131c99
commit 48ee689f19
13 changed files with 1190 additions and 796 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/articles/wiki/index.html
View File

@ -268,6 +268,12 @@ view a wiki page. It will handle URLs prefixed with "/view/".
{{code "doc/articles/wiki/part2.go" `/^func viewHandler/` `/^}/`}}
<p>
Again, note the use of <code>_</code> to ignore the <code>error</code>
return value from <code>loadPage</code>. This is done here for simplicity
and generally considered bad practice. We will attend to this later.
</p>
<p>
First, this function extracts the page title from <code>r.URL.Path</code>,
the path component of the request URL.
@ -282,12 +288,6 @@ The function then loads the page data, formats the page with a string of simple
HTML, and writes it to <code>w</code>, the <code>http.ResponseWriter</code>.
</p>
<p>
Again, note the use of <code>_</code> to ignore the <code>error</code>
return value from <code>loadPage</code>. This is done here for simplicity
and generally considered bad practice. We will attend to this later.
</p>
<p>
To use this handler, we rewrite our <code>main</code> function to
initialize <code>http</code> using the <code>viewHandler</code> to handle

65
doc/asm.html
View File

@ -738,6 +738,13 @@ The other codes are <code>-&gt;</code> (arithmetic right shift),
The ARM64 port is in an experimental state.
</p>
<p>
<code>R18</code> is the "platform register", reserved on the Apple platform.
<code>R27</code> and <code>R28</code> are reserved by the compiler and linker.
<code>R29</code> is the frame pointer.
<code>R30</code> is the link register.
</p>
<p>
Instruction modifiers are appended to the instruction following a period.
The only modifiers are <code>P</code> (postincrement) and <code>W</code>
@ -752,11 +759,61 @@ Addressing modes:
<ul>
<li>
<code>(R5, R6)</code>: Register pair for <code>LDP</code>/<code>STP</code>.
<code>R0-&gt;16</code>
<br>
<code>R0&gt;&gt;16</code>
<br>
<code>R0&lt;&lt;16</code>
<br>
<code>R0@&gt;16</code>:
These are the same as on the 32-bit ARM.
</li>
<li>
<code>$(8&lt;&lt;12)</code>:
Left shift the immediate value <code>8</code> by <code>12</code> bits.
</li>
<li>
<code>8(R0)</code>:
Add the value of <code>R0</code> and <code>8</code>.
</li>
<li>
<code>(R2)(R0)</code>:
The location at <code>R0</code> plus <code>R2</code>.
</li>
<li>
<code>R0.UXTB</code>
<br>
<code>R0.UXTB&lt;&lt;imm</code>:
<code>UXTB</code>: extract an 8-bit value from the low-order bits of <code>R0</code> and zero-extend it to the size of <code>R0</code>.
<code>R0.UXTB&lt;&lt;imm</code>: left shift the result of <code>R0.UXTB</code> by <code>imm</code> bits.
The <code>imm</code> value can be 0, 1, 2, 3, or 4.
The other extensions include <code>UXTH</code> (16-bit), <code>UXTW</code> (32-bit), and <code>UXTX</code> (64-bit).
</li>
<li>
<code>R0.SXTB</code>
<br>
<code>R0.SXTB&lt;&lt;imm</code>:
<code>SXTB</code>: extract an 8-bit value from the low-order bits of <code>R0</code> and sign-extend it to the size of <code>R0</code>.
<code>R0.SXTB&lt;&lt;imm</code>: left shift the result of <code>R0.SXTB</code> by <code>imm</code> bits.
The <code>imm</code> value can be 0, 1, 2, 3, or 4.
The other extensions include <code>SXTH</code> (16-bit), <code>SXTW</code> (32-bit), and <code>SXTX</code> (64-bit).
</li>
<li>
<code>(R5, R6)</code>: Register pair for <code>LDAXP</code>/<code>LDP</code>/<code>LDXP</code>/<code>STLXP</code>/<code>STP</code>/<code>STP</code>.
</li>
</ul>
<p>
Reference: <a href="/pkg/cmd/internal/obj/arm64">Go ARM64 Assembly Instructions Reference Manual</a>
</p>
<h3 id="ppc64">64-bit PowerPC, a.k.a. ppc64</h3>
<p>
@ -882,6 +939,12 @@ The value of <code>GOMIPS</code> environment variable (<code>hardfloat</code> or
<code>GOMIPS_hardfloat</code> or <code>GOMIPS_softfloat</code>.
</p>
<p>
The value of <code>GOMIPS64</code> environment variable (<code>hardfloat</code> or
<code>softfloat</code>) is made available to assembly code by predefining either
<code>GOMIPS64_hardfloat</code> or <code>GOMIPS64_softfloat</code>.
</p>
<h3 id="unsupported_opcodes">Unsupported opcodes</h3>
<p>

1780
doc/contribute.html
View File

File diff suppressed because it is too large Load Diff

8
doc/devel/release.html
View File

@ -16,11 +16,11 @@ git checkout <i>release-branch</i>
<p>
Each major Go release is supported until there are two newer major releases.
For example, Go 1.8 is supported until Go 1.10 is released,
and Go 1.9 is supported until Go 1.11 is released.
For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was
supported until the Go 1.8 release.
We fix critical problems, including <a href="/security">critical security problems</a>,
in supported releases as needed by issuing minor revisions
(for example, Go 1.9.1, Go 1.9.2, and so on).
(for example, Go 1.6.1, Go 1.6.2, and so on).
</p>
<h2 id="go1.10">go1.10 (released 2018/02/16)</h2>
@ -153,7 +153,7 @@ See the <a href="https://github.com/golang/go/issues?q=milestone%3AGo1.8.5">Go
</p>
<p>
go1.8.6 (released 2018/01/22) includes the the same fix in <code>math/big</code>
go1.8.6 (released 2018/01/22) includes the same fix in <code>math/big</code>
as Go 1.9.3 and was released at the same time.
See the <a href="https://github.com/golang/go/issues?q=milestone%3AGo1.8.6">Go
1.8.6 milestone</a> on our issue tracker for details.

3
doc/effective_go.html
View File

@ -3588,8 +3588,7 @@ That's left as an exercise for the reader.
<p>
Let's finish with a complete Go program, a web server.
This one is actually a kind of web re-server.
Google provides a service at
<a href="http://chart.apis.google.com">http://chart.apis.google.com</a>
Google provides a service at <code>chart.apis.google.com</code>
that does automatic formatting of data into charts and graphs.
It's hard to use interactively, though,
because you need to put the data into the URL as a query.

4
doc/go1.10.html
View File

@ -43,9 +43,9 @@ There are no significant changes to the language specification.
</p>
<p><!-- CL 60230 -->
A corner case involving shifts by untyped constants has been clarified,
A corner case involving shifts of untyped constants has been clarified,
and as a result the compilers have been updated to allow the index expression
<code>x[1.0</code>&nbsp;<code>&lt;&lt;</code>&nbsp;<code>s]</code> where <code>s</code> is an untyped constant;
<code>x[1.0</code>&nbsp;<code>&lt;&lt;</code>&nbsp;<code>s]</code> where <code>s</code> is an unsigned integer;
the <a href="/pkg/go/types/">go/types</a> package already did.
</p>

66
doc/go_faq.html
View File

@ -45,7 +45,7 @@ analysis easy and avoids much of the overhead of C-style include files and
libraries.
<li>
Go's type system has no hierarchy, so no time is spent defining the
relationships between types. Also, although Go has static types the language
relationships between types. Also, although Go has static types, the language
attempts to make types feel lighter weight than in typical OO languages.
<li>
Go is fully garbage-collected and provides fundamental support for
@ -1097,24 +1097,27 @@ The <code>go get</code> command therefore uses HTTPS for safety.
</p>
<p>
If you use <code>git</code> and prefer to push changes through SSH using your existing key
it's easy to work around this. For GitHub, try one of these solutions:
<code>Git</code> can be configured to authenticate over HTTPS or to use SSH in place of HTTPS.
To authenticate over HTTPS, you can add a line
to the <code>$HOME/.netrc</code> file that git consults:
</p>
<ul>
<li>Manually clone the repository in the expected package directory:
<pre>
$ cd src/github.com/username
$ git clone git@github.com:username/package.git
machine github.com login <i>USERNAME</i> password <i>APIKEY</i>
</pre>
</li>
<li>Force <code>git push</code> to use the <code>SSH</code> protocol by appending
these two lines to <code>~/.gitconfig</code>:
<p>
For GitHub accounts, the password can be a
<a href="https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/">personal access token</a>.
</p>
<p>
<code>Git</code> can also be configured to use SSH in place of HTTPS for URLs matching a given prefix.
For example, to use SSH for all GitHub access,
add these lines to your <code>~/.gitconfig</code>:
</p>
<pre>
[url "git@github.com:"]
pushInsteadOf = https://github.com/
[url "ssh://git@github.com/"]
insteadOf = https://github.com/
</pre>
</li>
</ul>
<h3 id="get_version">
How should I manage package versions using "go get"?</h3>
@ -1852,18 +1855,19 @@ Why is my trivial program such a large binary?</h3>
<p>
The linker in the <code>gc</code> toolchain
creates statically-linked binaries by default. All Go binaries therefore include the Go
creates statically-linked binaries by default.
All Go binaries therefore include the Go
run-time, along with the run-time type information necessary to support dynamic
type checks, reflection, and even panic-time stack traces.
</p>
<p>
A simple C "hello, world" program compiled and linked statically using gcc
on Linux is around 750 kB,
including an implementation of <code>printf</code>.
An equivalent Go program using <code>fmt.Printf</code>
is around 1.5 MB, but
that includes more powerful run-time support and type information.
A simple C "hello, world" program compiled and linked statically using
gcc on Linux is around 750 kB, including an implementation of
<code>printf</code>.
An equivalent Go program using
<code>fmt.Printf</code> weighs a couple of megabytes, but that includes
more powerful run-time support and type and debugging information.
</p>
<h3 id="unused_variables_and_imports">
@ -1931,6 +1935,26 @@ eliminating the unused imports issue in practice.
This program is easily connected to most editors to run automatically when a Go source file is written.
</p>
<h3 id="virus">
Why does my virus-scanning software think my Go distribution or compiled binary is infected?</h3>
<p>
This is a common occurrence, especially on Windows machines, and is almost always a false positive.
Commercial virus scanning programs are often confused by the structure of Go binaries, which
they don't see as often as those compiled from other languages.
</p>
<p>
If you've just installed the Go distribution and the system reports it is infected, that's certainly a mistake.
To be really thorough, you can verify the download by comparing the checksum with those on the
<a href="https://golang.org/dl/">downloads page</a>.
</p>
<p>
In any case, if you believe the report is in error, please report a bug to the supplier of your virus scanner.
Maybe in time virus scanners can learn to understand Go programs.
</p>
<h2 id="Performance">Performance</h2>
<h3 id="Why_does_Go_perform_badly_on_benchmark_x">

22
doc/go_spec.html
View File

@ -1,6 +1,6 @@
<!--{
"Title": "The Go Programming Language Specification",
"Subtitle": "Version of February 1, 2018",
"Subtitle": "Version of May 9, 2018",
"Path": "/ref/spec"
}-->
@ -3051,7 +3051,6 @@ used in an <a href="#Assignments">assignment</a> or initialization of the specia
v, ok = a[x]
v, ok := a[x]
var v, ok = a[x]
var v, ok T = a[x]
</pre>
<p>
@ -4161,11 +4160,6 @@ operands and are evaluated at compile time.
Untyped boolean, numeric, and string constants may be used as operands
wherever it is legal to use an operand of boolean, numeric, or string type,
respectively.
Except for shift operations, if the operands of a binary operation are
different kinds of untyped constants, the operation and, for non-boolean operations, the result use
the kind that appears later in this list: integer, rune, floating-point, complex.
For example, an untyped integer constant divided by an
untyped complex constant yields an untyped complex constant.
</p>
<p>
@ -4175,9 +4169,17 @@ an untyped boolean constant. If the left operand of a constant
result is an integer constant; otherwise it is a constant of the same
type as the left operand, which must be of
<a href="#Numeric_types">integer type</a>.
Applying all other operators to untyped constants results in an untyped
constant of the same kind (that is, a boolean, integer, floating-point,
complex, or string constant).
</p>
<p>
Any other operation on untyped constants results in an untyped constant of the
same kind; that is, a boolean, integer, floating-point, complex, or string
constant.
If the untyped operands of a binary operation (other than a shift) are of
different kinds, the result is of the operand's kind that appears later in this
list: integer, rune, floating-point, complex.
For example, an untyped integer constant divided by an
untyped complex constant yields an untyped complex constant.
</p>
<pre>

2
doc/install-source.html
View File

@ -307,7 +307,7 @@ package main
import "fmt"
func main() {
fmt.Printf("hello, world\n")
fmt.Printf("hello, world\n")
}
</pre>

12
doc/install.html
View File

@ -106,6 +106,14 @@ variable. You can do this by adding this line to your <code>/etc/profile</code>
export PATH=$PATH:/usr/local/go/bin
</pre>
<p>
<b>Note</b>: changes made to a <code>profile</code> file may not apply until the
next time you log into your computer.
To apply the changes immediately, just run the shell commands directly
or execute them from the profile using a command such as
<code>source $HOME/.profile</code>.
</p>
<h4 id="tarball_non_standard">Installing to a custom location</h4>
<p>
@ -236,7 +244,7 @@ package main
import "fmt"
func main() {
fmt.Printf("hello, world\n")
fmt.Printf("hello, world\n")
}
</pre>
@ -278,7 +286,7 @@ If you see the "hello, world" message then your Go installation is working.
<p>
You can run <code>go</code> <code>install</code> to install the binary into
your workspace's <code>bin</code> directory
or <code>go</code> <code>clean</code> to remove it.
or <code>go</code> <code>clean</code> <code>-i</code> to remove it.
</p>
<p>

4
doc/progs/error2.go
View File

@ -20,11 +20,11 @@ func viewRecord(w http.ResponseWriter, r *http.Request) {
key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
record := new(Record)
if err := datastore.Get(c, key, record); err != nil {
http.Error(w, err.Error(), 500)
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
if err := viewTemplate.Execute(w, record); err != nil {
http.Error(w, err.Error(), 500)
http.Error(w, err.Error(), http.StatusInternalServerError)
}
}

2
doc/progs/error3.go
View File

@ -33,7 +33,7 @@ type appHandler func(http.ResponseWriter, *http.Request) error
func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if err := fn(w, r); err != nil {
http.Error(w, err.Error(), 500)
http.Error(w, err.Error(), http.StatusInternalServerError)
}
}

6
doc/root.html
View File

@ -74,7 +74,7 @@ Linux, Mac OS X, Windows, and more.
<div class="left">
<div id="video">
<div class="rootHeading">Featured video</div>
<iframe width="415" height="241" src="//www.youtube.com/embed/ytEkHepK08c" frameborder="0" allowfullscreen></iframe>
<div class="js-frontpage-video" style="--aspect-ratio-padding: 58.07%;"><iframe width="415" height="241" src="//www.youtube.com/embed/ytEkHepK08c" frameborder="0" allowfullscreen></iframe></div>
</div>
</div>
@ -153,6 +153,10 @@ Linux, Mac OS X, Windows, and more.
];
var v = videos[Math.floor(Math.random()*videos.length)];
$('#video iframe').attr('height', v.h).attr('src', v.s);
// Compute the aspect ratio (as a percentage) of the video
// using the fixed width 415 and the height of the current video, v.h.
var ar = 100*v.h/415;
$('.js-frontpage-video').attr('style', '--aspect-ratio-padding: ' + ar + '%;');
});
{{end}}