doc: fix install instructions in main README and contributing
Spotted whilst addressing:
github.com/cuelang/cue/discussions/706#discussioncomment-329870
go get -u has not done the right thing for some time. The -u gets the
latest version of all dependencies of the target package. Whereas what
we want is for the dependency versions described in the cuelang.org/go
module to be used.
In Go 1.16 there is a nicer form for this kind of direct install.
Add long tests to ensure we don't regress on this with a comment link
from the README and contributing to ensure we don't regress. "long"
tests only run on master CI commits, or when run with -tags long.
Generally speaking, automated tests for our docs, readmes etc are
covered by cuelang.org/issue/712.
Change-Id: I3af0802d052eb351a1e09699c985d14aa0c19d00
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/8501
Reviewed-by: CUE cueckoo <cueckoo@gmail.com>
Reviewed-by: Paul Jolly <paul@myitcv.org.uk>
diff --git a/README.md b/README.md
index 9381984..98c23f9 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@
[](https://pkg.go.dev/cuelang.org/go)
[](https://github.com/cuelang/cue/actions)
[](https://golangci.com/r/github.com/cuelang/cue)
-[](https://golang.org/dl/)
+[](https://golang.org/dl/)
[]()
@@ -93,18 +93,30 @@
### Download and Install
+#### Release builds
+
+[Download](https://github.com/cuelang/cue/releases) the latest release from GitHub.
+
#### Install using Homebrew
Using [Homebrew](https://brew.sh), you can install using the CUE Homebrew tap:
`brew install cuelang/tap/cue`
-#### Install From Source
+#### Install from Source
+
+<!-- Keep the following in sync with cmd/cue/cmd/testdata/script/install*.txt -->
If you already have Go installed, the short version is:
```
-go get -u cuelang.org/go/cmd/cue
+GO111MODULE=on go get cuelang.org/go/cmd/cue
+```
+
+Or, if you are using Go 1.16:
+
+```
+go install cuelang.org/go/cmd/cue@latest
```
This will install the `cue` command line tool.
@@ -148,6 +160,7 @@
You can get in touch with the cuelang community in the following ways:
+- Ask questions via [GitHub Discussions](https://github.com/cuelang/cue/discussions)
- Chat with us on our
[Slack workspace](https://join.slack.com/t/cuelang/shared_invite/enQtNzQwODc3NzYzNTA0LTAxNWQwZGU2YWFiOWFiOWQ4MjVjNGQ2ZTNlMmIxODc4MDVjMDg5YmIyOTMyMjQ2MTkzMTU5ZjA1OGE0OGE1NmE).
diff --git a/cmd/cue/cmd/testdata/script/install.txt b/cmd/cue/cmd/testdata/script/install.txt
new file mode 100644
index 0000000..d4495c3
--- /dev/null
+++ b/cmd/cue/cmd/testdata/script/install.txt
@@ -0,0 +1,20 @@
+# Test that we can install CUE via the pre Go 1.16 install
+# method (which should also work with Go 1.16) described in
+# the project README
+#
+# Keep this test in sync with all places that describe install
+# instructions
+
+[!long] skip 'Install tests use the network and take some time'
+
+# For this test we want to use the real proxy
+env GOPROXY=https://proxy.golang.org
+
+# Sanity check pre install
+! exists $WORK/gopath/bin/cue
+
+# Install
+env GO111MODULE=on
+go get cuelang.org/go/cmd/cue
+exec $WORK/gopath/bin/cue help
+stdout 'cue evaluates CUE files'
diff --git a/cmd/cue/cmd/testdata/script/install_contributing.txt b/cmd/cue/cmd/testdata/script/install_contributing.txt
new file mode 100644
index 0000000..1dd49dd
--- /dev/null
+++ b/cmd/cue/cmd/testdata/script/install_contributing.txt
@@ -0,0 +1,20 @@
+# Test that we can install tools required to contribute to the CUE
+# project using the pre Go 1.16 install method (which should also
+# work with Go 1.16)
+#
+# Keep this test in sync with all places that describe install
+# instructions for contributing
+
+[!long] skip 'Install tests use the network and take some time'
+
+# For this test we want to use the real proxy
+env GOPROXY=https://proxy.golang.org
+
+# Sanity check pre install
+! exists $WORK/gopath/bin/git-codereview
+
+# Install
+env GO111MODULE=on
+go get golang.org/x/review/git-codereview
+exec $WORK/gopath/bin/git-codereview help
+stdout 'Git-codereview is a git helper'
diff --git a/cmd/cue/cmd/testdata/script/install_contributing_go1.16.txt b/cmd/cue/cmd/testdata/script/install_contributing_go1.16.txt
new file mode 100644
index 0000000..86047f7
--- /dev/null
+++ b/cmd/cue/cmd/testdata/script/install_contributing_go1.16.txt
@@ -0,0 +1,20 @@
+# Test that we can install tools required to contribute to the CUE
+# project via the new Go 1.16 method
+#
+# Keep this test in sync with all places that describe install
+# instructions for contributing
+
+[!go1.16] skip 'Test only applies to Go 1.16'
+[!long] skip 'Install tests use the network and take some time'
+
+# For this test we want to use the real proxy
+env GOPROXY=https://proxy.golang.org
+
+# Sanity check pre install
+! exists $WORK/gopath/bin/git-codereview
+
+# Install
+env GO111MODULE=on
+go install golang.org/x/review/git-codereview@latest
+exec $WORK/gopath/bin/git-codereview help
+stdout 'Git-codereview is a git helper'
diff --git a/cmd/cue/cmd/testdata/script/install_go1.16.txt b/cmd/cue/cmd/testdata/script/install_go1.16.txt
new file mode 100644
index 0000000..95325a1
--- /dev/null
+++ b/cmd/cue/cmd/testdata/script/install_go1.16.txt
@@ -0,0 +1,19 @@
+# Test that we can install CUE via the new Go 1.16 go install
+# method described in the project README
+#
+# Keep this test in sync with all places that describe install
+# instructions
+
+[!go1.16] skip 'Test only applies to Go 1.16'
+[!long] skip 'Install tests use the network and take some time'
+
+# For this test we want to use the real proxy
+env GOPROXY=https://proxy.golang.org
+
+# Sanity check pre install
+! exists $WORK/gopath/bin/cue
+
+# Install
+go install cuelang.org/go/cmd/cue@latest
+exec $WORK/gopath/bin/cue help
+stdout 'cue evaluates CUE files'
diff --git a/doc/contribute.md b/doc/contribute.md
index b1c4a9c..200dd0f 100644
--- a/doc/contribute.md
+++ b/doc/contribute.md
@@ -29,8 +29,12 @@
- **Step 3**: Register for Gerrit, the code review tool used by the CUE team,
by [visiting this page](https://cue-review.googlesource.com/login/).
The CLA and the registration need to be done only once for your account.
-- **Step 4**: Install `git-codereview` by running
-`go get -u golang.org/x/review/git-codereview`
+- **Step 4**: Install `git-codereview` by running: `GO111MODULE=on go get
+ golang.org/x/review/git-codereview` (or just `go install
+ golang.org/x/review/git-codereview@latest` if you are using Go 1.16)
+
+<!-- Keep the above steps in sync with cmd/cue/cmd/testdata/script/contributing_install*.txt -->
+
<!-- TODO
If you prefer, there is an automated tool that walks through these steps.
@@ -169,12 +173,18 @@
A custom `git` command called `git-codereview`
simplifies sending changes to Gerrit.
+<!-- Keep the following in sync with cmd/cue/cmd/testdata/script/contributing_install*.txt -->
Install the `git-codereview` command by running,
+```
+$ GO111MODULE=on go get golang.org/x/review/git-codereview
+```
+
+or with Go 1.16:
```
-$ go get -u golang.org/x/review/git-codereview
+$ go install golang.org/x/review/git-codereview@latest
```
Make sure `git-codereview` is installed in your shell path, so that the
diff --git a/doc/install.md b/doc/install.md
index ba6ada4..3879f62 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -6,14 +6,22 @@
### Prerequisites
-Go 1.12 or higher (see below)
+Go 1.14 or higher (see below)
### Installing CUE
+<!-- Keep the following in sync with cmd/cue/cmd/testdata/script/install*.txt -->
+
To download and install the `cue` command line tool run
```
-go get -u cuelang.org/go/cmd/cue
+GO111MODULE=on go get cuelang.org/go/cmd/cue
+```
+
+Or, if you are using Go 1.16:
+
+```
+go install cuelang.org/go/cmd/cue@latest
```
And make sure the install directory is in your path.
@@ -21,18 +29,21 @@
To also download the API and documentation, run
```
-go get -u cuelang.org/go/cue
+go get cuelang.org/go/cue@latest
```
+in a module context.
+
### Installing Go
#### Download Go
-You can load the binary for Windows, MacOS X, and Linux at https://golang.org/dl/. If you use a different OS you can install Go from source.
+You can install binaries for Windows, MacOS X, and Linux at https://golang.org/dl/. If you use a different OS you can
+[install Go from source](https://golang.org/doc/install/source).
#### Install Go
-Follow the instructions at https://golang.org/doc/install#install.
-Make sure the go binary is in your path.
+Follow the instructions at https://golang.org/doc/install#install.
+Make sure the `go` binary is in your path.
CUE uses Go modules, so there is no need to set up a GOPATH.
