mirror of https://github.com/golang/go.git
109 lines
4.4 KiB
Markdown
109 lines
4.4 KiB
Markdown
# README.md
|
|
|
|
This directory holds build scripts for unofficial, unsupported
|
|
distributions of Go+BoringCrypto.
|
|
|
|
## Version strings
|
|
|
|
The distribution name for a Go+BoringCrypto release has the form `<GoVersion>b<BoringCryptoVersion>`,
|
|
where `<GoVersion>` is the Go version the release is based on, and `<BoringCryptoVersion>` is
|
|
an integer that increments each time there is a new release with different BoringCrypto bits.
|
|
The `<BoringCryptoVersion>` is stored in the `VERSION` file in this directory.
|
|
|
|
For example, the first release is based on Go 1.8.3 is `go1.8.3b1`.
|
|
If the BoringCrypto bits are updated, the next would be `go1.8.3b2`.
|
|
If, after that, Go 1.9 is released and the same BoringCrypto code added to it,
|
|
that would result in `go1.9b2`. There would likely not be a `go1.9b1`,
|
|
since that would indicate Go 1.9 with the older BoringCrypto code.
|
|
|
|
## Releases
|
|
|
|
The `build.release` script prepares a binary release and publishes it in Google Cloud Storage
|
|
at `gs://go-boringcrypto/`, making it available for download at
|
|
`https://go-boringcrypto.storage.googleapis.com/<FILE>`.
|
|
The script records each published release in the `RELEASES` file in this directory.
|
|
|
|
The `build.docker` script, which must be run after `build.release`, prepares a Docker image
|
|
and publishes it on Google Artifact Registry.
|
|
`go1.17.2b7` is published as `us-docker.pkg.dev/google.com/api-project-999119582588/go-boringcrypto/golang:1.17.2b7`.
|
|
|
|
## Release process
|
|
|
|
Development is done on the dev.boringcrypto branch, which tracks
|
|
master. Releases are cut from dev.boringcrypto.go1.X branches,
|
|
which are BoringCrypto backported to the Go 1.X release branches.
|
|
To issue new BoringCrypto releases based on Go 1.X:
|
|
|
|
1. If the BoringCrypto bits have been updated, increment the
|
|
number in `VERSION`, send that change out as a CL for review,
|
|
get it committed to dev.boringcrypto, and run `git sync`.
|
|
|
|
2. Change to the dev.boringcrypto.go1.X branch and cherry-pick
|
|
all BoringCrypto updates, including the update of the
|
|
`VERSION` file. If desired, merge release-branch.go1.X into
|
|
dev.boringcrypto.go1.X. Mail them out and get them committed.
|
|
|
|
3. **Back on the dev.boringcrypto branch**, run `git fetch`,
|
|
`make.bash` and then `build.release dev.boringcrypto.go1.X`.
|
|
The script will determine the base Go version and the
|
|
BoringCrypto version, build a release, and upload it.
|
|
|
|
4. Run `build.docker`, which will build and upload a Docker image
|
|
from the latest release.
|
|
|
|
5. Send out a CL with the updated `RELEASES` file and get it
|
|
committed to dev.boringcrypto.
|
|
|
|
## Building from Docker
|
|
|
|
A Dockerfile that starts with `FROM golang:1.17.2` can switch
|
|
to `FROM us-docker.pkg.dev/google.com/api-project-999119582588/go-boringcrypto/golang:1.17.2b7`
|
|
and should need no other modifications.
|
|
|
|
## Building from Bazel
|
|
|
|
Starting from [bazelbuild/rules_go](https://github.com/bazelbuild/rules_go)
|
|
tag 0.7.1, simply download the BoringCrypto-enabled Go SDK using
|
|
`go_download_sdk()` before calling `go_register_toolchains()`.
|
|
|
|
For example, to use Go 1.9.3 with BoringCrypto on Linux, use the following lines
|
|
in `WORKSPACE`:
|
|
```python
|
|
load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_download_sdk", "go_register_toolchains")
|
|
|
|
go_rules_dependencies()
|
|
|
|
go_download_sdk(
|
|
name = "go_sdk",
|
|
sdks = {
|
|
"linux_amd64": ("go1.9.3b4.linux-amd64.tar.gz", "db1997b2454a2f27669b849d2d2cafb247a55128d53da678f06cb409310d6660"),
|
|
},
|
|
urls = ["https://storage.googleapis.com/go-boringcrypto/{}"],
|
|
)
|
|
|
|
go_register_toolchains()
|
|
```
|
|
|
|
**Note**: you must *not* enable `pure` mode, since cgo must be enabled. To
|
|
ensure that binaries are linked with BoringCrypto, you can set `pure = "off"` on
|
|
all relevant `go_binary` rules.
|
|
|
|
## Caveat
|
|
|
|
BoringCrypto is used for a given build only in limited circumstances:
|
|
|
|
- The build must be GOOS=linux, GOARCH=amd64.
|
|
- The build must have cgo enabled.
|
|
- The android build tag must not be specified.
|
|
- The cmd_go_bootstrap build tag must not be specified.
|
|
|
|
The version string reported by `runtime.Version` does not indicate that BoringCrypto
|
|
was actually used for the build. For example, linux/386 and non-cgo linux/amd64 binaries
|
|
will report a version of `go1.8.3b2` but not be using BoringCrypto.
|
|
|
|
To check whether a given binary is using BoringCrypto, run `go tool nm` on it and check
|
|
that it has symbols named `*_Cfunc__goboringcrypto_*`.
|
|
|
|
The program [rsc.io/goversion](https://godoc.org/rsc.io/goversion) will report the
|
|
crypto implementation used by a given binary when invoked with the `-crypto` flag.
|