Prepare to tag 0.20240913.0 as the first periodic snapshot
BoringSSL is a "live at head" project and does not make release
branches and thus releases.
However, some systems cannot consume git revisions and expect git tags.
In Bazel Central Registry's case, the toolchain is suspicious of
non-"release" archives of
https://github.blog/open-source/git/update-on-the-future-stability-of-source-code-archives-and-hashes/
To accommodate such systems, let's start periodically tagging snapshots
as "releases". These versions do not represent any kind of stability or
development milestone. BoringSSL does not branch at these releases and
will not cherry-pick bugfixes to them. Unless there is a technical
constraint to use one of these revisions, projects should simply use the
latest revision when updating.
Also, so that cutting such revisions is less tedious, probably the
simplest is to set MODULE.bazel's version field in HEAD to whatever the
last revision was. The process will then be:
1. Bump MODULE.bazel's version
2. Create a git tag
3. Create a GitHub "release"
4. Kick off a BCR update
All that mess will ideally be automated, but for now we'll drive that
manually. Update INCORPORATING.md to explain these tags, and also to
discuss the new pregenerated build files.
Versioning scheme is chosen as 0.YYYYMMDD.N so that:
- It is deterministic from the date
- It begins with zero lest anyone misinterpret these as semver versions
- We have a digit at the end to bump when we need to cut two revisions
in one day
Change-Id: Ie256a5f0f7eaac5928b537c75f82402c934f9fc3
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/71227
Reviewed-by: Adam Langley <agl@google.com>
Auto-Submit: David Benjamin <davidben@google.com>
Commit-Queue: David Benjamin <davidben@google.com>
diff --git a/INCORPORATING.md b/INCORPORATING.md
index afe61d9..1a4eb47 100644
--- a/INCORPORATING.md
+++ b/INCORPORATING.md
@@ -15,6 +15,13 @@
model. Projects pin to whatever the current latest of BoringSSL is at the time
of update, and regularly update it to pick up new changes.
+Some systems cannot consume git revisions and expect git tags. BoringSSL tags
+periodic snapshots as "releases", to meet the needs of those systems. These
+versions do not represent any kind of stability or development milestone.
+BoringSSL does not branch at these releases and will not cherry-pick bugfixes to
+them. Unless there is a technical constraint to use one of these revisions,
+projects should simply use the latest untagged revision when updating.
+
While the BoringSSL repository may contain project-specific branches, e.g.
`chromium-2214`, those are _not_ supported release branches and must not as
such. In rare cases, BoringSSL will temporarily maintain a short-lived branch on
@@ -26,21 +33,17 @@
## Bazel
-If you are using [Bazel](https://bazel.build) then you can incorporate
-BoringSSL as an external repository by using a commit from the
-`master-with-bazel` branch. That branch is maintained by a bot from `master`
-and includes the needed generated files and a top-level BUILD file.
+If you are using [Bazel](https://bazel.build) then you can use the [boringssl
+module](https://registry.bazel.build/modules/boringssl) in the Bazel Central
+Registry with bzlmod. Look up the latest version and add the following to your
+`MODULE.bazel` file:
-For example:
+ bazel_dep(name = "boringssl", version = "INSERT_VERSION_HERE")
- git_repository(
- name = "boringssl",
- commit = "_some commit_",
- remote = "https://boringssl.googlesource.com/boringssl",
- )
+Substitute the latest version in for `INSERT_VERSION_HERE`.
-You would still need to keep the referenced commit up to date if a specific
-commit is referred to.
+BoringSSL will periodically ship snapshots to Bazel Central Registry. As with
+other dependencies, periodically keep the referenced version up-to-date.
## Directory layout
@@ -50,45 +53,34 @@
[submodule](https://git-scm.com/docs/git-submodule).
It's generally a mistake to put BoringSSL's source code into
-`third_party/boringssl` directly because pre-built files and custom build files
-need to go somewhere and merging these with the BoringSSL source code makes
-updating things more complex.
+`third_party/boringssl` directly because custom build files need to go somewhere
+and merging these with the BoringSSL source code makes updating things more
+complex.
## Build support
-BoringSSL is designed to work with many different build systems. Currently,
-different projects use [GYP](https://gyp.gsrc.io/),
-[GN](https://gn.googlesource.com/gn/+/master/docs/quick_start.md),
-[Bazel](https://bazel.build/) and [Make](https://www.gnu.org/software/make/) to
-build BoringSSL, without too much pain.
+BoringSSL is designed to work with many different build systems. The project
+currently has [CMake](https://cmake.org/) and [Bazel](https://bazel.build/)
+builds checked in. Other build systems, and embedders with custom build needs,
+are supported by separating the source list, maintained by BoringSSL, and the
+top-level build logic, maintained by the embedder.
-The development build system is CMake and the CMake build knows how to
-automatically generate the intermediate files that BoringSSL needs. However,
-outside of the CMake environment, these intermediates are generated once and
-checked into the incorporating project's source repository. This avoids
-incorporating projects needing to support Perl and Go in their build systems.
+Source lists for various build systems are pre-generated and live in the `gen`
+directory. For example, source lists for
+[GN](https://gn.googlesource.com/gn/+/master/docs/quick_start.md) live in
+[gen/sources.gni](./gen/sources.gni). There is also a generic
+[gen/sources.json](./gen/sources.json) file for projects to consume if needed.
+[util/build/build.go](./util/build/build.go) describes what the various source
+lists mean. Most projects should concatenate the `bcm` and `crypto` targets.
-The script [`util/generate_build_files.py`](./util/generate_build_files.py)
-expects to be run from the `third_party/boringssl` directory and to find the
-BoringSSL source code in `src/`. You should pass it a single argument: the name
-of the build system that you're using. If you don't use any of the supported
-build systems then you should augment `generate_build_files.py` with support
-for it.
+If you don't use any of the supported build systems, you should augment the
+[util/pregenerate](./util/pregenerate) tool to support it, or
+consume [gen/sources.json](./gen/sources.json).
-The script will pregenerate the intermediate files (see
-[BUILDING.md](./BUILDING.md) for details about which tools will need to be
-installed) and output helper files for that build system. It doesn't generate a
-complete build script, just file and test lists, which change often. For
-example, see the
-[file](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/boringssl/BUILD.generated.gni)
-and
-[test](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/boringssl/BUILD.generated_tests.gni)
-lists generated for GN in Chromium.
-
-Generally one checks in these generated files alongside the hand-written build
-files. Periodically an engineer updates the BoringSSL revision, regenerates
-these files and checks in the updated result. As an example, see how this is
-done [in Chromium](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/boringssl/).
+Historically, source lists were generated at update time with the
+[`util/generate_build_files.py`](./util/generate_build_files.py) script. We are
+in the process of transitioning builds to the pre-generated files, so that
+embedders do not need to run a custom script when updating BoringSSL.
## Defines
diff --git a/MODULE.bazel b/MODULE.bazel
index 0447733..69a29fc 100644
--- a/MODULE.bazel
+++ b/MODULE.bazel
@@ -12,11 +12,11 @@
# OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-# When publishing to BCR, replace the version field below with
-# 0.0.0-YYYYMMDD-HASH, e.g. "0.0.0-20240126-22d349c".
+# When tagging a new periodic snapshot, bump the version here and then tag at
+# the revision where we bump the version.
module(
name = "boringssl",
- version = "0.0.0-dev",
+ version = "0.20240913.0",
compatibility_level = 2,
)
