Generate Javadoc (API) info

[xtbe]

Besides the binary build, Javadoc for the corresponding release should also be produced.

After generation it could be:

• hosted online
• made available as an downloadable offline package

[brunoborges]

One thing that we often suffer with Javadoc for Core Java APIs is offline access. Right now, it is only available for download from the Oracle site (OpenJDK does not offer).

Two things that AOJDK could do:

1. Offer Javadoc downloads
2. Offer Docker images for running Javadoc straight from the command-line (e.g. docker run adoptopenjdk:javadoc-11 … then visiting localhost:8080/)

[asbachb]

What's the benefit of having a docker image instead of the well known and used approach of offering a javadoc download?
All major IDEs provide functionalities to use it.

[brunoborges]

So I could simply do this: $ docker run javadoc:8 && open http://localhost:8080/

Instead of this:

1. Download a ZIP
2. Extract a ZIP
3. Navigate to the folder
4. Open index.html in a browser

But sure, solving the delivery of Javadoc download files ZIP from AdoptOpenJDK would be a great step already.

[chat-roux]

Hello,

the preceding person (brunoborges) said 5 months ago, that the javadoc from AdoptOpenJDK (in form of a downloadable file) is not available on internet.

Is that still impossible today (5 months later) ?

Or does another way exist, to get this javadoc file ? Eventually, by generating it by myself ?

Thank you in advance for the answer(s).

[lumpfish]

The AdoptOpenJDK builds appear to run the build target 'make images'. This target does not generate the javadoc.
'make docs' should create the javadoc, 'make all' should both build the jdk and the create the javadoc.
The javadoc is built into a /docs directory alongside /images (jdk8) or in /images/docs (post jdk8).
Once created, the Jenkins pipelines would need to archive the folder for downloading from the AdoptOpenJDK jobs or website.

[chat-roux]

Thank you for your explanation !

So now, I shall do following :

1. Clone the whole project on my local workspace
2. Run the build-target 'make docs'. (and see what happens !)

Best thanks.

[chat-roux]

Hello everyone,

I am seeking for your help !
I processed following actions :

(01.) Clone the repository given above (on my local computer).

(02.) Launch following commands (from ubuntu terminal on my local computer) :

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export JDK11_BOOT_DIR=/usr/lib/jvm/java-11-openjdk-amd64
sudo ./makejdk-any-platform.sh -s ./workspace/src -d ./workspace/target -T MyOpenJDK11.tar.gz jdk11

(03.) Get following log-messages (in the ubuntu terminal) :

