Add initial documentation for Java-based packages

[md5]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?

---

Per the discussion at Homebrew/discussions#910, this PR adds a "Homebrew and Java" page that documents the use of openjdk or versioned alternatives by Java-based packages, as well as the ability to bring your own JDK by means of the JAVA_HOME environment variable.

[jonchang]

Great start! We should probably talk about the macOS system Java wrappers in /usr/bin/java, /usr/bin/javac, and /usr/libexec/java_home. Our openjdk formulae say this in their caveats:

For the system Java wrappers to find this JDK, symlink it with
  sudo ln -sfn /usr/local/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk

We should repeat the guidance here and point out that this will enable these system Java wrappers to function properly when running e.g. java from the Terminal or when double-clicking a .jar file from Finder to avoid these sorts of errors:

% java 
The operation couldn’t be completed. Unable to locate a Java Runtime.
Please visit http://www.java.com for information on installing Java.

[SMillerDev]

Since /usr/libexec/java_home is deprecated by Apple, let's avoid dragging that documentation in.

[jonchang]

Where do you see that /usr/libexec/java_home is deprecated by Apple? I note that it's actually been updated in Big Sur. We just don't use it internally in Homebrew anymore because we have other solutions that work better for us.

[SMillerDev]

Okay, I swear I read that during the Big Sur beta cycles. I can't find it anymore so I guess I was wrong.

But since it's functionally equivalent to setting $JAVA_HOME now, it might still be good to keep it out of the documentation since $JAVA_HOME is the cross-platform standard.

[md5]

Since /usr/libexec/java_home is deprecated by Apple, let's avoid dragging that documentation in.

Apologies @SMillerDev that I didn't see this discussion until after I had already worked on adding the relevant documentation, so I pushed the commit anyways. I can amend or reverse it out if that's the consensus.

I would also add that getting JARs to work in Finder is not possible by just setting the JAVA_HOME environment variable, as far as I know. That requires putting the JDK bundle in a directory recognized by java_home.

[MikeMcQuaid]

Looking good so far, thanks for the PR (and the sponsorship)!

[md5]

I ended up adding a blurb about confirming the symlink with /usr/libexec/java_home -V and noticed that the vendor name of the bundle from the openjdk packages is coming through as UNDEFINED. Not sure if that indicates a missing plist entry or what.

[md5]

I ended up adding a blurb about confirming the symlink with /usr/libexec/java_home -V and noticed that the vendor name of the bundle from the openjdk packages is coming through as UNDEFINED. Not sure if that indicates a missing plist entry or what.

It appears the way to fix the UNDEFINED would be to set --with-vendor-name in openjdk.rb when building the JDK. Also, looking at openjdk.rb, I think it would make sense to have the bundle directory names exactly match the Homebrew package names. Right now, both openjdk and openjdk@8 call the directory openjdk.jdk leading to slightly divergent symlinking instructions between the two packages, but if openjdk@8 used the name openjdk@8.jdk instead, the symlinking instructions could be the same for all OpenJDK packages:

% sudo ln -sfn $(brew --prefix $OPENJDK)/libexec/$OPENJDK.jdk /Library/Java/JavaVirtualMachines/

[SMillerDev]

I'm not sure if that would work. Java is kinda finicky about it's paths. Could you test it and make a pull request if it does?

[md5]

I'm not sure if that would work. Java is kinda finicky about it's paths. Could you test it and make a pull request if it does?

Not sure that what would work? A symlink with @ in the name or something else?

It works fine:

% pwd
/Library/Java/JavaVirtualMachines
% ls
jdk-14.0.2.jdk  jdk-15.0.2.jdk  jdk1.8.0_20.jdk openjdk.jdk
% /usr/libexec/java_home -V
Matching Java Virtual Machines (5):
    15.0.2 (x86_64) "Oracle Corporation" - "Java SE 15.0.2" /Library/Java/JavaVirtualMachines/jdk-15.0.2.jdk/Contents/Home
    15.0.1 (x86_64) "UNDEFINED" - "OpenJDK 15.0.1" /usr/local/Cellar/openjdk/15.0.1/libexec/openjdk.jdk/Contents/Home
    14.0.2 (x86_64) "Oracle Corporation" - "Java SE 14.0.2" /Library/Java/JavaVirtualMachines/jdk-14.0.2.jdk/Contents/Home
    1.8.271.09 (x86_64) "Oracle Corporation" - "Java" /Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home
    1.8.0_20 (x86_64) "Oracle Corporation" - "Java SE 8" /Library/Java/JavaVirtualMachines/jdk1.8.0_20.jdk/Contents/Home
/Library/Java/JavaVirtualMachines/jdk-15.0.2.jdk/Contents/Home
% sudo mv openjdk.jdk openjdk@stuff.jdk
% /usr/libexec/java_home -V
Matching Java Virtual Machines (5):
    15.0.2 (x86_64) "Oracle Corporation" - "Java SE 15.0.2" /Library/Java/JavaVirtualMachines/jdk-15.0.2.jdk/Contents/Home
    15.0.1 (x86_64) "UNDEFINED" - "OpenJDK 15.0.1" /usr/local/Cellar/openjdk/15.0.1/libexec/openjdk.jdk/Contents/Home
    14.0.2 (x86_64) "Oracle Corporation" - "Java SE 14.0.2" /Library/Java/JavaVirtualMachines/jdk-14.0.2.jdk/Contents/Home
    1.8.271.09 (x86_64) "Oracle Corporation" - "Java" /Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home
    1.8.0_20 (x86_64) "Oracle Corporation" - "Java SE 8" /Library/Java/JavaVirtualMachines/jdk1.8.0_20.jdk/Contents/Home
/Library/Java/JavaVirtualMachines/jdk-15.0.2.jdk/Contents/Home

[SMillerDev]

Not sure that what would work? A symlink with @ in the name or something else?

We'll, Java after that. But if you tested this I guess it's fine.

[Bo98]

if openjdk@8 used the name openjdk@8.jdk instead,

Makes sense, but will break existing symlinks when people brew upgrade, and potentially any formulae where we install a script that sets JAVA_HOME to this.

It's doable but probably not worth the effort, when it's just for a slightly different looking ln command.

[MikeMcQuaid]

Thanks so much for your sponsorship and first contribution (and sorry for all the back and forth)! Without people like you submitting PRs we couldn't run this project. You rock, @md5!