stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8276746: Add section on reproducible builds in building.md

Browse Source 
Reviewed-by: erikj, sgehwolf, aleonard
This commit is contained in:
Magnus Ihse Bursie 2021-11-05 21:21:38 +00:00
parent 0e0dd33fff
commit 59c3dcc761
2 changed files with 89 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/building.html
View File

@ -96,6 +96,7 @@
<li><a href="#specific-build-issues">Specific Build Issues</a></li>
<li><a href="#getting-help">Getting Help</a></li>
</ul></li>
<li><a href="#reproducible-builds">Reproducible Builds</a></li>
<li><a href="#hints-and-suggestions-for-advanced-users">Hints and Suggestions for Advanced Users</a><ul>
<li><a href="#bash-completion">Bash Completion</a></li>
<li><a href="#using-multiple-configurations">Using Multiple Configurations</a></li>
@ -884,6 +885,32 @@ spawn failed</code></pre>
<h3 id="getting-help">Getting Help</h3>
<p>If none of the suggestions in this document helps you, or if you find what you believe is a bug in the build system, please contact the Build Group by sending a mail to <a href="mailto:build-dev@openjdk.java.net">build-dev@openjdk.java.net</a>. Please include the relevant parts of the configure and/or build log.</p>
<p>If you need general help or advice about developing for the JDK, you can also contact the Adoption Group. See the section on <a href="#contributing-to-openjdk">Contributing to OpenJDK</a> for more information.</p>
<h2 id="reproducible-builds">Reproducible Builds</h2>
<p>Build reproducibility is the property of getting exactly the same bits out when building, every time, independent on who builds the product, or where. This is for many reasons a harder goal than it initially appears, but it is an important goal, for security reasons and others. Please see <a href="https://reproducible-builds.org">Reproducible Builds</a> for more information about the background and reasons for reproducible builds.</p>
<p>Currently, it is not possible to build OpenJDK fully reproducibly, but getting there is an ongoing effort. There are some things you can do to minimize non-determinism and make a larger part of the build reproducible:</p>
<ul>
<li>Turn on build system support for reproducible builds</li>
</ul>
<p>Add the flag <code>--enable-reproducible-builds</code> to your <code>configure</code> command line. This will turn on support for reproducible builds where it could otherwise be lacking.</p>
<ul>
<li>Do not rely on <code>configure</code>'s default adhoc version strings</li>
</ul>
<p>Default adhoc version strings OPT segment include user name, source directory and timestamp. You can either override just the OPT segment using <code>--with-version-opt=&lt;any fixed string&gt;</code>, or you can specify the entire version string using <code>--with-version-string=&lt;your version&gt;</code>.</p>
<ul>
<li>Specify how the build sets <code>SOURCE_DATE_EPOCH</code></li>
</ul>
<p>The JDK build system will set the <code>SOURCE_DATE_EPOCH</code> environment variable during building, depending on the value of the <code>--with-source-date</code> option for <code>configure</code>. The default value is <code>updated</code>, which means that <code>SOURCE_DATE_EPOCH</code> will be set to the current time each time you are running <code>make</code>.</p>
<p>The <a href="https://reproducible-builds.org/docs/source-date-epoch/"><code>SOURCE_DATE_EPOCH</code> environment variable</a> is an industry standard, that many tools, such as gcc, recognize, and use in place of the current time when generating output.</p>
<p>For reproducible builds, you need to set this to a fixed value. You can use the special value <code>version</code> which will use the nominal release date for the current JDK version, or a value describing a date, either an epoch based timestamp as an integer, or a valid ISO-8601 date.</p>
<p><strong>Hint:</strong> If your build environment already sets <code>SOURCE_DATE_EPOCH</code>, you can propagate this using <code>--with-source-date=$SOURCE_DATE_EPOCH</code>.</p>
<ul>
<li>Specify a hotspot build time</li>
</ul>
<p>Set a fixed hotspot build time. This will be included in the hotspot library (<code>libjvm.so</code> or <code>jvm.dll</code>) and defaults to the current time when building hotspot. Use <code>--with-hotspot-build-time=&lt;any fixed string&gt;</code> for reproducible builds. It's a string so you don't need to format it specifically, so e.g. <code>n/a</code> will do. Another solution is to use the <code>SOURCE_DATE_EPOCH</code> variable, e.g. <code>--with-hotspot-build-time=$(date --date=@$SOURCE_DATE_EPOCH)</code>.</p>
<ul>
<li>Copyright year</li>
</ul>
<p>The copyright year in some generated text files are normally set to the current year. This can be overridden by <code>--with-copyright-year=&lt;year&gt;</code>. For fully reproducible builds, this needs to be set to a fixed value.</p>
<h2 id="hints-and-suggestions-for-advanced-users">Hints and Suggestions for Advanced Users</h2>
<h3 id="bash-completion">Bash Completion</h3>
<p>The <code>configure</code> and <code>make</code> commands tries to play nice with bash command-line completion (using <code>&lt;tab&gt;</code> or <code>&lt;tab&gt;&lt;tab&gt;</code>). To use this functionality, make sure you enable completion in your <code>~/.bashrc</code> (see instructions for bash in your operating system).</p>

