91 <li><a href="#fixing-unexpected-build-failures">Fixing Unexpected Build Failures</a></li> |
91 <li><a href="#fixing-unexpected-build-failures">Fixing Unexpected Build Failures</a></li> |
92 <li><a href="#specific-build-issues">Specific Build Issues</a></li> |
92 <li><a href="#specific-build-issues">Specific Build Issues</a></li> |
93 <li><a href="#getting-help">Getting Help</a></li> |
93 <li><a href="#getting-help">Getting Help</a></li> |
94 </ul></li> |
94 </ul></li> |
95 <li><a href="#hints-and-suggestions-for-advanced-users">Hints and Suggestions for Advanced Users</a><ul> |
95 <li><a href="#hints-and-suggestions-for-advanced-users">Hints and Suggestions for Advanced Users</a><ul> |
96 <li><a href="#setting-up-a-forest-for-pushing-changes-defpath">Setting Up a Forest for Pushing Changes (defpath)</a></li> |
96 <li><a href="#setting-up-a-repository-for-pushing-changes-defpath">Setting Up a Repository for Pushing Changes (defpath)</a></li> |
97 <li><a href="#bash-completion">Bash Completion</a></li> |
97 <li><a href="#bash-completion">Bash Completion</a></li> |
98 <li><a href="#using-multiple-configurations">Using Multiple Configurations</a></li> |
98 <li><a href="#using-multiple-configurations">Using Multiple Configurations</a></li> |
99 <li><a href="#handling-reconfigurations">Handling Reconfigurations</a></li> |
99 <li><a href="#handling-reconfigurations">Handling Reconfigurations</a></li> |
100 <li><a href="#using-fine-grained-make-targets">Using Fine-Grained Make Targets</a></li> |
100 <li><a href="#using-fine-grained-make-targets">Using Fine-Grained Make Targets</a></li> |
101 <li><a href="#learn-about-mercurial">Learn About Mercurial</a></li> |
101 <li><a href="#learn-about-mercurial">Learn About Mercurial</a></li> |
129 <p>If any of these steps failed, or if you want to know more about build requirements or build functionality, please continue reading this document.</p> |
129 <p>If any of these steps failed, or if you want to know more about build requirements or build functionality, please continue reading this document.</p> |
130 <h2 id="introduction">Introduction</h2> |
130 <h2 id="introduction">Introduction</h2> |
131 <p>The JDK is a complex software project. Building it requires a certain amount of technical expertise, a fair number of dependencies on external software, and reasonably powerful hardware.</p> |
131 <p>The JDK is a complex software project. Building it requires a certain amount of technical expertise, a fair number of dependencies on external software, and reasonably powerful hardware.</p> |
132 <p>If you just want to use the JDK and not build it yourself, this document is not for you. See for instance <a href="http://openjdk.java.net/install">OpenJDK installation</a> for some methods of installing a prebuilt JDK.</p> |
132 <p>If you just want to use the JDK and not build it yourself, this document is not for you. See for instance <a href="http://openjdk.java.net/install">OpenJDK installation</a> for some methods of installing a prebuilt JDK.</p> |
133 <h2 id="getting-the-source-code">Getting the Source Code</h2> |
133 <h2 id="getting-the-source-code">Getting the Source Code</h2> |
134 <p>Make sure you are getting the correct version. As of JDK 10, the source is no longer split into separate repositories so you only need to clone one single repository. At the <a href="http://hg.openjdk.java.net/">OpenJDK Mercurial server</a> you can see a list of all available forests. If you want to build an older version, e.g. JDK 8, it is recommended that you get the <code>jdk8u</code> forest, which contains incremental updates, instead of the <code>jdk8</code> forest, which was frozen at JDK 8 GA.</p> |
134 <p>Make sure you are getting the correct version. As of JDK 10, the source is no longer split into separate repositories so you only need to clone one single repository. At the <a href="http://hg.openjdk.java.net/">OpenJDK Mercurial server</a> you can see a list of all available repositories. If you want to build an older version, e.g. JDK 8, it is recommended that you get the <code>jdk8u</code> forest, which contains incremental updates, instead of the <code>jdk8</code> forest, which was frozen at JDK 8 GA.</p> |
135 <p>If you are new to Mercurial, a good place to start is the <a href="http://www.mercurial-scm.org/guide">Mercurial Beginner's Guide</a>. The rest of this document assumes a working knowledge of Mercurial.</p> |
135 <p>If you are new to Mercurial, a good place to start is the <a href="http://www.mercurial-scm.org/guide">Mercurial Beginner's Guide</a>. The rest of this document assumes a working knowledge of Mercurial.</p> |
136 <h3 id="special-considerations">Special Considerations</h3> |
136 <h3 id="special-considerations">Special Considerations</h3> |
137 <p>For a smooth building experience, it is recommended that you follow these rules on where and how to check out the source code.</p> |
137 <p>For a smooth building experience, it is recommended that you follow these rules on where and how to check out the source code.</p> |
138 <ul> |
138 <ul> |
139 <li><p>Do not check out the source code in a path which contains spaces. Chances are the build will not work. This is most likely to be an issue on Windows systems.</p></li> |
139 <li><p>Do not check out the source code in a path which contains spaces. Chances are the build will not work. This is most likely to be an issue on Windows systems.</p></li> |
778 <h4 id="problems-with-the-build-environment">Problems with the Build Environment</h4> |
778 <h4 id="problems-with-the-build-environment">Problems with the Build Environment</h4> |
779 <p>Make sure your configuration is correct. Re-run <code>configure</code>, and look for any warnings. Warnings that appear in the middle of the <code>configure</code> output is also repeated at the end, after the summary. The entire log is stored in <code>$BUILD/configure.log</code>.</p> |
779 <p>Make sure your configuration is correct. Re-run <code>configure</code>, and look for any warnings. Warnings that appear in the middle of the <code>configure</code> output is also repeated at the end, after the summary. The entire log is stored in <code>$BUILD/configure.log</code>.</p> |
780 <p>Verify that the summary at the end looks correct. Are you indeed using the Boot JDK and native toolchain that you expect?</p> |
780 <p>Verify that the summary at the end looks correct. Are you indeed using the Boot JDK and native toolchain that you expect?</p> |
781 <p>By default, the JDK has a strict approach where warnings from the compiler is considered errors which fail the build. For very new or very old compiler versions, this can trigger new classes of warnings, which thus fails the build. Run <code>configure</code> with <code>--disable-warnings-as-errors</code> to turn of this behavior. (The warnings will still show, but not make the build fail.)</p> |
781 <p>By default, the JDK has a strict approach where warnings from the compiler is considered errors which fail the build. For very new or very old compiler versions, this can trigger new classes of warnings, which thus fails the build. Run <code>configure</code> with <code>--disable-warnings-as-errors</code> to turn of this behavior. (The warnings will still show, but not make the build fail.)</p> |
782 <h4 id="problems-with-incremental-rebuilds">Problems with Incremental Rebuilds</h4> |
782 <h4 id="problems-with-incremental-rebuilds">Problems with Incremental Rebuilds</h4> |
783 <p>Incremental rebuilds mean that when you modify part of the product, only the affected parts get rebuilt. While this works great in most cases, and significantly speed up the development process, from time to time complex interdependencies will result in an incorrect build result. This is the most common cause for unexpected build problems, together with inconsistencies between the different Mercurial repositories in the forest.</p> |
783 <p>Incremental rebuilds mean that when you modify part of the product, only the affected parts get rebuilt. While this works great in most cases, and significantly speed up the development process, from time to time complex interdependencies will result in an incorrect build result. This is the most common cause for unexpected build problems.</p> |
784 <p>Here are a suggested list of things to try if you are having unexpected build problems. Each step requires more time than the one before, so try them in order. Most issues will be solved at step 1 or 2.</p> |
784 <p>Here are a suggested list of things to try if you are having unexpected build problems. Each step requires more time than the one before, so try them in order. Most issues will be solved at step 1 or 2.</p> |
785 <ol type="1"> |
785 <ol type="1"> |
786 <li><p>Make sure your forest is up-to-date</p> |
786 <li><p>Make sure your repository is up-to-date</p> |
787 <p>Run <code>bash get_source.sh</code> to make sure you have the latest version of all repositories.</p></li> |
787 <p>Run <code>hg pull -u</code> to make sure you have the latest changes.</p></li> |
788 <li><p>Clean build results</p> |
788 <li><p>Clean build results</p> |
789 <p>The simplest way to fix incremental rebuild issues is to run <code>make clean</code>. This will remove all build results, but not the configuration or any build system support artifacts. In most cases, this will solve build errors resulting from incremental build mismatches.</p></li> |
789 <p>The simplest way to fix incremental rebuild issues is to run <code>make clean</code>. This will remove all build results, but not the configuration or any build system support artifacts. In most cases, this will solve build errors resulting from incremental build mismatches.</p></li> |
790 <li><p>Completely clean the build directory.</p> |
790 <li><p>Completely clean the build directory.</p> |
791 <p>If this does not work, the next step is to run <code>make dist-clean</code>, or removing the build output directory (<code>$BUILD</code>). This will clean all generated output, including your configuration. You will need to re-run <code>configure</code> after this step. A good idea is to run <code>make print-configuration</code> before running <code>make dist-clean</code>, as this will print your current <code>configure</code> command line. Here's a way to do this:</p> |
791 <p>If this does not work, the next step is to run <code>make dist-clean</code>, or removing the build output directory (<code>$BUILD</code>). This will clean all generated output, including your configuration. You will need to re-run <code>configure</code> after this step. A good idea is to run <code>make print-configuration</code> before running <code>make dist-clean</code>, as this will print your current <code>configure</code> command line. Here's a way to do this:</p> |
792 <pre><code>make print-configuration > current-configuration |
792 <pre><code>make print-configuration > current-configuration |
793 make dist-clean |
793 make dist-clean |
794 bash configure $(cat current-configuration) |
794 bash configure $(cat current-configuration) |
795 make</code></pre></li> |
795 make</code></pre></li> |
796 <li><p>Re-clone the Mercurial forest</p> |
796 <li><p>Re-clone the Mercurial repository</p> |
797 <p>Sometimes the Mercurial repositories themselves gets in a state that causes the product to be un-buildable. In such a case, the simplest solution is often the "sledgehammer approach": delete the entire forest, and re-clone it. If you have local changes, save them first to a different location using <code>hg export</code>.</p></li> |
797 <p>Sometimes the Mercurial repository gets in a state that causes the product to be un-buildable. In such a case, the simplest solution is often the "sledgehammer approach": delete the entire repository, and re-clone it. If you have local changes, save them first to a different location using <code>hg export</code>.</p></li> |
798 </ol> |
798 </ol> |
799 <h3 id="specific-build-issues">Specific Build Issues</h3> |
799 <h3 id="specific-build-issues">Specific Build Issues</h3> |
800 <h4 id="clock-skew">Clock Skew</h4> |
800 <h4 id="clock-skew">Clock Skew</h4> |
801 <p>If you get an error message like this:</p> |
801 <p>If you get an error message like this:</p> |
802 <pre><code>File 'xxx' has modification time in the future. |
802 <pre><code>File 'xxx' has modification time in the future. |
814 <p>This can be a sign of a Cygwin problem. See the information about solving problems in the <a href="#cygwin">Cygwin</a> section. Rebooting the computer might help temporarily.</p> |
814 <p>This can be a sign of a Cygwin problem. See the information about solving problems in the <a href="#cygwin">Cygwin</a> section. Rebooting the computer might help temporarily.</p> |
815 <h3 id="getting-help">Getting Help</h3> |
815 <h3 id="getting-help">Getting Help</h3> |
816 <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> |
816 <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> |
817 <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> |
817 <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> |
818 <h2 id="hints-and-suggestions-for-advanced-users">Hints and Suggestions for Advanced Users</h2> |
818 <h2 id="hints-and-suggestions-for-advanced-users">Hints and Suggestions for Advanced Users</h2> |
819 <h3 id="setting-up-a-forest-for-pushing-changes-defpath">Setting Up a Forest for Pushing Changes (defpath)</h3> |
819 <h3 id="setting-up-a-repository-for-pushing-changes-defpath">Setting Up a Repository for Pushing Changes (defpath)</h3> |
820 <p>To help you prepare a proper push path for a Mercurial repository, there exists a useful tool known as <a href="http://openjdk.java.net/projects/code-tools/defpath">defpath</a>. It will help you setup a proper push path for pushing changes to the JDK.</p> |
820 <p>To help you prepare a proper push path for a Mercurial repository, there exists a useful tool known as <a href="http://openjdk.java.net/projects/code-tools/defpath">defpath</a>. It will help you setup a proper push path for pushing changes to the JDK.</p> |
821 <p>Install the extension by cloning <code>http://hg.openjdk.java.net/code-tools/defpath</code> and updating your <code>.hgrc</code> file. Here's one way to do this:</p> |
821 <p>Install the extension by cloning <code>http://hg.openjdk.java.net/code-tools/defpath</code> and updating your <code>.hgrc</code> file. Here's one way to do this:</p> |
822 <pre><code>cd ~ |
822 <pre><code>cd ~ |
823 mkdir hg-ext |
823 mkdir hg-ext |
824 cd hg-ext |
824 cd hg-ext |
827 [extensions] |
827 [extensions] |
828 defpath=~/hg-ext/defpath/defpath.py |
828 defpath=~/hg-ext/defpath/defpath.py |
829 EOT</code></pre> |
829 EOT</code></pre> |
830 <p>You can now setup a proper push path using:</p> |
830 <p>You can now setup a proper push path using:</p> |
831 <pre><code>hg defpath -d -u <your OpenJDK username></code></pre> |
831 <pre><code>hg defpath -d -u <your OpenJDK username></code></pre> |
832 <p>If you also have the <code>trees</code> extension installed in Mercurial, you will automatically get a <code>tdefpath</code> command, which is even more useful. By running <code>hg tdefpath -du <username></code> in the top repository of your forest, all repos will get setup automatically. This is the recommended usage.</p> |
|
833 <h3 id="bash-completion">Bash Completion</h3> |
832 <h3 id="bash-completion">Bash Completion</h3> |
834 <p>The <code>configure</code> and <code>make</code> commands tries to play nice with bash command-line completion (using <code><tab></code> or <code><tab><tab></code>). To use this functionality, make sure you enable completion in your <code>~/.bashrc</code> (see instructions for bash in your operating system).</p> |
833 <p>The <code>configure</code> and <code>make</code> commands tries to play nice with bash command-line completion (using <code><tab></code> or <code><tab><tab></code>). To use this functionality, make sure you enable completion in your <code>~/.bashrc</code> (see instructions for bash in your operating system).</p> |
835 <p>Make completion will work out of the box, and will complete valid make targets. For instance, typing <code>make jdk-i<tab></code> will complete to <code>make jdk-image</code>.</p> |
834 <p>Make completion will work out of the box, and will complete valid make targets. For instance, typing <code>make jdk-i<tab></code> will complete to <code>make jdk-image</code>.</p> |
836 <p>The <code>configure</code> script can get completion for options, but for this to work you need to help <code>bash</code> on the way. The standard way of running the script, <code>bash configure</code>, will not be understood by bash completion. You need <code>configure</code> to be the command to run. One way to achieve this is to add a simple helper script to your path:</p> |
835 <p>The <code>configure</code> script can get completion for options, but for this to work you need to help <code>bash</code> on the way. The standard way of running the script, <code>bash configure</code>, will not be understood by bash completion. You need <code>configure</code> to be the command to run. One way to achieve this is to add a simple helper script to your path:</p> |
837 <pre><code>cat << EOT > /tmp/configure |
836 <pre><code>cat << EOT > /tmp/configure |
845 EOT |
844 EOT |
846 chmod +x /tmp/configure |
845 chmod +x /tmp/configure |
847 sudo mv /tmp/configure /usr/local/bin</code></pre> |
846 sudo mv /tmp/configure /usr/local/bin</code></pre> |
848 <p>Now <code>configure --en<tab>-dt<tab></code> will result in <code>configure --enable-dtrace</code>.</p> |
847 <p>Now <code>configure --en<tab>-dt<tab></code> will result in <code>configure --enable-dtrace</code>.</p> |
849 <h3 id="using-multiple-configurations">Using Multiple Configurations</h3> |
848 <h3 id="using-multiple-configurations">Using Multiple Configurations</h3> |
850 <p>You can have multiple configurations for a single source forest. When you create a new configuration, run <code>configure --with-conf-name=<name></code> to create a configuration with the name <code><name></code>. Alternatively, you can create a directory under <code>build</code> and run <code>configure</code> from there, e.g. <code>mkdir build/<name> && cd build/<name> && bash ../../configure</code>.</p> |
849 <p>You can have multiple configurations for a single source repository. When you create a new configuration, run <code>configure --with-conf-name=<name></code> to create a configuration with the name <code><name></code>. Alternatively, you can create a directory under <code>build</code> and run <code>configure</code> from there, e.g. <code>mkdir build/<name> && cd build/<name> && bash ../../configure</code>.</p> |
851 <p>Then you can build that configuration using <code>make CONF_NAME=<name></code> or <code>make CONF=<pattern></code>, where <code><pattern></code> is a substring matching one or several configurations, e.g. <code>CONF=debug</code>. The special empty pattern (<code>CONF=</code>) will match <em>all</em> available configuration, so <code>make CONF= hotspot</code> will build the <code>hotspot</code> target for all configurations. Alternatively, you can execute <code>make</code> in the configuration directory, e.g. <code>cd build/<name> && make</code>.</p> |
850 <p>Then you can build that configuration using <code>make CONF_NAME=<name></code> or <code>make CONF=<pattern></code>, where <code><pattern></code> is a substring matching one or several configurations, e.g. <code>CONF=debug</code>. The special empty pattern (<code>CONF=</code>) will match <em>all</em> available configuration, so <code>make CONF= hotspot</code> will build the <code>hotspot</code> target for all configurations. Alternatively, you can execute <code>make</code> in the configuration directory, e.g. <code>cd build/<name> && make</code>.</p> |
852 <h3 id="handling-reconfigurations">Handling Reconfigurations</h3> |
851 <h3 id="handling-reconfigurations">Handling Reconfigurations</h3> |
853 <p>If you update the forest and part of the configure script has changed, the build system will force you to re-run <code>configure</code>.</p> |
852 <p>If you update the repository and part of the configure script has changed, the build system will force you to re-run <code>configure</code>.</p> |
854 <p>Most of the time, you will be fine by running <code>configure</code> again with the same arguments as the last time, which can easily be performed by <code>make reconfigure</code>. To simplify this, you can use the <code>CONF_CHECK</code> make control variable, either as <code>make CONF_CHECK=auto</code>, or by setting an environment variable. For instance, if you add <code>export CONF_CHECK=auto</code> to your <code>.bashrc</code> file, <code>make</code> will always run <code>reconfigure</code> automatically whenever the configure script has changed.</p> |
853 <p>Most of the time, you will be fine by running <code>configure</code> again with the same arguments as the last time, which can easily be performed by <code>make reconfigure</code>. To simplify this, you can use the <code>CONF_CHECK</code> make control variable, either as <code>make CONF_CHECK=auto</code>, or by setting an environment variable. For instance, if you add <code>export CONF_CHECK=auto</code> to your <code>.bashrc</code> file, <code>make</code> will always run <code>reconfigure</code> automatically whenever the configure script has changed.</p> |
855 <p>You can also use <code>CONF_CHECK=ignore</code> to skip the check for a needed configure update. This might speed up the build, but comes at the risk of an incorrect build result. This is only recommended if you know what you're doing.</p> |
854 <p>You can also use <code>CONF_CHECK=ignore</code> to skip the check for a needed configure update. This might speed up the build, but comes at the risk of an incorrect build result. This is only recommended if you know what you're doing.</p> |
856 <p>From time to time, you will also need to modify the command line to <code>configure</code> due to changes. Use <code>make print-configure</code> to show the command line used for your current configuration.</p> |
855 <p>From time to time, you will also need to modify the command line to <code>configure</code> due to changes. Use <code>make print-configure</code> to show the command line used for your current configuration.</p> |
857 <h3 id="using-fine-grained-make-targets">Using Fine-Grained Make Targets</h3> |
856 <h3 id="using-fine-grained-make-targets">Using Fine-Grained Make Targets</h3> |
858 <p>The default behavior for make is to create consistent and correct output, at the expense of build speed, if necessary.</p> |
857 <p>The default behavior for make is to create consistent and correct output, at the expense of build speed, if necessary.</p> |