Skip to content

Starting out

Jump to bottom
Sofía Celi edited this page Dec 8, 2020 · 21 revisions

How to start out with cloning Golang

Most of the steps here are taken from the Golang contribution guide. These are the steps we took to clone Golang:

  • Step 1: Clone the Go source code from go.googlesource.com: you can check out the Go source repo onto your local file system anywhere you want as long as it's outside your GOPATH. Make sure it's stable by compiling and testing it once:
$ git clone https://go.googlesource.com/go
$ cd go/src
$ ./all.bash                                # compile and test
  • Step 2: Prepare changes in a new branch, created from the master branch
$ git checkout -b mybranch
$ [edit files...]
$ git add [files...]
  • Step 3: Test your changes, re-running all.bash. To build under Windows use all.bat; this also requires setting the environment variable GOROOT_BOOTSTRAP to the directory holding the Go tree for the bootstrap compiler.
$ ./all.bash    # recompile and test

After running for a while and printing a lot of testing output, the command should finish by printing:

ALL TESTS PASSED

You can use make.bash instead of all.bash to just build the compiler and the standard library without running the test suite. Once the go tool is built, it will be installed as bin/go under the directory in which you cloned the Go repository, and you can run it directly from there.

For quickly testing, you can:

  • In general, you can run make.bash instead of all.bash to only rebuild the Go tool chain without running the whole test suite. Or you can run run.bash to only run the whole test suite without rebuilding the tool chain. You can think of all.bash as make.bash followed by run.bash.

  • In this section, we'll call the directory into which you cloned the Go repository $GODIR. The go tool built by $GODIR/make.bash will be installed in $GODIR/bin/go and you can invoke it to test your code. For instance, if you have modified the compiler and you want to test how it affects the test suite of your own project, just run go test using it:

$ cd <MYPROJECTDIR>
$ $GODIR/bin/go test
  • If you're changing the standard library, you probably don't need to rebuild the compiler: you can just run the tests for the package you've changed. You can do that either with the Go version you normally use, or with the Go compiler built from your clone (which is sometimes required because the standard library code you're modifying might require a newer version than the stable one you have installed).
$ cd $GODIR/src/hash/sha1
$ [make changes...]
$ $GODIR/bin/go test .
  • If you're modifying the compiler itself, you can just recompile the compile tool (which is the internal binary invoked by go build to compile each single package). After that, you will want to test it by compiling or running something.
$ cd $GODIR/src
$ [make changes...]
$ $GODIR/bin/go install cmd/compile
$ $GODIR/bin/go build [something...]   # test the new compiler
$ $GODIR/bin/go run [something...]     # test the new compiler
$ $GODIR/bin/go test [something...]    # test the new compiler

The same applies to other internal tools of the Go tool chain, such as asm, cover, link, and so on. Just recompile and install the tool using go install cmd/<TOOL> and then use the built Go binary to test it.

In addition to the standard per-package tests, there is a top-level test suite in $GODIR/test that contains several black-box and regression tests. The test suite is run by all.bash but you can also run it manually:

$ cd $GODIR/test
$ $GODIR/bin/go run run.go

Rebuild the standard library

If you want to re build the standard library, use this command $GODIR/bin/go install std. If you want to include the command-line tools, use this command $GODIR/bin/go install cmd std.

Specifics for our clone

Rebasing

The cf branch tracks the latest stable release with all other custom changes on top of it. Once a new release (say, 1.15.5) is made, the following procedure can be used to update the branch to a newer version:

  1. git rebase go1.15.5
  2. Resolve the Add cf tag to VERSION conflict with echo -n go1.15.5-devel-cf > VERSION (adjust version number accordingly) and continue with git add VERSION && git rebase --continue
  3. Build and run tests with cd src && ./all.bash
  4. Force push to the cf branch.

For minor releases, this should go relatively smoothly. For major releases, more conflicts may occur due to evasive changes in the standard library. In any case, merge commits will be dropped as part of the rebase.

Alternatively, you can:

# set the upstram
 git remote add upstream git@github.com:golang/go.git

# fetch the needed branch
 git fetch upstream release-branch.go1.15

# rebase 
  git rebase upstream/release-branch.go1.15
Clone this wiki locally