OCaml Forge

Detail: [#1362] building documentation no longer works

Bugs: Browse | Download .csv | Monitor

[#1362] building documentation no longer works

Date:
2014-01-02 10:03
Priority:
3
State:
Closed
Submitted by:
Jérémie Dimino (dim)
Assigned to:
Sylvain Le Gall (gildor-admin)
Product:
OASIS
Due in version:
None
Resolution:
Awaiting Response
Severity:
major
Version:
0.4.0
Component:
OASIS
Operating System:
All
 
URL:
Summary:
building documentation no longer works

Detailed description
"ocaml setup.ml -doc" doesn't work anymore in JS pacakges since oasis 0.4.0: it seems that the -package flags are not passed to ocamlfind when building the documentation.

Followup

Message
Date: 2014-02-25 12:06
Sender: Sylvain Le Gall

I will have a look at findlib and propose a patch to Gerd tonight.
Date: 2014-02-25 10:56
Sender: Jérémie Dimino

> Can you see the order reverted ?

Yes.

> At this point I don't think the issue is OASIS related, Most probably this is an issue for findlib + ocamldoc.

> What is your opinion ?

Agreed. We can consider this issue as fixed.
Date: 2014-02-25 10:42
Sender: Sylvain Le Gall

OK, so reading myocamlbuild, shows thet you set:
--popt -pa-ounit-lib and then --ppopt core_kernel

Then ocamlbuild launch the command with the right order:
+ ocamlfind ocamldoc -dump [...] -package bin_prot -package bigarray -ppopt -pa-ounit-lib -ppopt core_kernel -I lib lib/array_permute.ml

Then ocamlfind for whatever reason reverse the order of the argument:
camlp4 '-I' '/home/jdimino/.opam/4.01.0+fp/lib/ocaml/camlp4' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/type_conv' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/ocaml' '-I' [...] 'pa_variants_conv.cma' 'core_kernel' '-pa-ounit-lib' 'lib/array_permute.ml'

Can you see the order reverted ?

At this point I don't think the issue is OASIS related, Most probably this is an issue for findlib + ocamldoc.

What is your opinion ?
Date: 2014-02-25 09:16
Sender: Jérémie Dimino

Yes, it's to tell pa_ounit the name of the library. The tag is handled by myocamlbuild.ml.
Date: 2014-02-25 00:04
Sender: Sylvain Le Gall

I did some extra research using core_kernel-109.60.00.tar.gz

It turns out that core_kernel and pa_ounit_lib maybe related with the first line added in _tags:
<lib/*.ml{,i}> : pa_ounit_lib(core_kernel)

This is something not added by OASIS, and I am not very familiar with this. Is it some kind of plugins ?
Date: 2014-02-24 13:12
Sender: Sylvain Le Gall

Great ! So 0.4.2 solves the issue with -package, but ppopt things is wrong.

What is core_kernel ? Why do we have"-pa-ounit-lib" ?

I think I understand where the problem can be, just check that core_kernel and -pa-ounit-lib are fine and I will do what is needed to fix them.

Concerning the automatic generation of API documentation, this will probably appear in the next version, under the feature name "ocamldoc_auto". Thomas Gazagnaire asked for the same things and I think it is something we should have.
Date: 2014-02-24 11:41
Sender: Jérémie Dimino

> I have no strong opinion on the the fact you use opam-doc (which is indeed nice looking) but it also means for some packagers (Debian, Fedora), they will have to create the doc by hand. Why not just let the section and check it works from time to time, with low importance. This will allow them to not have to code by hand all this.

I had to remove the sections because it was causing the build to fail when users were setting the OPAMBUILDDOC environment variable. We can add them again if the problem is fixed. Though oasis could probably have a default doc target, it was always the same for all packages.

> Anyway, I would be very grateful if you can spend 15 minutes to check these. If I am right, it will be even less time because the bugs probably doesn't exist anymore. If not, send me your build logs (esp. setup.data) or even more simple a .tar.gz of the problematic build (including _build). So that I can check myself all this.

Sure. I tried with oasis 0.4.2 and now get a different error, but it might be a problem on my side. Here is how to reproduce the bug (after installing all the dependencies):


$ wget https://ocaml.janestreet.com/ocaml-core/109.60.00/individual/core_kernel-109.60.00.tar.gz
$ tar xf core_kernel-109.60.00.tar.gz
$ cd core_kernel-109.60.00
$ make
$ make doc

without changing the contents of the tarball (so with oasis 0.4.1):

./setup.exe -build
W: Cannot find source file matching module 'check_caml_modify' in library check_caml_modify
W: Cannot find source file matching module 'core_kernel' in library core_kernel
Finished, 0 targets (0 cached) in 00:00:00.
Finished, 789 targets (789 cached) in 00:00:03.
./setup.exe -doc
Finished, 0 targets (0 cached) in 00:00:00.
Warning: tag "package" does not expect a parameter, but is used with parameter "variantslib.syntax"
Warning: tag "package" does not expect a parameter, but is used with parameter "variantslib"
Warning: tag "package" does not expect a parameter, but is used with parameter "unix"
Warning: tag "package" does not expect a parameter, but is used with parameter "typerep_kernel.syntax"
Warning: tag "package" does not expect a parameter, but is used with parameter "typerep_kernel"
Warning: tag "package" does not expect a parameter, but is used with parameter "sexplib.syntax"
Warning: tag "package" does not expect a parameter, but is used with parameter "sexplib"
Warning: tag "package" does not expect a parameter, but is used with parameter "pa_pipebang"
Warning: tag "package" does not expect a parameter, but is used with parameter "pa_bench.syntax"
Warning: tag "package" does not expect a parameter, but is used with parameter "pa_bench"
Warning: tag "package" does not expect a parameter, but is used with parameter "herelib.syntax"
Warning: tag "package" does not expect a parameter, but is used with parameter "herelib"
Warning: tag "package" does not expect a parameter, but is used with parameter "fieldslib.syntax"
Warning: tag "package" does not expect a parameter, but is used with parameter "fieldslib"
Warning: tag "package" does not expect a parameter, but is used with parameter "comparelib.syntax"
Warning: tag "package" does not expect a parameter, but is used with parameter "bin_prot.syntax"
Warning: tag "package" does not expect a parameter, but is used with parameter "bin_prot"
Warning: tag "package" does not expect a parameter, but is used with parameter "bigarray"
Warning: tag "package" does not expect a parameter, but is used with parameter "pa_ounit.syntax"
Warning: tag "package" does not expect a parameter, but is used with parameter "pa_ounit"
Warning: tag "package" does not expect a parameter, but is used with parameter "camlp4.macro"
+ /home/jdimino/.opam/4.01.0+fp/bin/ocamlfind ocamldep -syntax camlp4o -ppopt -pa-ounit-lib -ppopt core_kernel -modules lib/array_permute.ml > lib/array_permute.ml.depends
ocamlfind: Using -syntax, but no package is selected specifying a preprocessor as required for -syntax
Command exited with code 2.
Compilation unsuccessful after building 1 target (0 cached) in 00:00:00.
E: Failure("Command ''/home/jdimino/.opam/4.01.0+fp/bin/ocamlbuild' lib/core_kernel.docdir/index.html -tag debug' terminated with error code 10")
make: *** [doc] Error 1

After running "oasis setup" with oasis 0.4.2:

./setup.exe -build
W: Cannot find source file matching module 'check_caml_modify' in library check_caml_modify
W: Cannot find source file matching module 'core_kernel' in library core_kernel
Finished, 1 target (0 cached) in 00:00:00.
Finished, 789 targets (31 cached) in 00:02:11.
./setup.exe -doc
Finished, 0 targets (0 cached) in 00:00:00.
+ ocamlfind ocamldoc -dump lib/array_permute.odoc -syntax camlp4o -package variantslib.syntax -package variantslib -package unix -package typerep_kernel.syntax -package typerep_kernel -package sexplib.syntax -package sexplib -package pa_pipebang -package pa_ounit.syntax -package pa_ounit -package pa_bench.syntax -package pa_bench -package herelib.syntax -package herelib -package fieldslib.syntax -package fieldslib -package comparelib.syntax -package bin_prot.syntax -package bin_prot -package bigarray -ppopt -pa-ounit-lib -ppopt core_kernel -I lib lib/array_permute.ml
Error: don't know what to do with core_kernel
Use option -help for usage
Preprocessing error
Error while running external preprocessor
Command line: camlp4 '-I' '/home/jdimino/.opam/4.01.0+fp/lib/ocaml/camlp4' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/type_conv' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/ocaml' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/ocaml' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/bin_prot' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/bin_prot' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/comparelib' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/comparelib' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/fieldslib' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/fieldslib' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/herelib' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/oUnit' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/oUnit' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/pa_ounit' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/pa_ounit' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/pa_bench' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/pa_pipebang' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/sexplib' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/sexplib' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/typerep_kernel' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/variantslib' '-I' '/home/jdimino/.opam/4.01.0+fp/lib/variantslib' '-parser' 'o' '-parser' 'op' '-printer' 'p' 'pa_type_conv.cma' 'unix.cma' 'bigarray.cma' 'bin_prot.cma' 'pa_bin_prot.cma' 'comparelib.cma' 'pa_compare.cma' 'fieldslib.cma' 'pa_fields_conv.cma' 'pa_herelib.cma' 'oUnitAdvanced.cma' 'oUnit.cma' 'pa_ounit_lib.cma' 'pa_ounit_syntax.cma' 'pa_bench_syntax.cma' 'pa_pipebang.cma' 'sexplib.cma' 'pa_sexp_conv.cma' 'typerep_kernel_syntax.cma' 'variantslib.cma' 'pa_variants_conv.cma' 'core_kernel' '-pa-ounit-lib' 'lib/array_permute.ml' > /tmp/ocamlppdce15c

Command exited with code 2.
Compilation unsuccessful after building 330 targets (329 cached) in 00:00:01.
E: Failure("Command ''/home/jdimino/.opam/4.01.0+fp/bin/ocamlbuild' lib/core_kernel.docdir/index.html -use-ocamlfind -tag debug' terminated with error code 10")
make: *** [doc] Error 1




Date: 2014-02-24 11:15
Sender: Sylvain Le Gall

I have no strong opinion on the the fact you use opam-doc (which is indeed nice looking) but it also means for some packagers (Debian, Fedora), they will have to create the doc by hand. Why not just let the section and check it works from time to time, with low importance. This will allow them to not have to code by hand all this.

Anyway, I would be very grateful if you can spend 15 minutes to check these. If I am right, it will be even less time because the bugs probably doesn't exist anymore. If not, send me your build logs (esp. setup.data) or even more simple a .tar.gz of the problematic build (including _build). So that I can check myself all this.
Date: 2014-02-24 09:39
Sender: Jérémie Dimino

Basically "make doc" in any JS packages defining a doc section in _oasis failed because the -package flags were not passed to ocamlfind. But we removed the doc section from _oasis and are now using opam-doc which is much better than ocamldoc anyway, so we are not really concerned about this anymore.
Date: 2014-02-22 11:58
Sender: Sylvain Le Gall

This commit removes the "Warning: tag "package" does not expect a...".
https://github.com/ocaml/oasis/commit/f2bb1c48372de57f1bb5b4cccb60441fc5d8b469

Right now, I have no idea how to reproduce this bug. I'll close it next week.
Date: 2014-02-20 23:03
Sender: Sylvain Le Gall

Note that the warning is due to a missing -use-ocamlfind. This one need to be fixed but should not prevent to generate documentation.
Date: 2014-02-20 22:40
Sender: Sylvain Le Gall

I cannot reproduce your bug:
~/tmp/bin_prot-109.53.02$ ocaml setup.ml -configure --enable-docs
~/tmp/bin_prot-109.53.02$ ocaml setup.ml -doc
Finished, 1 target (0 cached) in 00:00:00.
Warning: tag "package" does not expect a parameter, but is used with parameter "bigarray"
Warning: tag "package" does not expect a parameter, but is used with parameter "unix"
Warning: tag "package" does not expect a parameter, but is used with parameter "type_conv"
Warning: tag "package" does not expect a parameter, but is used with parameter "camlp4.extend"
...
:~/tmp/bin_prot-109.53.02$ ls _build/lib/bin_prot.docdir/
Binable.html index_modules.html ...

In setup.ml:
Regenerated by OASIS v0.4.1

So it has been generated with the latest version of OASIS.

Can you provide me with a way to reproduce your bug ?

Attached Files:

Changes:

Field Old Value Date By
status_idOpen2014-02-25 12:06gildor-admin
close_dateNone2014-02-25 12:06gildor-admin
ResolutionAccepted As Bug2014-02-22 11:58gildor-admin
assigned_tonone2014-01-02 19:12gildor-admin
ResolutionNone2014-01-02 19:12gildor-admin