Starting ./makejdk-any-platform.sh to configure, build (Adopt)OpenJDK binary
Parsing opt: -s
Possible opt arg: ./workspace/src
Parsing opt: -d
Possible opt arg: ./workspace/target
Parsing opt: -T
Possible opt arg: MyOpenJDK11.tar.gz
Working dir is ./workspace/src
[debug] COPY_MACOSX_FREE_FONT_LIB_FOR_JDK_FLAG=false
[debug] COPY_MACOSX_FREE_FONT_LIB_FOR_JRE_FLAG=false
JDK Image folder name: jdk
JRE Image folder name: jre
Searching for JDK_BOOT_DIR
Guessing JDK_BOOT_DIR: /usr/lib/jvm/java-11-openjdk-amd64
If this is incorrect explicitly configure JDK_BOOT_DIR
Boot dir set to /usr/lib/jvm/java-11-openjdk-amd64
# ============================
# OPENJDK BUILD CONFIGURATION:
# ============================
BUILD_CONFIG[ADOPT_PATCHES]="true"
BUILD_CONFIG[BRANCH]="dev"
BUILD_CONFIG[BUILD_FULL_NAME]="linux-x86_64--server-release"
BUILD_CONFIG[BUILD_VARIANT]="hotspot"
BUILD_CONFIG[CLEAN_DOCKER_BUILD]="false"
BUILD_CONFIG[CLEAN_GIT_REPO]="false"
BUILD_CONFIG[CLEAN_LIBS]="false"
BUILD_CONFIG[CONFIGURE_ARGS_FOR_ANY_PLATFORM]=""
BUILD_CONFIG[CONTAINER_NAME]="openjdk_container"
BUILD_CONFIG[COPY_MACOSX_FREE_FONT_LIB_FOR_JDK_FLAG]="false"
BUILD_CONFIG[COPY_MACOSX_FREE_FONT_LIB_FOR_JRE_FLAG]="false"
BUILD_CONFIG[DEBUG_DOCKER]="false"
BUILD_CONFIG[DISABLE_ADOPT_BRANCH_SAFETY]="false"
BUILD_CONFIG[DOCKER]="docker"
BUILD_CONFIG[DOCKER_FILE_PATH]=""
BUILD_CONFIG[DOCKER_SOURCE_VOLUME_NAME]="openjdk-source-volume-jdk11-hotspot"
BUILD_CONFIG[FREETYPE]="true"
BUILD_CONFIG[FREETYPE_DIRECTORY]=""
BUILD_CONFIG[FREETYPE_FONT_BUILD_TYPE_PARAM]=""
BUILD_CONFIG[FREETYPE_FONT_VERSION]="2.9.1"
BUILD_CONFIG[JDK_BOOT_DIR]="/usr/lib/jvm/java-11-openjdk-amd64"
BUILD_CONFIG[JDK_PATH]="jdk"
BUILD_CONFIG[JRE_PATH]="jre"
BUILD_CONFIG[JVM_VARIANT]="server"
BUILD_CONFIG[KEEP_CONTAINER]="false"
BUILD_CONFIG[MAKE_ARGS_FOR_ANY_PLATFORM]="product-images legacy-jre-image"
BUILD_CONFIG[MAKE_COMMAND_NAME]="make"
BUILD_CONFIG[NUM_PROCESSORS]="1"
BUILD_CONFIG[OPENJDK_BUILD_NUMBER]=""
BUILD_CONFIG[OPENJDK_CORE_VERSION]="jdk11"
BUILD_CONFIG[OPENJDK_FEATURE_NUMBER]="11"
BUILD_CONFIG[OPENJDK_FOREST_NAME]="jdk11"
BUILD_CONFIG[OPENJDK_SOURCE_DIR]="src"
BUILD_CONFIG[OPENJDK_UPDATE_VERSION]=""
BUILD_CONFIG[OS_ARCHITECTURE]="x86_64"
BUILD_CONFIG[OS_KERNEL_NAME]="linux"
BUILD_CONFIG[PATCHES]=""
BUILD_CONFIG[RELEASE]="false"
BUILD_CONFIG[REPOSITORY]="https://github.com/adoptopenjdk/openjdk-jdk11"
BUILD_CONFIG[REUSE_CONTAINER]="true"
BUILD_CONFIG[SHALLOW_CLONE_OPTION]="--depth=1"
BUILD_CONFIG[SIGN]="false"
BUILD_CONFIG[TAG]=""
BUILD_CONFIG[TARGET_DIR]="./workspace/target"
BUILD_CONFIG[TARGET_FILE_NAME]="MyOpenJDK11.tar.gz"
BUILD_CONFIG[TEST_IMAGE_PATH]="test"
BUILD_CONFIG[TMP_CONTAINER_NAME]="openjdk-copy-src"
BUILD_CONFIG[TMP_SPACE_BUILD]="false"
BUILD_CONFIG[USER_SUPPLIED_CONFIGURE_ARGS]=""
BUILD_CONFIG[USER_SUPPLIED_MAKE_ARGS]=""
BUILD_CONFIG[USE_DOCKER]="false"
BUILD_CONFIG[USE_JEP319_CERTS]="false"
BUILD_CONFIG[USE_SSH]="false"
BUILD_CONFIG[WORKING_DIR]="./workspace/src"
BUILD_CONFIG[WORKSPACE_DIR]="/home/aa/Documents/04-SOFTWAR/50-ApplicationDeveloppementTools/_AdoptOpenJDK/workspace"
Unable to find java to run gradle with, set JAVA_HOME, JDK8_BOOT_DIR or JDK11_BOOT_DIR: []
Running gradle with []
To honour the JVM settings for this build a new JVM will be forked. Please consider using the daemon: https://docs.gradle.org/5.2.1/userguide/gradle_daemon.html.
Daemon will be stopped at the end of the build stopping after processing

