1 ![OpenJDK](http://openjdk.java.net/images/openjdk.png)

     2 # OpenJDK Build README

     3 

     4 *****

     5 

     6 <a name="introduction"></a>

     7 ## Introduction

     8 

     9 This README file contains build instructions for the

    10 [OpenJDK](http://openjdk.java.net). Building the source code for the OpenJDK

    11 requires a certain degree of technical expertise.

    12 

    13 ### !!!!!!!!!!!!!!! THIS IS A MAJOR RE-WRITE of this document. !!!!!!!!!!!!!

    14 

    15 Some Headlines:

    16 

    17  * The build is now a "`configure && make`" style build

    18  * Any GNU make 3.81 or newer should work, except on Windows where 4.0 or newer

    19    is recommended.

    20  * The build should scale, i.e. more processors should cause the build to be

    21    done in less wall-clock time

    22  * Nested or recursive make invocations have been significantly reduced,

    23    as has the total fork/exec or spawning of sub processes during the build

    24  * Windows MKS usage is no longer supported

    25  * Windows Visual Studio `vsvars*.bat` and `vcvars*.bat` files are run

    26    automatically

    27  * Ant is no longer used when building the OpenJDK

    28  * Use of ALT_* environment variables for configuring the build is no longer

    29    supported

    30 

    31 *****

    32 

    33 ## Contents

    34 

    35   * [Introduction](#introduction)

    36   * [Use of Mercurial](#hg)

    37     * [Getting the Source](#get_source)

    38     * [Repositories](#repositories)

    39   * [Building](#building)

    40     * [System Setup](#setup)

    41       * [Linux](#linux)

    42       * [Solaris](#solaris)

    43       * [Mac OS X](#macosx)

    44       * [Windows](#windows)

    45     * [Configure](#configure)

    46     * [Make](#make)

    47   * [Testing](#testing)

    48 

    49 *****

    50 

    51   * [Appendix A: Hints and Tips](#hints)

    52     * [FAQ](#faq)

    53     * [Build Performance Tips](#performance)

    54     * [Troubleshooting](#troubleshooting)

    55   * [Appendix B: GNU Make Information](#gmake)

    56   * [Appendix C: Build Environments](#buildenvironments)

    57 

    58 *****

    59 

    60 <a name="hg"></a>

    61 ## Use of Mercurial

    62 

    63 The OpenJDK sources are maintained with the revision control system

    64 [Mercurial](http://mercurial.selenic.com/wiki/Mercurial). If you are new to

    65 Mercurial, please see the [Beginner Guides](http://mercurial.selenic.com/wiki/

    66 BeginnersGuides) or refer to the [Mercurial Book](http://hgbook.red-bean.com/).

    67 The first few chapters of the book provide an excellent overview of Mercurial,

    68 what it is and how it works.

    69 

    70 For using Mercurial with the OpenJDK refer to the [Developer Guide: Installing

    71 and Configuring Mercurial](http://openjdk.java.net/guide/

    72 repositories.html#installConfig) section for more information.

    73 

    74 <a name="get_source"></a>

    75 ### Getting the Source

    76 

    77 To get the entire set of OpenJDK Mercurial repositories use the script

    78 `get_source.sh` located in the root repository:

    79 

    80       hg clone http://hg.openjdk.java.net/jdk9/jdk9 YourOpenJDK

    81       cd YourOpenJDK

    82       bash ./get_source.sh

    83 

    84 Once you have all the repositories, keep in mind that each repository is its

    85 own independent repository. You can also re-run `./get_source.sh` anytime to

    86 pull over all the latest changesets in all the repositories. This set of

    87 nested repositories has been given the term "forest" and there are various

    88 ways to apply the same `hg` command to each of the repositories. For

    89 example, the script `make/scripts/hgforest.sh` can be used to repeat the

    90 same `hg` command on every repository, e.g.

    91 

    92       cd YourOpenJDK

    93       bash ./make/scripts/hgforest.sh status

    94 

    95 <a name="repositories"></a>

    96 ### Repositories

    97 

    98 The set of repositories and what they contain:

    99 

   100  * **. (root)** contains common configure and makefile logic

   101  * **hotspot** contains source code and make files for building the OpenJDK

   102    Hotspot Virtual Machine

   103  * **langtools** contains source code for the OpenJDK javac and language tools

   104  * **jdk** contains source code and make files for building the OpenJDK runtime

   105    libraries and misc files

   106  * **jaxp** contains source code for the OpenJDK JAXP functionality

   107  * **jaxws** contains source code for the OpenJDK JAX-WS functionality

   108  * **corba** contains source code for the OpenJDK Corba functionality

   109  * **nashorn** contains source code for the OpenJDK JavaScript implementation

   110 

   111 ### Repository Source Guidelines

   112 

   113 There are some very basic guidelines:

   114 

   115  * Use of whitespace in source files (.java, .c, .h, .cpp, and .hpp files) is

   116    restricted. No TABs, no trailing whitespace on lines, and files should not

   117    terminate in more than one blank line.

   118  * Files with execute permissions should not be added to the source

   119    repositories.

   120  * All generated files need to be kept isolated from the files maintained or

   121    managed by the source control system. The standard area for generated files

   122    is the top level `build/` directory.

   123  * The default build process should be to build the product and nothing else,

   124    in one form, e.g. a product (optimized), debug (non-optimized, -g plus

   125    assert logic), or fastdebug (optimized, -g plus assert logic).

   126  * The `.hgignore` file in each repository must exist and should include

   127    `^build/`, `^dist/` and optionally any `nbproject/private` directories. **It

   128    should NEVER** include anything in the `src/` or `test/` or any managed

   129    directory area of a repository.

   130  * Directory names and file names should never contain blanks or non-printing

   131    characters.

   132  * Generated source or binary files should NEVER be added to the repository

   133    (that includes `javah` output). There are some exceptions to this rule, in

   134    particular with some of the generated configure scripts.

   135  * Files not needed for typical building or testing of the repository should

   136    not be added to the repository.

   137 

   138 *****

   139 

   140 <a name="building"></a>

   141 ## Building

   142 

   143 The very first step in building the OpenJDK is making sure the system itself

   144 has everything it needs to do OpenJDK builds. Once a system is setup, it

   145 generally doesn't need to be done again.

   146 

   147 Building the OpenJDK is now done with running a `configure` script which will

   148 try and find and verify you have everything you need, followed by running

   149 `make`, e.g.

   150 

   151 >  **`bash ./configure`**  

   152 >  **`make all`**

   153 

   154 Where possible the `configure` script will attempt to located the various

   155 components in the default locations or via component specific variable

   156 settings. When the normal defaults fail or components cannot be found,

   157 additional `configure` options may be necessary to help `configure` find the

   158 necessary tools for the build, or you may need to re-visit the setup of your

   159 system due to missing software packages.

   160 

   161 **NOTE:** The `configure` script file does not have execute permissions and

   162 will need to be explicitly run with `bash`, see the source guidelines.

   163 

   164 *****

   165 

   166 <a name="setup"></a>

   167 ### System Setup

   168 

   169 Before even attempting to use a system to build the OpenJDK there are some very

   170 basic system setups needed. For all systems:

   171 

   172  * Be sure the GNU make utility is version 3.81 (4.0 on windows) or newer, e.g.

   173    run "`make -version`"

   174 

   175    <a name="bootjdk"></a>

   176  * Install a Bootstrap JDK. All OpenJDK builds require access to a previously

   177    released JDK called the _bootstrap JDK_ or _boot JDK._ The general rule is

   178    that the bootstrap JDK must be an instance of the previous major release of

   179    the JDK. In addition, there may be a requirement to use a release at or

   180    beyond a particular update level.

   181 

   182    **_Building JDK 9 requires JDK 8. JDK 9 developers should not use JDK 9 as

   183    the boot JDK, to ensure that JDK 9 dependencies are not introduced into the

   184    parts of the system that are built with JDK 8._**

   185 

   186    The JDK 8 binaries can be downloaded from Oracle's [JDK 8 download

   187    site](http://www.oracle.com/technetwork/java/javase/downloads/index.html).

   188    For build performance reasons it is very important that this bootstrap JDK

   189    be made available on the local disk of the machine doing the build. You

   190    should add its `bin` directory to the `PATH` environment variable. If

   191    `configure` has any issues finding this JDK, you may need to use the

   192    `configure` option `--with-boot-jdk`.

   193 

   194  * Ensure that GNU make, the Bootstrap JDK, and the compilers are all in your

   195    PATH environment variable.

   196 

   197 And for specific systems:

   198 

   199  * **Linux**

   200 

   201    Install all the software development packages needed including

   202    [alsa](#alsa), [freetype](#freetype), [cups](#cups), and

   203    [xrender](#xrender). See [specific system packages](#SDBE).

   204 

   205  * **Solaris**

   206 

   207    Install all the software development packages needed including [Studio

   208    Compilers](#studio), [freetype](#freetype), [cups](#cups), and

   209    [xrender](#xrender). See [specific system packages](#SDBE).

   210 

   211  * **Windows**

   212 

   213    * Install one of [CYGWIN](#cygwin) or [MinGW/MSYS](#msys)

   214    * Install [Visual Studio 2013](#vs2013)

   215 

   216  * **Mac OS X**

   217 

   218    Install [XCode 6.3](https://developer.apple.com/xcode/)

   219 

   220 <a name="linux"></a>

   221 #### Linux

   222 

   223 With Linux, try and favor the system packages over building your own or getting

   224 packages from other areas. Most Linux builds should be possible with the

   225 system's available packages.

   226 

   227 Note that some Linux systems have a habit of pre-populating your environment

   228 variables for you, for example `JAVA_HOME` might get pre-defined for you to

   229 refer to the JDK installed on your Linux system. You will need to unset

   230 `JAVA_HOME`. It's a good idea to run `env` and verify the environment variables

   231 you are getting from the default system settings make sense for building the

   232 OpenJDK.

   233 

   234 <a name="solaris"></a>

   235 #### Solaris

   236 

   237 <a name="studio"></a>

   238 ##### Studio Compilers

   239 

   240 At a minimum, the [Studio 12 Update 4 Compilers](http://www.oracle.com/

   241 technetwork/server-storage/solarisstudio/downloads/index.htm) (containing

   242 version 5.13 of the C and C++ compilers) is required, including specific

   243 patches.

   244 

   245 The Solaris Studio installation should contain at least these packages:

   246 

   247 >  <table border="1">

   248      <thead>

   249        <tr>

   250          <td>**Package**</td>

   251          <td>**Version**</td>

   252        </tr>

   253      </thead>

   254      <tbody>

   255        <tr>

   256          <td>developer/solarisstudio-124/backend</td>

   257          <td>12.4-1.0.6.0</td>

   258        </tr>

   259        <tr>

   260          <td>developer/solarisstudio-124/c++</td>

   261          <td>12.4-1.0.10.0</td>

   262        </tr>

   263        <tr>

   264          <td>developer/solarisstudio-124/cc</td>

   265          <td>12.4-1.0.4.0</td>

   266        </tr>

   267        <tr>

   268          <td>developer/solarisstudio-124/library/c++-libs</td>

   269          <td>12.4-1.0.10.0</td>

   270        </tr>

   271        <tr>

   272          <td>developer/solarisstudio-124/library/math-libs</td>

   273          <td>12.4-1.0.0.1</td>

   274        </tr>

   275        <tr>

   276          <td>developer/solarisstudio-124/library/studio-gccrt</td>

   277          <td>12.4-1.0.0.1</td>

   278        </tr>

   279        <tr>

   280          <td>developer/solarisstudio-124/studio-common</td>

   281          <td>12.4-1.0.0.1</td>

   282        </tr>

   283        <tr>

   284          <td>developer/solarisstudio-124/studio-ja</td>

   285          <td>12.4-1.0.0.1</td>

   286        </tr>

   287        <tr>

   288          <td>developer/solarisstudio-124/studio-legal</td>

   289          <td>12.4-1.0.0.1</td>

   290        </tr>

   291        <tr>

   292          <td>developer/solarisstudio-124/studio-zhCN</td>

   293          <td>12.4-1.0.0.1</td>

   294        </tr>

   295      </tbody>

   296    </table>

   297 

   298 In particular backend 12.4-1.0.6.0 contains a critical patch for the sparc

   299 version.

   300 

   301 Place the `bin` directory in `PATH`.

   302 

   303 The Oracle Solaris Studio Express compilers at: [Oracle Solaris Studio Express

   304 Download site](http://www.oracle.com/technetwork/server-storage/solarisstudio/

   305 downloads/index-jsp-142582.html) are also an option, although these compilers

   306 have not been extensively used yet.

   307 

   308 <a name="windows"></a>

   309 #### Windows

   310 

   311 ##### Windows Unix Toolkit

   312 

   313 Building on Windows requires a Unix-like environment, notably a Unix-like

   314 shell. There are several such environments available of which

   315 [Cygwin](http://www.cygwin.com/) and

   316 [MinGW/MSYS](http://www.mingw.org/wiki/MSYS) are currently supported for the

   317 OpenJDK build. One of the differences of these systems from standard Windows

   318 tools is the way they handle Windows path names, particularly path names which

   319 contain spaces, backslashes as path separators and possibly drive letters.

   320 Depending on the use case and the specifics of each environment these path

   321 problems can be solved by a combination of quoting whole paths, translating

   322 backslashes to forward slashes, escaping backslashes with additional

   323 backslashes and translating the path names to their ["8.3"

   324 version](http://en.wikipedia.org/wiki/8.3_filename).

   325 

   326 <a name="cygwin"></a>

   327 ###### CYGWIN

   328 

   329 CYGWIN is an open source, Linux-like environment which tries to emulate a

   330 complete POSIX layer on Windows. It tries to be smart about path names and can

   331 usually handle all kinds of paths if they are correctly quoted or escaped

   332 although internally it maps drive letters `<drive>:` to a virtual directory

   333 `/cygdrive/<drive>`.

   334 

   335 You can always use the `cygpath` utility to map pathnames with spaces or the

   336 backslash character into the `C:/` style of pathname (called 'mixed'), e.g.

   337 `cygpath -s -m "<path>"`.

   338 

   339 Note that the use of CYGWIN creates a unique problem with regards to setting

   340 [`PATH`](#path). Normally on Windows the `PATH` variable contains directories

   341 separated with the ";" character (Solaris and Linux use ":"). With CYGWIN, it

   342 uses ":", but that means that paths like "C:/path" cannot be placed in the

   343 CYGWIN version of `PATH` and instead CYGWIN uses something like

   344 `/cygdrive/c/path` which CYGWIN understands, but only CYGWIN understands.

   345 

   346 The OpenJDK build requires CYGWIN version 1.7.16 or newer. Information about

   347 CYGWIN can be obtained from the CYGWIN website at

   348 [www.cygwin.com](http://www.cygwin.com).

   349 

   350 By default CYGWIN doesn't install all the tools required for building the

   351 OpenJDK. Along with the default installation, you need to install the following

   352 tools.

   353 

   354 >  <table border="1">

   355      <thead>

   356        <tr>

   357          <td>Binary Name</td>

   358          <td>Category</td>

   359          <td>Package</td>

   360          <td>Description</td>

   361       </tr>

   362      </thead>

   363      <tbody>

   364        <tr>

   365          <td>ar.exe</td>

   366          <td>Devel</td>

   367          <td>binutils</td>

   368          <td>The GNU assembler, linker and binary utilities</td>

   369        </tr>

   370        <tr>

   371          <td>make.exe</td>

   372          <td>Devel</td>

   373          <td>make</td>

   374          <td>The GNU version of the 'make' utility built for CYGWIN</td>

   375        </tr>

   376        <tr>

   377          <td>m4.exe</td>

   378          <td>Interpreters</td>

   379          <td>m4</td>

   380          <td>GNU implementation of the traditional Unix macro processor</td>

   381        </tr>

   382        <tr>

   383          <td>cpio.exe</td>

   384          <td>Utils</td>

   385          <td>cpio</td>

   386          <td>A program to manage archives of files</td>

   387        </tr>

   388        <tr>

   389          <td>gawk.exe</td>

   390          <td>Utils</td>

   391          <td>awk</td>

   392          <td>Pattern-directed scanning and processing language</td>

   393        </tr>

   394        <tr>

   395          <td>file.exe</td>

   396          <td>Utils</td>

   397          <td>file</td>

   398          <td>Determines file type using 'magic' numbers</td>

   399        </tr>

   400        <tr>

   401          <td>zip.exe</td>

   402          <td>Archive</td>

   403          <td>zip</td>

   404          <td>Package and compress (archive) files</td>

   405        </tr>

   406        <tr>

   407          <td>unzip.exe</td>

   408          <td>Archive</td>

   409          <td>unzip</td>

   410          <td>Extract compressed files in a ZIP archive</td>

   411        </tr>

   412        <tr>

   413          <td>free.exe</td>

   414          <td>System</td>

   415          <td>procps</td>

   416          <td>Display amount of free and used memory in the system</td>

   417        </tr>

   418      </tbody>

   419    </table>

   420 

   421 Note that the CYGWIN software can conflict with other non-CYGWIN software on

   422 your Windows system. CYGWIN provides a [FAQ](http://cygwin.com/faq/

   423 faq.using.html) for known issues and problems, of particular interest is the

   424 section on [BLODA (applications that interfere with

   425 CYGWIN)](http://cygwin.com/faq/faq.using.html#faq.using.bloda).

   426 

   427 <a name="msys"></a>

   428 ###### MinGW/MSYS

   429 

   430 MinGW ("Minimalist GNU for Windows") is a collection of free Windows specific

   431 header files and import libraries combined with GNU toolsets that allow one to

   432 produce native Windows programs that do not rely on any 3rd-party C runtime

   433 DLLs. MSYS is a supplement to MinGW which allows building applications and

   434 programs which rely on traditional UNIX tools to be present. Among others this

   435 includes tools like `bash` and `make`. See [MinGW/MSYS](http://www.mingw.org/

   436 wiki/MSYS) for more information.

   437 

   438 Like Cygwin, MinGW/MSYS can handle different types of path formats. They are

   439 internally converted to paths with forward slashes and drive letters

   440 `<drive>:` replaced by a virtual directory `/<drive>`. Additionally, MSYS

   441 automatically detects binaries compiled for the MSYS environment and feeds them

   442 with the internal, Unix-style path names. If native Windows applications are

   443 called from within MSYS programs their path arguments are automatically

   444 converted back to Windows style path names with drive letters and backslashes

   445 as path separators. This may cause problems for Windows applications which use

   446 forward slashes as parameter separator (e.g. `cl /nologo /I`) because MSYS may

   447 wrongly [replace such parameters by drive letters](http://mingw.org/wiki/

   448 Posix_path_conversion).

   449 

   450 In addition to the tools which will be installed by default, you have to

   451 manually install the `msys-zip` and `msys-unzip` packages. This can be easily

   452 done with the MinGW command line installer:

   453 

   454       mingw-get.exe install msys-zip

   455       mingw-get.exe install msys-unzip

   456 

   457 <a name="vs2013"></a>

   458 ##### Visual Studio 2013 Compilers

   459 

   460 The 32-bit and 64-bit OpenJDK Windows build requires Microsoft Visual Studio

   461 C++ 2013 (VS2013) Professional Edition or Express compiler. The compiler and

   462 other tools are expected to reside in the location defined by the variable

   463 `VS120COMNTOOLS` which is set by the Microsoft Visual Studio installer.

   464 

   465 Only the C++ part of VS2013 is needed. Try to let the installation go to the

   466 default install directory. Always reboot your system after installing VS2013.

   467 The system environment variable VS120COMNTOOLS should be set in your

   468 environment.

   469 

   470 Make sure that TMP and TEMP are also set in the environment and refer to

   471 Windows paths that exist, like `C:\temp`, not `/tmp`, not `/cygdrive/c/temp`,

   472 and not `C:/temp`. `C:\temp` is just an example, it is assumed that this area

   473 is private to the user, so by default after installs you should see a unique

   474 user path in these variables.

   475 

   476 <a name="macosx"></a>

   477 #### Mac OS X

   478 

   479 Make sure you get the right XCode version.

   480 

   481 *****

   482 

   483 <a name="configure"></a>

   484 ### Configure

   485 

   486 The basic invocation of the `configure` script looks like:

   487 

   488 >  **`bash ./configure [options]`**

   489 

   490 This will create an output directory containing the "configuration" and setup

   491 an area for the build result. This directory typically looks like:

   492 

   493 >  **`build/linux-x64-normal-server-release`**

   494 

   495 `configure` will try to figure out what system you are running on and where all

   496 necessary build components are. If you have all prerequisites for building

   497 installed, it should find everything. If it fails to detect any component

   498 automatically, it will exit and inform you about the problem. When this

   499 happens, read more below in [the `configure` options](#configureoptions).

   500 

   501 Some examples:

   502 

   503 >  **Windows 32bit build with freetype specified:**  

   504 >  `bash ./configure --with-freetype=/cygdrive/c/freetype-i586 --with-target-

   505 bits=32`

   506 

   507 >  **Debug 64bit Build:**  

   508 >  `bash ./configure --enable-debug --with-target-bits=64`

   509 

   510 <a name="configureoptions"></a>

   511 #### Configure Options

   512 

   513 Complete details on all the OpenJDK `configure` options can be seen with:

   514 

   515 >  **`bash ./configure --help=short`**

   516 

   517 Use `-help` to see all the `configure` options available. You can generate any

   518 number of different configurations, e.g. debug, release, 32, 64, etc.

   519 

   520 Some of the more commonly used `configure` options are:

   521 

   522 >  **`--enable-debug`**  

   523 >  set the debug level to fastdebug (this is a shorthand for `--with-debug-

   524    level=fastdebug`)

   525 

   526 <a name="alsa"></a>

   527 >  **`--with-alsa=`**_path_  

   528 >  select the location of the Advanced Linux Sound Architecture (ALSA)

   529 

   530 >  Version 0.9.1 or newer of the ALSA files are required for building the

   531    OpenJDK on Linux. These Linux files are usually available from an "alsa" of

   532    "libasound" development package, and it's highly recommended that you try

   533    and use the package provided by the particular version of Linux that you are

   534    using.

   535 

   536 >  **`--with-boot-jdk=`**_path_  

   537 >  select the [Bootstrap JDK](#bootjdk)

   538 

   539 >  **`--with-boot-jdk-jvmargs=`**"_args_"  

   540 >  provide the JVM options to be used to run the [Bootstrap JDK](#bootjdk)

   541 

   542 >  **`--with-cacerts=`**_path_  

   543 >  select the path to the cacerts file.

   544 

   545 >  See [Certificate Authority on Wikipedia](http://en.wikipedia.org/wiki/

   546    Certificate_Authority) for a better understanding of the Certificate

   547    Authority (CA). A certificates file named "cacerts" represents a system-wide

   548    keystore with CA certificates. In JDK and JRE binary bundles, the "cacerts"

   549    file contains root CA certificates from several public CAs (e.g., VeriSign,

   550    Thawte, and Baltimore). The source contain a cacerts file without CA root

   551    certificates. Formal JDK builders will need to secure permission from each

   552    public CA and include the certificates into their own custom cacerts file.

   553    Failure to provide a populated cacerts file will result in verification

   554    errors of a certificate chain during runtime. By default an empty cacerts

   555    file is provided and that should be fine for most JDK developers.

   556 

   557 <a name="cups"></a>

   558 >  **`--with-cups=`**_path_  

   559 >  select the CUPS install location

   560 

   561 >  The Common UNIX Printing System (CUPS) Headers are required for building the

   562    OpenJDK on Solaris and Linux. The Solaris header files can be obtained by

   563    installing the package **print/cups**.

   564 

   565 >  The CUPS header files can always be downloaded from

   566    [www.cups.org](http://www.cups.org).

   567 

   568 >  **`--with-cups-include=`**_path_  

   569 >  select the CUPS include directory location

   570 

   571 >  **`--with-debug-level=`**_level_  

   572 >  select the debug information level of release, fastdebug, or slowdebug

   573 

   574 >  **`--with-dev-kit=`**_path_  

   575 >  select location of the compiler install or developer install location

   576 

   577 <a name="freetype"></a>

   578 >  **`--with-freetype=`**_path_  

   579 >  select the freetype files to use.

   580 

   581 >  Expecting the freetype libraries under `lib/` and the headers under

   582    `include/`.

   583 

   584 >  Version 2.3 or newer of FreeType is required. On Unix systems required files

   585    can be available as part of your distribution (while you still may need to

   586    upgrade them). Note that you need development version of package that

   587    includes both the FreeType library and header files.

   588 

   589 >  You can always download latest FreeType version from the [FreeType

   590    website](http://www.freetype.org). Building the freetype 2 libraries from

   591    scratch is also possible, however on Windows refer to the [Windows FreeType

   592    DLL build instructions](http://freetype.freedesktop.org/wiki/FreeType_DLL).

   593 

   594 >  Note that by default FreeType is built with byte code hinting support

   595    disabled due to licensing restrictions. In this case, text appearance and

   596    metrics are expected to differ from Sun's official JDK build. See the

   597    [SourceForge FreeType2 Home Page](http://freetype.sourceforge.net/freetype2)

   598    for more information.

   599 

   600 >  **`--with-import-hotspot=`**_path_  

   601 >  select the location to find hotspot binaries from a previous build to avoid

   602    building hotspot

   603 

   604 >  **`--with-target-bits=`**_arg_  

   605 >  select 32 or 64 bit build

   606 

   607 >  **`--with-jvm-variants=`**_variants_  

   608 >  select the JVM variants to build from, comma separated list that can

   609    include: server, client, kernel, zero and zeroshark

   610 

   611 >  **`--with-memory-size=`**_size_  

   612 >  select the RAM size that GNU make will think this system has

   613 

   614 >  **`--with-msvcr-dll=`**_path_  

   615 >  select the `msvcr100.dll` file to include in the Windows builds (C/C++

   616    runtime library for Visual Studio).

   617 

   618 >  This is usually picked up automatically from the redist directories of

   619    Visual Studio 2013.

   620 

   621 >  **`--with-num-cores=`**_cores_  

   622 >  select the number of cores to use (processor count or CPU count)

   623 

   624 <a name="xrender"></a>

   625 >  **`--with-x=`**_path_  

   626 >  select the location of the X11 and xrender files.

   627 

   628 >  The XRender Extension Headers are required for building the OpenJDK on

   629    Solaris and Linux. The Linux header files are usually available from a

   630    "Xrender" development package, it's recommended that you try and use the

   631    package provided by the particular distribution of Linux that you are using.

   632    The Solaris XRender header files is included with the other X11 header files

   633    in the package **SFWxwinc** on new enough versions of Solaris and will be

   634    installed in `/usr/X11/include/X11/extensions/Xrender.h` or

   635    `/usr/openwin/share/include/X11/extensions/Xrender.h`

   636 

   637 *****

   638 

   639 <a name="make"></a>

   640 ### Make

   641 

   642 The basic invocation of the `make` utility looks like:

   643 

   644 >  **`make all`**

   645 

   646 This will start the build to the output directory containing the

   647 "configuration" that was created by the `configure` script. Run `make help` for

   648 more information on the available targets.

   649 

   650 There are some of the make targets that are of general interest:

   651 

   652 >  _empty_  

   653 >  build everything but no images

   654 

   655 >  **`all`**  

   656 >  build everything including images

   657 

   658 >  **`all-conf`**  

   659 >  build all configurations

   660 

   661 >  **`images`**  

   662 >  create complete j2sdk and j2re images

   663 

   664 >  **`install`**  

   665 >  install the generated images locally, typically in `/usr/local`

   666 

   667 >  **`clean`**  

   668 >  remove all files generated by make, but not those generated by `configure`

   669 

   670 >  **`dist-clean`**  

   671 >  remove all files generated by both and `configure` (basically killing the

   672    configuration)

   673 

   674 >  **`help`**  

   675 >  give some help on using `make`, including some interesting make targets

   676 

   677 *****

   678 

   679 <a name="testing"></a>

   680 ## Testing

   681 

   682 When the build is completed, you should see the generated binaries and

   683 associated files in the `j2sdk-image` directory in the output directory. In

   684 particular, the `build/*/images/j2sdk-image/bin` directory should contain

   685 executables for the OpenJDK tools and utilities for that configuration. The

   686 testing tool `jtreg` will be needed and can be found at: [the jtreg

   687 site](http://openjdk.java.net/jtreg/). The provided regression tests in the

   688 repositories can be run with the command:

   689 

   690 >  **``cd test && make PRODUCT_HOME=`pwd`/../build/*/images/j2sdk-image all``**

   691 

   692 *****

   693 

   694 <a name="hints"></a>

   695 ## Appendix A: Hints and Tips

   696 

   697 <a name="faq"></a>

   698 ### FAQ

   699 

   700 **Q:** The `generated-configure.sh` file looks horrible! How are you going to

   701 edit it?  

   702 **A:** The `generated-configure.sh` file is generated (think "compiled") by the

   703 autoconf tools. The source code is in `configure.ac` and various .m4 files in

   704 common/autoconf, which are much more readable.

   705 

   706 **Q:** Why is the `generated-configure.sh` file checked in, if it is 

   707 generated?  

   708 **A:** If it was not generated, every user would need to have the autoconf

   709 tools installed, and re-generate the `configure` file as the first step. Our

   710 goal is to minimize the work needed to be done by the user to start building

   711 OpenJDK, and to minimize the number of external dependencies required.

   712 

   713 **Q:** Do you require a specific version of autoconf for regenerating

   714 `generated-configure.sh`?  

   715 **A:** Yes, version 2.69 is required and should be easy enough to aquire on all

   716 supported operating systems. The reason for this is to avoid large spurious

   717 changes in `generated-configure.sh`.

   718 

   719 **Q:** How do you regenerate `generated-configure.sh` after making changes to

   720 the input files?  

   721 **A:** Regnerating `generated-configure.sh` should always be done using the

   722 script `common/autoconf/autogen.sh` to ensure that the correct files get

   723 updated. This script should also be run after mercurial tries to merge

   724 `generated-configure.sh` as a merge of the generated file is not guaranteed to

   725 be correct.

   726 

   727 **Q:** What are the files in `common/makefiles/support/*` for? They look like

   728 gibberish.  

   729 **A:** They are a somewhat ugly hack to compensate for command line length

   730 limitations on certain platforms (Windows, Solaris). Due to a combination of

   731 limitations in make and the shell, command lines containing too many files will

   732 not work properly. These helper files are part of an elaborate hack that will

   733 compress the command line in the makefile and then uncompress it safely. We're

   734 not proud of it, but it does fix the problem. If you have any better

   735 suggestions, we're all ears! :-)

   736 

   737 **Q:** I want to see the output of the commands that make runs, like in the old

   738 build. How do I do that?  

   739 **A:** You specify the `LOG` variable to make. There are several log levels:

   740 

   741  * **`warn`** -- Default and very quiet.

   742  * **`info`** -- Shows more progress information than warn.

   743  * **`debug`** -- Echos all command lines and prints all macro calls for

   744    compilation definitions.

   745  * **`trace`** -- Echos all $(shell) command lines as well.

   746 

   747 **Q:** When do I have to re-run `configure`?  

   748 **A:** Normally you will run `configure` only once for creating a

   749 configuration. You need to re-run configuration only if you want to change any

   750 configuration options, or if you pull down changes to the `configure` script.

   751 

   752 **Q:** I have added a new source file. Do I need to modify the makefiles?  

   753 **A:** Normally, no. If you want to create e.g. a new native library, you will

   754 need to modify the makefiles. But for normal file additions or removals, no

   755 changes are needed. There are certan exceptions for some native libraries where

   756 the source files are spread over many directories which also contain sources

   757 for other libraries. In these cases it was simply easier to create include

   758 lists rather than excludes.

   759 

   760 **Q:** When I run `configure --help`, I see many strange options, like

   761 `--dvidir`. What is this?  

   762 **A:** Configure provides a slew of options by default, to all projects that

   763 use autoconf. Most of them are not used in OpenJDK, so you can safely ignore

   764 them. To list only OpenJDK specific features, use `configure --help=short`

   765 instead.

   766 

   767 **Q:** `configure` provides OpenJDK-specific features such as `--with-

   768 builddeps-server` that are not described in this document. What about those?  

   769 **A:** Try them out if you like! But be aware that most of these are

   770 experimental features. Many of them don't do anything at all at the moment; the

   771 option is just a placeholder. Others depend on pieces of code or infrastructure

   772 that is currently not ready for prime time.

   773 

   774 **Q:** How will you make sure you don't break anything?  

   775 **A:** We have a script that compares the result of the new build system with

   776 the result of the old. For most part, we aim for (and achieve) byte-by-byte

   777 identical output. There are however technical issues with e.g. native binaries,

   778 which might differ in a byte-by-byte comparison, even when building twice with

   779 the old build system. For these, we compare relevant aspects (e.g. the symbol

   780 table and file size). Note that we still don't have 100% equivalence, but we're

   781 close.

   782 

   783 **Q:** I noticed this thing X in the build that looks very broken by design.

   784 Why don't you fix it?  

   785 **A:** Our goal is to produce a build output that is as close as technically

   786 possible to the old build output. If things were weird in the old build, they

   787 will be weird in the new build. Often, things were weird before due to

   788 obscurity, but in the new build system the weird stuff comes up to the surface.

   789 The plan is to attack these things at a later stage, after the new build system

   790 is established.

   791 

   792 **Q:** The code in the new build system is not that well-structured. Will you

   793 fix this?  

   794 **A:** Yes! The new build system has grown bit by bit as we converted the old

   795 system. When all of the old build system is converted, we can take a step back

   796 and clean up the structure of the new build system. Some of this we plan to do

   797 before replacing the old build system and some will need to wait until after.

   798 

   799 **Q:** Is anything able to use the results of the new build's default make

   800 target?  

   801 **A:** Yes, this is the minimal (or roughly minimal) set of compiled output

   802 needed for a developer to actually execute the newly built JDK. The idea is

   803 that in an incremental development fashion, when doing a normal make, you

   804 should only spend time recompiling what's changed (making it purely

   805 incremental) and only do the work that's needed to actually run and test your

   806 code. The packaging stuff that is part of the `images` target is not needed for

   807 a normal developer who wants to test his new code. Even if it's quite fast,

   808 it's still unnecessary. We're targeting sub-second incremental rebuilds! ;-)

   809 (Or, well, at least single-digit seconds...)

   810 

   811 **Q:** I usually set a specific environment variable when building, but I can't

   812 find the equivalent in the new build. What should I do?  

   813 **A:** It might very well be that we have neglected to add support for an

   814 option that was actually used from outside the build system. Email us and we

   815 will add support for it!

   816 

   817 <a name="performance"></a>

   818 ### Build Performance Tips

   819 

   820 Building OpenJDK requires a lot of horsepower. Some of the build tools can be

   821 adjusted to utilize more or less of resources such as parallel threads and

   822 memory. The `configure` script analyzes your system and selects reasonable

   823 values for such options based on your hardware. If you encounter resource

   824 problems, such as out of memory conditions, you can modify the detected values

   825 with:

   826 

   827  * **`--with-num-cores`** -- number of cores in the build system, e.g.

   828    `--with-num-cores=8`

   829  * **`--with-memory-size`** -- memory (in MB) available in the build system,

   830     e.g. `--with-memory-size=1024`

   831 

   832 It might also be necessary to specify the JVM arguments passed to the Bootstrap

   833 JDK, using e.g. `--with-boot-jdk-jvmargs="-Xmx8G -enableassertions"`. Doing

   834 this will override the default JVM arguments passed to the Bootstrap JDK.

   835 

   836 One of the top goals of the new build system is to improve the build

   837 performance and decrease the time needed to build. This will soon also apply to

   838 the java compilation when the Smart Javac wrapper is fully supported.

   839 

   840 At the end of a successful execution of `configure`, you will get a performance

   841 summary, indicating how well the build will perform. Here you will also get

   842 performance hints. If you want to build fast, pay attention to those!

   843 

   844 #### Building with ccache

   845 

   846 The OpenJDK build supports building with ccache when using gcc or clang. Using

   847 ccache can radically speed up compilation of native code if you often rebuild

   848 the same sources. Your milage may vary however so we recommend evaluating it

   849 for yourself. To enable it, make sure it's on the path and configure with

   850 `--enable-ccache`.

   851 

   852 #### Building on local disk

   853 

   854 If you are using network shares, e.g. via NFS, for your source code, make sure

   855 the build directory is situated on local disk. The performance penalty is

   856 extremely high for building on a network share, close to unusable.

   857 

   858 #### Building only one JVM

   859 

   860 The old build builds multiple JVMs on 32-bit systems (client and server; and on

   861 Windows kernel as well). In the new build we have changed this default to only

   862 build server when it's available. This improves build times for those not

   863 interested in multiple JVMs. To mimic the old behavior on platforms that

   864 support it, use `--with-jvm-variants=client,server`.

   865 

   866 #### Selecting the number of cores to build on

   867 

   868 By default, `configure` will analyze your machine and run the make process in

   869 parallel with as many threads as you have cores. This behavior can be

   870 overridden, either "permanently" (on a `configure` basis) using

   871 `--with-num-cores=N` or for a single build only (on a make basis), using

   872 `make JOBS=N`.

   873 

   874 If you want to make a slower build just this time, to save some CPU power for

   875 other processes, you can run e.g. `make JOBS=2`. This will force the makefiles

   876 to only run 2 parallel processes, or even `make JOBS=1` which will disable

   877 parallelism.

   878 

   879 If you want to have it the other way round, namely having slow builds default

   880 and override with fast if you're impatient, you should call `configure` with

   881 `--with-num-cores=2`, making 2 the default. If you want to run with more cores,

   882 run `make JOBS=8`

   883 

   884 <a name="troubleshooting"></a>

   885 ### Troubleshooting

   886 

   887 #### Solving build problems

   888 

   889 If the build fails (and it's not due to a compilation error in a source file

   890 you've changed), the first thing you should do is to re-run the build with more

   891 verbosity. Do this by adding `LOG=debug` to your make command line.

   892 

   893 The build log (with both stdout and stderr intermingled, basically the same as

   894 you see on your console) can be found as `build.log` in your build directory.

   895 

   896 You can ask for help on build problems with the new build system on either the

   897 [build-dev](http://mail.openjdk.java.net/mailman/listinfo/build-dev) or the

   898 [build-infra-dev](http://mail.openjdk.java.net/mailman/listinfo/build-infra-dev)

   899 mailing lists. Please include the relevant parts of the build log.

   900 

   901 A build can fail for any number of reasons. Most failures are a result of

   902 trying to build in an environment in which all the pre-build requirements have

   903 not been met. The first step in troubleshooting a build failure is to recheck

   904 that you have satisfied all the pre-build requirements for your platform.

   905 Scanning the `configure` log is a good first step, making sure that what it

   906 found makes sense for your system. Look for strange error messages or any

   907 difficulties that `configure` had in finding things.

   908 

   909 Some of the more common problems with builds are briefly described below, with

   910 suggestions for remedies.

   911 

   912  * **Corrupted Bundles on Windows:**  

   913    Some virus scanning software has been known to corrupt the downloading of

   914    zip bundles. It may be necessary to disable the 'on access' or 'real time'

   915    virus scanning features to prevent this corruption. This type of 'real time'

   916    virus scanning can also slow down the build process significantly.

   917    Temporarily disabling the feature, or excluding the build output directory

   918    may be necessary to get correct and faster builds.

   919 

   920  * **Slow Builds:**  

   921    If your build machine seems to be overloaded from too many simultaneous C++

   922    compiles, try setting the `JOBS=1` on the `make` command line. Then try

   923    increasing the count slowly to an acceptable level for your system. Also:

   924 

   925    Creating the javadocs can be very slow, if you are running javadoc, consider

   926    skipping that step.

   927 

   928    Faster CPUs, more RAM, and a faster DISK usually helps. The VM build tends

   929    to be CPU intensive (many C++ compiles), and the rest of the JDK will often

   930    be disk intensive.

   931 

   932    Faster compiles are possible using a tool called

   933    [ccache](http://ccache.samba.org/).

   934 

   935  * **File time issues:**  

   936    If you see warnings that refer to file time stamps, e.g.

   937 

   938    > _Warning message:_ ` File 'xxx' has modification time in the future.`  

   939    > _Warning message:_ ` Clock skew detected. Your build may be incomplete.`

   940 

   941    These warnings can occur when the clock on the build machine is out of sync

   942    with the timestamps on the source files. Other errors, apparently unrelated

   943    but in fact caused by the clock skew, can occur along with the clock skew

   944    warnings. These secondary errors may tend to obscure the fact that the true

   945    root cause of the problem is an out-of-sync clock.

   946 

   947    If you see these warnings, reset the clock on the build machine, run

   948    "`gmake clobber`" or delete the directory containing the build output, and

   949    restart the build from the beginning.

   950 

   951  * **Error message: `Trouble writing out table to disk`**  

   952    Increase the amount of swap space on your build machine. This could be

   953    caused by overloading the system and it may be necessary to use:

   954 

   955    > `make JOBS=1`

   956 

   957    to reduce the load on the system.

   958 

   959  * **Error Message: `libstdc++ not found`:**  

   960    This is caused by a missing libstdc++.a library. This is installed as part

   961    of a specific package (e.g. libstdc++.so.devel.386). By default some 64-bit

   962    Linux versions (e.g. Fedora) only install the 64-bit version of the

   963    libstdc++ package. Various parts of the JDK build require a static link of

   964    the C++ runtime libraries to allow for maximum portability of the built

   965    images.

   966 

   967  * **Linux Error Message: `cannot restore segment prot after reloc`**  

   968    This is probably an issue with SELinux (See [SELinux on

   969    Wikipedia](http://en.wikipedia.org/wiki/SELinux)). Parts of the VM is built

   970    without the `-fPIC` for performance reasons.

   971 

   972    To completely disable SELinux:

   973 

   974    1. `$ su root`

   975    2. `# system-config-securitylevel`

   976    3. `In the window that appears, select the SELinux tab`

   977    4. `Disable SELinux`

   978 

   979    Alternatively, instead of completely disabling it you could disable just

   980    this one check.

   981 

   982    1. Select System->Administration->SELinux Management

   983    2. In the SELinux Management Tool which appears, select "Boolean" from the

   984       menu on the left

   985    3. Expand the "Memory Protection" group

   986    4. Check the first item, labeled "Allow all unconfined executables to use

   987       libraries requiring text relocation ..."

   988 

   989  * **Windows Error Messages:**  

   990    `*** fatal error - couldn't allocate heap, ... `  

   991    `rm fails with "Directory not empty"`  

   992    `unzip fails with "cannot create ... Permission denied"`  

   993    `unzip fails with "cannot create ... Error 50"`

   994 

   995    The CYGWIN software can conflict with other non-CYGWIN software. See the

   996    CYGWIN FAQ section on [BLODA (applications that interfere with

   997    CYGWIN)](http://cygwin.com/faq/faq.using.html#faq.using.bloda).

   998 

   999  * **Windows Error Message: `spawn failed`**  

  1000    Try rebooting the system, or there could be some kind of issue with the disk

  1001    or disk partition being used. Sometimes it comes with a "Permission Denied"

  1002    message.

  1003 

  1004 *****

  1005 

  1006 <a name="gmake"></a>

  1007 ## Appendix B: GNU make

  1008 

  1009 The Makefiles in the OpenJDK are only valid when used with the GNU version of

  1010 the utility command `make` (usually called `gmake` on Solaris). A few notes

  1011 about using GNU make:

  1012 

  1013  * You need GNU make version 3.81 or newer. On Windows 4.0 or newer is

  1014    recommended. If the GNU make utility on your systems is not of a suitable

  1015    version, see "[Building GNU make](#buildgmake)".

  1016  * Place the location of the GNU make binary in the `PATH`.

  1017  * **Solaris:** Do NOT use `/usr/bin/make` on Solaris. If your Solaris system

  1018    has the software from the Solaris Developer Companion CD installed, you

  1019    should try and use `/usr/bin/gmake` or `/usr/gnu/bin/make`.

  1020  * **Windows:** Make sure you start your build inside a bash shell.

  1021  * **Mac OS X:** The XCode "command line tools" must be installed on your Mac.

  1022 

  1023 Information on GNU make, and access to ftp download sites, are available on the

  1024 [GNU make web site ](http://www.gnu.org/software/make/make.html). The latest

  1025 source to GNU make is available at

  1026 [ftp.gnu.org/pub/gnu/make/](http://ftp.gnu.org/pub/gnu/make/).

  1027 

  1028 <a name="buildgmake"></a>

  1029 ### Building GNU make

  1030 

  1031 First step is to get the GNU make 3.81 or newer source from

  1032 [ftp.gnu.org/pub/gnu/make/](http://ftp.gnu.org/pub/gnu/make/). Building is a

  1033 little different depending on the OS but is basically done with:

  1034 

  1035       bash ./configure

  1036       make

  1037 

  1038 *****

  1039 

  1040 <a name="buildenvironments"></a>

  1041 ## Appendix C: Build Environments

  1042 

  1043 ### Minimum Build Environments

  1044 

  1045 This file often describes specific requirements for what we call the "minimum

  1046 build environments" (MBE) for this specific release of the JDK. What is listed

  1047 below is what the Oracle Release Engineering Team will use to build the Oracle

  1048 JDK product. Building with the MBE will hopefully generate the most compatible

  1049 bits that install on, and run correctly on, the most variations of the same

  1050 base OS and hardware architecture. In some cases, these represent what is often

  1051 called the least common denominator, but each Operating System has different

  1052 aspects to it.

  1053 

  1054 In all cases, the Bootstrap JDK version minimum is critical, we cannot

  1055 guarantee builds will work with older Bootstrap JDK's. Also in all cases, more

  1056 RAM and more processors is better, the minimums listed below are simply

  1057 recommendations.

  1058 

  1059 With Solaris and Mac OS X, the version listed below is the oldest release we

  1060 can guarantee builds and works, and the specific version of the compilers used

  1061 could be critical.

  1062 

  1063 With Windows the critical aspect is the Visual Studio compiler used, which due

  1064 to it's runtime, generally dictates what Windows systems can do the builds and

  1065 where the resulting bits can be used.

  1066 

  1067 **NOTE: We expect a change here off these older Windows OS releases and to a

  1068 'less older' one, probably Windows 2008R2 X64.**

  1069 

  1070 With Linux, it was just a matter of picking a stable distribution that is a

  1071 good representative for Linux in general.

  1072 

  1073 It is understood that most developers will NOT be using these specific

  1074 versions, and in fact creating these specific versions may be difficult due to

  1075 the age of some of this software. It is expected that developers are more often

  1076 using the more recent releases and distributions of these operating systems.

  1077 

  1078 Compilation problems with newer or different C/C++ compilers is a common

  1079 problem. Similarly, compilation problems related to changes to the

  1080 `/usr/include` or system header files is also a common problem with older,

  1081 newer, or unreleased OS versions. Please report these types of problems as bugs

  1082 so that they can be dealt with accordingly.

  1083 

  1084 >  <table border="1">

  1085      <thead>

  1086        <tr>

  1087          <th>Base OS and Architecture</th>

  1088          <th>OS</th>

  1089          <th>C/C++ Compiler</th>

  1090          <th>Bootstrap JDK</th>

  1091          <th>Processors</th>

  1092          <th>RAM Minimum</th>

  1093          <th>DISK Needs</th>

  1094        </tr>

  1095      </thead>

  1096      <tbody>

  1097        <tr>

  1098          <td>Linux X86 (32-bit) and X64 (64-bit)</td>

  1099          <td>Oracle Enterprise Linux 6.4</td>

  1100          <td>gcc 4.9.2 </td>

  1101          <td>JDK 8</td>

  1102          <td>2 or more</td>

  1103          <td>1 GB</td>

  1104          <td>6 GB</td>

  1105        </tr>

  1106        <tr>

  1107          <td>Solaris SPARCV9 (64-bit)</td>

  1108          <td>Solaris 11 Update 1</td>

  1109          <td>Studio 12 Update 4 + patches</td>

  1110          <td>JDK 8</td>

  1111          <td>4 or more</td>

  1112          <td>4 GB</td>

  1113          <td>8 GB</td>

  1114        </tr>

  1115        <tr>

  1116          <td>Solaris X64 (64-bit)</td>

  1117          <td>Solaris 11 Update 1</td>

  1118          <td>Studio 12 Update 4 + patches</td>

  1119          <td>JDK 8</td>

  1120          <td>4 or more</td>

  1121          <td>4 GB</td>

  1122          <td>8 GB</td>

  1123        </tr>

  1124        <tr>

  1125          <td>Windows X86 (32-bit)</td>

  1126          <td>Windows Server 2012 R2 x64</td>

  1127          <td>Microsoft Visual Studio C++ 2013 Professional Edition</td>

  1128          <td>JDK 8</td>

  1129          <td>2 or more</td>

  1130          <td>2 GB</td>

  1131          <td>6 GB</td>

  1132        </tr>

  1133        <tr>

  1134          <td>Windows X64 (64-bit)</td>