Skip to content

Commit

Permalink
Update docs for Go 1.11
Browse files Browse the repository at this point in the history
  • Loading branch information
fd0 committed Aug 31, 2018
1 parent 65129bd commit e9a7641
Show file tree
Hide file tree
Showing 3 changed files with 53 additions and 16 deletions.
48 changes: 37 additions & 11 deletions CONTRIBUTING.md
Expand Up @@ -46,12 +46,15 @@ Remember, the easier it is for us to reproduce the bug, the earlier it will be
corrected!

In addition, you can compile restic with debug support by running
`go run build.go -tags debug` and instructing it to create a debug log by
setting the environment variable `DEBUG_LOG` to a file, e.g. like this:
`go run -mod=vendor build.go -tags debug` and instructing it to create a debug
log by setting the environment variable `DEBUG_LOG` to a file, e.g. like this:

$ export DEBUG_LOG=/tmp/restic-debug.log
$ restic backup ~/work

For Go < 1.11, you need to remove the `-mod=vendor` option from the build
command.

Please be aware that the debug log file will contain potentially sensitive
things like file and directory names, so please either redact it before
uploading it somewhere or post only the parts that are really relevant.
Expand All @@ -60,9 +63,37 @@ uploading it somewhere or post only the parts that are really relevant.
Development Environment
=======================

In order to compile restic with the `go` tool directly, it needs to be checked
out at the right path within a `GOPATH`. The concept of a `GOPATH` is explained
in ["How to write Go code"](https://golang.org/doc/code.html).
The repository contains several sets of directories with code: `cmd/` and
`internal/` contain the code written for restic, whereas `vendor/` contains
copies of libraries restic depends on. The libraries are managed with the
command `go mod vendor`.

Go >= 1.11
----------

For Go version 1.11 or later, you should clone the repo (without having
`$GOPATH` set) and `cd` into the directory:

$ unset GOPATH
$ git clone https://github.com/restic/restic
$ cd restic

Then use the `go` tool to build restic:

$ go build ./cmd/restic
$ ./restic version
restic 0.9.2-dev (compiled manually) compiled with go1.11 on linux/amd64

You can run all tests with the following command:

$ go test ./...

Go < 1.11
---------

In order to compile restic with Go before 1.11, it needs to be checked out at
the right path within a `GOPATH`. The concept of a `GOPATH` is explained in
["How to write Go code"](https://golang.org/doc/code.html).

If you do not have a directory with Go code yet, executing the following
instructions in your shell will create one for you and check out the restic
Expand All @@ -83,12 +114,7 @@ You can then build restic as follows:

The following commands can be used to run all the tests:

$ go test ./cmd/... ./internal/...

The repository contains two sets of directories with code: `cmd/` and
`internal/` contain the code written for restic, whereas `vendor/` contains
copies of libraries restic depends on. The libraries are managed with the
[`dep`](https://github.com/golang/dep) tool.
$ go test ./...

Providing Patches
=================
Expand Down
17 changes: 13 additions & 4 deletions doc/020_installation.rst
Expand Up @@ -221,6 +221,13 @@ In order to build restic from source, execute the following steps:
$ cd restic
$ go run -mod=vendor build.go
For Go versions < 1.11, the option ``-mod=vendor`` needs to be removed, like
this:

.. code-block:: console
$ go run build.go
You can easily cross-compile restic for all supported platforms, just
Expand All @@ -229,12 +236,14 @@ supply the target OS and platform via the command-line options like this

.. code-block:: console
$ go run build.go --goos windows --goarch amd64
$ go run -mod=vendor build.go --goos windows --goarch amd64
$ go run build.go --goos freebsd --goarch 386
$ go run -mod=vendor build.go --goos freebsd --goarch 386
$ go run -mod=vendor build.go --goos linux --goarch arm --goarm 6
Again, for Go < 1.11 ``-mod=vendor`` needs to be removed.

$ go run build.go --goos linux --goarch arm --goarm 6
The resulting binary is statically linked and does not require any
libraries.

Expand Down
4 changes: 3 additions & 1 deletion doc/090_participating.rst
Expand Up @@ -22,7 +22,9 @@ The program can be built with debug support like this:

.. code-block:: console
$ go run build.go -tags debug
$ go run build.go -mod=vendor -tags debug
For Go < 1.11, the option ``-mod=vendor`` needs to be removed.

Afterwards, extensive debug messages are written to the file in
environment variable ``DEBUG_LOG``, e.g.:
Expand Down

0 comments on commit e9a7641

Please sign in to comment.