(04.) My question :

• It seems like the environment variables "JAVA_HOME" and "JDK11_ROOT_DIR" are not found, although I did set them with the correct values just before.
• Did someone still have the same behaviour ?
• How can we explain that ?

I am thankful to all of you for your help.
chat-roux

[chat-roux]

Just a small correction :

I was meaning "JDK11_BOOT_DIR" (I wrote by mistake "JDK11_ROOT_DIR". This is a spelling error !).
But, anyway, the environment variable I exported before was written correctly : "JDK11_BOOT_DIR"

I welcome any help to solve this problem.
(Because this is preventing me from building the open-JDK).
Thank you !
chat-roux

[lumpfish]

I don't think sudo inherits the environment variables - e.g. see https://www.petefreitag.com/item/877.cfm.
I also don't think the sudo is needed at all.

[karianna]

Being discussed at TSC

[chat-roux]

Thank you @karianna for having a look to the problem.
Thank you @lumpfish for this information.

So, for now :
I shall launch the "makejdk-any-platform.sh"-script without "sudo".
I inform you about the result.

chat-roux

[chat-roux]

Hi everyone,

This time, I proceeded as follows :
(01.) Log in, as super-user (from ubuntu terminal) :

sudo su
[sudo] Mot de passe de aa :

This was necessary, in order to prevent that the "makejdk-any-platform.sh"-script gets interrupted with an error-message like "access permission refused on file 'xxxx'".

(02.) Launch following 2 commands (from ubuntu terminal) :

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
./openjdk-build/makejdk-any-platform.sh -J /usr/lib/jvm/java-11-openjdk-amd64 -s src -d target -T MyOpenJDK11.tar.gz jdk11u

(03.) Get the logs (from the ubuntu terminal) :