62
doc/building.md
View File

@ -1503,6 +1503,68 @@ If you need general help or advice about developing for the JDK, you can also
contact the Adoption Group. See the section on [Contributing to OpenJDK](
#contributing-to-openjdk) for more information.
## Reproducible Builds
Build reproducibility is the property of getting exactly the same bits out when
building, every time, independent on who builds the product, or where. This is
for many reasons a harder goal than it initially appears, but it is an important
goal, for security reasons and others. Please see [Reproducible Builds](
https://reproducible-builds.org) for more information about the background and
reasons for reproducible builds.
Currently, it is not possible to build OpenJDK fully reproducibly, but getting
there is an ongoing effort. There are some things you can do to minimize
non-determinism and make a larger part of the build reproducible:
* Turn on build system support for reproducible builds
Add the flag `--enable-reproducible-builds` to your `configure` command line.
This will turn on support for reproducible builds where it could otherwise be
lacking.
* Do not rely on `configure`'s default adhoc version strings
Default adhoc version strings OPT segment include user name, source directory
and timestamp. You can either override just the OPT segment using
`--with-version-opt=<any fixed string>`, or you can specify the entire version
string using `--with-version-string=<your version>`.
* Specify how the build sets `SOURCE_DATE_EPOCH`
The JDK build system will set the `SOURCE_DATE_EPOCH` environment variable
during building, depending on the value of the `--with-source-date` option for
`configure`. The default value is `updated`, which means that
`SOURCE_DATE_EPOCH` will be set to the current time each time you are running
`make`.
The [`SOURCE_DATE_EPOCH` environment variable](
https://reproducible-builds.org/docs/source-date-epoch/) is an industry
standard, that many tools, such as gcc, recognize, and use in place of the
current time when generating output.
For reproducible builds, you need to set this to a fixed value. You can use the
special value `version` which will use the nominal release date for the current
JDK version, or a value describing a date, either an epoch based timestamp as an
integer, or a valid ISO-8601 date.
**Hint:** If your build environment already sets `SOURCE_DATE_EPOCH`, you can
propagate this using `--with-source-date=$SOURCE_DATE_EPOCH`.
* Specify a hotspot build time
Set a fixed hotspot build time. This will be included in the hotspot library
(`libjvm.so` or `jvm.dll`) and defaults to the current time when building
hotspot. Use `--with-hotspot-build-time=<any fixed string>` for reproducible
builds. It's a string so you don't need to format it specifically, so e.g. `n/a`
will do. Another solution is to use the `SOURCE_DATE_EPOCH` variable, e.g.
`--with-hotspot-build-time=$(date --date=@$SOURCE_DATE_EPOCH)`.
* Copyright year
The copyright year in some generated text files are normally set to the current
year. This can be overridden by `--with-copyright-year=<year>`. For fully
reproducible builds, this needs to be set to a fixed value.
## Hints and Suggestions for Advanced Users
### Bash Completion