Help installing Erlang with docs

export KERL_BUILD_DOCS=yes
export KERL_INSTALL_MANPAGES=yes
export KERL_INSTALL_HTMLDOCS=yes
asdf install erlang 21.3.8

# ... much later ...

Extracting source code
Building Erlang/OTP 21.3.8 (asdf_21.3.8), please wait...
Building docs...
Building docs failed.
Generating ../doc/html/java/allclasses-index.html...
Generating ../doc/html/java/allpackages-index.html...
Generating ../doc/html/java/index.html...
Generating ../doc/html/java/help-doc.html...
4 errors
97 warnings
make[3]: *** [jdoc] Error 1
make[2]: *** [docs] Error 2
make[1]: *** [docs] Error 2
make: *** [docs] Error 2

Please see /Users/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_21.3.8/otp_build_21.3.8.log for full details.

So I did, but nothing informative at the end of it:

# ...a lot of successful Java docs generation going on for a while...
Generating ../doc/html/java/allclasses-index.html...
Generating ../doc/html/java/allpackages-index.html...
Generating ../doc/html/java/index.html...
Generating ../doc/html/java/help-doc.html...
4 errors
97 warnings
make[3]: *** [jdoc] Error 1
make[2]: *** [docs] Error 2
make[1]: *** [docs] Error 2
make: *** [docs] Error 2

Not sure how to troubleshoot further, any pointers? kerl GitHub page isn’t helping me (as far as I can see).

To build the documentation you need to have:

Unfortunately the erlang install document doesn’t mention which versions of the above are needed. I read in another thread someone had problems with fop.

If I remember correctly. If the erlang version is an official release (and not just a github release). I think the compiled documentation is available in the release and kerl will download it instead of building it. Then you just do the KERL_INSTALL_… and not the BUILD_DOCS env variable.

Most of this is from http://erlang.org/doc/installation_guide/INSTALL.html and https://github.com/erlang/otp/blob/master/HOWTO/INSTALL.md

3 Likes
fop -version
FOP Version 2.3

xsltproc --version
Using libxml 20904, libxslt 10129 and libexslt 817
xsltproc was compiled against libxml 20904, libxslt 10129 and libexslt 817
libxslt 10129 was compiled against libxml 20904
libexslt 817 was compiled against libxml 20904

Tried installing 22.0 through asdf, same problem.

As far as I understood kerl docs, the KERL_INSTALL_... variables will not make a difference when compiling from source (and it appears asdf does that). So KERL_BUILD_DOCS seems to be mandatory. I also validated this by unsetting this variable and an install went through fine but no docs were found:

unset KERL_BUILD_DOCS
export KERL_INSTALL_MANPAGES=yes
export KERL_INSTALL_HTMLDOCS=yes

asdf install erlang 22.0
# ...nothing here says anything about docs...
asdf global erlang 22.0
elixir -v
Erlang/OTP 22 [erts-10.4] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [hipe]

Elixir 1.8.2 (compiled with Erlang/OTP 21)
erl -man atomics
No manual entry for atomics

Any recommendations? I haven’t yet made an extensive research on the right fop and xsltproc versions that Erlang docs requires.

I don’t know what I did wrong or if kerl or asdf plugin changed in some way. But I have man pages and documentation for my installs < 21 (18,19,20). However, installing 21 and 22 the same way didn’t work.

In the end I had to put the variables in a file inside of the asdf erlang plugin.

[moana] asdf $ cat plugins/erlang/kerl-home/.kerlrc
KERL_BUILD_DOCS=yes
KERL_INSTALL_MANPAGES=yes
KERL_INSTALL_HTMLDOCS=yes

And then:

[moana] $ asdf install erlang 22.0
Extracting source code
Building Erlang/OTP 22.0 (asdf_22.0), please wait...
APPLICATIONS DISABLED (See: /home/martink/software/git/asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_build_22.0.log)
 * odbc           : ODBC library - link check failed