Starting ./openjdk-build/makejdk-any-platform.sh to configure, build (Adopt)OpenJDK binary
Parsing opt: -J
Possible opt arg: /usr/lib/jvm/java-11-openjdk-amd64
Parsing opt: -s
Possible opt arg: src
Parsing opt: -d
Possible opt arg: target
Parsing opt: -T
Possible opt arg: MyOpenJDK11.tar.gz
Working dir is src
[debug] COPY_MACOSX_FREE_FONT_LIB_FOR_JDK_FLAG=false
[debug] COPY_MACOSX_FREE_FONT_LIB_FOR_JRE_FLAG=false
JDK Image folder name: jdk
JRE Image folder name: jre
Overriding JDK_BOOT_DIR, set to /usr/lib/jvm/java-11-openjdk-amd64
Boot dir set to /usr/lib/jvm/java-11-openjdk-amd64
# ============================
# OPENJDK BUILD CONFIGURATION:
# ============================
BUILD_CONFIG[ADOPT_PATCHES]="true"
BUILD_CONFIG[BRANCH]="dev"
BUILD_CONFIG[BUILD_FULL_NAME]="linux-x86_64--server-release"
BUILD_CONFIG[BUILD_VARIANT]="hotspot"
BUILD_CONFIG[CLEAN_DOCKER_BUILD]="false"
BUILD_CONFIG[CLEAN_GIT_REPO]="false"
BUILD_CONFIG[CLEAN_LIBS]="false"
BUILD_CONFIG[CONFIGURE_ARGS_FOR_ANY_PLATFORM]=""
BUILD_CONFIG[CONTAINER_NAME]="openjdk_container"
BUILD_CONFIG[COPY_MACOSX_FREE_FONT_LIB_FOR_JDK_FLAG]="false"
BUILD_CONFIG[COPY_MACOSX_FREE_FONT_LIB_FOR_JRE_FLAG]="false"
BUILD_CONFIG[DEBUG_DOCKER]="false"
BUILD_CONFIG[DISABLE_ADOPT_BRANCH_SAFETY]="false"
BUILD_CONFIG[DOCKER]="docker"
BUILD_CONFIG[DOCKER_FILE_PATH]=""
BUILD_CONFIG[DOCKER_SOURCE_VOLUME_NAME]="openjdk-source-volume-jdk11u-hotspot"
BUILD_CONFIG[FREETYPE]="true"
BUILD_CONFIG[FREETYPE_DIRECTORY]=""
BUILD_CONFIG[FREETYPE_FONT_BUILD_TYPE_PARAM]=""
BUILD_CONFIG[FREETYPE_FONT_VERSION]="2.9.1"
BUILD_CONFIG[JDK_BOOT_DIR]="/usr/lib/jvm/java-11-openjdk-amd64"
BUILD_CONFIG[JDK_PATH]="jdk"
BUILD_CONFIG[JRE_PATH]="jre"
BUILD_CONFIG[JVM_VARIANT]="server"
BUILD_CONFIG[KEEP_CONTAINER]="false"
BUILD_CONFIG[MAKE_ARGS_FOR_ANY_PLATFORM]="product-images legacy-jre-image"
BUILD_CONFIG[MAKE_COMMAND_NAME]="make"
BUILD_CONFIG[NUM_PROCESSORS]="1"
BUILD_CONFIG[OPENJDK_BUILD_NUMBER]=""
BUILD_CONFIG[OPENJDK_CORE_VERSION]="jdk11"
BUILD_CONFIG[OPENJDK_FEATURE_NUMBER]="11"
BUILD_CONFIG[OPENJDK_FOREST_NAME]="jdk11u"
BUILD_CONFIG[OPENJDK_SOURCE_DIR]="src"
BUILD_CONFIG[OPENJDK_UPDATE_VERSION]=""
BUILD_CONFIG[OS_ARCHITECTURE]="x86_64"
BUILD_CONFIG[OS_KERNEL_NAME]="linux"
BUILD_CONFIG[PATCHES]=""
BUILD_CONFIG[RELEASE]="false"
BUILD_CONFIG[REPOSITORY]="https://github.com/adoptopenjdk/openjdk-jdk11u"
BUILD_CONFIG[REUSE_CONTAINER]="true"
BUILD_CONFIG[SHALLOW_CLONE_OPTION]="--depth=1"
BUILD_CONFIG[SIGN]="false"
BUILD_CONFIG[TAG]=""
BUILD_CONFIG[TARGET_DIR]="target"
BUILD_CONFIG[TARGET_FILE_NAME]="MyOpenJDK11.tar.gz"
BUILD_CONFIG[TEST_IMAGE_PATH]="test"
BUILD_CONFIG[TMP_CONTAINER_NAME]="openjdk-copy-src"
BUILD_CONFIG[TMP_SPACE_BUILD]="false"
BUILD_CONFIG[USER_SUPPLIED_CONFIGURE_ARGS]=""
BUILD_CONFIG[USER_SUPPLIED_MAKE_ARGS]=""
BUILD_CONFIG[USE_DOCKER]="false"
BUILD_CONFIG[USE_JEP319_CERTS]="false"
BUILD_CONFIG[USE_SSH]="false"
BUILD_CONFIG[WORKING_DIR]="src"
BUILD_CONFIG[WORKSPACE_DIR]="/home/aa/Documents/04-SOFTWAR/50-ApplicationDeveloppementTools/_AdoptOpenJDK/workspace"
Running gradle with /usr/lib/jvm/java-11-openjdk-amd64
To honour the JVM settings for this build a new JVM will be forked. Please consider using the daemon: https://docs.gradle.org/5.2.1/userguide/gradle_daemon.html.
Daemon will be stopped at the end of the build stopping after processing

