diff options
Diffstat (limited to 'misc/boring/README.md')
-rw-r--r-- | misc/boring/README.md | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/misc/boring/README.md b/misc/boring/README.md new file mode 100644 index 0000000000..bd8deff1cc --- /dev/null +++ b/misc/boring/README.md @@ -0,0 +1,108 @@ +# 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 hub.docker.com in the goboring organization. +`go1.8.3b1` is published as `goboring/golang:1.8.3b1`. + +## 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.8.3` can switch +to `FROM goboring/golang:1.8.3b2` (see [goboring/golang on Docker Hub](https://hub.docker.com/r/goboring/golang/)) +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. |