Odoc and odig - not quite working for me?

Learning
1

Hi-- I’m pretty new to OCaml, so likely I’m just doing something boneheaded.

But: for a little while I used odig/odoc to generate local manuals/API docs in html on my system.

Sometime a few days ago – I think it was after an “opam update” invocation, though I’m not at all sure what was updated… – I began having trouble with odig. As far as I can tell, odig (or odoc – I’m not sure which to “blame”) fails to make the html docs for core_kernel.

More precisely,

$ odig odoc core_kernel

results in a fair amount of noise, which terminates in

…

[ABORTED][read:2174] ‘/home/george/.opam/default/var/cache/odig/odoc/core_kernel/core_kernel.html.deps’
[ABORTED][write:9081] ‘/home/george/.opam/default/var/cache/odig/html/index.html’
odig: [ERROR] Roots never became ready:
{“/home/george/.opam/default/var/cache/odig/html/core_kernel/index.html”}

I just now tried “starting over with my installation”, as follows.

I moved ~/.opam to a ~/opam-keep

and ran

$ opam init
$ opam install core utop
$ opam install async yojson core_extended core_bench cohttp async_graphics cryptokit menhir
$ opam install odoc odig

Then, doing next

$ odig odoc

results in the “[ABORTED]” errors included above. I can provide more output from this error if it is useful, but I doubt that I’ve found something unknown…!

I should perhaps add (if it is useful?) that I’m on a debian system,
I’m running opam installed via apt. And I installed the mccs package via debian, and set

OPAMEXTERNALSOLVER

to mccs (acpud and gringo used up all the CPU/RAM on my system when running opam).

Maybe I need to pin some package versions?? (Well, I tried pinning a few things – e.g. I believe I tried using one version older of odoc and/or odig and/or core_kernel – but wasn’t successful and what I was doing felt a bit random).

Thanks for any suggestions!

Best,
george

2

Could you please provide the exact version numbers please (including the ocaml compiler).

3

Hi-- sure.

$ ocamlc --version
4.09.0

$ opam --version
2.0.3

$ odig --version
v0.0.4

$ odoc --version
1.4.2

$ opam list core_kernel
[…]
core_kernel.v0.13.0 v0.13.0 Industrial strength alternative to OCaml’

1 Like
4

The “noise” actually has the details :slight_smile: :

[FAILED][spawn:2822]
 Illegal exit status: exited [2] expected: 0
 cmd: ['/Users/dbuenzli/.opam/4.09.0/bin/odoc' 'compile' '--pkg' 'core_kernel' '-o' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/core_kernel/core_kernel__List0.odoc' '/Users/dbuenzli/.opam/4.09.0/lib/core_kernel/core_kernel__List0.cmt' [...]
[...]
 stdo-ui: odoc: internal error, uncaught exception:
      Stack overflow
      Raised at file "hashtbl.ml", line 506, characters 17-32
      Called from file "src/xref/expand.ml", line 692, characters 6-38

I tried to pin odoc but alas the problem is still there. I have filed a bug with odoc here.

Juste note that if odig fails, doing such extreme things will likely not help. At most if you think there’s a problem with odig generation, try to issue an odig cache clear && odig odoc to start over. The next version should also have nicer (less noisy by default) error reporting capabilites via a dedicated odig log command.

So for now when there’s a failed package the package index page doesn’t get produced. I thought I had fixed that but it doesn’t seem so. I have opened this issue to track that this in odig.

The docs for the other packages is however generated, you can do a xdg-open $(odig cache path)/html/PKG/index.html to access them. That’s not optimal but at least it gives you something. (Alternatively uninstall core_kernel generate your docset and reinstall core_kernel that way you’ll have an index for the rest but :frowning: )

2 Likes
5

Hi Daniel,

Thanks for the reply.

The “noise” actually has the details :slight_smile: :

Right. I had convinced myself that it was happening because of some
mis-configuration on my end!

Anyhow, the output was longish, and I wasn’t sure exactly what would be
useful. Though in hindsight I guess the ‘Stack overflow’ should have
stood out!

I tried to pin odoc but alas the problem is still there. I have
filed a bug with odoc
here.

Ah; good to know

Juste note that if odig fails, doing such extreme things will likely
not help.

Indeed – it felt a little silly, though I guess doing that is what
convinced me that there was really might be an issue to report.

At most if you think there’s a problem with odig generation,
try to issue an odig cache clear && odig odoc to start over.

[…]

The docs for the other packages is however generated, you can do a
xdg-open $(odig cache path)/html/PKG/index.html to access
them. That’s not optimal but at least it gives you
something. (Alternatively uninstall core_kernel generate your docset
and reinstall core_kernel that way you’ll have an index for the rest
but :frowning: )

Good tips; thanks!

Best,
george

6

To be fair it doesn’t stand out that much, it’s there but in the noise. On that particular example the next odig release makes that more clear:

> odig odoc 
Updating documentation, this may take some time...
odig: [ERROR] Documentation might be incomplete (see: odig log -e).
> odig log -e 
[FAILED 2338:spawn 1.04s core_kernel e:2ac2dd78fb169973] ['/Users/dbuenzli/.opam/4.09.0/bin/odoc' 'compile' '--pkg' 'core_kernel' '-o' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/core_kernel/core_kernel__List0.odoc' '/Users/dbuenzli/.opam/4.09.0/lib/core_kernel/core_kernel__List0.cmt' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/base/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/base/base_internalhash_types/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/base/caml/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/base/md5/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/base/shadow_stdlib/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/base_quickcheck/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/bin_prot/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/bin_prot/shape/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/core_kernel/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/core_kernel/base_for_tests/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/fieldslib/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/ocaml/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/parsexp/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/ppx_bench/runtime-lib/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/ppx_expect/collector/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/ppx_expect/common/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/ppx_expect/config/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/ppx_hash/runtime-lib/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/ppx_inline_test/config/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/ppx_inline_test/runtime-lib/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/ppx_sexp_conv/runtime-lib/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/sexplib/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/sexplib0/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/splittable_random/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/stdio/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/typerep/' '-I' '/Users/dbuenzli/.opam/4.09.0/var/cache/odig/odoc/variantslib/'][2]
odoc: internal error, uncaught exception:
      Stack overflow
      Raised by primitive operation at file "src/odoc/compile.ml", line 43, characters 4-55
      Called from file "cmdliner_term.ml", line 25, characters 19-24
      Called from file "cmdliner_term.ml", line 23, characters 12-19
      Called from file "cmdliner.ml", line 117, characters 32-39

Anyways thanks for taking the time to report.

2 Likes