From bc1d8d54074b6c5a7c9e93b01513e434e46f2f51 Mon Sep 17 00:00:00 2001 From: Yuri Nesterenko Date: Thu, 22 Apr 2021 08:59:03 +0000 Subject: [PATCH] 8251549: Update docs on building for Git Reviewed-by: dcherepanov Backport-of: 042734cc5b17302a8f2ecdf577511bd6d5ec5e22 --- doc/building.html | 52 +++++++++------------------- doc/building.md | 87 +++++++++++++++++------------------------------ 2 files changed, 47 insertions(+), 92 deletions(-) diff --git a/doc/building.html b/doc/building.html index e5000a34ed1..235d8c442b1 100644 --- a/doc/building.html +++ b/doc/building.html @@ -99,12 +99,10 @@

Building the JDK

  • Getting Help
  • Hints and Suggestions for Advanced Users
  • Understanding the Build System

    TL;DR (Instructions for the Impatient)

    -

    If you are eager to try out building the JDK, these simple steps works most of the time. They assume that you have installed Mercurial (and Cygwin if running on Windows) and cloned the top-level JDK repository that you want to build.

    +

    If you are eager to try out building the JDK, these simple steps works most of the time. They assume that you have installed Git (and Cygwin if running on Windows) and cloned the top-level JDK repository that you want to build.

    1. Get the complete source code:
      -hg clone http://hg.openjdk.java.net/jdk/jdk

    2. +git clone https://git.openjdk.java.net/jdk/

    3. Run configure:
      bash configure

      If configure fails due to missing dependencies (to either the toolchain, build tools, external libraries or the boot JDK), most of the time it prints a suggestion on how to resolve the situation on your platform. Follow the instructions, and try running bash configure again.

    4. @@ -137,8 +135,8 @@

      Introduction

      The JDK is a complex software project. Building it requires a certain amount of technical expertise, a fair number of dependencies on external software, and reasonably powerful hardware.

      If you just want to use the JDK and not build it yourself, this document is not for you. See for instance OpenJDK installation for some methods of installing a prebuilt JDK.

      Getting the Source Code

      -

      Make sure you are getting the correct version. As of JDK 10, the source is no longer split into separate repositories so you only need to clone one single repository. At the OpenJDK Mercurial server you can see a list of all available repositories. If you want to build an older version, e.g. JDK 8, it is recommended that you get the jdk8u forest, which contains incremental updates, instead of the jdk8 forest, which was frozen at JDK 8 GA.

      -

      If you are new to Mercurial, a good place to start is the Mercurial Beginner's Guide. The rest of this document assumes a working knowledge of Mercurial.

      +

      Make sure you are getting the correct version. As of JDK 10, the source is no longer split into separate repositories so you only need to clone one single repository. At the OpenJDK Git site you can see a list of all available repositories. If you want to build an older version, e.g. JDK 11, it is recommended that you get the jdk11u repo, which contains incremental updates, instead of the jdk11 repo, which was frozen at JDK 11 GA.

      +

      If you are new to Git, a good place to start is the book Pro Git. The rest of this document assumes a working knowledge of Git.

      Special Considerations

      For a smooth building experience, it is recommended that you follow these rules on where and how to check out the source code.

        @@ -149,7 +147,11 @@

        Special Considerations

        • Create the directory that is going to contain the top directory of the JDK clone by using the mkdir command in the Cygwin bash shell. That is, do not create it using Windows Explorer. This will ensure that it will have proper Cygwin attributes, and that it's children will inherit those attributes.

        • Do not put the JDK clone in a path under your Cygwin home directory. This is especially important if your user name contains spaces and/or mixed upper and lower case letters.

        • -
        • Clone the JDK repository using the Cygwin command line hg client as instructed in this document. That is, do not use another Mercurial client such as TortoiseHg.

        • +
        • You need to install a git client. You have two choices, Cygwin git or Git for Windows. Unfortunately there are pros and cons with each choice.

          +
            +
          • The Cygwin git client has no line ending issues and understands Cygwin paths (which are used throughout the JDK build system). However, it does not currently work well with the Skara CLI tooling. Please see the Skara wiki on Git clients for up-to-date information about the Skara git client support.

          • +
          • The Git for Windows client has issues with line endings, and do not understand Cygwin paths. It does work well with the Skara CLI tooling, however. To alleviate the line ending problems, make sure you set core.autocrlf to false (this is asked during installation).

          • +

        Failure to follow this procedure might result in hard-to-debug build problems.

      @@ -202,7 +204,7 @@

      Windows

      Windows XP is not a supported platform, but all newer Windows should be able to build the JDK.

      On Windows, it is important that you pay attention to the instructions in the Special Considerations.

      Windows is the only non-POSIX OS supported by the JDK, and as such, requires some extra care. A POSIX support layer is required to build on Windows. Currently, the only supported such layers are Cygwin and Windows Subsystem for Linux (WSL). (Msys is no longer supported due to a too old bash; msys2 would likely be possible to support in a future version but that would require effort to implement.)

      -

      Internally in the build system, all paths are represented as Unix-style paths, e.g. /cygdrive/c/hg/jdk9/Makefile rather than C:\hg\jdk9\Makefile. This rule also applies to input to the build system, e.g. in arguments to configure. So, use --with-msvcr-dll=/cygdrive/c/msvcr100.dll rather than --with-msvcr-dll=c:\msvcr100.dll. For details on this conversion, see the section on Fixpath.

      +

      Internally in the build system, all paths are represented as Unix-style paths, e.g. /cygdrive/c/git/jdk/Makefile rather than C:\git\jdk\Makefile. This rule also applies to input to the build system, e.g. in arguments to configure. So, use --with-msvcr-dll=/cygdrive/c/msvcr100.dll rather than --with-msvcr-dll=c:\msvcr100.dll. For details on this conversion, see the section on Fixpath.

      Cygwin

      A functioning Cygwin environment is required for building the JDK on Windows. If you have a 64-bit OS, we strongly recommend using the 64-bit version of Cygwin.

      Note: Cygwin has a model of continuously updating all packages without any easy way to install or revert to a specific version of a package. This means that whenever you add or update a package in Cygwin, you might (inadvertently) update tools that are used by the JDK build process, and that can cause unexpected build problems.

      @@ -572,7 +574,6 @@

      Advanced Make Control Variables

    5. CONF_CHECK
    6. COMPARE_BUILD
    7. JDK_FILTER
    8. -
    9. SPEC_FILTER
    10. Running Tests

      Most of the JDK tests are using the JTReg test framework. Make sure that your configuration knows where to find your installation of JTReg. If this is not picked up automatically, use the --with-jtreg=<path to jtreg home> option to point to the JTReg framework. Note that this option should point to the JTReg home, i.e. the top directory, containing lib/jtreg.jar etc.

      @@ -814,14 +815,14 @@

      Build Failure Summary

      === Output from failing command(s) repeated here === * For target hotspot_variant-server_libjvm_objs_psMemoryPool.o: -/localhome/hg/jdk9-sandbox/hotspot/src/share/vm/services/psMemoryPool.cpp:1:1: error: 'failhere' does not name a type +/localhome/git/jdk-sandbox/hotspot/src/share/vm/services/psMemoryPool.cpp:1:1: error: 'failhere' does not name a type ... (rest of output omitted) -* All command lines available in /localhome/hg/jdk9-sandbox/build/linux-x64/make-support/failure-logs. +* All command lines available in /localhome/git/jdk-sandbox/build/linux-x64/make-support/failure-logs. === End of repeated output === === Make failed targets repeated here === -lib/CompileJvm.gmk:207: recipe for target '/localhome/hg/jdk9-sandbox/build/linux-x64/hotspot/variant-server/libjvm/objs/psMemoryPool.o' failed +lib/CompileJvm.gmk:207: recipe for target '/localhome/git/jdk-sandbox/build/linux-x64/hotspot/variant-server/libjvm/objs/psMemoryPool.o' failed make/Main.gmk:263: recipe for target 'hotspot-server-libs' failed === End of repeated output === @@ -848,7 +849,7 @@

      Problems with Incremental RebuildsHere are a suggested list of things to try if you are having unexpected build problems. Each step requires more time than the one before, so try them in order. Most issues will be solved at step 1 or 2.

      1. Make sure your repository is up-to-date

        -

        Run hg pull -u to make sure you have the latest changes.

      2. +

        Run git pull origin master to make sure you have the latest changes.

      3. Clean build results

        The simplest way to fix incremental rebuild issues is to run make clean. This will remove all build results, but not the configuration or any build system support artifacts. In most cases, this will solve build errors resulting from incremental build mismatches.

      4. Completely clean the build directory.

        @@ -857,8 +858,8 @@

        Problems with Incremental Rebuilds

      5. -
      6. Re-clone the Mercurial repository

        -

        Sometimes the Mercurial repository gets in a state that causes the product to be un-buildable. In such a case, the simplest solution is often the "sledgehammer approach": delete the entire repository, and re-clone it. If you have local changes, save them first to a different location using hg export.

      7. +
      8. Re-clone the Git repository

        +

        Sometimes the Git repository gets in a state that causes the product to be un-buildable. In such a case, the simplest solution is often the "sledgehammer approach": delete the entire repository, and re-clone it. If you have local changes, save them first to a different location using git format-patch.

      Specific Build Issues

      Clock Skew

      @@ -880,19 +881,6 @@

      Getting Help

      If none of the suggestions in this document helps you, or if you find what you believe is a bug in the build system, please contact the Build Group by sending a mail to build-dev@openjdk.java.net. Please include the relevant parts of the configure and/or build log.

      If you need general help or advice about developing for the JDK, you can also contact the Adoption Group. See the section on Contributing to OpenJDK for more information.

      Hints and Suggestions for Advanced Users

      -

      Setting Up a Repository for Pushing Changes (defpath)

      -

      To help you prepare a proper push path for a Mercurial repository, there exists a useful tool known as defpath. It will help you setup a proper push path for pushing changes to the JDK.

      -

      Install the extension by cloning http://hg.openjdk.java.net/code-tools/defpath and updating your .hgrc file. Here's one way to do this:

      -
      cd ~
      -mkdir hg-ext
      -cd hg-ext
      -hg clone http://hg.openjdk.java.net/code-tools/defpath
      -cat << EOT >> ~/.hgrc
      -[extensions]
      -defpath=~/hg-ext/defpath/defpath.py
      -EOT
      -

      You can now setup a proper push path using:

      -
      hg defpath -d -u <your OpenJDK username>

      Bash Completion

      The configure and make commands tries to play nice with bash command-line completion (using <tab> or <tab><tab>). To use this functionality, make sure you enable completion in your ~/.bashrc (see instructions for bash in your operating system).

      Make completion will work out of the box, and will complete valid make targets. For instance, typing make jdk-i<tab> will complete to make jdk-image.

      @@ -946,14 +934,6 @@

      Skipping the Dependency Check

      Rebuilding Part of java.base (JDK_FILTER)

      If you are modifying files in java.base, which is the by far largest module in the JDK, then you need to rebuild all those files whenever a single file has changed. (This inefficiency will hopefully be addressed in JDK 10.)

      As a hack, you can use the make control variable JDK_FILTER to specify a pattern that will be used to limit the set of files being recompiled. For instance, make java.base JDK_FILTER=javax/crypto (or, to combine methods, make java.base-java-only JDK_FILTER=javax/crypto) will limit the compilation to files in the javax.crypto package.

      -

      Learn About Mercurial

      -

      To become an efficient JDK developer, it is recommended that you invest in learning Mercurial properly. Here are some links that can get you started:

      -

      Understanding the Build System

      This section will give you a more technical description on the details of the build system.

      Configurations

      diff --git a/doc/building.md b/doc/building.md index ceaeb730c84..40a10185894 100644 --- a/doc/building.md +++ b/doc/building.md @@ -3,11 +3,11 @@ ## TL;DR (Instructions for the Impatient) If you are eager to try out building the JDK, these simple steps works most of -the time. They assume that you have installed Mercurial (and Cygwin if running +the time. They assume that you have installed Git (and Cygwin if running on Windows) and cloned the top-level JDK repository that you want to build. 1. [Get the complete source code](#getting-the-source-code): \ - `hg clone http://hg.openjdk.java.net/jdk/jdk` + `git clone https://git.openjdk.java.net/jdk/` 2. [Run configure](#running-configure): \ `bash configure` @@ -47,14 +47,14 @@ JDK. Make sure you are getting the correct version. As of JDK 10, the source is no longer split into separate repositories so you only need to clone one single -repository. At the [OpenJDK Mercurial server](http://hg.openjdk.java.net/) you +repository. At the [OpenJDK Git site](https://git.openjdk.java.net/) you can see a list of all available repositories. If you want to build an older version, -e.g. JDK 8, it is recommended that you get the `jdk8u` forest, which contains -incremental updates, instead of the `jdk8` forest, which was frozen at JDK 8 GA. +e.g. JDK 11, it is recommended that you get the `jdk11u` repo, which contains +incremental updates, instead of the `jdk11` repo, which was frozen at JDK 11 GA. -If you are new to Mercurial, a good place to start is the [Mercurial Beginner's -Guide](http://www.mercurial-scm.org/guide). The rest of this document assumes a -working knowledge of Mercurial. +If you are new to Git, a good place to start is the book [Pro +Git](https://git-scm.com/book/en/v2). The rest of this document +assumes a working knowledge of Git. ### Special Considerations @@ -89,9 +89,21 @@ on where and how to check out the source code. directory. This is especially important if your user name contains spaces and/or mixed upper and lower case letters. - * Clone the JDK repository using the Cygwin command line `hg` client - as instructed in this document. That is, do *not* use another Mercurial - client such as TortoiseHg. + * You need to install a git client. You have two choices, Cygwin git or + Git for Windows. Unfortunately there are pros and cons with each choice. + + * The Cygwin `git` client has no line ending issues and understands + Cygwin paths (which are used throughout the JDK build system). + However, it does not currently work well with the Skara CLI tooling. + Please see the [Skara wiki on Git clients]( + https://wiki.openjdk.java.net/display/SKARA/Skara#Skara-Git) for + up-to-date information about the Skara git client support. + + * The [Git for Windows](https://gitforwindows.org) client has issues + with line endings, and do not understand Cygwin paths. It does work + well with the Skara CLI tooling, however. To alleviate the line ending + problems, make sure you set `core.autocrlf` to `false` (this is asked + during installation). Failure to follow this procedure might result in hard-to-debug build problems. @@ -180,7 +192,7 @@ likely be possible to support in a future version but that would require effort to implement.) Internally in the build system, all paths are represented as Unix-style paths, -e.g. `/cygdrive/c/hg/jdk9/Makefile` rather than `C:\hg\jdk9\Makefile`. This +e.g. `/cygdrive/c/git/jdk/Makefile` rather than `C:\git\jdk\Makefile`. This rule also applies to input to the build system, e.g. in arguments to `configure`. So, use `--with-msvcr-dll=/cygdrive/c/msvcr100.dll` rather than `--with-msvcr-dll=c:\msvcr100.dll`. For details on this conversion, see the section @@ -1302,14 +1314,14 @@ ERROR: Build failed for target 'hotspot' in configuration 'linux-x64' (exit code === Output from failing command(s) repeated here === * For target hotspot_variant-server_libjvm_objs_psMemoryPool.o: -/localhome/hg/jdk9-sandbox/hotspot/src/share/vm/services/psMemoryPool.cpp:1:1: error: 'failhere' does not name a type +/localhome/git/jdk-sandbox/hotspot/src/share/vm/services/psMemoryPool.cpp:1:1: error: 'failhere' does not name a type ... (rest of output omitted) -* All command lines available in /localhome/hg/jdk9-sandbox/build/linux-x64/make-support/failure-logs. +* All command lines available in /localhome/git/jdk-sandbox/build/linux-x64/make-support/failure-logs. === End of repeated output === === Make failed targets repeated here === -lib/CompileJvm.gmk:207: recipe for target '/localhome/hg/jdk9-sandbox/build/linux-x64/hotspot/variant-server/libjvm/objs/psMemoryPool.o' failed +lib/CompileJvm.gmk:207: recipe for target '/localhome/git/jdk-sandbox/build/linux-x64/hotspot/variant-server/libjvm/objs/psMemoryPool.o' failed make/Main.gmk:263: recipe for target 'hotspot-server-libs' failed === End of repeated output === @@ -1407,7 +1419,7 @@ order. Most issues will be solved at step 1 or 2. 1. Make sure your repository is up-to-date - Run `hg pull -u` to make sure you have the latest changes. + Run `git pull origin master` to make sure you have the latest changes. 2. Clean build results @@ -1432,13 +1444,13 @@ order. Most issues will be solved at step 1 or 2. make ``` - 4. Re-clone the Mercurial repository + 4. Re-clone the Git repository - Sometimes the Mercurial repository gets in a state that causes the product + Sometimes the Git repository gets in a state that causes the product to be un-buildable. In such a case, the simplest solution is often the "sledgehammer approach": delete the entire repository, and re-clone it. If you have local changes, save them first to a different location using - `hg export`. + `git format-patch`. ### Specific Build Issues @@ -1489,33 +1501,6 @@ contact the Adoption Group. See the section on [Contributing to OpenJDK]( ## Hints and Suggestions for Advanced Users -### Setting Up a Repository for Pushing Changes (defpath) - -To help you prepare a proper push path for a Mercurial repository, there exists -a useful tool known as [defpath]( -http://openjdk.java.net/projects/code-tools/defpath). It will help you setup a -proper push path for pushing changes to the JDK. - -Install the extension by cloning -`http://hg.openjdk.java.net/code-tools/defpath` and updating your `.hgrc` file. -Here's one way to do this: - -``` -cd ~ -mkdir hg-ext -cd hg-ext -hg clone http://hg.openjdk.java.net/code-tools/defpath -cat << EOT >> ~/.hgrc -[extensions] -defpath=~/hg-ext/defpath/defpath.py -EOT -``` - -You can now setup a proper push path using: -``` -hg defpath -d -u -``` - ### Bash Completion The `configure` and `make` commands tries to play nice with bash command-line @@ -1658,16 +1643,6 @@ instance, `make java.base JDK_FILTER=javax/crypto` (or, to combine methods, `make java.base-java-only JDK_FILTER=javax/crypto`) will limit the compilation to files in the `javax.crypto` package. -### Learn About Mercurial - -To become an efficient JDK developer, it is recommended that you invest in -learning Mercurial properly. Here are some links that can get you started: - - * [Mercurial for git users](http://www.mercurial-scm.org/wiki/GitConcepts) - * [The official Mercurial tutorial](http://www.mercurial-scm.org/wiki/Tutorial) - * [hg init](http://hginit.com/) - * [Mercurial: The Definitive Guide](http://hgbook.red-bean.com/read/) - ## Understanding the Build System This section will give you a more technical description on the details of the