OpenJDK / jdk-updates / jdk15u

annotate README-builds.md @ 34787:36167bbe1a9f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
8055197: TextField deletes multiline strings Reviewed-by: serb, alexsch
author arapte
date Thu, 26 Nov 2015 19:12:28 +0400
parents de12d9a875ed
children 09596fe63e2d
rev   line source
ihse@33030 1 ![OpenJDK](http://openjdk.java.net/images/openjdk.png)
ihse@33030 2 # OpenJDK Build README
ihse@33030 3
ihse@33030 4 *****
ihse@33030 5
ihse@33030 6 <a name="introduction"></a>
ihse@33030 7 ## Introduction
ihse@33030 8
ihse@33030 9 This README file contains build instructions for the
ihse@33030 10 [OpenJDK](http://openjdk.java.net). Building the source code for the OpenJDK
ihse@33030 11 requires a certain degree of technical expertise.
ihse@33030 12
ihse@33030 13 ### !!!!!!!!!!!!!!! THIS IS A MAJOR RE-WRITE of this document. !!!!!!!!!!!!!
ihse@33030 14
ihse@33030 15 Some Headlines:
ihse@33030 16
ihse@33030 17 * The build is now a "`configure && make`" style build
ihse@33030 18 * Any GNU make 3.81 or newer should work, except on Windows where 4.0 or newer
ihse@33030 19 is recommended.
ihse@33030 20 * The build should scale, i.e. more processors should cause the build to be
ihse@33030 21 done in less wall-clock time
ihse@33030 22 * Nested or recursive make invocations have been significantly reduced,
ihse@33030 23 as has the total fork/exec or spawning of sub processes during the build
ihse@33030 24 * Windows MKS usage is no longer supported
ihse@33030 25 * Windows Visual Studio `vsvars*.bat` and `vcvars*.bat` files are run
ihse@33030 26 automatically
ihse@33030 27 * Ant is no longer used when building the OpenJDK
ihse@33030 28 * Use of ALT_* environment variables for configuring the build is no longer
ihse@33030 29 supported
ihse@33030 30
ihse@33030 31 *****
ihse@33030 32
ihse@33030 33 ## Contents
ihse@33030 34
ihse@33030 35 * [Introduction](#introduction)
ihse@33030 36 * [Use of Mercurial](#hg)
ihse@33030 37 * [Getting the Source](#get_source)
ihse@33030 38 * [Repositories](#repositories)
ihse@33030 39 * [Building](#building)
ihse@33030 40 * [System Setup](#setup)
ihse@33030 41 * [Linux](#linux)
ihse@33030 42 * [Solaris](#solaris)
ihse@33030 43 * [Mac OS X](#macosx)
ihse@33030 44 * [Windows](#windows)
ihse@33030 45 * [Configure](#configure)
ihse@33030 46 * [Make](#make)
ihse@33030 47 * [Testing](#testing)
ihse@33030 48
ihse@33030 49 *****
ihse@33030 50
ihse@33030 51 * [Appendix A: Hints and Tips](#hints)
ihse@33030 52 * [FAQ](#faq)
ihse@33030 53 * [Build Performance Tips](#performance)
ihse@33030 54 * [Troubleshooting](#troubleshooting)
ihse@33030 55 * [Appendix B: GNU Make Information](#gmake)
ihse@33030 56 * [Appendix C: Build Environments](#buildenvironments)
ihse@33030 57
ihse@33030 58 *****
ihse@33030 59
ihse@33030 60 <a name="hg"></a>
ihse@33030 61 ## Use of Mercurial
ihse@33030 62
ihse@33030 63 The OpenJDK sources are maintained with the revision control system
ihse@33030 64 [Mercurial](http://mercurial.selenic.com/wiki/Mercurial). If you are new to
ihse@33030 65 Mercurial, please see the [Beginner Guides](http://mercurial.selenic.com/wiki/
ihse@33030 66 BeginnersGuides) or refer to the [Mercurial Book](http://hgbook.red-bean.com/).
ihse@33030 67 The first few chapters of the book provide an excellent overview of Mercurial,
ihse@33030 68 what it is and how it works.
ihse@33030 69
ihse@33030 70 For using Mercurial with the OpenJDK refer to the [Developer Guide: Installing
ihse@33030 71 and Configuring Mercurial](http://openjdk.java.net/guide/
ihse@33030 72 repositories.html#installConfig) section for more information.
ihse@33030 73
ihse@33030 74 <a name="get_source"></a>
ihse@33030 75 ### Getting the Source
ihse@33030 76
ihse@33030 77 To get the entire set of OpenJDK Mercurial repositories use the script
ihse@33030 78 `get_source.sh` located in the root repository:
ihse@33030 79
ihse@33030 80 hg clone http://hg.openjdk.java.net/jdk9/jdk9 YourOpenJDK
ihse@33030 81 cd YourOpenJDK
ihse@33030 82 bash ./get_source.sh
ihse@33030 83
ihse@33030 84 Once you have all the repositories, keep in mind that each repository is its
ihse@33030 85 own independent repository. You can also re-run `./get_source.sh` anytime to
ihse@33030 86 pull over all the latest changesets in all the repositories. This set of
ihse@33030 87 nested repositories has been given the term "forest" and there are various
ihse@33030 88 ways to apply the same `hg` command to each of the repositories. For
ihse@33030 89 example, the script `make/scripts/hgforest.sh` can be used to repeat the
ihse@33030 90 same `hg` command on every repository, e.g.
ihse@33030 91
ihse@33030 92 cd YourOpenJDK
ihse@33030 93 bash ./make/scripts/hgforest.sh status
ihse@33030 94
ihse@33030 95 <a name="repositories"></a>
ihse@33030 96 ### Repositories
ihse@33030 97
ihse@33030 98 The set of repositories and what they contain:
ihse@33030 99
ihse@33030 100 * **. (root)** contains common configure and makefile logic
ihse@33030 101 * **hotspot** contains source code and make files for building the OpenJDK
ihse@33030 102 Hotspot Virtual Machine
ihse@33030 103 * **langtools** contains source code for the OpenJDK javac and language tools
ihse@33030 104 * **jdk** contains source code and make files for building the OpenJDK runtime
ihse@33030 105 libraries and misc files
ihse@33030 106 * **jaxp** contains source code for the OpenJDK JAXP functionality
ihse@33030 107 * **jaxws** contains source code for the OpenJDK JAX-WS functionality
ihse@33030 108 * **corba** contains source code for the OpenJDK Corba functionality
ihse@33030 109 * **nashorn** contains source code for the OpenJDK JavaScript implementation
ihse@33030 110
ihse@33030 111 ### Repository Source Guidelines
ihse@33030 112
ihse@33030 113 There are some very basic guidelines:
ihse@33030 114
ihse@33030 115 * Use of whitespace in source files (.java, .c, .h, .cpp, and .hpp files) is
ihse@33030 116 restricted. No TABs, no trailing whitespace on lines, and files should not
ihse@33030 117 terminate in more than one blank line.
ihse@33030 118 * Files with execute permissions should not be added to the source
ihse@33030 119 repositories.
ihse@33030 120 * All generated files need to be kept isolated from the files maintained or
ihse@33030 121 managed by the source control system. The standard area for generated files
ihse@33030 122 is the top level `build/` directory.
ihse@33030 123 * The default build process should be to build the product and nothing else,
ihse@33030 124 in one form, e.g. a product (optimized), debug (non-optimized, -g plus
ihse@33030 125 assert logic), or fastdebug (optimized, -g plus assert logic).
ihse@33030 126 * The `.hgignore` file in each repository must exist and should include
ihse@33030 127 `^build/`, `^dist/` and optionally any `nbproject/private` directories. **It
ihse@33030 128 should NEVER** include anything in the `src/` or `test/` or any managed
ihse@33030 129 directory area of a repository.
ihse@33030 130 * Directory names and file names should never contain blanks or non-printing
ihse@33030 131 characters.
ihse@33030 132 * Generated source or binary files should NEVER be added to the repository
ihse@33030 133 (that includes `javah` output). There are some exceptions to this rule, in
ihse@33030 134 particular with some of the generated configure scripts.
ihse@33030 135 * Files not needed for typical building or testing of the repository should
ihse@33030 136 not be added to the repository.
ihse@33030 137
ihse@33030 138 *****
ihse@33030 139
ihse@33030 140 <a name="building"></a>
ihse@33030 141 ## Building
ihse@33030 142
ihse@33030 143 The very first step in building the OpenJDK is making sure the system itself
ihse@33030 144 has everything it needs to do OpenJDK builds. Once a system is setup, it
ihse@33030 145 generally doesn't need to be done again.
ihse@33030 146
ihse@33030 147 Building the OpenJDK is now done with running a `configure` script which will
ihse@33030 148 try and find and verify you have everything you need, followed by running
ihse@33030 149 `make`, e.g.
ihse@33030 150
ihse@33030 151 > **`bash ./configure`**
ihse@33030 152 > **`make all`**
ihse@33030 153
ihse@33030 154 Where possible the `configure` script will attempt to located the various
ihse@33030 155 components in the default locations or via component specific variable
ihse@33030 156 settings. When the normal defaults fail or components cannot be found,
ihse@33030 157 additional `configure` options may be necessary to help `configure` find the
ihse@33030 158 necessary tools for the build, or you may need to re-visit the setup of your
ihse@33030 159 system due to missing software packages.
ihse@33030 160
ihse@33030 161 **NOTE:** The `configure` script file does not have execute permissions and
ihse@33030 162 will need to be explicitly run with `bash`, see the source guidelines.
ihse@33030 163
ihse@33030 164 *****
ihse@33030 165
ihse@33030 166 <a name="setup"></a>
ihse@33030 167 ### System Setup
ihse@33030 168
ihse@33030 169 Before even attempting to use a system to build the OpenJDK there are some very
ihse@33030 170 basic system setups needed. For all systems:
ihse@33030 171
ihse@33030 172 * Be sure the GNU make utility is version 3.81 (4.0 on windows) or newer, e.g.
ihse@33030 173 run "`make -version`"
ihse@33030 174
ihse@33030 175 <a name="bootjdk"></a>
ihse@33030 176 * Install a Bootstrap JDK. All OpenJDK builds require access to a previously
ihse@33030 177 released JDK called the _bootstrap JDK_ or _boot JDK._ The general rule is
ihse@33030 178 that the bootstrap JDK must be an instance of the previous major release of
ihse@33030 179 the JDK. In addition, there may be a requirement to use a release at or
ihse@33030 180 beyond a particular update level.
ihse@33030 181
ihse@33030 182 **_Building JDK 9 requires JDK 8. JDK 9 developers should not use JDK 9 as
ihse@33030 183 the boot JDK, to ensure that JDK 9 dependencies are not introduced into the
ihse@33030 184 parts of the system that are built with JDK 8._**
ihse@33030 185
ihse@33030 186 The JDK 8 binaries can be downloaded from Oracle's [JDK 8 download
ihse@33030 187 site](http://www.oracle.com/technetwork/java/javase/downloads/index.html).
ihse@33030 188 For build performance reasons it is very important that this bootstrap JDK
ihse@33030 189 be made available on the local disk of the machine doing the build. You
ihse@33030 190 should add its `bin` directory to the `PATH` environment variable. If
ihse@33030 191 `configure` has any issues finding this JDK, you may need to use the
ihse@33030 192 `configure` option `--with-boot-jdk`.
ihse@33030 193
ihse@33030 194 * Ensure that GNU make, the Bootstrap JDK, and the compilers are all in your
ihse@33030 195 PATH environment variable.
ihse@33030 196
ihse@33030 197 And for specific systems:
ihse@33030 198
ihse@33030 199 * **Linux**
ihse@33030 200
ihse@33030 201 Install all the software development packages needed including
ihse@33030 202 [alsa](#alsa), [freetype](#freetype), [cups](#cups), and
ihse@33030 203 [xrender](#xrender). See [specific system packages](#SDBE).
ihse@33030 204
ihse@33030 205 * **Solaris**
ihse@33030 206
ihse@33030 207 Install all the software development packages needed including [Studio
ihse@33030 208 Compilers](#studio), [freetype](#freetype), [cups](#cups), and
ihse@33030 209 [xrender](#xrender). See [specific system packages](#SDBE).
ihse@33030 210
ihse@33030 211 * **Windows**
ihse@33030 212
ihse@33030 213 * Install one of [CYGWIN](#cygwin) or [MinGW/MSYS](#msys)
ihse@33030 214 * Install [Visual Studio 2013](#vs2013)
ihse@33030 215
ihse@33030 216 * **Mac OS X**
ihse@33030 217
ihse@33030 218 Install [XCode 4.5.2](https://developer.apple.com/xcode/) and also
ihse@33030 219 install the "Command line tools" found under the preferences pane
ihse@33030 220 "Downloads"
ihse@33030 221
ihse@33030 222 <a name="linux"></a>
ihse@33030 223 #### Linux
ihse@33030 224
ihse@33030 225 With Linux, try and favor the system packages over building your own or getting
ihse@33030 226 packages from other areas. Most Linux builds should be possible with the
ihse@33030 227 system's available packages.
ihse@33030 228
ihse@33030 229 Note that some Linux systems have a habit of pre-populating your environment
ihse@33030 230 variables for you, for example `JAVA_HOME` might get pre-defined for you to
ihse@33030 231 refer to the JDK installed on your Linux system. You will need to unset
ihse@33030 232 `JAVA_HOME`. It's a good idea to run `env` and verify the environment variables
ihse@33030 233 you are getting from the default system settings make sense for building the
ihse@33030 234 OpenJDK.
ihse@33030 235
ihse@33030 236 <a name="solaris"></a>
ihse@33030 237 #### Solaris
ihse@33030 238
ihse@33030 239 <a name="studio"></a>
ihse@33030 240 ##### Studio Compilers
ihse@33030 241
ihse@33030 242 At a minimum, the [Studio 12 Update 1 Compilers](http://www.oracle.com/
ihse@33030 243 technetwork/server-storage/solarisstudio/downloads/index.htm) (containing
ihse@33030 244 version 5.10 of the C and C++ compilers) is required, including specific
ihse@33030 245 patches.
ihse@33030 246
ihse@33030 247 The Solaris SPARC patch list is:
ihse@33030 248
ihse@33030 249 * 118683-05: SunOS 5.10: Patch for profiling libraries and assembler
ihse@33030 250 * 119963-21: SunOS 5.10: Shared library patch for C++
ihse@33030 251 * 120753-08: SunOS 5.10: Microtasking libraries (libmtsk) patch
ihse@33030 252 * 128228-09: Sun Studio 12 Update 1: Patch for Sun C++ Compiler
ihse@33030 253 * 141860-03: Sun Studio 12 Update 1: Patch for Compiler Common patch for Sun C
ihse@33030 254 C++ F77 F95
ihse@33030 255 * 141861-05: Sun Studio 12 Update 1: Patch for Sun C Compiler
ihse@33030 256 * 142371-01: Sun Studio 12.1 Update 1: Patch for dbx
ihse@33030 257 * 143384-02: Sun Studio 12 Update 1: Patch for debuginfo handling
ihse@33030 258 * 143385-02: Sun Studio 12 Update 1: Patch for Compiler Common patch for Sun C
ihse@33030 259 C++ F77 F95
ihse@33030 260 * 142369-01: Sun Studio 12.1: Patch for Performance Analyzer Tools
ihse@33030 261
ihse@33030 262 The Solaris X86 patch list is:
ihse@33030 263
ihse@33030 264 * 119961-07: SunOS 5.10_x86, x64, Patch for profiling libraries and assembler
ihse@33030 265 * 119964-21: SunOS 5.10_x86: Shared library patch for C++\_x86
ihse@33030 266 * 120754-08: SunOS 5.10_x86: Microtasking libraries (libmtsk) patch
ihse@33030 267 * 141858-06: Sun Studio 12 Update 1_x86: Sun Compiler Common patch for x86
ihse@33030 268 backend
ihse@33030 269 * 128229-09: Sun Studio 12 Update 1_x86: Patch for C++ Compiler
ihse@33030 270 * 142363-05: Sun Studio 12 Update 1_x86: Patch for C Compiler
ihse@33030 271 * 142368-01: Sun Studio 12.1_x86: Patch for Performance Analyzer Tools
ihse@33030 272
ihse@33030 273 Place the `bin` directory in `PATH`.
ihse@33030 274
ihse@33030 275 The Oracle Solaris Studio Express compilers at: [Oracle Solaris Studio Express
ihse@33030 276 Download site](http://www.oracle.com/technetwork/server-storage/solarisstudio/
ihse@33030 277 downloads/index-jsp-142582.html) are also an option, although these compilers
ihse@33030 278 have not been extensively used yet.
ihse@33030 279
ihse@33030 280 <a name="windows"></a>
ihse@33030 281 #### Windows
ihse@33030 282
ihse@33030 283 ##### Windows Unix Toolkit
ihse@33030 284
ihse@33030 285 Building on Windows requires a Unix-like environment, notably a Unix-like
ihse@33030 286 shell. There are several such environments available of which
ihse@33030 287 [Cygwin](http://www.cygwin.com/) and
ihse@33030 288 [MinGW/MSYS](http://www.mingw.org/wiki/MSYS) are currently supported for the
ihse@33030 289 OpenJDK build. One of the differences of these systems from standard Windows
ihse@33030 290 tools is the way they handle Windows path names, particularly path names which
ihse@33030 291 contain spaces, backslashes as path separators and possibly drive letters.
ihse@33030 292 Depending on the use case and the specifics of each environment these path
ihse@33030 293 problems can be solved by a combination of quoting whole paths, translating
ihse@33030 294 backslashes to forward slashes, escaping backslashes with additional
ihse@33030 295 backslashes and translating the path names to their ["8.3"
ihse@33030 296 version](http://en.wikipedia.org/wiki/8.3_filename).
ihse@33030 297
ihse@33030 298 <a name="cygwin"></a>
ihse@33030 299 ###### CYGWIN
ihse@33030 300
ihse@33030 301 CYGWIN is an open source, Linux-like environment which tries to emulate a
ihse@33030 302 complete POSIX layer on Windows. It tries to be smart about path names and can
ihse@33030 303 usually handle all kinds of paths if they are correctly quoted or escaped
ihse@33030 304 although internally it maps drive letters `<drive>:` to a virtual directory
ihse@33030 305 `/cygdrive/<drive>`.
ihse@33030 306
ihse@33030 307 You can always use the `cygpath` utility to map pathnames with spaces or the
ihse@33030 308 backslash character into the `C:/` style of pathname (called 'mixed'), e.g.
ihse@33030 309 `cygpath -s -m "<path>"`.
ihse@33030 310
ihse@33030 311 Note that the use of CYGWIN creates a unique problem with regards to setting
ihse@33030 312 [`PATH`](#path). Normally on Windows the `PATH` variable contains directories
ihse@33030 313 separated with the ";" character (Solaris and Linux use ":"). With CYGWIN, it
ihse@33030 314 uses ":", but that means that paths like "C:/path" cannot be placed in the
ihse@33030 315 CYGWIN version of `PATH` and instead CYGWIN uses something like
ihse@33030 316 `/cygdrive/c/path` which CYGWIN understands, but only CYGWIN understands.
ihse@33030 317
ihse@33030 318 The OpenJDK build requires CYGWIN version 1.7.16 or newer. Information about
ihse@33030 319 CYGWIN can be obtained from the CYGWIN website at
ihse@33030 320 [www.cygwin.com](http://www.cygwin.com).
ihse@33030 321
ihse@33030 322 By default CYGWIN doesn't install all the tools required for building the
ihse@33030 323 OpenJDK. Along with the default installation, you need to install the following
ihse@33030 324 tools.
ihse@33030 325
ihse@33030 326 > <table border="1">
ihse@33030 327 <thead>
ihse@33030 328 <tr>
ihse@33030 329 <td>Binary Name</td>
ihse@33030 330 <td>Category</td>
ihse@33030 331 <td>Package</td>
ihse@33030 332 <td>Description</td>
ihse@33030 333 </tr>
ihse@33030 334 </thead>
ihse@33030 335 <tbody>
ihse@33030 336 <tr>
ihse@33030 337 <td>ar.exe</td>
ihse@33030 338 <td>Devel</td>
ihse@33030 339 <td>binutils</td>
ihse@33030 340 <td>The GNU assembler, linker and binary utilities</td>
ihse@33030 341 </tr>
ihse@33030 342 <tr>
ihse@33030 343 <td>make.exe</td>
ihse@33030 344 <td>Devel</td>
ihse@33030 345 <td>make</td>
ihse@33030 346 <td>The GNU version of the 'make' utility built for CYGWIN</td>
ihse@33030 347 </tr>
ihse@33030 348 <tr>
ihse@33030 349 <td>m4.exe</td>
ihse@33030 350 <td>Interpreters</td>
ihse@33030 351 <td>m4</td>
ihse@33030 352 <td>GNU implementation of the traditional Unix macro processor</td>
ihse@33030 353 </tr>
ihse@33030 354 <tr>
ihse@33030 355 <td>cpio.exe</td>
ihse@33030 356 <td>Utils</td>
ihse@33030 357 <td>cpio</td>
ihse@33030 358 <td>A program to manage archives of files</td>
ihse@33030 359 </tr>
ihse@33030 360 <tr>
ihse@33030 361 <td>gawk.exe</td>
ihse@33030 362 <td>Utils</td>
ihse@33030 363 <td>awk</td>
ihse@33030 364 <td>Pattern-directed scanning and processing language</td>
ihse@33030 365 </tr>
ihse@33030 366 <tr>
ihse@33030 367 <td>file.exe</td>
ihse@33030 368 <td>Utils</td>
ihse@33030 369 <td>file</td>
ihse@33030 370 <td>Determines file type using 'magic' numbers</td>
ihse@33030 371 </tr>
ihse@33030 372 <tr>
ihse@33030 373 <td>zip.exe</td>
ihse@33030 374 <td>Archive</td>
ihse@33030 375 <td>zip</td>
ihse@33030 376 <td>Package and compress (archive) files</td>
ihse@33030 377 </tr>
ihse@33030 378 <tr>
ihse@33030 379 <td>unzip.exe</td>
ihse@33030 380 <td>Archive</td>
ihse@33030 381 <td>unzip</td>
ihse@33030 382 <td>Extract compressed files in a ZIP archive</td>
ihse@33030 383 </tr>
ihse@33030 384 <tr>
ihse@33030 385 <td>free.exe</td>
ihse@33030 386 <td>System</td>
ihse@33030 387 <td>procps</td>
ihse@33030 388 <td>Display amount of free and used memory in the system</td>
ihse@33030 389 </tr>
ihse@33030 390 </tbody>
ihse@33030 391 </table>
ihse@33030 392
ihse@33030 393 Note that the CYGWIN software can conflict with other non-CYGWIN software on
ihse@33030 394 your Windows system. CYGWIN provides a [FAQ](http://cygwin.com/faq/
ihse@33030 395 faq.using.html) for known issues and problems, of particular interest is the
ihse@33030 396 section on [BLODA (applications that interfere with
ihse@33030 397 CYGWIN)](http://cygwin.com/faq/faq.using.html#faq.using.bloda).
ihse@33030 398
ihse@33030 399 <a name="msys"></a>
ihse@33030 400 ###### MinGW/MSYS
ihse@33030 401
ihse@33030 402 MinGW ("Minimalist GNU for Windows") is a collection of free Windows specific
ihse@33030 403 header files and import libraries combined with GNU toolsets that allow one to
ihse@33030 404 produce native Windows programs that do not rely on any 3rd-party C runtime
ihse@33030 405 DLLs. MSYS is a supplement to MinGW which allows building applications and
ihse@33030 406 programs which rely on traditional UNIX tools to be present. Among others this
ihse@33030 407 includes tools like `bash` and `make`. See [MinGW/MSYS](http://www.mingw.org/
ihse@33030 408 wiki/MSYS) for more information.
ihse@33030 409
ihse@33030 410 Like Cygwin, MinGW/MSYS can handle different types of path formats. They are
ihse@33030 411 internally converted to paths with forward slashes and drive letters
ihse@33030 412 `<drive>:` replaced by a virtual directory `/<drive>`. Additionally, MSYS
ihse@33030 413 automatically detects binaries compiled for the MSYS environment and feeds them
ihse@33030 414 with the internal, Unix-style path names. If native Windows applications are
ihse@33030 415 called from within MSYS programs their path arguments are automatically
ihse@33030 416 converted back to Windows style path names with drive letters and backslashes
ihse@33030 417 as path separators. This may cause problems for Windows applications which use
ihse@33030 418 forward slashes as parameter separator (e.g. `cl /nologo /I`) because MSYS may
ihse@33030 419 wrongly [replace such parameters by drive letters](http://mingw.org/wiki/
ihse@33030 420 Posix_path_conversion).
ihse@33030 421
ihse@33030 422 In addition to the tools which will be installed by default, you have to
ihse@33030 423 manually install the `msys-zip` and `msys-unzip` packages. This can be easily
ihse@33030 424 done with the MinGW command line installer:
ihse@33030 425
ihse@33030 426 mingw-get.exe install msys-zip
ihse@33030 427 mingw-get.exe install msys-unzip
ihse@33030 428
ihse@33030 429 <a name="vs2013"></a>
ihse@33030 430 ##### Visual Studio 2013 Compilers
ihse@33030 431
ihse@33030 432 The 32-bit and 64-bit OpenJDK Windows build requires Microsoft Visual Studio
ihse@33030 433 C++ 2013 (VS2013) Professional Edition or Express compiler. The compiler and
ihse@33030 434 other tools are expected to reside in the location defined by the variable
ihse@33030 435 `VS120COMNTOOLS` which is set by the Microsoft Visual Studio installer.
ihse@33030 436
ihse@33030 437 Only the C++ part of VS2013 is needed. Try to let the installation go to the
ihse@33030 438 default install directory. Always reboot your system after installing VS2013.
ihse@33030 439 The system environment variable VS120COMNTOOLS should be set in your
ihse@33030 440 environment.
ihse@33030 441
ihse@33030 442 Make sure that TMP and TEMP are also set in the environment and refer to
ihse@33030 443 Windows paths that exist, like `C:\temp`, not `/tmp`, not `/cygdrive/c/temp`,
ihse@33030 444 and not `C:/temp`. `C:\temp` is just an example, it is assumed that this area
ihse@33030 445 is private to the user, so by default after installs you should see a unique
ihse@33030 446 user path in these variables.
ihse@33030 447
ihse@33030 448 <a name="macosx"></a>
ihse@33030 449 #### Mac OS X
ihse@33030 450
ihse@33030 451 Make sure you get the right XCode version.
ihse@33030 452
ihse@33030 453 *****
ihse@33030 454
ihse@33030 455 <a name="configure"></a>
ihse@33030 456 ### Configure
ihse@33030 457
ihse@33030 458 The basic invocation of the `configure` script looks like:
ihse@33030 459
ihse@33030 460 > **`bash ./configure [options]`**
ihse@33030 461
ihse@33030 462 This will create an output directory containing the "configuration" and setup
ihse@33030 463 an area for the build result. This directory typically looks like:
ihse@33030 464
ihse@33030 465 > **`build/linux-x64-normal-server-release`**
ihse@33030 466
ihse@33030 467 `configure` will try to figure out what system you are running on and where all
ihse@33030 468 necessary build components are. If you have all prerequisites for building
ihse@33030 469 installed, it should find everything. If it fails to detect any component
ihse@33030 470 automatically, it will exit and inform you about the problem. When this
ihse@33030 471 happens, read more below in [the `configure` options](#configureoptions).
ihse@33030 472
ihse@33030 473 Some examples:
ihse@33030 474
ihse@33030 475 > **Windows 32bit build with freetype specified:**
ihse@33030 476 > `bash ./configure --with-freetype=/cygdrive/c/freetype-i586 --with-target-
ihse@33030 477 bits=32`
ihse@33030 478
ihse@33030 479 > **Debug 64bit Build:**
ihse@33030 480 > `bash ./configure --enable-debug --with-target-bits=64`
ihse@33030 481
ihse@33030 482 <a name="configureoptions"></a>
ihse@33030 483 #### Configure Options
ihse@33030 484
ihse@33030 485 Complete details on all the OpenJDK `configure` options can be seen with:
ihse@33030 486
ihse@33030 487 > **`bash ./configure --help=short`**
ihse@33030 488
ihse@33030 489 Use `-help` to see all the `configure` options available. You can generate any
ihse@33030 490 number of different configurations, e.g. debug, release, 32, 64, etc.
ihse@33030 491
ihse@33030 492 Some of the more commonly used `configure` options are:
ihse@33030 493
ihse@33030 494 > **`--enable-debug`**
ihse@33030 495 > set the debug level to fastdebug (this is a shorthand for `--with-debug-
ihse@33030 496 level=fastdebug`)
ihse@33030 497
ihse@33030 498 <a name="alsa"></a>
ihse@33030 499 > **`--with-alsa=`**_path_
ihse@33030 500 > select the location of the Advanced Linux Sound Architecture (ALSA)
ihse@33030 501
ihse@33030 502 > Version 0.9.1 or newer of the ALSA files are required for building the
ihse@33030 503 OpenJDK on Linux. These Linux files are usually available from an "alsa" of
ihse@33030 504 "libasound" development package, and it's highly recommended that you try
ihse@33030 505 and use the package provided by the particular version of Linux that you are
ihse@33030 506 using.
ihse@33030 507
ihse@33030 508 > **`--with-boot-jdk=`**_path_
ihse@33030 509 > select the [Bootstrap JDK](#bootjdk)
ihse@33030 510
ihse@33030 511 > **`--with-boot-jdk-jvmargs=`**"_args_"
ihse@33030 512 > provide the JVM options to be used to run the [Bootstrap JDK](#bootjdk)
ihse@33030 513
ihse@33030 514 > **`--with-cacerts=`**_path_
ihse@33030 515 > select the path to the cacerts file.
ihse@33030 516
ihse@33030 517 > See [Certificate Authority on Wikipedia](http://en.wikipedia.org/wiki/
ihse@33030 518 Certificate_Authority) for a better understanding of the Certificate
ihse@33030 519 Authority (CA). A certificates file named "cacerts" represents a system-wide
ihse@33030 520 keystore with CA certificates. In JDK and JRE binary bundles, the "cacerts"
ihse@33030 521 file contains root CA certificates from several public CAs (e.g., VeriSign,
ihse@33030 522 Thawte, and Baltimore). The source contain a cacerts file without CA root
ihse@33030 523 certificates. Formal JDK builders will need to secure permission from each
ihse@33030 524 public CA and include the certificates into their own custom cacerts file.
ihse@33030 525 Failure to provide a populated cacerts file will result in verification
ihse@33030 526 errors of a certificate chain during runtime. By default an empty cacerts
ihse@33030 527 file is provided and that should be fine for most JDK developers.
ihse@33030 528
ihse@33030 529 <a name="cups"></a>
ihse@33030 530 > **`--with-cups=`**_path_
ihse@33030 531 > select the CUPS install location
ihse@33030 532
ihse@33030 533 > The Common UNIX Printing System (CUPS) Headers are required for building the
ihse@33030 534 OpenJDK on Solaris and Linux. The Solaris header files can be obtained by
ihse@33030 535 installing the package **SFWcups** from the Solaris Software Companion
ihse@33030 536 CD/DVD, these often will be installed into the directory `/opt/sfw/cups`.
ihse@33030 537
ihse@33030 538 > The CUPS header files can always be downloaded from
ihse@33030 539 [www.cups.org](http://www.cups.org).
ihse@33030 540
ihse@33030 541 > **`--with-cups-include=`**_path_
ihse@33030 542 > select the CUPS include directory location
ihse@33030 543
ihse@33030 544 > **`--with-debug-level=`**_level_
ihse@33030 545 > select the debug information level of release, fastdebug, or slowdebug
ihse@33030 546
ihse@33030 547 > **`--with-dev-kit=`**_path_
ihse@33030 548 > select location of the compiler install or developer install location
ihse@33030 549
ihse@33030 550 <a name="freetype"></a>
ihse@33030 551 > **`--with-freetype=`**_path_
ihse@33030 552 > select the freetype files to use.
ihse@33030 553
ihse@33030 554 > Expecting the freetype libraries under `lib/` and the headers under
ihse@33030 555 `include/`.
ihse@33030 556
ihse@33030 557 > Version 2.3 or newer of FreeType is required. On Unix systems required files
ihse@33030 558 can be available as part of your distribution (while you still may need to
ihse@33030 559 upgrade them). Note that you need development version of package that
ihse@33030 560 includes both the FreeType library and header files.
ihse@33030 561
ihse@33030 562 > You can always download latest FreeType version from the [FreeType
ihse@33030 563 website](http://www.freetype.org). Building the freetype 2 libraries from
ihse@33030 564 scratch is also possible, however on Windows refer to the [Windows FreeType
ihse@33030 565 DLL build instructions](http://freetype.freedesktop.org/wiki/FreeType_DLL).
ihse@33030 566
ihse@33030 567 > Note that by default FreeType is built with byte code hinting support
ihse@33030 568 disabled due to licensing restrictions. In this case, text appearance and
ihse@33030 569 metrics are expected to differ from Sun's official JDK build. See the
ihse@33030 570 [SourceForge FreeType2 Home Page](http://freetype.sourceforge.net/freetype2)
ihse@33030 571 for more information.
ihse@33030 572
ihse@33030 573 > **`--with-import-hotspot=`**_path_
ihse@33030 574 > select the location to find hotspot binaries from a previous build to avoid
ihse@33030 575 building hotspot
ihse@33030 576
ihse@33030 577 > **`--with-target-bits=`**_arg_
ihse@33030 578 > select 32 or 64 bit build
ihse@33030 579
ihse@33030 580 > **`--with-jvm-variants=`**_variants_
ihse@33030 581 > select the JVM variants to build from, comma separated list that can
ihse@33030 582 include: server, client, kernel, zero and zeroshark
ihse@33030 583
ihse@33030 584 > **`--with-memory-size=`**_size_
ihse@33030 585 > select the RAM size that GNU make will think this system has
ihse@33030 586
ihse@33030 587 > **`--with-msvcr-dll=`**_path_
ihse@33030 588 > select the `msvcr100.dll` file to include in the Windows builds (C/C++
ihse@33030 589 runtime library for Visual Studio).
ihse@33030 590
ihse@33030 591 > This is usually picked up automatically from the redist directories of
ihse@33030 592 Visual Studio 2013.
ihse@33030 593
ihse@33030 594 > **`--with-num-cores=`**_cores_
ihse@33030 595 > select the number of cores to use (processor count or CPU count)
ihse@33030 596
ihse@33030 597 <a name="xrender"></a>
ihse@33030 598 > **`--with-x=`**_path_
ihse@33030 599 > select the location of the X11 and xrender files.
ihse@33030 600
ihse@33030 601 > The XRender Extension Headers are required for building the OpenJDK on
ihse@33030 602 Solaris and Linux. The Linux header files are usually available from a
ihse@33030 603 "Xrender" development package, it's recommended that you try and use the
ihse@33030 604 package provided by the particular distribution of Linux that you are using.
ihse@33030 605 The Solaris XRender header files is included with the other X11 header files
ihse@33030 606 in the package **SFWxwinc** on new enough versions of Solaris and will be
ihse@33030 607 installed in `/usr/X11/include/X11/extensions/Xrender.h` or
ihse@33030 608 `/usr/openwin/share/include/X11/extensions/Xrender.h`
ihse@33030 609
ihse@33030 610 *****
ihse@33030 611
ihse@33030 612 <a name="make"></a>
ihse@33030 613 ### Make
ihse@33030 614
ihse@33030 615 The basic invocation of the `make` utility looks like:
ihse@33030 616
ihse@33030 617 > **`make all`**
ihse@33030 618
ihse@33030 619 This will start the build to the output directory containing the
ihse@33030 620 "configuration" that was created by the `configure` script. Run `make help` for
ihse@33030 621 more information on the available targets.
ihse@33030 622
ihse@33030 623 There are some of the make targets that are of general interest:
ihse@33030 624
ihse@33030 625 > _empty_
ihse@33030 626 > build everything but no images
ihse@33030 627
ihse@33030 628 > **`all`**
ihse@33030 629 > build everything including images
ihse@33030 630
ihse@33030 631 > **`all-conf`**
ihse@33030 632 > build all configurations
ihse@33030 633
ihse@33030 634 > **`images`**
ihse@33030 635 > create complete j2sdk and j2re images
ihse@33030 636
ihse@33030 637 > **`install`**
ihse@33030 638 > install the generated images locally, typically in `/usr/local`
ihse@33030 639
ihse@33030 640 > **`clean`**
ihse@33030 641 > remove all files generated by make, but not those generated by `configure`
ihse@33030 642
ihse@33030 643 > **`dist-clean`**
ihse@33030 644 > remove all files generated by both and `configure` (basically killing the
ihse@33030 645 configuration)
ihse@33030 646
ihse@33030 647 > **`help`**
ihse@33030 648 > give some help on using `make`, including some interesting make targets
ihse@33030 649
ihse@33030 650 *****
ihse@33030 651
ihse@33030 652 <a name="testing"></a>
ihse@33030 653 ## Testing
ihse@33030 654
ihse@33030 655 When the build is completed, you should see the generated binaries and
ihse@33030 656 associated files in the `j2sdk-image` directory in the output directory. In
ihse@33030 657 particular, the `build/*/images/j2sdk-image/bin` directory should contain
ihse@33030 658 executables for the OpenJDK tools and utilities for that configuration. The
ihse@33030 659 testing tool `jtreg` will be needed and can be found at: [the jtreg
ihse@33030 660 site](http://openjdk.java.net/jtreg/). The provided regression tests in the
ihse@33030 661 repositories can be run with the command:
ihse@33030 662
ihse@33030 663 > **``cd test && make PRODUCT_HOME=`pwd`/../build/*/images/j2sdk-image all``**
ihse@33030 664
ihse@33030 665 *****
ihse@33030 666
ihse@33030 667 <a name="hints"></a>
ihse@33030 668 ## Appendix A: Hints and Tips
ihse@33030 669
ihse@33030 670 <a name="faq"></a>
ihse@33030 671 ### FAQ
ihse@33030 672
ihse@33030 673 **Q:** The `generated-configure.sh` file looks horrible! How are you going to
ihse@33030 674 edit it?
ihse@33030 675 **A:** The `generated-configure.sh` file is generated (think "compiled") by the
ihse@33030 676 autoconf tools. The source code is in `configure.ac` and various .m4 files in
ihse@33030 677 common/autoconf, which are much more readable.
ihse@33030 678
ihse@33030 679 **Q:** Why is the `generated-configure.sh` file checked in, if it is
ihse@33030 680 generated?
ihse@33030 681 **A:** If it was not generated, every user would need to have the autoconf
ihse@33030 682 tools installed, and re-generate the `configure` file as the first step. Our
ihse@33030 683 goal is to minimize the work needed to be done by the user to start building
ihse@33030 684 OpenJDK, and to minimize the number of external dependencies required.
ihse@33030 685
ihse@33030 686 **Q:** Do you require a specific version of autoconf for regenerating
ihse@33030 687 `generated-configure.sh`?
ihse@33030 688 **A:** Yes, version 2.69 is required and should be easy enough to aquire on all
ihse@33030 689 supported operating systems. The reason for this is to avoid large spurious
ihse@33030 690 changes in `generated-configure.sh`.
ihse@33030 691
ihse@33030 692 **Q:** How do you regenerate `generated-configure.sh` after making changes to
ihse@33030 693 the input files?
ihse@33030 694 **A:** Regnerating `generated-configure.sh` should always be done using the
ihse@33030 695 script `common/autoconf/autogen.sh` to ensure that the correct files get
ihse@33030 696 updated. This script should also be run after mercurial tries to merge
ihse@33030 697 `generated-configure.sh` as a merge of the generated file is not guaranteed to
ihse@33030 698 be correct.
ihse@33030 699
ihse@33030 700 **Q:** What are the files in `common/makefiles/support/*` for? They look like
ihse@33030 701 gibberish.
ihse@33030 702 **A:** They are a somewhat ugly hack to compensate for command line length
ihse@33030 703 limitations on certain platforms (Windows, Solaris). Due to a combination of
ihse@33030 704 limitations in make and the shell, command lines containing too many files will
ihse@33030 705 not work properly. These helper files are part of an elaborate hack that will
ihse@33030 706 compress the command line in the makefile and then uncompress it safely. We're
ihse@33030 707 not proud of it, but it does fix the problem. If you have any better
ihse@33030 708 suggestions, we're all ears! :-)
ihse@33030 709
ihse@33030 710 **Q:** I want to see the output of the commands that make runs, like in the old
ihse@33030 711 build. How do I do that?
ihse@33030 712 **A:** You specify the `LOG` variable to make. There are several log levels:
ihse@33030 713
ihse@33030 714 * **`warn`** -- Default and very quiet.
ihse@33030 715 * **`info`** -- Shows more progress information than warn.
ihse@33030 716 * **`debug`** -- Echos all command lines and prints all macro calls for
ihse@33030 717 compilation definitions.
ihse@33030 718 * **`trace`** -- Echos all $(shell) command lines as well.
ihse@33030 719
ihse@33030 720 **Q:** When do I have to re-run `configure`?
ihse@33030 721 **A:** Normally you will run `configure` only once for creating a
ihse@33030 722 configuration. You need to re-run configuration only if you want to change any
ihse@33030 723 configuration options, or if you pull down changes to the `configure` script.
ihse@33030 724
ihse@33030 725 **Q:** I have added a new source file. Do I need to modify the makefiles?
ihse@33030 726 **A:** Normally, no. If you want to create e.g. a new native library, you will
ihse@33030 727 need to modify the makefiles. But for normal file additions or removals, no
ihse@33030 728 changes are needed. There are certan exceptions for some native libraries where
ihse@33030 729 the source files are spread over many directories which also contain sources
ihse@33030 730 for other libraries. In these cases it was simply easier to create include
ihse@33030 731 lists rather than excludes.
ihse@33030 732
ihse@33030 733 **Q:** When I run `configure --help`, I see many strange options, like
ihse@33030 734 `--dvidir`. What is this?
ihse@33030 735 **A:** Configure provides a slew of options by default, to all projects that
ihse@33030 736 use autoconf. Most of them are not used in OpenJDK, so you can safely ignore
ihse@33030 737 them. To list only OpenJDK specific features, use `configure --help=short`
ihse@33030 738 instead.
ihse@33030 739
ihse@33030 740 **Q:** `configure` provides OpenJDK-specific features such as `--with-
ihse@33030 741 builddeps-server` that are not described in this document. What about those?
ihse@33030 742 **A:** Try them out if you like! But be aware that most of these are
ihse@33030 743 experimental features. Many of them don't do anything at all at the moment; the
ihse@33030 744 option is just a placeholder. Others depend on pieces of code or infrastructure
ihse@33030 745 that is currently not ready for prime time.
ihse@33030 746
ihse@33030 747 **Q:** How will you make sure you don't break anything?
ihse@33030 748 **A:** We have a script that compares the result of the new build system with
ihse@33030 749 the result of the old. For most part, we aim for (and achieve) byte-by-byte
ihse@33030 750 identical output. There are however technical issues with e.g. native binaries,
ihse@33030 751 which might differ in a byte-by-byte comparison, even when building twice with
ihse@33030 752 the old build system. For these, we compare relevant aspects (e.g. the symbol
ihse@33030 753 table and file size). Note that we still don't have 100% equivalence, but we're
ihse@33030 754 close.
ihse@33030 755
ihse@33030 756 **Q:** I noticed this thing X in the build that looks very broken by design.
ihse@33030 757 Why don't you fix it?
ihse@33030 758 **A:** Our goal is to produce a build output that is as close as technically
ihse@33030 759 possible to the old build output. If things were weird in the old build, they
ihse@33030 760 will be weird in the new build. Often, things were weird before due to
ihse@33030 761 obscurity, but in the new build system the weird stuff comes up to the surface.
ihse@33030 762 The plan is to attack these things at a later stage, after the new build system
ihse@33030 763 is established.
ihse@33030 764
ihse@33030 765 **Q:** The code in the new build system is not that well-structured. Will you
ihse@33030 766 fix this?
ihse@33030 767 **A:** Yes! The new build system has grown bit by bit as we converted the old
ihse@33030 768 system. When all of the old build system is converted, we can take a step back
ihse@33030 769 and clean up the structure of the new build system. Some of this we plan to do
ihse@33030 770 before replacing the old build system and some will need to wait until after.
ihse@33030 771
ihse@33030 772 **Q:** Is anything able to use the results of the new build's default make
ihse@33030 773 target?
ihse@33030 774 **A:** Yes, this is the minimal (or roughly minimal) set of compiled output
ihse@33030 775 needed for a developer to actually execute the newly built JDK. The idea is
ihse@33030 776 that in an incremental development fashion, when doing a normal make, you
ihse@33030 777 should only spend time recompiling what's changed (making it purely
ihse@33030 778 incremental) and only do the work that's needed to actually run and test your
ihse@33030 779 code. The packaging stuff that is part of the `images` target is not needed for
ihse@33030 780 a normal developer who wants to test his new code. Even if it's quite fast,
ihse@33030 781 it's still unnecessary. We're targeting sub-second incremental rebuilds! ;-)
ihse@33030 782 (Or, well, at least single-digit seconds...)
ihse@33030 783
ihse@33030 784 **Q:** I usually set a specific environment variable when building, but I can't
ihse@33030 785 find the equivalent in the new build. What should I do?
ihse@33030 786 **A:** It might very well be that we have neglected to add support for an
ihse@33030 787 option that was actually used from outside the build system. Email us and we
ihse@33030 788 will add support for it!
ihse@33030 789
ihse@33030 790 <a name="performance"></a>
ihse@33030 791 ### Build Performance Tips
ihse@33030 792
ihse@33030 793 Building OpenJDK requires a lot of horsepower. Some of the build tools can be
ihse@33030 794 adjusted to utilize more or less of resources such as parallel threads and
ihse@33030 795 memory. The `configure` script analyzes your system and selects reasonable
ihse@33030 796 values for such options based on your hardware. If you encounter resource
ihse@33030 797 problems, such as out of memory conditions, you can modify the detected values
ihse@33030 798 with:
ihse@33030 799
ihse@33030 800 * **`--with-num-cores`** -- number of cores in the build system, e.g.
ihse@33030 801 `--with-num-cores=8`
ihse@33030 802 * **`--with-memory-size`** -- memory (in MB) available in the build system,
ihse@33030 803 e.g. `--with-memory-size=1024`
ihse@33030 804
ihse@33030 805 It might also be necessary to specify the JVM arguments passed to the Bootstrap
ihse@33030 806 JDK, using e.g. `--with-boot-jdk-jvmargs="-Xmx8G -enableassertions"`. Doing
ihse@33030 807 this will override the default JVM arguments passed to the Bootstrap JDK.
ihse@33030 808
ihse@33030 809 One of the top goals of the new build system is to improve the build
ihse@33030 810 performance and decrease the time needed to build. This will soon also apply to
ihse@33030 811 the java compilation when the Smart Javac wrapper is fully supported.
ihse@33030 812
ihse@33030 813 At the end of a successful execution of `configure`, you will get a performance
ihse@33030 814 summary, indicating how well the build will perform. Here you will also get
ihse@33030 815 performance hints. If you want to build fast, pay attention to those!
ihse@33030 816
ihse@33030 817 #### Building with ccache
ihse@33030 818
ihse@33030 819 The OpenJDK build supports building with ccache when using gcc or clang. Using
ihse@33030 820 ccache can radically speed up compilation of native code if you often rebuild
ihse@33030 821 the same sources. Your milage may vary however so we recommend evaluating it
ihse@33030 822 for yourself. To enable it, make sure it's on the path and configure with
ihse@33030 823 `--enable-ccache`.
ihse@33030 824
ihse@33030 825 #### Building on local disk
ihse@33030 826
ihse@33030 827 If you are using network shares, e.g. via NFS, for your source code, make sure
ihse@33030 828 the build directory is situated on local disk. The performance penalty is
ihse@33030 829 extremely high for building on a network share, close to unusable.
ihse@33030 830
ihse@33030 831 #### Building only one JVM
ihse@33030 832
ihse@33030 833 The old build builds multiple JVMs on 32-bit systems (client and server; and on
ihse@33030 834 Windows kernel as well). In the new build we have changed this default to only
ihse@33030 835 build server when it's available. This improves build times for those not
ihse@33030 836 interested in multiple JVMs. To mimic the old behavior on platforms that
ihse@33030 837 support it, use `--with-jvm-variants=client,server`.
ihse@33030 838
ihse@33030 839 #### Selecting the number of cores to build on
ihse@33030 840
ihse@33030 841 By default, `configure` will analyze your machine and run the make process in
ihse@33030 842 parallel with as many threads as you have cores. This behavior can be
ihse@33030 843 overridden, either "permanently" (on a `configure` basis) using
ihse@33030 844 `--with-num-cores=N` or for a single build only (on a make basis), using
ihse@33030 845 `make JOBS=N`.
ihse@33030 846
ihse@33030 847 If you want to make a slower build just this time, to save some CPU power for
ihse@33030 848 other processes, you can run e.g. `make JOBS=2`. This will force the makefiles
ihse@33030 849 to only run 2 parallel processes, or even `make JOBS=1` which will disable
ihse@33030 850 parallelism.
ihse@33030 851
ihse@33030 852 If you want to have it the other way round, namely having slow builds default
ihse@33030 853 and override with fast if you're impatient, you should call `configure` with
ihse@33030 854 `--with-num-cores=2`, making 2 the default. If you want to run with more cores,
ihse@33030 855 run `make JOBS=8`
ihse@33030 856
ihse@33030 857 <a name="troubleshooting"></a>
ihse@33030 858 ### Troubleshooting
ihse@33030 859
ihse@33030 860 #### Solving build problems
ihse@33030 861
ihse@33030 862 If the build fails (and it's not due to a compilation error in a source file
ihse@33030 863 you've changed), the first thing you should do is to re-run the build with more
ihse@33030 864 verbosity. Do this by adding `LOG=debug` to your make command line.
ihse@33030 865
ihse@33030 866 The build log (with both stdout and stderr intermingled, basically the same as
ihse@33030 867 you see on your console) can be found as `build.log` in your build directory.
ihse@33030 868
ihse@33030 869 You can ask for help on build problems with the new build system on either the
ihse@33030 870 [build-dev](http://mail.openjdk.java.net/mailman/listinfo/build-dev) or the
ihse@33030 871 [build-infra-dev](http://mail.openjdk.java.net/mailman/listinfo/build-infra-dev)
ihse@33030 872 mailing lists. Please include the relevant parts of the build log.
ihse@33030 873
ihse@33030 874 A build can fail for any number of reasons. Most failures are a result of
ihse@33030 875 trying to build in an environment in which all the pre-build requirements have
ihse@33030 876 not been met. The first step in troubleshooting a build failure is to recheck
ihse@33030 877 that you have satisfied all the pre-build requirements for your platform.
ihse@33030 878 Scanning the `configure` log is a good first step, making sure that what it
ihse@33030 879 found makes sense for your system. Look for strange error messages or any
ihse@33030 880 difficulties that `configure` had in finding things.
ihse@33030 881
ihse@33030 882 Some of the more common problems with builds are briefly described below, with
ihse@33030 883 suggestions for remedies.
ihse@33030 884
ihse@33030 885 * **Corrupted Bundles on Windows:**
ihse@33030 886 Some virus scanning software has been known to corrupt the downloading of
ihse@33030 887 zip bundles. It may be necessary to disable the 'on access' or 'real time'
ihse@33030 888 virus scanning features to prevent this corruption. This type of 'real time'
ihse@33030 889 virus scanning can also slow down the build process significantly.
ihse@33030 890 Temporarily disabling the feature, or excluding the build output directory
ihse@33030 891 may be necessary to get correct and faster builds.
ihse@33030 892
ihse@33030 893 * **Slow Builds:**
ihse@33030 894 If your build machine seems to be overloaded from too many simultaneous C++
ihse@33030 895 compiles, try setting the `JOBS=1` on the `make` command line. Then try
ihse@33030 896 increasing the count slowly to an acceptable level for your system. Also:
ihse@33030 897
ihse@33030 898 Creating the javadocs can be very slow, if you are running javadoc, consider
ihse@33030 899 skipping that step.
ihse@33030 900
ihse@33030 901 Faster CPUs, more RAM, and a faster DISK usually helps. The VM build tends
ihse@33030 902 to be CPU intensive (many C++ compiles), and the rest of the JDK will often
ihse@33030 903 be disk intensive.
ihse@33030 904
ihse@33030 905 Faster compiles are possible using a tool called
ihse@33030 906 [ccache](http://ccache.samba.org/).
ihse@33030 907
ihse@33030 908 * **File time issues:**
ihse@33030 909 If you see warnings that refer to file time stamps, e.g.
ihse@33030 910
ihse@33030 911 > _Warning message:_ ` File 'xxx' has modification time in the future.`
ihse@33030 912 > _Warning message:_ ` Clock skew detected. Your build may be incomplete.`
ihse@33030 913
ihse@33030 914 These warnings can occur when the clock on the build machine is out of sync
ihse@33030 915 with the timestamps on the source files. Other errors, apparently unrelated
ihse@33030 916 but in fact caused by the clock skew, can occur along with the clock skew
ihse@33030 917 warnings. These secondary errors may tend to obscure the fact that the true
ihse@33030 918 root cause of the problem is an out-of-sync clock.
ihse@33030 919
ihse@33030 920 If you see these warnings, reset the clock on the build machine, run
ihse@33030 921 "`gmake clobber`" or delete the directory containing the build output, and
ihse@33030 922 restart the build from the beginning.
ihse@33030 923
ihse@33030 924 * **Error message: `Trouble writing out table to disk`**
ihse@33030 925 Increase the amount of swap space on your build machine. This could be
ihse@33030 926 caused by overloading the system and it may be necessary to use:
ihse@33030 927
ihse@33030 928 > `make JOBS=1`
ihse@33030 929
ihse@33030 930 to reduce the load on the system.
ihse@33030 931
ihse@33030 932 * **Error Message: `libstdc++ not found`:**
ihse@33030 933 This is caused by a missing libstdc++.a library. This is installed as part
ihse@33030 934 of a specific package (e.g. libstdc++.so.devel.386). By default some 64-bit
ihse@33030 935 Linux versions (e.g. Fedora) only install the 64-bit version of the
ihse@33030 936 libstdc++ package. Various parts of the JDK build require a static link of
ihse@33030 937 the C++ runtime libraries to allow for maximum portability of the built
ihse@33030 938 images.
ihse@33030 939
ihse@33030 940 * **Linux Error Message: `cannot restore segment prot after reloc`**
ihse@33030 941 This is probably an issue with SELinux (See [SELinux on
ihse@33030 942 Wikipedia](http://en.wikipedia.org/wiki/SELinux)). Parts of the VM is built
ihse@33030 943 without the `-fPIC` for performance reasons.
ihse@33030 944
ihse@33030 945 To completely disable SELinux:
ihse@33030 946
ihse@33030 947 1. `$ su root`
ihse@33030 948 2. `# system-config-securitylevel`
ihse@33030 949 3. `In the window that appears, select the SELinux tab`
ihse@33030 950 4. `Disable SELinux`
ihse@33030 951
ihse@33030 952 Alternatively, instead of completely disabling it you could disable just
ihse@33030 953 this one check.
ihse@33030 954
ihse@33030 955 1. Select System->Administration->SELinux Management
ihse@33030 956 2. In the SELinux Management Tool which appears, select "Boolean" from the
ihse@33030 957 menu on the left
ihse@33030 958 3. Expand the "Memory Protection" group
ihse@33030 959 4. Check the first item, labeled "Allow all unconfined executables to use
ihse@33030 960 libraries requiring text relocation ..."
ihse@33030 961
ihse@33030 962 * **Windows Error Messages:**
ihse@33030 963 `*** fatal error - couldn't allocate heap, ... `
ihse@33030 964 `rm fails with "Directory not empty"`
ihse@33030 965 `unzip fails with "cannot create ... Permission denied"`
ihse@33030 966 `unzip fails with "cannot create ... Error 50"`
ihse@33030 967
ihse@33030 968 The CYGWIN software can conflict with other non-CYGWIN software. See the
ihse@33030 969 CYGWIN FAQ section on [BLODA (applications that interfere with
ihse@33030 970 CYGWIN)](http://cygwin.com/faq/faq.using.html#faq.using.bloda).
ihse@33030 971
ihse@33030 972 * **Windows Error Message: `spawn failed`**
ihse@33030 973 Try rebooting the system, or there could be some kind of issue with the disk
ihse@33030 974 or disk partition being used. Sometimes it comes with a "Permission Denied"
ihse@33030 975 message.
ihse@33030 976
ihse@33030 977 *****
ihse@33030 978
ihse@33030 979 <a name="gmake"></a>
ihse@33030 980 ## Appendix B: GNU make
ihse@33030 981
ihse@33030 982 The Makefiles in the OpenJDK are only valid when used with the GNU version of
ihse@33030 983 the utility command `make` (usually called `gmake` on Solaris). A few notes
ihse@33030 984 about using GNU make:
ihse@33030 985
ihse@33030 986 * You need GNU make version 3.81 or newer. On Windows 4.0 or newer is
ihse@33030 987 recommended. If the GNU make utility on your systems is not of a suitable
ihse@33030 988 version, see "[Building GNU make](#buildgmake)".
ihse@33030 989 * Place the location of the GNU make binary in the `PATH`.
ihse@33030 990 * **Solaris:** Do NOT use `/usr/bin/make` on Solaris. If your Solaris system
ihse@33030 991 has the software from the Solaris Developer Companion CD installed, you
ihse@33030 992 should try and use `gmake` which will be located in either the `/usr/bin`,
ihse@33030 993 `/opt/sfw/bin` or `/usr/sfw/bin` directory.
ihse@33030 994 * **Windows:** Make sure you start your build inside a bash shell.
ihse@33030 995 * **Mac OS X:** The XCode "command line tools" must be installed on your Mac.
ihse@33030 996
ihse@33030 997 Information on GNU make, and access to ftp download sites, are available on the
ihse@33030 998 [GNU make web site ](http://www.gnu.org/software/make/make.html). The latest
ihse@33030 999 source to GNU make is available at
ihse@33030 1000 [ftp.gnu.org/pub/gnu/make/](http://ftp.gnu.org/pub/gnu/make/).
ihse@33030 1001
ihse@33030 1002 <a name="buildgmake"></a>
ihse@33030 1003 ### Building GNU make
ihse@33030 1004
ihse@33030 1005 First step is to get the GNU make 3.81 or newer source from
ihse@33030 1006 [ftp.gnu.org/pub/gnu/make/](http://ftp.gnu.org/pub/gnu/make/). Building is a
ihse@33030 1007 little different depending on the OS but is basically done with:
ihse@33030 1008
ihse@33030 1009 bash ./configure
ihse@33030 1010 make
ihse@33030 1011
ihse@33030 1012 *****
ihse@33030 1013
ihse@33030 1014 <a name="buildenvironments"></a>
ihse@33030 1015 ## Appendix C: Build Environments
ihse@33030 1016
ihse@33030 1017 ### Minimum Build Environments
ihse@33030 1018
ihse@33030 1019 This file often describes specific requirements for what we call the "minimum
ihse@33030 1020 build environments" (MBE) for this specific release of the JDK. What is listed
ihse@33030 1021 below is what the Oracle Release Engineering Team will use to build the Oracle
ihse@33030 1022 JDK product. Building with the MBE will hopefully generate the most compatible
ihse@33030 1023 bits that install on, and run correctly on, the most variations of the same
ihse@33030 1024 base OS and hardware architecture. In some cases, these represent what is often
ihse@33030 1025 called the least common denominator, but each Operating System has different
ihse@33030 1026 aspects to it.
ihse@33030 1027
ihse@33030 1028 In all cases, the Bootstrap JDK version minimum is critical, we cannot
ihse@33030 1029 guarantee builds will work with older Bootstrap JDK's. Also in all cases, more
ihse@33030 1030 RAM and more processors is better, the minimums listed below are simply
ihse@33030 1031 recommendations.
ihse@33030 1032
ihse@33030 1033 With Solaris and Mac OS X, the version listed below is the oldest release we
ihse@33030 1034 can guarantee builds and works, and the specific version of the compilers used
ihse@33030 1035 could be critical.
ihse@33030 1036
ihse@33030 1037 With Windows the critical aspect is the Visual Studio compiler used, which due
ihse@33030 1038 to it's runtime, generally dictates what Windows systems can do the builds and
ihse@33030 1039 where the resulting bits can be used.
ihse@33030 1040
ihse@33030 1041 **NOTE: We expect a change here off these older Windows OS releases and to a
ihse@33030 1042 'less older' one, probably Windows 2008R2 X64.**
ihse@33030 1043
ihse@33030 1044 With Linux, it was just a matter of picking a stable distribution that is a
ihse@33030 1045 good representative for Linux in general.
ihse@33030 1046
ihse@33030 1047 **NOTE: We expect a change here from Fedora 9 to something else, but it has not
ihse@33030 1048 been completely determined yet, possibly Ubuntu 12.04 X64, unbiased community
ihse@33030 1049 feedback would be welcome on what a good choice would be here.**
ihse@33030 1050
ihse@33030 1051 It is understood that most developers will NOT be using these specific
ihse@33030 1052 versions, and in fact creating these specific versions may be difficult due to
ihse@33030 1053 the age of some of this software. It is expected that developers are more often
ihse@33030 1054 using the more recent releases and distributions of these operating systems.
ihse@33030 1055
ihse@33030 1056 Compilation problems with newer or different C/C++ compilers is a common
ihse@33030 1057 problem. Similarly, compilation problems related to changes to the
ihse@33030 1058 `/usr/include` or system header files is also a common problem with older,
ihse@33030 1059 newer, or unreleased OS versions. Please report these types of problems as bugs
ihse@33030 1060 so that they can be dealt with accordingly.
ihse@33030 1061
ihse@33030 1062 > <table border="1">
ihse@33030 1063 <thead>
ihse@33030 1064 <tr>
ihse@33030 1065 <th>Base OS and Architecture</th>
ihse@33030 1066 <th>OS</th>
ihse@33030 1067 <th>C/C++ Compiler</th>
ihse@33030 1068 <th>Bootstrap JDK</th>
ihse@33030 1069 <th>Processors</th>
ihse@33030 1070 <th>RAM Minimum</th>
ihse@33030 1071 <th>DISK Needs</th>
ihse@33030 1072 </tr>
ihse@33030 1073 </thead>
ihse@33030 1074 <tbody>
ihse@33030 1075 <tr>
ihse@33030 1076 <td>Linux X86 (32-bit) and X64 (64-bit)</td>
ihse@33030 1077 <td>Oracle Enterprise Linux 6.4</td>
ihse@33030 1078 <td>gcc 4.8.2 </td>
ihse@33030 1079 <td>JDK 8</td>
ihse@33030 1080 <td>2 or more</td>
ihse@33030 1081 <td>1 GB</td>
ihse@33030 1082 <td>6 GB</td>
ihse@33030 1083 </tr>
ihse@33030 1084 <tr>
ihse@33030 1085 <td>Solaris SPARCV9 (64-bit)</td>
ihse@33030 1086 <td>Solaris 10 Update 10</td>
ihse@33030 1087 <td>Studio 12 Update 3 + patches</td>
ihse@33030 1088 <td>JDK 8</td>
ihse@33030 1089 <td>4 or more</td>
ihse@33030 1090 <td>4 GB</td>
ihse@33030 1091 <td>8 GB</td>
ihse@33030 1092 </tr>
ihse@33030 1093 <tr>
ihse@33030 1094 <td>Solaris X64 (64-bit)</td>
ihse@33030 1095 <td>Solaris 10 Update 10</td>
ihse@33030 1096 <td>Studio 12 Update 3 + patches</td>
ihse@33030 1097 <td>JDK 8</td>
ihse@33030 1098 <td>4 or more</td>
ihse@33030 1099 <td>4 GB</td>
ihse@33030 1100 <td>8 GB</td>
ihse@33030 1101 </tr>
ihse@33030 1102 <tr>
ihse@33030 1103 <td>Windows X86 (32-bit)</td>
ihse@33030 1104 <td>Windows Server 2012 R2 x64</td>
ihse@33030 1105 <td>Microsoft Visual Studio C++ 2013 Professional Edition</td>
ihse@33030 1106 <td>JDK 8</td>
ihse@33030 1107 <td>2 or more</td>
ihse@33030 1108 <td>2 GB</td>
ihse@33030 1109 <td>6 GB</td>
ihse@33030 1110 </tr>
ihse@33030 1111 <tr>
ihse@33030 1112 <td>Windows X64 (64-bit)</td>
ihse@33030 1113 <td>Windows Server 2012 R2 x64</td>
ihse@33030 1114 <td>Microsoft Visual Studio C++ 2013 Professional Edition</td>
ihse@33030 1115 <td>JDK 8</td>
ihse@33030 1116 <td>2 or more</td>
ihse@33030 1117 <td>2 GB</td>
ihse@33030 1118 <td>6 GB</td>
ihse@33030 1119 </tr>
ihse@33030 1120 <tr>
ihse@33030 1121 <td>Mac OS X X64 (64-bit)</td>
ihse@33030 1122 <td>Mac OS X 10.9 "Mavericks"</td>
ihse@33030 1123 <td>XCode 5.1.1 or newer</td>
ihse@33030 1124 <td>JDK 8</td>
ihse@33030 1125 <td>2 or more</td>
ihse@33030 1126 <td>4 GB</td>
ihse@33030 1127 <td>6 GB</td>
ihse@33030 1128 </tr>
ihse@33030 1129 </tbody>
ihse@33030 1130 </table>
ihse@33030 1131
ihse@33030 1132 *****
ihse@33030 1133
ihse@33030 1134 <a name="SDBE"></a>
ihse@33030 1135 ### Specific Developer Build Environments
ihse@33030 1136
ihse@33030 1137 We won't be listing all the possible environments, but we will try to provide
ihse@33030 1138 what information we have available to us.
ihse@33030 1139
ihse@33030 1140 **NOTE: The community can help out by updating this part of the document.**
ihse@33030 1141
ihse@33030 1142 #### Fedora
ihse@33030 1143
ihse@33030 1144 After installing the latest [Fedora](http://fedoraproject.org) you need to
ihse@33030 1145 install several build dependencies. The simplest way to do it is to execute the
ihse@33030 1146 following commands as user `root`:
ihse@33030 1147
ihse@33030 1148 yum-builddep java-1.7.0-openjdk
ihse@33030 1149 yum install gcc gcc-c++
ihse@33030 1150
ihse@33030 1151 In addition, it's necessary to set a few environment variables for the build:
ihse@33030 1152
ihse@33030 1153 export LANG=C
ihse@33030 1154 export PATH="/usr/lib/jvm/java-openjdk/bin:${PATH}"
ihse@33030 1155
ihse@33030 1156 #### CentOS 5.5
ihse@33030 1157
ihse@33030 1158 After installing [CentOS 5.5](http://www.centos.org/) you need to make sure you
ihse@33030 1159 have the following Development bundles installed:
ihse@33030 1160
ihse@33030 1161 * Development Libraries
ihse@33030 1162 * Development Tools
ihse@33030 1163 * Java Development
ihse@33030 1164 * X Software Development (Including XFree86-devel)
ihse@33030 1165
ihse@33030 1166 Plus the following packages:
ihse@33030 1167
ihse@33030 1168 * cups devel: Cups Development Package
ihse@33030 1169 * alsa devel: Alsa Development Package
ihse@33030 1170 * Xi devel: libXi.so Development Package
ihse@33030 1171
ihse@33030 1172 The freetype 2.3 packages don't seem to be available, but the freetype 2.3
ihse@33030 1173 sources can be downloaded, built, and installed easily enough from [the
ihse@33030 1174 freetype site](http://downloads.sourceforge.net/freetype). Build and install
ihse@33030 1175 with something like:
ihse@33030 1176
ihse@33030 1177 bash ./configure
ihse@33030 1178 make
ihse@33030 1179 sudo -u root make install
ihse@33030 1180
ihse@33030 1181 Mercurial packages could not be found easily, but a Google search should find
ihse@33030 1182 ones, and they usually include Python if it's needed.
ihse@33030 1183
ihse@33030 1184 #### Debian 5.0 (Lenny)
ihse@33030 1185
ihse@33030 1186 After installing [Debian](http://debian.org) 5 you need to install several
ihse@33030 1187 build dependencies. The simplest way to install the build dependencies is to
ihse@33030 1188 execute the following commands as user `root`:
ihse@33030 1189
ihse@33030 1190 aptitude build-dep openjdk-7
ihse@33030 1191 aptitude install openjdk-7-jdk libmotif-dev
ihse@33030 1192
ihse@33030 1193 In addition, it's necessary to set a few environment variables for the build:
ihse@33030 1194
ihse@33030 1195 export LANG=C
ihse@33030 1196 export PATH="/usr/lib/jvm/java-7-openjdk/bin:${PATH}"
ihse@33030 1197
ihse@33030 1198 #### Ubuntu 12.04
ihse@33030 1199
ihse@33030 1200 After installing [Ubuntu](http://ubuntu.org) 12.04 you need to install several
ihse@33030 1201 build dependencies. The simplest way to do it is to execute the following
ihse@33030 1202 commands:
ihse@33030 1203
ihse@33030 1204 sudo aptitude build-dep openjdk-7
ihse@33030 1205 sudo aptitude install openjdk-7-jdk
ihse@33030 1206
ihse@33030 1207 In addition, it's necessary to set a few environment variables for the build:
ihse@33030 1208
ihse@33030 1209 export LANG=C
ihse@33030 1210 export PATH="/usr/lib/jvm/java-7-openjdk/bin:${PATH}"
ihse@33030 1211
ihse@33030 1212 #### OpenSUSE 11.1
ihse@33030 1213
ihse@33030 1214 After installing [OpenSUSE](http://opensuse.org) 11.1 you need to install
ihse@33030 1215 several build dependencies. The simplest way to install the build dependencies
ihse@33030 1216 is to execute the following commands:
ihse@33030 1217
ihse@33030 1218 sudo zypper source-install -d java-1_7_0-openjdk
ihse@33030 1219 sudo zypper install make
ihse@33030 1220
ihse@33030 1221 In addition, it is necessary to set a few environment variables for the build:
ihse@33030 1222
ihse@33030 1223 export LANG=C
ihse@33030 1224 export PATH="/usr/lib/jvm/java-1.7.0-openjdk/bin:$[PATH}"
ihse@33030 1225
ihse@33030 1226 Finally, you need to unset the `JAVA_HOME` environment variable:
ihse@33030 1227
ihse@33030 1228 export -n JAVA_HOME`
ihse@33030 1229
ihse@33030 1230 #### Mandriva Linux One 2009 Spring
ihse@33030 1231
ihse@33030 1232 After installing [Mandriva](http://mandriva.org) Linux One 2009 Spring you need
ihse@33030 1233 to install several build dependencies. The simplest way to install the build
ihse@33030 1234 dependencies is to execute the following commands as user `root`:
ihse@33030 1235
ihse@33030 1236 urpmi java-1.7.0-openjdk-devel make gcc gcc-c++ freetype-devel zip unzip
ihse@33030 1237 libcups2-devel libxrender1-devel libalsa2-devel libstc++-static-devel
ihse@33030 1238 libxtst6-devel libxi-devel
ihse@33030 1239
ihse@33030 1240 In addition, it is necessary to set a few environment variables for the build:
ihse@33030 1241
ihse@33030 1242 export LANG=C
ihse@33030 1243 export PATH="/usr/lib/jvm/java-1.7.0-openjdk/bin:${PATH}"
ihse@33030 1244
ihse@33030 1245 #### OpenSolaris 2009.06
ihse@33030 1246
ihse@33030 1247 After installing [OpenSolaris](http://opensolaris.org) 2009.06 you need to
ihse@33030 1248 install several build dependencies. The simplest way to install the build
ihse@33030 1249 dependencies is to execute the following commands:
ihse@33030 1250
ihse@33030 1251 pfexec pkg install SUNWgmake SUNWj7dev sunstudioexpress SUNWcups SUNWzip
ihse@33030 1252 SUNWunzip SUNWxwhl SUNWxorg-headers SUNWaudh SUNWfreetype2
ihse@33030 1253
ihse@33030 1254 In addition, it is necessary to set a few environment variables for the build:
ihse@33030 1255
ihse@33030 1256 export LANG=C
ihse@33030 1257 export PATH="/opt/SunStudioExpress/bin:${PATH}"
ihse@33030 1258
ihse@33030 1259 *****
ihse@33030 1260
ihse@33030 1261 End of the OpenJDK build README document.
ihse@33030 1262
ihse@33030 1263 Please come again!
© 2007, Oracle and/or its affiliates
Terms of Use · Privacy · Trademarks