Building docs...
Erlang/OTP 22.0 (asdf_22.0) has been successfully built
Installing Erlang/OTP 22.0 (asdf_22.0) in /home/martink/software/git/asdf/installs/erlang/22.0...
Installing docs...
You can activate this installation running the following command:
. /home/martink/software/git/asdf/installs/erlang/22.0/activate
Later on, you can leave the installation typing:
kerl_deactivate
Cleaning up compilation products for
Cleaned up compilation products for  under /home/martink/software/git/asdf/plugins/erlang/kerl-home/builds

Erlang 22.0 has been installed. Activate globally with:

    asdf global erlang 22.0

Activate locally in the current folder with:

    asdf local erlang 22.0

From here it worked:

$ mkdir tmp/22
$ cd tmp/22
$ asdf local erlang 22.0
$ erl -man lists
asdf install erlang 22.0
Extracting source code
Building Erlang/OTP 22.0 (asdf_22.0), please wait...
Building docs...
Building docs failed.
Generating ../doc/html/java/allclasses-index.html...
Generating ../doc/html/java/allpackages-index.html...
Generating ../doc/html/java/index.html...
Generating ../doc/html/java/help-doc.html...
4 errors
97 warnings
make[3]: *** [jdoc] Error 1
make[2]: *** [docs] Error 2
make[1]: *** [docs] Error 2
make: *** [docs] Error 2

Please see /Users/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_build_22.0.log for full details.

Sadly same thing. BTW, ~/.asdf/plugins/erlang/kerl-home/.kerlrc didn’t exist. I had to create it. All directories were in place but the file wasn’t.

Problem is, the error output is not at all helpful.

I am on macOS. Will try on Linux and let you know.

Yep same here on linux, 22.0 won’t install via asdf.

In my case it seems to be because the recipe for jdoc is failing.

Looking in to it it’s because the java files have a lot of error: tag not supported in the generated HTML version: tt (only seems to be tt though) as well as a holy-TON of warnings on invalid java doctags.

EDIT1: Yep, looks like many years ago Java deprecated tt in HTML5 javadoc generation as people should be using the code element instead, so that looks like an OTP doc bug (in addition to the huge warning count). But still can’t install it via asdf… ^.^;

EDIT2: It looks like direct html tags like tt and code should never ever be used in javadoc anyway, apparently {@code your-code-here} should have always been used as it will safely escape the your-code-here part where the HTML tags themselves will not (as well as wrapping in tt/code properly anyway).

1 Like

My Manjaro fails even more differently. :smiley:

$ export KERL_BUILD_DOCS=yes
$ export KERL_INSTALL_MANPAGES=yes
$ export KERL_INSTALL_HTMLDOCS=yes
$ fop -version
FOP Version 2.3
$ xsltproc -version
Using libxml 20909, libxslt 10133-GITv1.1.33 and libexslt 820
xsltproc was compiled against libxml 20908, libxslt 10133 and libexslt 820
libxslt 10133 was compiled against libxml 20908
libexslt 820 was compiled against libxml 20908
$ time asdf install erlang 22.0
Downloading OTP-22.0.tar.gz to /home/dimi/.asdf/plugins/erlang/kerl-home/archives
 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                Dload  Upload   Total   Spent    Left  Speed
100   120    0   120    0     0    333      0 --:--:-- --:--:-- --:--:--   333
100 52.2M    0 52.2M    0     0  1943k      0 --:--:--  0:00:27 --:--:-- 2414k
Extracting source code
Building Erlang/OTP 22.0 (asdf_22.0), please wait...
APPLICATIONS DISABLED (See: /home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_build_22.0.log)
* odbc           : ODBC library - link check failed

