Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fix the intro and stuff for Go 1

  • Loading branch information...
commit f1d9418c10f15dd2dd003d70e51476f73e9bfd4b 1 parent 78c103e
@miekg miekg authored
Showing with 73 additions and 120 deletions.
  1. +21 −17 ex-intro/ex-doc.tex
  2. +1 −0  go-basics.tex
  3. +37 −89 go-intro.tex
  4. +14 −14 go.bib
View
38 ex-intro/ex-doc.tex
@@ -4,36 +4,40 @@
Go's documentation can be read with the \prog{go doc} program, which is
included the Go distribution.
-\prog{go doc hash} gives information about the \package{hash} package. Reading the
-documentation on \package{compress} gives the following result:
+\prog{go doc hash} gives information about the \package{hash} package:
\vskip\baselineskip
\begin{display}
-\pr \user{go doc compress}
+\pr \user{go doc hash}
+PACKAGE
+
+package hash
+
+...
+...
+...
+
SUBDIRECTORIES
- bzip2
- flate
- gzip
- lzw
- testdata
- zlib
+ adler32
+ crc32
+ crc64
+ fnv
+
\end{display}
\vskip\baselineskip
-With which \prog{go doc} command can you read the documentation of \package{gzip} contained in
-\package{compress}?
+With which \prog{go doc} command can you read the documentation of \package{fnv} contained in
+\package{hash}?
\end{Exercise}
\begin{Answer}
\Question
-The package \package{gzip} is in a \emph{subdirectory} of
-\package{compress}, so you will only need\quad \texttt{go doc compress/gzip}.
+The package \package{fnv} is in a \emph{subdirectory} of
+\package{hash}, so you will only need\quad \texttt{go doc hash/fnv}.
Specific functions inside the ``Go manual'' can also be accessed. For
instance the function \func{Printf} is described in \package{fmt}, but to
-only view the documentation concerning this function use: \prog{go doc fmt Printf}{} .
-
-You can even display the source code with: \prog{go doc -src fmt Printf} .
+only view the documentation concerning this function use: \prog{godoc fmt Printf}{} .
-All the built-in functions are also accesible by using go doc: \prog{go doc builtin}.
+All the built-in functions are also accesible by using \prog{godoc}: \prog{godoc builtin}.
\end{Answer}
View
1  go-basics.tex
@@ -334,6 +334,7 @@ \subsection{Errors}
Go has a builtin type specially for errors, called \lstinline{error}.
\section{Operators and built-in functions}
+\label{sec:builtins}
Go supports the normal set of numerical operations,
table \ref{tab:op-precedence}
lists the current ones and their relative precedence. They
View
126 go-intro.tex
@@ -14,8 +14,8 @@
interpreted language.
\end{quote}
-Go1 is the first stable release of the language Go.
-This document and all exercises work with Go1 -- if not, its
+Go 1 is the first stable release of the language Go.
+This document and all exercises work with Go 1 -- if not, its
a bug.
The following convention is used throughout this book:
@@ -40,17 +40,26 @@ \section{Official documentation}
document \cite{effective_go}. The
website \url{http://golang.org/doc/} is a very good starting point
for reading up on Go\footnote{\url{http://golang.org/doc/} itself is served by
-a Go program called \prog{go\ doc}.}. Reading these documents is
-certainly not required, but is recommended.
-
-Go comes with its own documentation in the form of a program called
-\prog{go doc}.
-You can use it yourself to look
-in the on-line documentation. For
-instance, suppose we want to know more about the package \package{hash}.
-We would then give the command \prog{go doc hash}.
-How to create your own package documentation
-is explained in chapter \ref{chap:packages}.
+a Go program called \prog{godoc}.}. Reading these documents is
+certainly not required, but it is recommended.
+
+Go 1 comes with its own documentation in the form of two programs:
+\begin{enumerate}
+\item \prog{go doc}, this one is used for the (third party)\emph{package} documentation;
+\item \prog{godoc}, used for the official package documentation, i.e. all the stuff
+relating to Go 1.
+\end{enumerate}
+
+The difference between the two is most apparent we you look at the documentation
+for the built-ins (see ``\titleref{sec:builtins}`` in the next chapter):
+\begin{display}
+\pr \user{go doc builtin} \coderemark{35 lines}
+\pr \user{godoc builtin} \coderemark{242 lines}
+\end{display}
+
+Normally the difference between the two shouldn't matter, but just be aware
+that \prog{go doc} and \prog{godoc} aren't identical.
+How to create your own package documentation is explained in chapter \ref{chap:packages}.
\section{Origins}
Go has it origins in Inferno \cite{inferno} (which in turn was based
@@ -104,12 +113,14 @@ \section{Getting Go}
also compile Go code online at \url{http://play.golang.org/}. To quickly
play with code this is by far the easiest route.
+You can also get pre-compiled binaries from \cite{go_install}.
+
Ubuntu and Debian both have a Go package in their repositories, look for
the package ``golang''. But there are still some minor issues being worked
out. For now we will stick to the installation from source.
-So we will retrieve the code from the mercurial archive and compile
-Go yourself. For other Unix like systems the procedure is the same.
+So we will have to retrieve the code from the mercurial archive and compile
+Go yourself. For other Unix-like systems the procedure is the same.
\begin{itemize}
\item First install Mercurial (to get the \prog{hg} command). In
Ubuntu/Debian/Fedora you must install the \prog{mercurial} package;
@@ -120,10 +131,10 @@ \section{Getting Go}
\item Set the environment variable \prog{GOROOT} to the root of your
Go install:
\begin{display}
-\pr \user{export GOROOT=/go}
+\pr \user{export GOROOT=\~{}/go}
\end{display}
-\item Then retrieve the Go source code:
+\item Then retrieve the latest release (= Go 1) source code:
\begin{display}
\pr \user{hg clone -r release https://go.googlecode.com/hg/ $GOROOT}
\end{display}
@@ -149,86 +160,23 @@ \section{Getting Go}
Installed Go for linux/amd64 in /home/go
Installed commands in /home/go/bin
\end{display}
-You now have Go installed on your system and you can start playing.
-Note that currently (March 2012) this install version r60 of, this version
-is old. If you want Go1, or something close to it, you will have to
-upgrade to the latest weekly, see the section ``\titleref{sec:weekly}''.
\section{Getting Go for Windows}
-The best way to use Go in Windows is together with the MinGW \cite{go_windows} environment.
-It provides an UNIX like environment for Windows. It is similar to Cygwin, but no POSIX
-emulation is attempted, the Microsoft C run time library and Windows APIs are used instead.
-\begin{itemize}
-\item Download the latest version from \cite{go_windows};
-\item Unpack it to your \verb|C:\| drive;
-\item Make sure that the contents are \verb|C:\MinGW|. Note: this directory should be
-created when you unpacked MinGW;
-\item Use the mintty shortcut to start a terminal window;
-\item Set the environment variable \prog{GOROOT} to the root of your
-Go install:
-\begin{display}
-\pr \user{export GOROOT=/c/go}
-\end{display}
-\item Download the latest Go stable release by issuing the following command
-\begin{display}
-\pr \user{hg clone -r release https://go.googlecode.com/hg/ $GOROOT}
-\end{display}
-\item Change to the \file{src} directory
-\begin{display}
-\pr \user{cd $GOROOT/src}
-\end{display}
-\item And build Go
-\begin{display}
-\pr \user{./all.bash}
-\end{display}
-\end{itemize}
-You should now have a working Go environment. Next we need to configure
-the GOBIN and PATH variables. Note that the GOROOT variable is also included here.
+The best way is to follow the instruction from \cite{go_install}, which are repeated
+here for the convience.
\begin{itemize}
-\item Create a file named \file{setup.sh} and place it inside the \file{MinGW} directory
-with the following content:
-\begin{display}
-export GOROOT=/c/go
-export GOBIN=$GOROOT/bin
-export PATH=$GOBIN:$PATH
-\end{display}
-\item Now when you start mintty, you can source the file to setup your Go enviroment:
+\item Download Go -1 from:
+\url{http://code.google.com/p/go/downloads/list?q=OpSys-Windows+Type%3DArchive};
+\item Unpack it to your \verb|C:\| drive;
+\item Make sure that the contents are \verb|C:\Go|. Note: this directory should be
+created when you unpacked the zip;
+\item Add \verb|C:\Go\bin| to your \$PATH:
\begin{display}
-\pr \user{. ./setup.sh}
+export PATH=\verb|C:\Go\bin|
\end{display}
\end{itemize}
-\section{Keeping up to date}
-\label{sec:weekly}
-New releases are announced on the Go Nuts mailing list \cite{go_nuts}. To update an
-existing tree to the latest release, you can run:
-\begin{display}
-\pr \user{cd $GOROOT}
-\pr \user{hg pull}
-\pr \user{hg update release}
-\pr \user{cd src}
-\pr \user{./all.bash}
-\end{display}
-\noindent{}To see what you are running right now:
-\begin{display}
-\pr \user{cd $GOROOT}
-\pr \user{hg identify}
-79997f0e5823 release/release.2010-10-20
-\end{display}
-\noindent{}That would be release \gorelease{2010-10-20}. The release as
-describe is a ``stable'' releases,
-as opposed to the ``weekly'' releases that are more volatile.
-If you want to track the weekly releases
-instead of the stable ones you can use:
-\begin{display}
-\pr \user{hg update weekly}
-\end{display}
-In stead of
-\begin{display}
-\pr \user{hg update release}
-\end{display}
-
\section{Exercises}
\input{ex-intro/ex-doc.tex}
View
28 go.bib
@@ -61,43 +61,50 @@ @misc{go_interfaces
year = 2010
}
+@misc{go_install,
+ author = "{G}o {A}uthors",
+ title = "{G}etting {S}tarted",
+ howpublished = {\url{http://golang.org/doc/install/}},
+ year = 2012
+}
+
@misc{go_intro,
author = "Mark C. Chu-Carroll",
- title = "{G}oogle's new language: Go",
+ title = "{G}oogle's new language: {G}o",
howpublished = {\url{http://scienceblogs.com/goodmath/2009/11/googles_new_language_go.php}},
year = 2010
}
@misc{go_doc,
- author = "{G}o Authors",
+ author = "{G}o {A}uthors",
title = "{G}o package documentation",
- howpublished = {\url{http://golang/doc/pkg/}},
+ howpublished = {\url{http://golang.org/doc/pkg/}},
year = 2010
}
@misc{go_cpp,
- author = "{G}o Authors",
+ author = "{G}o {A}uthors",
title = "{G}o for {C}++ programmers",
howpublished = {\url{http://golang.org/doc/go_for_cpp_programmers.html}},
year = 2010
}
@misc{go_blog,
- author = "{G}o Authors",
+ author = "{G}o {A}uthors",
title = "The {G}o programming language blog",
howpublished = {\url{http://blog.golang.org/}},
year = 2010
}
@misc{erlang,
- author = "Ericsson Cooperation",
+ author = "{E}ricsson {C}ooperation",
title = "Erlang",
howpublished = {\url{http://www.erlang.se/}},
year = 1896
}
@misc{scala,
- author = "LAMP Group at EPFL",
+ author = "{LAMP} {G}roup at EPFL",
title = "Scala",
howpublished = {
\url{http://www.scala-lang.org/}},
@@ -289,10 +296,3 @@ @misc{RFC4641
howpublished = {\url{http://www.ietf.org/rfc/rfc4641.txt}},
year = 2006,
}
-
-@misc{go_windows,
- author = "Joseph Poirier",
- title = "{G}o MinGW",
- howpublished = {\url{https://bitbucket.org/jpoirier/go_mingw/downloads/}},
- year = 2011,
-}
Please sign in to comment.
Something went wrong with that request. Please try again.