File README.SUSE of Package go

Updated: 05.05.2012
Authors: Graham Anderson, <graham@andtech.eu>

PROJECT DETAILS
---------------

OBS: https://build.opensuse.org/project/show?project=devel:languages:go

Maintainers: Sascha Peilicke (saschpe),
             Graham Anderson (andtecheu)

Wiki: http://en.opensuse.org/Go
      http://en.opensuse.org/openSUSE:Packaging_Go
	  
             
GENERAL NOTES
-------------

Go toolchain environmental variables are configured via go.sh, which is
installed to /etc/profile.d/go.sh

Packaging guidelines and an RPM spec file recipe for packaging third party Go
libraries can be found on the openSUSE wiki:

http://en.opensuse.org/openSUSE:Packaging_Go

The openSUSE go package uses the standard Go distribution toolchain, with a
a small patchset to modify a few of the toolchain commands to suit our
environment and packaging needs.

This means that many of the standard go toolchain commands are not inside a
users PATH, but rather are invoked and used via the "go" command. Should you
wish to script or manually use the commands, the install location on a 64 bit
system is /usr/lib64/go/pkg/tool/linux_amd64

The "go" tool, the "godoc" document server are inside a users PATH.

We currently don't support the gccgo implementation, this is not for
any other reason than contributer and maintainer time constraints.

GO DOCUMENTATION
----------------

As of yet, there are no man pages for the standard Go distribution toolchain,
please see the documentation provided by the "godoc" command. Man pages are
slated to be included in the release in future.

One of the diffs from the maintained patchset adds the distro specific doc and
source file locations of the *-doc RPM packages to the virtual filesystem of
the "godoc" documentation server. That is to say, as long as packages follow
the Go packaging guidelines, API and other documentation should always be
available via the godoc server if the packages "doc" RPM is installed.

PACKAGE INSTALL LOCATIONS
-------------------------

Go standard library packages are installed to a location in $GOROOT, which is
defined as /usr/lib64/go on 64bit systems.

Third party package binaries are installed to the default system wide
$GOPATH entry. On 64bit systems the location /usr/lib64/go/contrib is used.
This is specified in the macros.go RPM macro definition file that is part of
the main Go package and is used for packaging most third party Go libraries.

The reasons binary packages are installed to a GOPATH entry instead of GOROOT
are mainly to do with how the Go toolchain prioritises and behaves with
packages installed to the same location as the Go std library.

By installing third party packages to a system-wide GOPATH entry location,
we can ensure that no packages clobber the standard library namespace or file
tree. Additionally we can support binary only packages, which as of Go 1.1
will only be supported outside of the $GOROOT.

There are additional benefits to this location; such as allowing users and
developers to prioritise linking from their own user defined GOPATH, which
defaults to $HOME/go configured via /etc/profile.d/go.sh config. This has
particular benefit for development workflows.

For Go 1.1 and beyond, building and linking with binary only pacakges will
only be supported with the following caveat. Package source code must not
exist in the same GOPATH segment as the binary package .a archive file.

If both the binary archive (.a) and the package source are installed to the
same GOPATH segment, then the "go build" or "go install" command will
prioritise building the software using package sources before using package
binary archives. A side effect of this is that is actually possible to have
source code only third party packages.
   
To summarise the priority of binary package linking and building:

1. Any source files or binary packages in $GOROOT are considered first. Any
     binary packages in $GOROOT that are considered "stale" by the build tools
     are ignored in favour of the package source.

2. $GOPATH is considered next for import statements. GOPATH is a colon
     delimited list of paths. GOPATH segments are examined by the build tools
     in a FIFO manner, left to right.

Both a system wide and a user GOPATH segment are configured by default,
     the user GOPATH segment takes priority over the system segment to allow
     flexibility for development workflows.

The default user GOPATH is:

GOPATH=$HOME/go:$GOROOT/contrib

The default root user GOPATH is:

GOPATH=$GOROOT/contrib

3. For Go < 1.1, If both the source and binary archive is available for a
     package import in the same GOPATH segment, the binary archive will take
     precedence and will be linked during compilation.

For Go >= 1.1 If the package source is avaiable in the GOPATH segment, it
     will always be used in preference to the binary