39 <li><a href="#gcc">gcc</a></li>
40 <li><a href="#clang">clang</a></li>
41 <li><a href="#apple-xcode">Apple Xcode</a></li>
42 <li><a href="#oracle-solaris-studio">Oracle Solaris Studio</a></li>
43 <li><a href="#microsoft-visual-studio">Microsoft Visual Studio</a></li>
44 <li><a href="#ibm-xl-cc">IBM XL C/C++</a></li>
45 </ul></li>
46 <li><a href="#boot-jdk-requirements">Boot JDK Requirements</a><ul>
47 <li><a href="#jdk-8-on-linux">JDK 8 on Linux</a></li>
48 <li><a href="#jdk-8-on-windows">JDK 8 on Windows</a></li>
49 <li><a href="#jdk-8-on-macos">JDK 8 on macOS</a></li>
50 <li><a href="#jdk-8-on-aix">JDK 8 on AIX</a></li>
51 </ul></li>
52 <li><a href="#external-library-requirements">External Library Requirements</a><ul>
53 <li><a href="#freetype">FreeType</a></li>
54 <li><a href="#cups">CUPS</a></li>
55 <li><a href="#x11">X11</a></li>
56 <li><a href="#alsa">ALSA</a></li>
57 <li><a href="#libffi">libffi</a></li>
58 </ul></li>
59 <li><a href="#other-tooling-requirements">Other Tooling Requirements</a><ul>
60 <li><a href="#gnu-make">GNU Make</a></li>
61 <li><a href="#gnu-bash">GNU Bash</a></li>
62 <li><a href="#autoconf">Autoconf</a></li>
63 </ul></li>
64 <li><a href="#running-configure">Running Configure</a><ul>
65 <li><a href="#common-configure-arguments">Common Configure Arguments</a></li>
66 <li><a href="#configure-control-variables">Configure Control Variables</a></li>
67 </ul></li>
68 <li><a href="#running-make">Running Make</a><ul>
69 <li><a href="#common-make-targets">Common Make Targets</a></li>
70 <li><a href="#make-control-variables">Make Control Variables</a></li>
71 </ul></li>
72 <li><a href="#running-tests">Running Tests</a></li>
73 <li><a href="#cross-compiling">Cross-compiling</a><ul>
74 <li><a href="#boot-jdk-and-build-jdk">Boot JDK and Build JDK</a></li>
75 <li><a href="#specifying-the-target-platform">Specifying the Target Platform</a></li>
76 <li><a href="#toolchain-considerations">Toolchain Considerations</a></li>
77 <li><a href="#native-libraries">Native Libraries</a></li>
78 <li><a href="#building-for-armaarch64">Building for ARM/aarch64</a></li>
79 <li><a href="#verifying-the-build">Verifying the Build</a></li>
80 </ul></li>
81 <li><a href="#build-performance">Build Performance</a><ul>
82 <li><a href="#disk-speed">Disk Speed</a></li>
99 <li><a href="#using-multiple-configurations">Using Multiple Configurations</a></li>
100 <li><a href="#handling-reconfigurations">Handling Reconfigurations</a></li>
101 <li><a href="#using-fine-grained-make-targets">Using Fine-Grained Make Targets</a></li>
102 <li><a href="#learn-about-mercurial">Learn About Mercurial</a></li>
103 </ul></li>
104 <li><a href="#understanding-the-build-system">Understanding the Build System</a><ul>
105 <li><a href="#configurations">Configurations</a></li>
106 <li><a href="#build-output-structure">Build Output Structure</a></li>
107 <li><a href="#fixpath">Fixpath</a></li>
108 <li><a href="#native-debug-symbols">Native Debug Symbols</a></li>
109 <li><a href="#autoconf-details">Autoconf Details</a></li>
110 <li><a href="#developing-the-build-system-itself">Developing the Build System Itself</a></li>
111 </ul></li>
112 <li><a href="#contributing-to-openjdk">Contributing to OpenJDK</a></li>
113 </ul>
114 </nav>
115 <h2 id="tldr-instructions-for-the-impatient">TL;DR (Instructions for the Impatient)</h2>
116 <p>If you are eager to try out building OpenJDK, these simple steps works most of the time. They assume that you have installed Mercurial (and Cygwin if running on Windows) and cloned the top-level OpenJDK repository that you want to build.</p>
117 <ol type="1">
118 <li><p><a href="#getting-the-source-code">Get the complete source code</a>:<br />
119 <code>hg clone http://hg.openjdk.java.net/jdk10/master</code></p></li>
120 <li><p><a href="#running-configure">Run configure</a>:<br />
121 <code>bash configure</code></p>
122 <p>If <code>configure</code> fails due to missing dependencies (to either the <a href="#native-compiler-toolchain-requirements">toolchain</a>, <a href="#external-library-requirements">external libraries</a> or the <a href="#boot-jdk-requirements">boot JDK</a>), most of the time it prints a suggestion on how to resolve the situation on your platform. Follow the instructions, and try running <code>bash configure</code> again.</p></li>
123 <li><p><a href="#running-make">Run make</a>:<br />
124 <code>make images</code></p></li>
125 <li><p>Verify your newly built JDK:<br />
126 <code>./build/*/images/jdk/bin/java -version</code></p></li>
127 <li><p><a href="##running-tests">Run basic tests</a>:<br />
128 <code>make run-test-tier1</code></p></li>
129 </ol>
130 <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>
131 <h2 id="introduction">Introduction</h2>
132 <p>OpenJDK 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>
133 <p>If you just want to use OpenJDK 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 OpenJDK.</p>
134 <h2 id="getting-the-source-code">Getting the Source Code</h2>
135 <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>
136 <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>
137 <h3 id="special-considerations">Special Considerations</h3>
138 <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>
139 <ul>
140 <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>
141 <li><p>Do not check out the source code in a path which has a very long name or is nested many levels deep. Chances are you will hit an OS limitation during the build.</p></li>
142 <li><p>Put the source code on a local disk, not a network share. If possible, use an SSD. The build process is very disk intensive, and having slow disk access will significantly increase build times. If you need to use a network share for the source code, see below for suggestions on how to keep the build artifacts on a local disk.</p></li>
184 </tr>
185 <tr class="even">
186 <td style="text-align: left;">Windows</td>
187 <td style="text-align: left;">Windows Server 2012 R2</td>
188 </tr>
189 </tbody>
190 </table>
191 <p>The double version numbers for Linux, Solaris and macOS is due to the hybrid model used at Oracle, where header files and external libraries from an older version is used when building on a more modern version of the OS.</p>
192 <p>The Build Group has a wiki page with <a href="https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms">Supported Build Platforms</a>. From time to time, this is updated by the community to list successes or failures of building on different platforms.</p>
193 <h3 id="windows">Windows</h3>
194 <p>Windows XP is not a supported platform, but all newer Windows should be able to build OpenJDK.</p>
195 <p>On Windows, it is important that you pay attention to the instructions in the <a href="#special-considerations">Special Considerations</a>.</p>
196 <p>Windows is the only non-POSIX OS supported by OpenJDK, and as such, requires some extra care. A POSIX support layer is required to build on Windows. For OpenJDK 9, the only supported such layer is Cygwin. (Msys is no longer supported due to a too old bash; msys2 and the new Windows Subsystem for Linux (WSL) would likely be possible to support in a future version but that would require a community effort to implement.)</p>
197 <p>Internally in the build system, all paths are represented as Unix-style paths, e.g. <code>/cygdrive/c/hg/jdk9/Makefile</code> rather than <code>C:\hg\jdk9\Makefile</code>. This rule also applies to input to the build system, e.g. in arguments to <code>configure</code>. So, use <code>--with-freetype=/cygdrive/c/freetype</code> rather than <code>--with-freetype=c:\freetype</code>. For details on this conversion, see the section on <a href="#fixpath">Fixpath</a>.</p>
198 <h4 id="cygwin">Cygwin</h4>
199 <p>A functioning <a href="http://www.cygwin.com/">Cygwin</a> environment is thus required for building OpenJDK on Windows. If you have a 64-bit OS, we strongly recommend using the 64-bit version of Cygwin.</p>
200 <p><strong>Note:</strong> Cygwin has a model of continuously updating all packages without any easy way to install or revert to a specific version of a package. This means that whenever you add or update a package in Cygwin, you might (inadvertently) update tools that are used by the OpenJDK build process, and that can cause unexpected build problems.</p>
201 <p>OpenJDK requires GNU Make 4.0 or greater on Windows. This is usually not a problem, since Cygwin currently only distributes GNU Make at a version above 4.0.</p>
202 <p>Apart from the basic Cygwin installation, the following packages must also be installed:</p>
203 <ul>
204 <li><code>make</code></li>
205 <li><code>zip</code></li>
206 <li><code>unzip</code></li>
207 </ul>
208 <p>Often, you can install these packages using the following command line:</p>
209 <pre><code><path to Cygwin setup>/setup-x86_64 -q -P make -P unzip -P zip</code></pre>
210 <p>Unfortunately, Cygwin can be unreliable in certain circumstances. If you experience build tool crashes or strange issues when building on Windows, please check the Cygwin FAQ on the <a href="https://cygwin.com/faq/faq.html#faq.using.bloda">"BLODA" list</a> and the section on <a href="https://cygwin.com/faq/faq.html#faq.using.fixing-fork-failures">fork() failures</a>.</p>
211 <h3 id="solaris">Solaris</h3>
212 <p>See <code>make/devkit/solaris11.1-package-list.txt</code> for a list of recommended packages to install when building on Solaris. The versions specified in this list is the versions used by the daily builds at Oracle, and is likely to work properly.</p>
213 <p>Older versions of Solaris shipped a broken version of <code>objcopy</code>. At least version 2.21.1 is needed, which is provided by Solaris 11 Update 1. Objcopy is needed if you want to have external debug symbols. Please make sure you are using at least version 2.21.1 of objcopy, or that you disable external debug symbols.</p>
214 <h3 id="macos">macOS</h3>
215 <p>Apple is using a quite aggressive scheme of pushing OS updates, and coupling these updates with required updates of Xcode. Unfortunately, this makes it difficult for a project like OpenJDK to keep pace with a continuously updated machine running macOS. See the section on <a href="#apple-xcode">Apple Xcode</a> on some strategies to deal with this.</p>
216 <p>It is recommended that you use at least Mac OS X 10.9 (Mavericks). At the time of writing, OpenJDK has been successfully compiled on macOS versions up to 10.12.5 (Sierra), using XCode 8.3.2 and <code>--disable-warnings-as-errors</code>.</p>
217 <p>The standard macOS environment contains the basic tooling needed to build, but for external libraries a package manager is recommended. OpenJDK uses <a href="https://brew.sh/">homebrew</a> in the examples, but feel free to use whatever manager you want (or none).</p>
218 <h3 id="linux">Linux</h3>
219 <p>It is often not much problem to build OpenJDK on Linux. The only general advice is to try to use the compilers, external libraries and header files as provided by your distribution.</p>
220 <p>The basic tooling is provided as part of the core operating system, but you will most likely need to install developer packages.</p>
221 <p>For apt-based distributions (Debian, Ubuntu, etc), try this:</p>
222 <pre><code>sudo apt-get install build-essential</code></pre>
223 <p>For rpm-based distributions (Fedora, Red Hat, etc), try this:</p>
224 <pre><code>sudo yum groupinstall "Development Tools"</code></pre>
225 <h3 id="aix">AIX</h3>
226 <p>The regular builds by SAP is using AIX version 7.1, but AIX 5.3 is also supported. See the <a href="http://cr.openjdk.java.net/~simonis/ppc-aix-port">OpenJDK PowerPC Port Status Page</a> for details.</p>
227 <h2 id="native-compiler-toolchain-requirements">Native Compiler (Toolchain) Requirements</h2>
228 <p>Large portions of OpenJDK consists of native code, that needs to be compiled to be able to run on the target platform. In theory, toolchain and operating system should be independent factors, but in practice there's more or less a one-to-one correlation between target operating system and toolchain.</p>
229 <table>
407 <ul>
408 <li>To install on an apt-based Linux, try running <code>sudo apt-get install libx11-dev libxext-dev libxrender-dev libxtst-dev libxt-dev</code>.</li>
409 <li>To install on an rpm-based Linux, try running <code>sudo yum install libXtst-devel libXt-devel libXrender-devel libXi-devel</code>.</li>
410 <li>To install on Solaris, try running <code>pkg install x11/header/x11-protocols x11/library/libice x11/library/libpthread-stubs x11/library/libsm x11/library/libx11 x11/library/libxau x11/library/libxcb x11/library/libxdmcp x11/library/libxevie x11/library/libxext x11/library/libxrender x11/library/libxscrnsaver x11/library/libxtst x11/library/toolkit/libxt</code>.</li>
411 </ul>
412 <p>Use <code>--with-x=<path></code> if <code>configure</code> does not properly locate your X11 files.</p>
413 <h3 id="alsa">ALSA</h3>
414 <p>ALSA, <a href="https://www.alsa-project.org/">Advanced Linux Sound Architecture</a> is required on Linux. At least version 0.9.1 of ALSA is required.</p>
415 <ul>
416 <li>To install on an apt-based Linux, try running <code>sudo apt-get install libasound2-dev</code>.</li>
417 <li>To install on an rpm-based Linux, try running <code>sudo yum install alsa-lib-devel</code>.</li>
418 </ul>
419 <p>Use <code>--with-alsa=<path></code> if <code>configure</code> does not properly locate your ALSA files.</p>
420 <h3 id="libffi">libffi</h3>
421 <p>libffi, the <a href="http://sourceware.org/libffi">Portable Foreign Function Interface Library</a> is required when building the Zero version of Hotspot.</p>
422 <ul>
423 <li>To install on an apt-based Linux, try running <code>sudo apt-get install libffi-dev</code>.</li>
424 <li>To install on an rpm-based Linux, try running <code>sudo yum install libffi-devel</code>.</li>
425 </ul>
426 <p>Use <code>--with-libffi=<path></code> if <code>configure</code> does not properly locate your libffi files.</p>
427 <h2 id="other-tooling-requirements">Other Tooling Requirements</h2>
428 <h3 id="gnu-make">GNU Make</h3>
429 <p>OpenJDK requires <a href="http://www.gnu.org/software/make">GNU Make</a>. No other flavors of make are supported.</p>
430 <p>At least version 3.81 of GNU Make must be used. For distributions supporting GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful functionality to handle parallel building (supported by <code>--with-output-sync</code>) and speed and stability improvements.</p>
431 <p>Note that <code>configure</code> locates and verifies a properly functioning version of <code>make</code> and stores the path to this <code>make</code> binary in the configuration. If you start a build using <code>make</code> on the command line, you will be using the version of make found first in your <code>PATH</code>, and not necessarily the one stored in the configuration. This initial make will be used as "bootstrap make", and in a second stage, the make located by <code>configure</code> will be called. Normally, this will present no issues, but if you have a very old <code>make</code>, or a non-GNU Make <code>make</code> in your path, this might cause issues.</p>
432 <p>If you want to override the default make found by <code>configure</code>, use the <code>MAKE</code> configure variable, e.g. <code>configure MAKE=/opt/gnu/make</code>.</p>
433 <p>On Solaris, it is common to call the GNU version of make by using <code>gmake</code>.</p>
434 <h3 id="gnu-bash">GNU Bash</h3>
435 <p>OpenJDK requires <a href="http://www.gnu.org/software/bash">GNU Bash</a>. No other shells are supported.</p>
436 <p>At least version 3.2 of GNU Bash must be used.</p>
437 <h3 id="autoconf">Autoconf</h3>
438 <p>If you want to modify the build system itself, you need to install <a href="http://www.gnu.org/software/autoconf">Autoconf</a>.</p>
439 <p>However, if you only need to build OpenJDK or if you only edit the actual OpenJDK source files, there is no dependency on autoconf, since the source distribution includes a pre-generated <code>configure</code> shell script.</p>
440 <p>See the section on <a href="#autoconf-details">Autoconf Details</a> for details on how OpenJDK uses autoconf. This is especially important if you plan to contribute changes to OpenJDK that modifies the build system.</p>
441 <h2 id="running-configure">Running Configure</h2>
442 <p>To build OpenJDK, you need a "configuration", which consists of a directory where to store the build output, coupled with information about the platform, the specific build machine, and choices that affect how OpenJDK is built.</p>
443 <p>The configuration is created by the <code>configure</code> script. The basic invocation of the <code>configure</code> script looks like this:</p>
444 <pre><code>bash configure [options]</code></pre>
445 <p>This will create an output directory containing the configuration and setup an area for the build result. This directory typically looks like <code>build/linux-x64-normal-server-release</code>, but the actual name depends on your specific configuration. (It can also be set directly, see <a href="#using-multiple-configurations">Using Multiple Configurations</a>). This directory is referred to as <code>$BUILD</code> in this documentation.</p>
446 <p><code>configure</code> will try to figure out what system you are running on and where all necessary build components are. If you have all prerequisites for building installed, it should find everything. If it fails to detect any component automatically, it will exit and inform you about the problem.</p>
447 <p>Some command line examples:</p>
448 <ul>
449 <li><p>Create a 32-bit build for Windows with FreeType2 in <code>C:\freetype-i586</code>:</p>
450 <pre><code>bash configure --with-freetype=/cygdrive/c/freetype-i586 --with-target-bits=32</code></pre></li>
451 <li><p>Create a debug build with the <code>server</code> JVM and DTrace enabled:</p>
452 <pre><code>bash configure --enable-debug --with-jvm-variants=server --enable-dtrace</code></pre></li>
453 </ul>
454 <h3 id="common-configure-arguments">Common Configure Arguments</h3>
455 <p>Here follows some of the most common and important <code>configure</code> argument.</p>
456 <p>To get up-to-date information on <em>all</em> available <code>configure</code> argument, please run:</p>
457 <pre><code>bash configure --help</code></pre>
458 <p>(Note that this help text also include general autoconf options, like <code>--dvidir</code>, that is not relevant to OpenJDK. To list only OpenJDK specific features, use <code>bash configure --help=short</code> instead.)</p>
459 <h4 id="configure-arguments-for-tailoring-the-build">Configure Arguments for Tailoring the Build</h4>
460 <ul>
734 <li><p>Re-clone the Mercurial forest</p>
735 <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>
736 </ol>
737 <h3 id="specific-build-issues">Specific Build Issues</h3>
738 <h4 id="clock-skew">Clock Skew</h4>
739 <p>If you get an error message like this:</p>
740 <pre><code>File 'xxx' has modification time in the future.
741 Clock skew detected. Your build may be incomplete.</code></pre>
742 <p>then the clock on your build machine is out of sync with the timestamps on the source files. Other errors, apparently unrelated but in fact caused by the clock skew, can occur along with the clock skew warnings. These secondary errors may tend to obscure the fact that the true root cause of the problem is an out-of-sync clock.</p>
743 <p>If you see these warnings, reset the clock on the build machine, run <code>make clean</code> and restart the build.</p>
744 <h4 id="out-of-memory-errors">Out of Memory Errors</h4>
745 <p>On Solaris, you might get an error message like this:</p>
746 <pre><code>Trouble writing out table to disk</code></pre>
747 <p>To solve this, increase the amount of swap space on your build machine.</p>
748 <p>On Windows, you might get error messages like this:</p>
749 <pre><code>fatal error - couldn't allocate heap
750 cannot create ... Permission denied
751 spawn failed</code></pre>
752 <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>
753 <h3 id="getting-help">Getting Help</h3>
754 <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>
755 <p>If you need general help or advice about developing for OpenJDK, you can also contact the Adoption Group. See the section on <a href="#contributing-to-openjdk">Contributing to OpenJDK</a> for more information.</p>
756 <h2 id="hints-and-suggestions-for-advanced-users">Hints and Suggestions for Advanced Users</h2>
757 <h3 id="setting-up-a-forest-for-pushing-changes-defpath">Setting Up a Forest for Pushing Changes (defpath)</h3>
758 <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 OpenJDK.</p>
759 <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>
760 <pre><code>cd ~
761 mkdir hg-ext
762 cd hg-ext
763 hg clone http://hg.openjdk.java.net/code-tools/defpath
764 cat << EOT >> ~/.hgrc
765 [extensions]
766 defpath=~/hg-ext/defpath/defpath.py
767 EOT</code></pre>
768 <p>You can now setup a proper push path using:</p>
769 <pre><code>hg defpath -d -u <your OpenJDK username></code></pre>
770 <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>
771 <h3 id="bash-completion">Bash Completion</h3>
772 <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>
773 <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>
774 <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>
854 <li><p><code>buildtools</code>: This is an area for tools compiled for the build platform that are used during the rest of the build.</p></li>
855 <li><p><code>hotspot</code>: This is an area for intermediate files needed when building hotspot.</p></li>
856 <li><p><code>configure-support</code>, <code>make-support</code> and <code>test-support</code>: These directories contain files that are needed by the build system for <code>configure</code>, <code>make</code> and for running tests.</p></li>
857 </ul>
858 <h3 id="fixpath">Fixpath</h3>
859 <p>Windows path typically look like <code>C:\User\foo</code>, while Unix paths look like <code>/home/foo</code>. Tools with roots from Unix often experience issues related to this mismatch when running on Windows.</p>
860 <p>In the OpenJDK build, we always use Unix paths internally, and only just before calling a tool that does not understand Unix paths do we convert them to Windows paths.</p>
861 <p>This conversion is done by the <code>fixpath</code> tool, which is a small wrapper that modifies unix-style paths to Windows-style paths in command lines. Fixpath is compiled automatically by <code>configure</code>.</p>
862 <h3 id="native-debug-symbols">Native Debug Symbols</h3>
863 <p>Native libraries and executables can have debug symbol (and other debug information) associated with them. How this works is very much platform dependent, but a common problem is that debug symbol information takes a lot of disk space, but is rarely needed by the end user.</p>
864 <p>The OpenJDK supports different methods on how to handle debug symbols. The method used is selected by <code>--with-native-debug-symbols</code>, and available methods are <code>none</code>, <code>internal</code>, <code>external</code>, <code>zipped</code>.</p>
865 <ul>
866 <li><p><code>none</code> means that no debug symbols will be generated during the build.</p></li>
867 <li><p><code>internal</code> means that debug symbols will be generated during the build, and they will be stored in the generated binary.</p></li>
868 <li><p><code>external</code> means that debug symbols will be generated during the build, and after the compilation, they will be moved into a separate <code>.debuginfo</code> file. (This was previously known as FDS, Full Debug Symbols).</p></li>
869 <li><p><code>zipped</code> is like <code>external</code>, but the .debuginfo file will also be zipped into a <code>.diz</code> file.</p></li>
870 </ul>
871 <p>When building for distribution, <code>zipped</code> is a good solution. Binaries built with <code>internal</code> is suitable for use by developers, since they facilitate debugging, but should be stripped before distributed to end users.</p>
872 <h3 id="autoconf-details">Autoconf Details</h3>
873 <p>The <code>configure</code> script is based on the autoconf framework, but in some details deviate from a normal autoconf <code>configure</code> script.</p>
874 <p>The <code>configure</code> script in the top level directory of OpenJDK is just a thin wrapper that calls <code>make/autoconf/configure</code>. This in turn provides functionality that is not easily expressed in the normal Autoconf framework, and then calls into the core of the <code>configure</code> script, which is the <code>make/autoconf/generated-configure.sh</code> file.</p>
875 <p>As the name implies, this file is generated by Autoconf. It is checked in after regeneration, to alleviate the common user to have to install Autoconf.</p>
876 <p>The build system will detect if the Autoconf source files have changed, and will trigger a regeneration of <code>make/autoconf/generated-configure.sh</code> if needed. You can also manually request such an update by <code>bash make/autoconf/autogen.sh</code>.</p>
877 <p>If you make changes to the build system that requires a re-generation, note the following:</p>
878 <ul>
879 <li><p>You must use <em>exactly</em> version 2.69 of autoconf for your patch to be accepted. This is to avoid spurious changes in the generated file. Note that Ubuntu 16.04 ships a patched version of autoconf which claims to be 2.69, but is not.</p></li>
880 <li><p>You do not need to include the generated file in reviews.</p></li>
881 <li><p>If the generated file needs updating, the Oracle JDK closed counter-part will also need to be updated. It is very much appreciated if you ask for an Oracle engineer to sponsor your push so this can be made in tandem.</p></li>
882 </ul>
883 <h3 id="developing-the-build-system-itself">Developing the Build System Itself</h3>
884 <p>This section contains a few remarks about how to develop for the build system itself. It is not relevant if you are only making changes in the product source code.</p>
885 <p>While technically using <code>make</code>, the make source files of the OpenJDK does not resemble most other Makefiles. Instead of listing specific targets and actions (perhaps using patterns), the basic modus operandi is to call a high-level function (or properly, macro) from the API in <code>make/common</code>. For instance, to compile all classes in the <code>jdk.internal.foo</code> package in the <code>jdk.foo</code> module, a call like this would be made:</p>
886 <pre><code>$(eval $(call SetupJavaCompilation, BUILD_FOO_CLASSES, \
887 SETUP := GENERATE_OLDBYTECODE, \
888 SRC := $(TOPDIR)/src/jkd.foo/share/classes, \
889 INCLUDES := jdk/internal/foo, \
890 BIN := $(SUPPORT_OUTPUTDIR)/foo_classes, \
891 ))</code></pre>
892 <p>By encapsulating and expressing the high-level knowledge of <em>what</em> should be done, rather than <em>how</em> it should be done (as is normal in Makefiles), we can build a much more powerful and flexible build system.</p>
893 <p>Correct dependency tracking is paramount. Sloppy dependency tracking will lead to improper parallelization, or worse, race conditions.</p>
894 <p>To test for/debug race conditions, try running <code>make JOBS=1</code> and <code>make JOBS=100</code> and see if it makes any difference. (It shouldn't).</p>
895 <p>To compare the output of two different builds and see if, and how, they differ, run <code>$BUILD1/compare.sh -o $BUILD2</code>, where <code>$BUILD1</code> and <code>$BUILD2</code> are the two builds you want to compare.</p>
896 <p>To automatically build two consecutive versions and compare them, use <code>COMPARE_BUILD</code>. The value of <code>COMPARE_BUILD</code> is a set of variable=value assignments, like this:</p>
897 <pre><code>make COMPARE_BUILD=CONF=--enable-new-hotspot-feature:MAKE=hotspot</code></pre>
898 <p>See <code>make/InitSupport.gmk</code> for details on how to use <code>COMPARE_BUILD</code>.</p>
899 <p>To analyze build performance, run with <code>LOG=trace</code> and check <code>$BUILD/build-trace-time.log</code>. Use <code>JOBS=1</code> to avoid parallelism.</p>
900 <p>Please check that you adhere to the <a href="http://openjdk.java.net/groups/build/doc/code-conventions.html">Code Conventions for the Build System</a> before submitting patches. Also see the section in <a href="#autoconf-details">Autoconf Details</a> about the generated configure script.</p>
901 <h2 id="contributing-to-openjdk">Contributing to OpenJDK</h2>
902 <p>So, now you've build your OpenJDK, and made your first patch, and want to contribute it back to the OpenJDK community.</p>
903 <p>First of all: Thank you! We gladly welcome your contribution to the OpenJDK. However, please bear in mind that OpenJDK is a massive project, and we must ask you to follow our rules and guidelines to be able to accept your contribution.</p>
904 <p>The official place to start is the <a href="http://openjdk.java.net/contribute/">'How to contribute' page</a>. There is also an official (but somewhat outdated and skimpy on details) <a href="http://openjdk.java.net/guide/">Developer's Guide</a>.</p>
905 <p>If this seems overwhelming to you, the Adoption Group is there to help you! A good place to start is their <a href="https://wiki.openjdk.java.net/display/Adoption/New+Contributor">'New Contributor' page</a>, or start reading the comprehensive <a href="https://adoptopenjdk.gitbooks.io/adoptopenjdk-getting-started-kit/en/">Getting Started Kit</a>. The Adoption Group will also happily answer any questions you have about contributing. Contact them by <a href="http://mail.openjdk.java.net/mailman/listinfo/adoption-discuss">mail</a> or <a href="http://openjdk.java.net/irc/">IRC</a>.</p>
906 </body>
907 </html>
|
39 <li><a href="#gcc">gcc</a></li>
40 <li><a href="#clang">clang</a></li>
41 <li><a href="#apple-xcode">Apple Xcode</a></li>
42 <li><a href="#oracle-solaris-studio">Oracle Solaris Studio</a></li>
43 <li><a href="#microsoft-visual-studio">Microsoft Visual Studio</a></li>
44 <li><a href="#ibm-xl-cc">IBM XL C/C++</a></li>
45 </ul></li>
46 <li><a href="#boot-jdk-requirements">Boot JDK Requirements</a><ul>
47 <li><a href="#jdk-8-on-linux">JDK 8 on Linux</a></li>
48 <li><a href="#jdk-8-on-windows">JDK 8 on Windows</a></li>
49 <li><a href="#jdk-8-on-macos">JDK 8 on macOS</a></li>
50 <li><a href="#jdk-8-on-aix">JDK 8 on AIX</a></li>
51 </ul></li>
52 <li><a href="#external-library-requirements">External Library Requirements</a><ul>
53 <li><a href="#freetype">FreeType</a></li>
54 <li><a href="#cups">CUPS</a></li>
55 <li><a href="#x11">X11</a></li>
56 <li><a href="#alsa">ALSA</a></li>
57 <li><a href="#libffi">libffi</a></li>
58 </ul></li>
59 <li><a href="#build-tools-requirements">Build Tools Requirements</a><ul>
60 <li><a href="#autoconf">Autoconf</a></li>
61 <li><a href="#gnu-make">GNU Make</a></li>
62 <li><a href="#gnu-bash">GNU Bash</a></li>
63 </ul></li>
64 <li><a href="#running-configure">Running Configure</a><ul>
65 <li><a href="#common-configure-arguments">Common Configure Arguments</a></li>
66 <li><a href="#configure-control-variables">Configure Control Variables</a></li>
67 </ul></li>
68 <li><a href="#running-make">Running Make</a><ul>
69 <li><a href="#common-make-targets">Common Make Targets</a></li>
70 <li><a href="#make-control-variables">Make Control Variables</a></li>
71 </ul></li>
72 <li><a href="#running-tests">Running Tests</a></li>
73 <li><a href="#cross-compiling">Cross-compiling</a><ul>
74 <li><a href="#boot-jdk-and-build-jdk">Boot JDK and Build JDK</a></li>
75 <li><a href="#specifying-the-target-platform">Specifying the Target Platform</a></li>
76 <li><a href="#toolchain-considerations">Toolchain Considerations</a></li>
77 <li><a href="#native-libraries">Native Libraries</a></li>
78 <li><a href="#building-for-armaarch64">Building for ARM/aarch64</a></li>
79 <li><a href="#verifying-the-build">Verifying the Build</a></li>
80 </ul></li>
81 <li><a href="#build-performance">Build Performance</a><ul>
82 <li><a href="#disk-speed">Disk Speed</a></li>
99 <li><a href="#using-multiple-configurations">Using Multiple Configurations</a></li>
100 <li><a href="#handling-reconfigurations">Handling Reconfigurations</a></li>
101 <li><a href="#using-fine-grained-make-targets">Using Fine-Grained Make Targets</a></li>
102 <li><a href="#learn-about-mercurial">Learn About Mercurial</a></li>
103 </ul></li>
104 <li><a href="#understanding-the-build-system">Understanding the Build System</a><ul>
105 <li><a href="#configurations">Configurations</a></li>
106 <li><a href="#build-output-structure">Build Output Structure</a></li>
107 <li><a href="#fixpath">Fixpath</a></li>
108 <li><a href="#native-debug-symbols">Native Debug Symbols</a></li>
109 <li><a href="#autoconf-details">Autoconf Details</a></li>
110 <li><a href="#developing-the-build-system-itself">Developing the Build System Itself</a></li>
111 </ul></li>
112 <li><a href="#contributing-to-openjdk">Contributing to OpenJDK</a></li>
113 </ul>
114 </nav>
115 <h2 id="tldr-instructions-for-the-impatient">TL;DR (Instructions for the Impatient)</h2>
116 <p>If you are eager to try out building OpenJDK, these simple steps works most of the time. They assume that you have installed Mercurial (and Cygwin if running on Windows) and cloned the top-level OpenJDK repository that you want to build.</p>
117 <ol type="1">
118 <li><p><a href="#getting-the-source-code">Get the complete source code</a>:<br />
119 <code>hg clone http://hg.openjdk.java.net/jdk/jdk</code></p></li>
120 <li><p><a href="#running-configure">Run configure</a>:<br />
121 <code>bash configure</code></p>
122 <p>If <code>configure</code> fails due to missing dependencies (to either the <a href="#native-compiler-toolchain-requirements">toolchain</a>, <a href="#build-tools-requirements">build tools</a>, <a href="#external-library-requirements">external libraries</a> or the <a href="#boot-jdk-requirements">boot JDK</a>), most of the time it prints a suggestion on how to resolve the situation on your platform. Follow the instructions, and try running <code>bash configure</code> again.</p></li>
123 <li><p><a href="#running-make">Run make</a>:<br />
124 <code>make images</code></p></li>
125 <li><p>Verify your newly built JDK:<br />
126 <code>./build/*/images/jdk/bin/java -version</code></p></li>
127 <li><p><a href="##running-tests">Run basic tests</a>:<br />
128 <code>make run-test-tier1</code></p></li>
129 </ol>
130 <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>
131 <h2 id="introduction">Introduction</h2>
132 <p>OpenJDK 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>
133 <p>If you just want to use OpenJDK 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 OpenJDK.</p>
134 <h2 id="getting-the-source-code">Getting the Source Code</h2>
135 <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>
136 <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>
137 <h3 id="special-considerations">Special Considerations</h3>
138 <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>
139 <ul>
140 <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>
141 <li><p>Do not check out the source code in a path which has a very long name or is nested many levels deep. Chances are you will hit an OS limitation during the build.</p></li>
142 <li><p>Put the source code on a local disk, not a network share. If possible, use an SSD. The build process is very disk intensive, and having slow disk access will significantly increase build times. If you need to use a network share for the source code, see below for suggestions on how to keep the build artifacts on a local disk.</p></li>
184 </tr>
185 <tr class="even">
186 <td style="text-align: left;">Windows</td>
187 <td style="text-align: left;">Windows Server 2012 R2</td>
188 </tr>
189 </tbody>
190 </table>
191 <p>The double version numbers for Linux, Solaris and macOS is due to the hybrid model used at Oracle, where header files and external libraries from an older version is used when building on a more modern version of the OS.</p>
192 <p>The Build Group has a wiki page with <a href="https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms">Supported Build Platforms</a>. From time to time, this is updated by the community to list successes or failures of building on different platforms.</p>
193 <h3 id="windows">Windows</h3>
194 <p>Windows XP is not a supported platform, but all newer Windows should be able to build OpenJDK.</p>
195 <p>On Windows, it is important that you pay attention to the instructions in the <a href="#special-considerations">Special Considerations</a>.</p>
196 <p>Windows is the only non-POSIX OS supported by OpenJDK, and as such, requires some extra care. A POSIX support layer is required to build on Windows. For OpenJDK 9, the only supported such layer is Cygwin. (Msys is no longer supported due to a too old bash; msys2 and the new Windows Subsystem for Linux (WSL) would likely be possible to support in a future version but that would require a community effort to implement.)</p>
197 <p>Internally in the build system, all paths are represented as Unix-style paths, e.g. <code>/cygdrive/c/hg/jdk9/Makefile</code> rather than <code>C:\hg\jdk9\Makefile</code>. This rule also applies to input to the build system, e.g. in arguments to <code>configure</code>. So, use <code>--with-freetype=/cygdrive/c/freetype</code> rather than <code>--with-freetype=c:\freetype</code>. For details on this conversion, see the section on <a href="#fixpath">Fixpath</a>.</p>
198 <h4 id="cygwin">Cygwin</h4>
199 <p>A functioning <a href="http://www.cygwin.com/">Cygwin</a> environment is thus required for building OpenJDK on Windows. If you have a 64-bit OS, we strongly recommend using the 64-bit version of Cygwin.</p>
200 <p><strong>Note:</strong> Cygwin has a model of continuously updating all packages without any easy way to install or revert to a specific version of a package. This means that whenever you add or update a package in Cygwin, you might (inadvertently) update tools that are used by the OpenJDK build process, and that can cause unexpected build problems.</p>
201 <p>OpenJDK requires GNU Make 4.0 or greater on Windows. This is usually not a problem, since Cygwin currently only distributes GNU Make at a version above 4.0.</p>
202 <p>Apart from the basic Cygwin installation, the following packages must also be installed:</p>
203 <ul>
204 <li><code>autoconf</code></li>
205 <li><code>make</code></li>
206 <li><code>zip</code></li>
207 <li><code>unzip</code></li>
208 </ul>
209 <p>Often, you can install these packages using the following command line:</p>
210 <pre><code><path to Cygwin setup>/setup-x86_64 -q -P autoconf -P make -P unzip -P zip</code></pre>
211 <p>Unfortunately, Cygwin can be unreliable in certain circumstances. If you experience build tool crashes or strange issues when building on Windows, please check the Cygwin FAQ on the <a href="https://cygwin.com/faq/faq.html#faq.using.bloda">"BLODA" list</a> and the section on <a href="https://cygwin.com/faq/faq.html#faq.using.fixing-fork-failures">fork() failures</a>.</p>
212 <h3 id="solaris">Solaris</h3>
213 <p>See <code>make/devkit/solaris11.1-package-list.txt</code> for a list of recommended packages to install when building on Solaris. The versions specified in this list is the versions used by the daily builds at Oracle, and is likely to work properly.</p>
214 <p>Older versions of Solaris shipped a broken version of <code>objcopy</code>. At least version 2.21.1 is needed, which is provided by Solaris 11 Update 1. Objcopy is needed if you want to have external debug symbols. Please make sure you are using at least version 2.21.1 of objcopy, or that you disable external debug symbols.</p>
215 <h3 id="macos">macOS</h3>
216 <p>Apple is using a quite aggressive scheme of pushing OS updates, and coupling these updates with required updates of Xcode. Unfortunately, this makes it difficult for a project like OpenJDK to keep pace with a continuously updated machine running macOS. See the section on <a href="#apple-xcode">Apple Xcode</a> on some strategies to deal with this.</p>
217 <p>It is recommended that you use at least Mac OS X 10.9 (Mavericks). At the time of writing, OpenJDK has been successfully compiled on macOS versions up to 10.12.5 (Sierra), using XCode 8.3.2 and <code>--disable-warnings-as-errors</code>.</p>
218 <p>The standard macOS environment contains the basic tooling needed to build, but for external libraries a package manager is recommended. OpenJDK uses <a href="https://brew.sh/">homebrew</a> in the examples, but feel free to use whatever manager you want (or none).</p>
219 <h3 id="linux">Linux</h3>
220 <p>It is often not much problem to build OpenJDK on Linux. The only general advice is to try to use the compilers, external libraries and header files as provided by your distribution.</p>
221 <p>The basic tooling is provided as part of the core operating system, but you will most likely need to install developer packages.</p>
222 <p>For apt-based distributions (Debian, Ubuntu, etc), try this:</p>
223 <pre><code>sudo apt-get install build-essential</code></pre>
224 <p>For rpm-based distributions (Fedora, Red Hat, etc), try this:</p>
225 <pre><code>sudo yum groupinstall "Development Tools"</code></pre>
226 <h3 id="aix">AIX</h3>
227 <p>The regular builds by SAP is using AIX version 7.1, but AIX 5.3 is also supported. See the <a href="http://cr.openjdk.java.net/~simonis/ppc-aix-port">OpenJDK PowerPC Port Status Page</a> for details.</p>
228 <h2 id="native-compiler-toolchain-requirements">Native Compiler (Toolchain) Requirements</h2>
229 <p>Large portions of OpenJDK consists of native code, that needs to be compiled to be able to run on the target platform. In theory, toolchain and operating system should be independent factors, but in practice there's more or less a one-to-one correlation between target operating system and toolchain.</p>
230 <table>
408 <ul>
409 <li>To install on an apt-based Linux, try running <code>sudo apt-get install libx11-dev libxext-dev libxrender-dev libxtst-dev libxt-dev</code>.</li>
410 <li>To install on an rpm-based Linux, try running <code>sudo yum install libXtst-devel libXt-devel libXrender-devel libXi-devel</code>.</li>
411 <li>To install on Solaris, try running <code>pkg install x11/header/x11-protocols x11/library/libice x11/library/libpthread-stubs x11/library/libsm x11/library/libx11 x11/library/libxau x11/library/libxcb x11/library/libxdmcp x11/library/libxevie x11/library/libxext x11/library/libxrender x11/library/libxscrnsaver x11/library/libxtst x11/library/toolkit/libxt</code>.</li>
412 </ul>
413 <p>Use <code>--with-x=<path></code> if <code>configure</code> does not properly locate your X11 files.</p>
414 <h3 id="alsa">ALSA</h3>
415 <p>ALSA, <a href="https://www.alsa-project.org/">Advanced Linux Sound Architecture</a> is required on Linux. At least version 0.9.1 of ALSA is required.</p>
416 <ul>
417 <li>To install on an apt-based Linux, try running <code>sudo apt-get install libasound2-dev</code>.</li>
418 <li>To install on an rpm-based Linux, try running <code>sudo yum install alsa-lib-devel</code>.</li>
419 </ul>
420 <p>Use <code>--with-alsa=<path></code> if <code>configure</code> does not properly locate your ALSA files.</p>
421 <h3 id="libffi">libffi</h3>
422 <p>libffi, the <a href="http://sourceware.org/libffi">Portable Foreign Function Interface Library</a> is required when building the Zero version of Hotspot.</p>
423 <ul>
424 <li>To install on an apt-based Linux, try running <code>sudo apt-get install libffi-dev</code>.</li>
425 <li>To install on an rpm-based Linux, try running <code>sudo yum install libffi-devel</code>.</li>
426 </ul>
427 <p>Use <code>--with-libffi=<path></code> if <code>configure</code> does not properly locate your libffi files.</p>
428 <h2 id="build-tools-requirements">Build Tools Requirements</h2>
429 <h3 id="autoconf">Autoconf</h3>
430 <p>OpenJDK requires <a href="http://www.gnu.org/software/autoconf">Autoconf</a> on all platforms. At least version 2.69 is required.</p>
431 <ul>
432 <li>To install on an apt-based Linux, try running <code>sudo apt-get install autoconf</code>.</li>
433 <li>To install on an rpm-based Linux, try running <code>sudo yum install autoconf</code>.</li>
434 <li>To install on macOS, try running <code>brew install autoconf</code>.</li>
435 <li>To install on Windows, try running <code><path to Cygwin setup>/setup-x86_64 -q -P autoconf</code>.</li>
436 </ul>
437 <p>If <code>configure</code> has problems locating your installation of autoconf, you can specify it using the <code>AUTOCONF</code> environment variable, like this:</p>
438 <pre><code>AUTOCONF=<path to autoconf> configure ...</code></pre>
439 <h3 id="gnu-make">GNU Make</h3>
440 <p>OpenJDK requires <a href="http://www.gnu.org/software/make">GNU Make</a>. No other flavors of make are supported.</p>
441 <p>At least version 3.81 of GNU Make must be used. For distributions supporting GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful functionality to handle parallel building (supported by <code>--with-output-sync</code>) and speed and stability improvements.</p>
442 <p>Note that <code>configure</code> locates and verifies a properly functioning version of <code>make</code> and stores the path to this <code>make</code> binary in the configuration. If you start a build using <code>make</code> on the command line, you will be using the version of make found first in your <code>PATH</code>, and not necessarily the one stored in the configuration. This initial make will be used as "bootstrap make", and in a second stage, the make located by <code>configure</code> will be called. Normally, this will present no issues, but if you have a very old <code>make</code>, or a non-GNU Make <code>make</code> in your path, this might cause issues.</p>
443 <p>If you want to override the default make found by <code>configure</code>, use the <code>MAKE</code> configure variable, e.g. <code>configure MAKE=/opt/gnu/make</code>.</p>
444 <p>On Solaris, it is common to call the GNU version of make by using <code>gmake</code>.</p>
445 <h3 id="gnu-bash">GNU Bash</h3>
446 <p>OpenJDK requires <a href="http://www.gnu.org/software/bash">GNU Bash</a>. No other shells are supported.</p>
447 <p>At least version 3.2 of GNU Bash must be used.</p>
448 <h2 id="running-configure">Running Configure</h2>
449 <p>To build OpenJDK, you need a "configuration", which consists of a directory where to store the build output, coupled with information about the platform, the specific build machine, and choices that affect how OpenJDK is built.</p>
450 <p>The configuration is created by the <code>configure</code> script. The basic invocation of the <code>configure</code> script looks like this:</p>
451 <pre><code>bash configure [options]</code></pre>
452 <p>This will create an output directory containing the configuration and setup an area for the build result. This directory typically looks like <code>build/linux-x64-normal-server-release</code>, but the actual name depends on your specific configuration. (It can also be set directly, see <a href="#using-multiple-configurations">Using Multiple Configurations</a>). This directory is referred to as <code>$BUILD</code> in this documentation.</p>
453 <p><code>configure</code> will try to figure out what system you are running on and where all necessary build components are. If you have all prerequisites for building installed, it should find everything. If it fails to detect any component automatically, it will exit and inform you about the problem.</p>
454 <p>Some command line examples:</p>
455 <ul>
456 <li><p>Create a 32-bit build for Windows with FreeType2 in <code>C:\freetype-i586</code>:</p>
457 <pre><code>bash configure --with-freetype=/cygdrive/c/freetype-i586 --with-target-bits=32</code></pre></li>
458 <li><p>Create a debug build with the <code>server</code> JVM and DTrace enabled:</p>
459 <pre><code>bash configure --enable-debug --with-jvm-variants=server --enable-dtrace</code></pre></li>
460 </ul>
461 <h3 id="common-configure-arguments">Common Configure Arguments</h3>
462 <p>Here follows some of the most common and important <code>configure</code> argument.</p>
463 <p>To get up-to-date information on <em>all</em> available <code>configure</code> argument, please run:</p>
464 <pre><code>bash configure --help</code></pre>
465 <p>(Note that this help text also include general autoconf options, like <code>--dvidir</code>, that is not relevant to OpenJDK. To list only OpenJDK specific features, use <code>bash configure --help=short</code> instead.)</p>
466 <h4 id="configure-arguments-for-tailoring-the-build">Configure Arguments for Tailoring the Build</h4>
467 <ul>
741 <li><p>Re-clone the Mercurial forest</p>
742 <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>
743 </ol>
744 <h3 id="specific-build-issues">Specific Build Issues</h3>
745 <h4 id="clock-skew">Clock Skew</h4>
746 <p>If you get an error message like this:</p>
747 <pre><code>File 'xxx' has modification time in the future.
748 Clock skew detected. Your build may be incomplete.</code></pre>
749 <p>then the clock on your build machine is out of sync with the timestamps on the source files. Other errors, apparently unrelated but in fact caused by the clock skew, can occur along with the clock skew warnings. These secondary errors may tend to obscure the fact that the true root cause of the problem is an out-of-sync clock.</p>
750 <p>If you see these warnings, reset the clock on the build machine, run <code>make clean</code> and restart the build.</p>
751 <h4 id="out-of-memory-errors">Out of Memory Errors</h4>
752 <p>On Solaris, you might get an error message like this:</p>
753 <pre><code>Trouble writing out table to disk</code></pre>
754 <p>To solve this, increase the amount of swap space on your build machine.</p>
755 <p>On Windows, you might get error messages like this:</p>
756 <pre><code>fatal error - couldn't allocate heap
757 cannot create ... Permission denied
758 spawn failed</code></pre>
759 <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>
760 <h3 id="getting-help">Getting Help</h3>
761 <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 <script type="text/javascript">
762 <!--
763 h='openjdk.java.net';a='@';n='build-dev';e=n+a+h;
764 document.write('<a h'+'ref'+'="ma'+'ilto'+':'+e+'" clas'+'s="em' + 'ail">'+e+'<\/'+'a'+'>');
765 // -->
766 </script><noscript>build-dev at openjdk dot java dot net</noscript>. Please include the relevant parts of the configure and/or build log.</p>
767 <p>If you need general help or advice about developing for OpenJDK, you can also contact the Adoption Group. See the section on <a href="#contributing-to-openjdk">Contributing to OpenJDK</a> for more information.</p>
768 <h2 id="hints-and-suggestions-for-advanced-users">Hints and Suggestions for Advanced Users</h2>
769 <h3 id="setting-up-a-forest-for-pushing-changes-defpath">Setting Up a Forest for Pushing Changes (defpath)</h3>
770 <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 OpenJDK.</p>
771 <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>
772 <pre><code>cd ~
773 mkdir hg-ext
774 cd hg-ext
775 hg clone http://hg.openjdk.java.net/code-tools/defpath
776 cat << EOT >> ~/.hgrc
777 [extensions]
778 defpath=~/hg-ext/defpath/defpath.py
779 EOT</code></pre>
780 <p>You can now setup a proper push path using:</p>
781 <pre><code>hg defpath -d -u <your OpenJDK username></code></pre>
782 <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>
783 <h3 id="bash-completion">Bash Completion</h3>
784 <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>
785 <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>
786 <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>
866 <li><p><code>buildtools</code>: This is an area for tools compiled for the build platform that are used during the rest of the build.</p></li>
867 <li><p><code>hotspot</code>: This is an area for intermediate files needed when building hotspot.</p></li>
868 <li><p><code>configure-support</code>, <code>make-support</code> and <code>test-support</code>: These directories contain files that are needed by the build system for <code>configure</code>, <code>make</code> and for running tests.</p></li>
869 </ul>
870 <h3 id="fixpath">Fixpath</h3>
871 <p>Windows path typically look like <code>C:\User\foo</code>, while Unix paths look like <code>/home/foo</code>. Tools with roots from Unix often experience issues related to this mismatch when running on Windows.</p>
872 <p>In the OpenJDK build, we always use Unix paths internally, and only just before calling a tool that does not understand Unix paths do we convert them to Windows paths.</p>
873 <p>This conversion is done by the <code>fixpath</code> tool, which is a small wrapper that modifies unix-style paths to Windows-style paths in command lines. Fixpath is compiled automatically by <code>configure</code>.</p>
874 <h3 id="native-debug-symbols">Native Debug Symbols</h3>
875 <p>Native libraries and executables can have debug symbol (and other debug information) associated with them. How this works is very much platform dependent, but a common problem is that debug symbol information takes a lot of disk space, but is rarely needed by the end user.</p>
876 <p>The OpenJDK supports different methods on how to handle debug symbols. The method used is selected by <code>--with-native-debug-symbols</code>, and available methods are <code>none</code>, <code>internal</code>, <code>external</code>, <code>zipped</code>.</p>
877 <ul>
878 <li><p><code>none</code> means that no debug symbols will be generated during the build.</p></li>
879 <li><p><code>internal</code> means that debug symbols will be generated during the build, and they will be stored in the generated binary.</p></li>
880 <li><p><code>external</code> means that debug symbols will be generated during the build, and after the compilation, they will be moved into a separate <code>.debuginfo</code> file. (This was previously known as FDS, Full Debug Symbols).</p></li>
881 <li><p><code>zipped</code> is like <code>external</code>, but the .debuginfo file will also be zipped into a <code>.diz</code> file.</p></li>
882 </ul>
883 <p>When building for distribution, <code>zipped</code> is a good solution. Binaries built with <code>internal</code> is suitable for use by developers, since they facilitate debugging, but should be stripped before distributed to end users.</p>
884 <h3 id="autoconf-details">Autoconf Details</h3>
885 <p>The <code>configure</code> script is based on the autoconf framework, but in some details deviate from a normal autoconf <code>configure</code> script.</p>
886 <p>The <code>configure</code> script in the top level directory of OpenJDK is just a thin wrapper that calls <code>make/autoconf/configure</code>. This in turn will run <code>autoconf</code> to create the runnable (generated) configure script, as <code>.build/generated-configure.sh</code>. Apart from being responsible for the generation of the runnable script, the <code>configure</code> script also provides functionality that is not easily expressed in the normal Autoconf framework. As part of this functionality, the generated script is called.</p>
887 <p>The build system will detect if the Autoconf source files have changed, and will trigger a regeneration of the generated script if needed. You can also manually request such an update by <code>bash configure autogen</code>.</p>
888 <p>In previous versions of the OpenJDK, the generated script was checked in at <code>make/autoconf/generated-configure.sh</code>. This is no longer the case.</p>
889 <h3 id="developing-the-build-system-itself">Developing the Build System Itself</h3>
890 <p>This section contains a few remarks about how to develop for the build system itself. It is not relevant if you are only making changes in the product source code.</p>
891 <p>While technically using <code>make</code>, the make source files of the OpenJDK does not resemble most other Makefiles. Instead of listing specific targets and actions (perhaps using patterns), the basic modus operandi is to call a high-level function (or properly, macro) from the API in <code>make/common</code>. For instance, to compile all classes in the <code>jdk.internal.foo</code> package in the <code>jdk.foo</code> module, a call like this would be made:</p>
892 <pre><code>$(eval $(call SetupJavaCompilation, BUILD_FOO_CLASSES, \
893 SETUP := GENERATE_OLDBYTECODE, \
894 SRC := $(TOPDIR)/src/jkd.foo/share/classes, \
895 INCLUDES := jdk/internal/foo, \
896 BIN := $(SUPPORT_OUTPUTDIR)/foo_classes, \
897 ))</code></pre>
898 <p>By encapsulating and expressing the high-level knowledge of <em>what</em> should be done, rather than <em>how</em> it should be done (as is normal in Makefiles), we can build a much more powerful and flexible build system.</p>
899 <p>Correct dependency tracking is paramount. Sloppy dependency tracking will lead to improper parallelization, or worse, race conditions.</p>
900 <p>To test for/debug race conditions, try running <code>make JOBS=1</code> and <code>make JOBS=100</code> and see if it makes any difference. (It shouldn't).</p>
901 <p>To compare the output of two different builds and see if, and how, they differ, run <code>$BUILD1/compare.sh -o $BUILD2</code>, where <code>$BUILD1</code> and <code>$BUILD2</code> are the two builds you want to compare.</p>
902 <p>To automatically build two consecutive versions and compare them, use <code>COMPARE_BUILD</code>. The value of <code>COMPARE_BUILD</code> is a set of variable=value assignments, like this:</p>
903 <pre><code>make COMPARE_BUILD=CONF=--enable-new-hotspot-feature:MAKE=hotspot</code></pre>
904 <p>See <code>make/InitSupport.gmk</code> for details on how to use <code>COMPARE_BUILD</code>.</p>
905 <p>To analyze build performance, run with <code>LOG=trace</code> and check <code>$BUILD/build-trace-time.log</code>. Use <code>JOBS=1</code> to avoid parallelism.</p>
906 <p>Please check that you adhere to the <a href="http://openjdk.java.net/groups/build/doc/code-conventions.html">Code Conventions for the Build System</a> before submitting patches.</p>
907 <h2 id="contributing-to-openjdk">Contributing to OpenJDK</h2>
908 <p>So, now you've build your OpenJDK, and made your first patch, and want to contribute it back to the OpenJDK community.</p>
909 <p>First of all: Thank you! We gladly welcome your contribution to the OpenJDK. However, please bear in mind that OpenJDK is a massive project, and we must ask you to follow our rules and guidelines to be able to accept your contribution.</p>
910 <p>The official place to start is the <a href="http://openjdk.java.net/contribute/">'How to contribute' page</a>. There is also an official (but somewhat outdated and skimpy on details) <a href="http://openjdk.java.net/guide/">Developer's Guide</a>.</p>
911 <p>If this seems overwhelming to you, the Adoption Group is there to help you! A good place to start is their <a href="https://wiki.openjdk.java.net/display/Adoption/New+Contributor">'New Contributor' page</a>, or start reading the comprehensive <a href="https://adoptopenjdk.gitbooks.io/adoptopenjdk-getting-started-kit/en/">Getting Started Kit</a>. The Adoption Group will also happily answer any questions you have about contributing. Contact them by <a href="http://mail.openjdk.java.net/mailman/listinfo/adoption-discuss">mail</a> or <a href="http://openjdk.java.net/irc/">IRC</a>.</p>
912 </body>
913 </html>
|