doc: describe platform-specific conventions in code.html

R=r, rsc, gri
CC=golang-dev
https://golang.org/cl/4257049

doc/code.html

@@ -322,3 +322,47 @@ reported.
 See the <a href="/cmd/gotest/">gotest documentation</a> and the 
 <a href="/pkg/testing/">testing package</a> for more detail.
 </p>
+
+<h2 id="arch_os_specific">Architecture- and operating system-specific code</h2>
+
+<p>First, a disclaimer: very few Go packages should need to know about the
+hardware and operating system they run on.  In the vast majority of cases the
+language and standard library handle most portability issues.  This section is
+a guide for experienced systems programmers who have a good reason to write
+platform-specific code, such as assembly-language support for fast
+trigonometric functions or code that implements a common interface above
+different operating systems.</p>
+
+<p>To compile such code, use the <code>$GOOS</code> and <code>$GOARCH</code>
+<a href="/doc/install.html#environment">environment variables</a> in your
+source file names and <code>Makefile</code>.</p>
+
+<p>For example, this <code>Makefile</code> describes a package that builds on
+different operating systems by parameterizing the file name with
+<code>$GOOS</code>.</p>
+
+<pre>
+include $(GOROOT)/src/Make.inc
+
+TARG=mypackage
+GOFILES=\
+	my.go\
+	my_$(GOOS).go\
+
+include $(GOROOT)/src/Make.pkg
+</pre>
+
+<p>The OS-specific code goes in <code>my_linux.go</code>,
+<code>my_darwin.go</code>, and so on.</p>
+
+<p>If you follow these conventional parameterizations, tools such as
+<a href="/cmd/goinstall/">goinstall</a> will work seamlessly with your package:
+</p>
+
+<pre>
+my_$(GOOS).go
+my_$(GOARCH).go
+my_$(GOOS)_$(GOARCH).go
+</pre>
+
+<p>The same holds for <code>.s</code> (assembly) and <code>.cgo</code> files.</p>