BUILD SUCCESSFUL in 7s
3 actionable tasks: 3 executed
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by org.codehaus.groovy.vmplugin.v7.Java7$1 (file:/home/aa/Documents/04-SOFTWAR/50-ApplicationDeveloppementTools/_AdoptOpenJDK/openjdk-build/pipelines/target/libs/adopt-shared-lib.jar) to constructor java.lang.invoke.MethodHandles$Lookup(java.lang.Class,int)
WARNING: Please consider reporting this to the maintainers of org.codehaus.groovy.vmplugin.v7.Java7$1
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release
11.0.4+11.1.post-Ubuntu-1ubuntu218.04.3
Checking and downloading Alsa dependency
Checking for ALSA
Skipping ALSA download
Checking and download FreeType Font dependency
Checking for freetype at /home/aa/Documents/04-SOFTWAR/50-ApplicationDeveloppementTools/_AdoptOpenJDK/workspace/src
find: ‘/home/aa/Documents/04-SOFTWAR/50-ApplicationDeveloppementTools/_AdoptOpenJDK/workspace/src/installedfreetype/lib’: Aucun fichier ou dossier de ce type
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100 2474k  100 2474k    0     0   781k      0  0:00:03  0:00:03 --:--:-- 1336k
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100   181  100   181    0     0    167      0  0:00:01  0:00:01 --:--:--   167
rm: impossible de supprimer '/tmp/public_key.gpg': Aucun fichier ou dossier de ce type
gpg: en-tête d'armure : Version: GnuPG v2 gpg: Signature faite le mer. 02 mai 2018 10:42:26 CEST gpg: avec la clef DSA C1A60EACE707FDA5 gpg: /root/.gnupg/trustdb.gpg : base de confiance créée gpg: utilisation du modèle de confiance pgp gpg: Bonne signature de « Werner Lemberg <[email protected]> » [inconnu] gpg: Attention : cette clef n'est pas certifiée avec une signature de confiance. gpg: Rien n'indique que la signature appartient à son propriétaire. Empreinte de clef principale : 58E0 C111 E39F 5408 C5D3 EC76 C1A6 0EAC E707 FDA5 gpg: signature binaire, algorithme de hachage SHA1, algorithme de clef dsa1024
Failed to verify signature of freetype.tar.gz
expected "58E0 C111 E39F 5408 C5D3 EC76 C1A6 0EAC E707 FDA5" got ""

(04.) Conclusion :
The build of the open-jdk failed.
But the execution of the "makejdk-any-platform.sh"-script went a few steps further.
(The step of finding the "JAVA_HOME"-variable was completed successfully.)
And it was interrupted by a GPG-problem ("Failed to verify signature of freetype.tar.gz").

I wish, this posted message could help those who try to build the open-jdk.
I wish good luck to everyone. (And sorry for the terminal-logs in french ! I shall configure my ubuntu in english if it helps understanding !)
chat-roux

[lumpfish]

@chat-roux . This issue was raised for the publishing of javadoc at AdoptOpenJDK and is probably not being looked at by the people with the best knowledge to help you with your more general build issues. I suggest you create a separate issue in openjdk-build for this gpg issue.

[chat-roux]

@lumpfish.
OK, well received your remark.
So, I shall create a new issue concerning this "GPG-problem".

Thank you

[ddadon10]

Hi @karianna, I don't know what is the state of this issue right now but I would be happy to help generate a Javadoc for Adoptium that will be under a free license.

Any way I could start contributing on that front?

[karianna]