Build failed.
make[2]: Entering directory '/home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_src_22.0/lib/ssl'
=== Entering application ssl
make[3]: Entering directory '/home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_src_22.0/lib/ssl/src'
/home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_src_22.0/lib/ssl/src/deps/ssl.d:1: *** missing separator.  Stop.
make[3]: Leaving directory '/home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_src_22.0/lib/ssl/src'
make[2]: *** [/home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_src_22.0/make/otp_subdir.mk:29: opt] Error 2
make[2]: Leaving directory '/home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_src_22.0/lib/ssl'
make[1]: *** [/home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_src_22.0/make/otp_subdir.mk:29: opt] Error 2
make[1]: Leaving directory '/home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_src_22.0/lib'
make: *** [Makefile:490: libs] Error 2

Please see /home/dimi/.asdf/plugins/erlang/kerl-home/builds/asdf_22.0/otp_build_22.0.log for full details.

real	18m10.415s
user	56m10.946s
sys	8m36.866s

Guessing OpenSSL version requirement changed?

21.3.8 and 21.3.8.1 didn’t want to install as well.

@AstonJ / @OvermindDL1 / other mods – could you please split the extra comments from here to a split thread called “Help installing Erlang with docs through asdf”, please? We went way off-topic and my original question here was solved.

1 Like

It’s not necessarily the version that is the issue, but rather the version of Java in my case. The newer versions of Java mandate a more strict adherence to javadocs that Erlang’s java interface does not adhere too. ^.^;

Done.

So I have to downgrade Java, or?

If you are getting the same error as me you’ll need to use a java older than the current LTS, so just go back to java 9 or java 8 or so, maybe 10 will work.

For anyone interested in achieving compiling Erlang with offline documentation in the future:

  • Be on macOS 10.14+. Haven’t tried my guide on Linux yet.
  • Have brew and brew-cask installed.
  • Install cask-versions with brew tap homebrew/cask-versions.
  • Install jenv with brew install jenv.
  • Make jenv be loaded into your shell by following their instructions (very easy to find on the net).
  • Install an older version of Java – I installed 1.6 (also known as 6), through brew cask install java6.
  • (OPTIONAL) If you are interested in other versions, just do brew search java and install the package that interests you. I only had java6 and java11 and I haven’t tried v11, only v6.
  • Add the additional Java version you installed to jenv. In my case the proper path was this: jenv add /Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home/. If that doesn’t work for you, just use TAB completion when you get in the /Library/Java/JavaVirtualMachines/ directory. You’ll easily find the Java version you require.
  • I opted to only load Java 1.6 (aka 6) for one-off shell session with jenv local 1.6.
    - WARNING: The above will create a .java-version file in your current directory!
  • Run asdf install erlang 22.0.1 or whatever version you like.
  • The Building docs... step should now succeed.
  • After Erlang has been installed, switch to it: asdf local erlang 22.0.1 (or asdf global erlang 22.0.1).
  • Run erl -man atomics (or any other module you need) – it should succeed and show you the man page.

That should be it.

Sources:

2 Likes

UPDATE: Not sure exactly when it happened (I think since Erlang 22) but I can now issue asdf install erlang 22.x.x without having any older JDK/JRE versions on my Macs (confirmed on two). Erlang installs docs just fine while JDK/JRE 13.0.x is the only installed Java on your system.

I also confirmed it on a Manjaro laptop with JDK 13.0.1. So the above post describes some pretty meaningless gymnastics, as of today at least.

Disclaimer: I am using macOS 10.15 Catalina.

3 Likes

Ubuntu user here (pure Ubuntu 20.04 and/on WSL2),
I can also confirm that now I just followed asdf-erlang’s documents (the Before asdf install section) and built 22.3.4.1 fine with documents.
Just needed the env vars in the installation command:

env KERL_BUILD_DOCS=yes KERL_INSTALL_MANPAGES=yes KERL_INSTALL_HTMLDOCS=yes asdf install erlang 22.3.4.1
1 Like

I can also confirm it worked for me on Ubuntu 20.04 LTS.
Thank you so much.

1 Like

3 Likes