1 % Building OpenJDK
2
3 ## TL;DR (Instructions for the Impatient)
4
5 If you are eager to try out building OpenJDK, these simple steps works most of
6 the time. They assume that you have installed Mercurial (and Cygwin if running
7 on Windows) and cloned the top-level OpenJDK repository that you want to build.
8
9 1. [Get the complete source code](#getting-the-source-code): \
10 `hg clone http://hg.openjdk.java.net/jdk10/master`
11
12 2. [Run configure](#running-configure): \
13 `bash configure`
14
15 If `configure` fails due to missing dependencies (to either the
16 [toolchain](#native-compiler-toolchain-requirements), [external libraries](
17 #external-library-requirements) or the [boot JDK](#boot-jdk-requirements)),
18 most of the time it prints a suggestion on how to resolve the situation on
19 your platform. Follow the instructions, and try running `bash configure`
20 again.
21
22 3. [Run make](#running-make): \
23 `make images`
24
25 4. Verify your newly built JDK: \
26 `./build/*/images/jdk/bin/java -version`
27
28 5. [Run basic tests](##running-tests): \
29 `make run-test-tier1`
30
31 If any of these steps failed, or if you want to know more about build
32 requirements or build functionality, please continue reading this document.
33
34 ## Introduction
35
36 OpenJDK is a complex software project. Building it requires a certain amount of
178
179 #### Cygwin
180
181 A functioning [Cygwin](http://www.cygwin.com/) environment is thus required for
182 building OpenJDK on Windows. If you have a 64-bit OS, we strongly recommend
183 using the 64-bit version of Cygwin.
184
185 **Note:** Cygwin has a model of continuously updating all packages without any
186 easy way to install or revert to a specific version of a package. This means
187 that whenever you add or update a package in Cygwin, you might (inadvertently)
188 update tools that are used by the OpenJDK build process, and that can cause
189 unexpected build problems.
190
191 OpenJDK requires GNU Make 4.0 or greater on Windows. This is usually not a
192 problem, since Cygwin currently only distributes GNU Make at a version above
193 4.0.
194
195 Apart from the basic Cygwin installation, the following packages must also be
196 installed:
197
198 * `make`
199 * `zip`
200 * `unzip`
201
202 Often, you can install these packages using the following command line:
203 ```
204 <path to Cygwin setup>/setup-x86_64 -q -P make -P unzip -P zip
205 ```
206
207 Unfortunately, Cygwin can be unreliable in certain circumstances. If you
208 experience build tool crashes or strange issues when building on Windows,
209 please check the Cygwin FAQ on the ["BLODA" list](
210 https://cygwin.com/faq/faq.html#faq.using.bloda) and the section on [fork()
211 failures](https://cygwin.com/faq/faq.html#faq.using.fixing-fork-failures).
212
213 ### Solaris
214
215 See `make/devkit/solaris11.1-package-list.txt` for a list of recommended
216 packages to install when building on Solaris. The versions specified in this
217 list is the versions used by the daily builds at Oracle, and is likely to work
218 properly.
219
220 Older versions of Solaris shipped a broken version of `objcopy`. At least
221 version 2.21.1 is needed, which is provided by Solaris 11 Update 1. Objcopy is
222 needed if you want to have external debug symbols. Please make sure you are
223 using at least version 2.21.1 of objcopy, or that you disable external debug
224 symbols.
535 * To install on an rpm-based Linux, try running `sudo yum install
536 alsa-lib-devel`.
537
538 Use `--with-alsa=<path>` if `configure` does not properly locate your ALSA
539 files.
540
541 ### libffi
542
543 libffi, the [Portable Foreign Function Interface Library](
544 http://sourceware.org/libffi) is required when building the Zero version of
545 Hotspot.
546
547 * To install on an apt-based Linux, try running `sudo apt-get install
548 libffi-dev`.
549 * To install on an rpm-based Linux, try running `sudo yum install
550 libffi-devel`.
551
552 Use `--with-libffi=<path>` if `configure` does not properly locate your libffi
553 files.
554
555 ## Other Tooling Requirements
556
557 ### GNU Make
558
559 OpenJDK requires [GNU Make](http://www.gnu.org/software/make). No other flavors
560 of make are supported.
561
562 At least version 3.81 of GNU Make must be used. For distributions supporting
563 GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful
564 functionality to handle parallel building (supported by `--with-output-sync`)
565 and speed and stability improvements.
566
567 Note that `configure` locates and verifies a properly functioning version of
568 `make` and stores the path to this `make` binary in the configuration. If you
569 start a build using `make` on the command line, you will be using the version
570 of make found first in your `PATH`, and not necessarily the one stored in the
571 configuration. This initial make will be used as "bootstrap make", and in a
572 second stage, the make located by `configure` will be called. Normally, this
573 will present no issues, but if you have a very old `make`, or a non-GNU Make
574 `make` in your path, this might cause issues.
575
576 If you want to override the default make found by `configure`, use the `MAKE`
577 configure variable, e.g. `configure MAKE=/opt/gnu/make`.
578
579 On Solaris, it is common to call the GNU version of make by using `gmake`.
580
581 ### GNU Bash
582
583 OpenJDK requires [GNU Bash](http://www.gnu.org/software/bash). No other shells
584 are supported.
585
586 At least version 3.2 of GNU Bash must be used.
587
588 ### Autoconf
589
590 If you want to modify the build system itself, you need to install [Autoconf](
591 http://www.gnu.org/software/autoconf).
592
593 However, if you only need to build OpenJDK or if you only edit the actual
594 OpenJDK source files, there is no dependency on autoconf, since the source
595 distribution includes a pre-generated `configure` shell script.
596
597 See the section on [Autoconf Details](#autoconf-details) for details on how
598 OpenJDK uses autoconf. This is especially important if you plan to contribute
599 changes to OpenJDK that modifies the build system.
600
601 ## Running Configure
602
603 To build OpenJDK, you need a "configuration", which consists of a directory
604 where to store the build output, coupled with information about the platform,
605 the specific build machine, and choices that affect how OpenJDK is built.
606
607 The configuration is created by the `configure` script. The basic invocation of
608 the `configure` script looks like this:
609
610 ```
611 bash configure [options]
612 ```
613
614 This will create an output directory containing the configuration and setup an
615 area for the build result. This directory typically looks like
616 `build/linux-x64-normal-server-release`, but the actual name depends on your
617 specific configuration. (It can also be set directly, see [Using Multiple
618 Configurations](#using-multiple-configurations)). This directory is referred to
619 as `$BUILD` in this documentation.
620
1643 * `internal` means that debug symbols will be generated during the build, and
1644 they will be stored in the generated binary.
1645
1646 * `external` means that debug symbols will be generated during the build, and
1647 after the compilation, they will be moved into a separate `.debuginfo` file.
1648 (This was previously known as FDS, Full Debug Symbols).
1649
1650 * `zipped` is like `external`, but the .debuginfo file will also be zipped
1651 into a `.diz` file.
1652
1653 When building for distribution, `zipped` is a good solution. Binaries built
1654 with `internal` is suitable for use by developers, since they facilitate
1655 debugging, but should be stripped before distributed to end users.
1656
1657 ### Autoconf Details
1658
1659 The `configure` script is based on the autoconf framework, but in some details
1660 deviate from a normal autoconf `configure` script.
1661
1662 The `configure` script in the top level directory of OpenJDK is just a thin
1663 wrapper that calls `make/autoconf/configure`. This in turn provides
1664 functionality that is not easily expressed in the normal Autoconf framework,
1665 and then calls into the core of the `configure` script, which is the
1666 `make/autoconf/generated-configure.sh` file.
1667
1668 As the name implies, this file is generated by Autoconf. It is checked in after
1669 regeneration, to alleviate the common user to have to install Autoconf.
1670
1671 The build system will detect if the Autoconf source files have changed, and
1672 will trigger a regeneration of `make/autoconf/generated-configure.sh` if
1673 needed. You can also manually request such an update by `bash
1674 make/autoconf/autogen.sh`.
1675
1676 If you make changes to the build system that requires a re-generation, note the
1677 following:
1678
1679 * You must use *exactly* version 2.69 of autoconf for your patch to be
1680 accepted. This is to avoid spurious changes in the generated file. Note
1681 that Ubuntu 16.04 ships a patched version of autoconf which claims to be
1682 2.69, but is not.
1683
1684 * You do not need to include the generated file in reviews.
1685
1686 * If the generated file needs updating, the Oracle JDK closed counter-part
1687 will also need to be updated. It is very much appreciated if you ask for an
1688 Oracle engineer to sponsor your push so this can be made in tandem.
1689
1690 ### Developing the Build System Itself
1691
1692 This section contains a few remarks about how to develop for the build system
1693 itself. It is not relevant if you are only making changes in the product source
1694 code.
1695
1696 While technically using `make`, the make source files of the OpenJDK does not
1697 resemble most other Makefiles. Instead of listing specific targets and actions
1698 (perhaps using patterns), the basic modus operandi is to call a high-level
1699 function (or properly, macro) from the API in `make/common`. For instance, to
1700 compile all classes in the `jdk.internal.foo` package in the `jdk.foo` module,
1701 a call like this would be made:
1702
1703 ```
1704 $(eval $(call SetupJavaCompilation, BUILD_FOO_CLASSES, \
1705 SETUP := GENERATE_OLDBYTECODE, \
1706 SRC := $(TOPDIR)/src/jkd.foo/share/classes, \
1707 INCLUDES := jdk/internal/foo, \
1708 BIN := $(SUPPORT_OUTPUTDIR)/foo_classes, \
1719 To test for/debug race conditions, try running `make JOBS=1` and `make
1720 JOBS=100` and see if it makes any difference. (It shouldn't).
1721
1722 To compare the output of two different builds and see if, and how, they differ,
1723 run `$BUILD1/compare.sh -o $BUILD2`, where `$BUILD1` and `$BUILD2` are the two
1724 builds you want to compare.
1725
1726 To automatically build two consecutive versions and compare them, use
1727 `COMPARE_BUILD`. The value of `COMPARE_BUILD` is a set of variable=value
1728 assignments, like this:
1729 ```
1730 make COMPARE_BUILD=CONF=--enable-new-hotspot-feature:MAKE=hotspot
1731 ```
1732 See `make/InitSupport.gmk` for details on how to use `COMPARE_BUILD`.
1733
1734 To analyze build performance, run with `LOG=trace` and check `$BUILD/build-trace-time.log`.
1735 Use `JOBS=1` to avoid parallelism.
1736
1737 Please check that you adhere to the [Code Conventions for the Build System](
1738 http://openjdk.java.net/groups/build/doc/code-conventions.html) before
1739 submitting patches. Also see the section in [Autoconf Details](
1740 #autoconf-details) about the generated configure script.
1741
1742 ## Contributing to OpenJDK
1743
1744 So, now you've build your OpenJDK, and made your first patch, and want to
1745 contribute it back to the OpenJDK community.
1746
1747 First of all: Thank you! We gladly welcome your contribution to the OpenJDK.
1748 However, please bear in mind that OpenJDK is a massive project, and we must ask
1749 you to follow our rules and guidelines to be able to accept your contribution.
1750
1751 The official place to start is the ['How to contribute' page](
1752 http://openjdk.java.net/contribute/). There is also an official (but somewhat
1753 outdated and skimpy on details) [Developer's Guide](
1754 http://openjdk.java.net/guide/).
1755
1756 If this seems overwhelming to you, the Adoption Group is there to help you! A
1757 good place to start is their ['New Contributor' page](
1758 https://wiki.openjdk.java.net/display/Adoption/New+Contributor), or start
1759 reading the comprehensive [Getting Started Kit](
1760 https://adoptopenjdk.gitbooks.io/adoptopenjdk-getting-started-kit/en/). The
|
1 % Building OpenJDK
2
3 ## TL;DR (Instructions for the Impatient)
4
5 If you are eager to try out building OpenJDK, these simple steps works most of
6 the time. They assume that you have installed Mercurial (and Cygwin if running
7 on Windows) and cloned the top-level OpenJDK repository that you want to build.
8
9 1. [Get the complete source code](#getting-the-source-code): \
10 `hg clone http://hg.openjdk.java.net/jdk/jdk`
11
12 2. [Run configure](#running-configure): \
13 `bash configure`
14
15 If `configure` fails due to missing dependencies (to either the
16 [toolchain](#native-compiler-toolchain-requirements), [build tools](
17 #build-tools-requirements), [external libraries](
18 #external-library-requirements) or the [boot JDK](#boot-jdk-requirements)),
19 most of the time it prints a suggestion on how to resolve the situation on
20 your platform. Follow the instructions, and try running `bash configure`
21 again.
22
23 3. [Run make](#running-make): \
24 `make images`
25
26 4. Verify your newly built JDK: \
27 `./build/*/images/jdk/bin/java -version`
28
29 5. [Run basic tests](##running-tests): \
30 `make run-test-tier1`
31
32 If any of these steps failed, or if you want to know more about build
33 requirements or build functionality, please continue reading this document.
34
35 ## Introduction
36
37 OpenJDK is a complex software project. Building it requires a certain amount of
179
180 #### Cygwin
181
182 A functioning [Cygwin](http://www.cygwin.com/) environment is thus required for
183 building OpenJDK on Windows. If you have a 64-bit OS, we strongly recommend
184 using the 64-bit version of Cygwin.
185
186 **Note:** Cygwin has a model of continuously updating all packages without any
187 easy way to install or revert to a specific version of a package. This means
188 that whenever you add or update a package in Cygwin, you might (inadvertently)
189 update tools that are used by the OpenJDK build process, and that can cause
190 unexpected build problems.
191
192 OpenJDK requires GNU Make 4.0 or greater on Windows. This is usually not a
193 problem, since Cygwin currently only distributes GNU Make at a version above
194 4.0.
195
196 Apart from the basic Cygwin installation, the following packages must also be
197 installed:
198
199 * `autoconf`
200 * `make`
201 * `zip`
202 * `unzip`
203
204 Often, you can install these packages using the following command line:
205 ```
206 <path to Cygwin setup>/setup-x86_64 -q -P autoconf -P make -P unzip -P zip
207 ```
208
209 Unfortunately, Cygwin can be unreliable in certain circumstances. If you
210 experience build tool crashes or strange issues when building on Windows,
211 please check the Cygwin FAQ on the ["BLODA" list](
212 https://cygwin.com/faq/faq.html#faq.using.bloda) and the section on [fork()
213 failures](https://cygwin.com/faq/faq.html#faq.using.fixing-fork-failures).
214
215 ### Solaris
216
217 See `make/devkit/solaris11.1-package-list.txt` for a list of recommended
218 packages to install when building on Solaris. The versions specified in this
219 list is the versions used by the daily builds at Oracle, and is likely to work
220 properly.
221
222 Older versions of Solaris shipped a broken version of `objcopy`. At least
223 version 2.21.1 is needed, which is provided by Solaris 11 Update 1. Objcopy is
224 needed if you want to have external debug symbols. Please make sure you are
225 using at least version 2.21.1 of objcopy, or that you disable external debug
226 symbols.
537 * To install on an rpm-based Linux, try running `sudo yum install
538 alsa-lib-devel`.
539
540 Use `--with-alsa=<path>` if `configure` does not properly locate your ALSA
541 files.
542
543 ### libffi
544
545 libffi, the [Portable Foreign Function Interface Library](
546 http://sourceware.org/libffi) is required when building the Zero version of
547 Hotspot.
548
549 * To install on an apt-based Linux, try running `sudo apt-get install
550 libffi-dev`.
551 * To install on an rpm-based Linux, try running `sudo yum install
552 libffi-devel`.
553
554 Use `--with-libffi=<path>` if `configure` does not properly locate your libffi
555 files.
556
557 ## Build Tools Requirements
558
559 ### Autoconf
560
561 OpenJDK requires [Autoconf](http://www.gnu.org/software/autoconf) on all
562 platforms. At least version 2.69 is required.
563
564 * To install on an apt-based Linux, try running `sudo apt-get install
565 autoconf`.
566 * To install on an rpm-based Linux, try running `sudo yum install
567 autoconf`.
568 * To install on macOS, try running `brew install autoconf`.
569 * To install on Windows, try running `<path to Cygwin setup>/setup-x86_64 -q
570 -P autoconf`.
571
572 If `configure` has problems locating your installation of autoconf, you can
573 specify it using the `AUTOCONF` environment variable, like this:
574
575 ```
576 AUTOCONF=<path to autoconf> configure ...
577 ```
578
579 ### GNU Make
580
581 OpenJDK requires [GNU Make](http://www.gnu.org/software/make). No other flavors
582 of make are supported.
583
584 At least version 3.81 of GNU Make must be used. For distributions supporting
585 GNU Make 4.0 or above, we strongly recommend it. GNU Make 4.0 contains useful
586 functionality to handle parallel building (supported by `--with-output-sync`)
587 and speed and stability improvements.
588
589 Note that `configure` locates and verifies a properly functioning version of
590 `make` and stores the path to this `make` binary in the configuration. If you
591 start a build using `make` on the command line, you will be using the version
592 of make found first in your `PATH`, and not necessarily the one stored in the
593 configuration. This initial make will be used as "bootstrap make", and in a
594 second stage, the make located by `configure` will be called. Normally, this
595 will present no issues, but if you have a very old `make`, or a non-GNU Make
596 `make` in your path, this might cause issues.
597
598 If you want to override the default make found by `configure`, use the `MAKE`
599 configure variable, e.g. `configure MAKE=/opt/gnu/make`.
600
601 On Solaris, it is common to call the GNU version of make by using `gmake`.
602
603 ### GNU Bash
604
605 OpenJDK requires [GNU Bash](http://www.gnu.org/software/bash). No other shells
606 are supported.
607
608 At least version 3.2 of GNU Bash must be used.
609
610 ## Running Configure
611
612 To build OpenJDK, you need a "configuration", which consists of a directory
613 where to store the build output, coupled with information about the platform,
614 the specific build machine, and choices that affect how OpenJDK is built.
615
616 The configuration is created by the `configure` script. The basic invocation of
617 the `configure` script looks like this:
618
619 ```
620 bash configure [options]
621 ```
622
623 This will create an output directory containing the configuration and setup an
624 area for the build result. This directory typically looks like
625 `build/linux-x64-normal-server-release`, but the actual name depends on your
626 specific configuration. (It can also be set directly, see [Using Multiple
627 Configurations](#using-multiple-configurations)). This directory is referred to
628 as `$BUILD` in this documentation.
629
1652 * `internal` means that debug symbols will be generated during the build, and
1653 they will be stored in the generated binary.
1654
1655 * `external` means that debug symbols will be generated during the build, and
1656 after the compilation, they will be moved into a separate `.debuginfo` file.
1657 (This was previously known as FDS, Full Debug Symbols).
1658
1659 * `zipped` is like `external`, but the .debuginfo file will also be zipped
1660 into a `.diz` file.
1661
1662 When building for distribution, `zipped` is a good solution. Binaries built
1663 with `internal` is suitable for use by developers, since they facilitate
1664 debugging, but should be stripped before distributed to end users.
1665
1666 ### Autoconf Details
1667
1668 The `configure` script is based on the autoconf framework, but in some details
1669 deviate from a normal autoconf `configure` script.
1670
1671 The `configure` script in the top level directory of OpenJDK is just a thin
1672 wrapper that calls `make/autoconf/configure`. This in turn will run `autoconf`
1673 to create the runnable (generated) configure script, as
1674 `.build/generated-configure.sh`. Apart from being responsible for the
1675 generation of the runnable script, the `configure` script also provides
1676 functionality that is not easily expressed in the normal Autoconf framework. As
1677 part of this functionality, the generated script is called.
1678
1679 The build system will detect if the Autoconf source files have changed, and
1680 will trigger a regeneration of the generated script if needed. You can also
1681 manually request such an update by `bash configure autogen`.
1682
1683 In previous versions of the OpenJDK, the generated script was checked in at
1684 `make/autoconf/generated-configure.sh`. This is no longer the case.
1685
1686 ### Developing the Build System Itself
1687
1688 This section contains a few remarks about how to develop for the build system
1689 itself. It is not relevant if you are only making changes in the product source
1690 code.
1691
1692 While technically using `make`, the make source files of the OpenJDK does not
1693 resemble most other Makefiles. Instead of listing specific targets and actions
1694 (perhaps using patterns), the basic modus operandi is to call a high-level
1695 function (or properly, macro) from the API in `make/common`. For instance, to
1696 compile all classes in the `jdk.internal.foo` package in the `jdk.foo` module,
1697 a call like this would be made:
1698
1699 ```
1700 $(eval $(call SetupJavaCompilation, BUILD_FOO_CLASSES, \
1701 SETUP := GENERATE_OLDBYTECODE, \
1702 SRC := $(TOPDIR)/src/jkd.foo/share/classes, \
1703 INCLUDES := jdk/internal/foo, \
1704 BIN := $(SUPPORT_OUTPUTDIR)/foo_classes, \
1715 To test for/debug race conditions, try running `make JOBS=1` and `make
1716 JOBS=100` and see if it makes any difference. (It shouldn't).
1717
1718 To compare the output of two different builds and see if, and how, they differ,
1719 run `$BUILD1/compare.sh -o $BUILD2`, where `$BUILD1` and `$BUILD2` are the two
1720 builds you want to compare.
1721
1722 To automatically build two consecutive versions and compare them, use
1723 `COMPARE_BUILD`. The value of `COMPARE_BUILD` is a set of variable=value
1724 assignments, like this:
1725 ```
1726 make COMPARE_BUILD=CONF=--enable-new-hotspot-feature:MAKE=hotspot
1727 ```
1728 See `make/InitSupport.gmk` for details on how to use `COMPARE_BUILD`.
1729
1730 To analyze build performance, run with `LOG=trace` and check `$BUILD/build-trace-time.log`.
1731 Use `JOBS=1` to avoid parallelism.
1732
1733 Please check that you adhere to the [Code Conventions for the Build System](
1734 http://openjdk.java.net/groups/build/doc/code-conventions.html) before
1735 submitting patches.
1736
1737 ## Contributing to OpenJDK
1738
1739 So, now you've build your OpenJDK, and made your first patch, and want to
1740 contribute it back to the OpenJDK community.
1741
1742 First of all: Thank you! We gladly welcome your contribution to the OpenJDK.
1743 However, please bear in mind that OpenJDK is a massive project, and we must ask
1744 you to follow our rules and guidelines to be able to accept your contribution.
1745
1746 The official place to start is the ['How to contribute' page](
1747 http://openjdk.java.net/contribute/). There is also an official (but somewhat
1748 outdated and skimpy on details) [Developer's Guide](
1749 http://openjdk.java.net/guide/).
1750
1751 If this seems overwhelming to you, the Adoption Group is there to help you! A
1752 good place to start is their ['New Contributor' page](
1753 https://wiki.openjdk.java.net/display/Adoption/New+Contributor), or start
1754 reading the comprehensive [Getting Started Kit](
1755 https://adoptopenjdk.gitbooks.io/adoptopenjdk-getting-started-kit/en/). The
|