Yes, you can start by trying to create a build locally (or in a docker container) - the README should give you the first steps on how to do that. Once you have a local build working, ping me back here and I can guide you on what to change to try to get Javadocs out.

[ddadon10]

Awesome! I will keep you in touch :)

[ddadon10]

Hey @karianna! I have a local build working :) (Sorry for the delay, busy busy weeks at work)

Firstly, I am very impressed by the effort put around the shell scripts and docker image generation to build temurin, really 👏 .

I used ./makejdk-any-platform.sh --docker --clean-docker-build jdk17u and I have three small feedback on the build process:

1. I had to change buildDocker.sh and dockerfile-generator.sh to use curl instead of wget because wget is not present by default on macOS
2. The generated Dockerfile try to copy openjdk/pipelines but, as mentioned in the Readme, the pipeline now live in another repo, I had to clone it locally.
3. The README take Java 8 or Java 11 as example, but I cannot build Java 11 because Java 10 (the N-1 version required to build a N version) is not available in https://api.adoptium.net/v3/info/available_releases. I build it with Java 17 and it worked.

I totally can open some Pull Request related to those items if you think they are relevant

And happy to follow up on the Javadoc building when you are available!

[karianna]

@ddadon10 Thanks for digging in!

1. I'm not sure if we want to drop to wget or just tell folks that installing curl from HomeBrew or Macports is the way forward. Would like to hear your opinion on that.
2. That definitely needs fixing.
3. That's a doc bug for sure. You can still get Java 10 binaries from the previous API at adoptopenjdk (https://api.adoptopenjdk.net/v3/info/available_releases). Alternatively, you can actually build Java 11 with Java 11 so maybe that's the better approach for that particular version.

Thoughts and pull request most welcome :-)

[ddadon10]

1. I stopped using Homebrew because of the number of issues I got with it (things breaking without obvious reason, PATH nightmare etc...). But I could have installed/compiled wget directly from gnu.org, that's true. As a solution, I can write a wrapper that will use either wget or curl. So we keep backward compatibility and it will work out of the box for macOS because of curl. Wdyt?

2. We could add the pipeline as a git submodule and checkout the submodule automatically in one of the script?

3. "you can actually build Java 11 with Java 11" - That is good to know :D ! So we could change printDockerJDKs() to do something like if JDK_VERSION == 11 then printJDK $((JDK_VERSION)), we would then use Java 11 to build Java 11 and keep using the brand new Adoptium API :)

I can write PRs for the each point once I have your green light 🚥

[karianna]

1. That sounds like a great compromise

2. We've tried submodules in the past and it wasn't a good/consistent experience. I wonder if a regular git clone would do the trick?

3. Sounds good

Thanks so much for helping out!

[ddadon10]

Hey @karianna ! Thank you for reviewing and merging the dockerfile generator PR!

What would be the next step to generate the Javadoc under a free license? :)

[karianna]

I'd probably start by looking at configureBuild.sh and friends and see how we produce other artifacts like test images, static libs and so forth. I suspect you can follow that pattern to add a javadoc bundle as well.

[ddadon10]

Thanks for the hint!

I need that for a side-project so I am not on it all the time, will keep you in touch :)

[ddadon10]

Hey @karianna! I started to look on how to do that and I am a bit concerned about the discussion in AdoptOpenJDK/TSC#124

Any details on that issue related to the Hotspot JDK?

On one hand I don't want you to ask for legal advice given that I only need for a side project but on the other one I don't want to work on something and see us stuck at the end for that kind of reason.

The easiest solution would be to have the OpenJDK project directly removing this footer from the open-source project but I have no idea where to start on that.

[karianna]

AdoptOpenJDK/TSC#124

That's a good point. This will need to go to the new TSC (The Eclipse Adoptium Project Management Committee). I'll raise it with them to start with.

[ghost]

Hello!
Are there any updates on this?
Thank you!