[Caml-list] OCamldoc plugins & ocamlbuild

[Caml-list] OCamldoc plugins & ocamlbuild

[Armaël Guéneau]

[-- Attachment #1: Type: text/plain, Size: 1120 bytes --]

Hi list,

I'm wondering how one should compile ocamldoc custom generators 
<http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec333> using
ocamlbuild.

First, the ocamlbuild manual
(https://github.com/gasche/manual-ocamlbuild/blob/master/manual.md#basic-tags-)
says that the [use_ocamldoc] tag is deprecated; and that a corresponding
ocamlfind package should be used instead. Is there such a package for 
ocamldoc?
I did not found one.

Then, I did not manage to build the plugin into .cma/.cmxs files 
directly using
ocamlbuild. My command line was something along these lines:

    ocamlbuild -use-ocamlfind -tag use_ocamldoc -package compiler-libs 
plugin.cmxs

When trying to build plugin.cma/plugin.cmxs, ocamlbuild complained that 
"Cannot
find file ocamldoc.cma/ocamldoc.cmxa" (respectively). However, I can build
plugin.cmo/plugin.cmx using the same command line, then create the 
.cma/.cmxs
manually using ocamlc/ocamlopt - which I ended up doing.

Is there a better way to do so? If the whole process can be improved 
(how?), I
would be happy to write the required patches/documentation.

— Armaël


[-- Attachment #2: Type: text/html, Size: 1749 bytes --]

Re: [Caml-list] OCamldoc plugins & ocamlbuild

[Gabriel Scherer]

[-- Attachment #1: Type: text/plain, Size: 2830 bytes --]

So I just tried¹, and the failure is as follows:

$ ocamlbuild -tag use_ocamldoc test.cmxs
+ /home/gasche/.opam/4.02.3/bin/ocamlopt.opt -shared -I +ocamldoc
ocamldoc.cmxa test.cmx -o test.cmxs
File "_none_", line 1:
Error: Cannot find file ocamldoc.cmxa

It looks like the tag use_ocamldoc expects a file ocamldoc.cmxa to exist,
providing library support for ocamldoc plugins, and it does not seem to
exist -- it seems that the preferred way to use ocamldoc plugins is to use
"ocamldoc.opt -g foo.cmxs", with ocamldoc libraries already linked inside
ocamldoc.opt. So just using

  ocamlbuild -cflags -I,+ocamldoc test.cmxs

works and seems to do what you expect.

It goes without saying that this is not a perfect long-term solution, as it
assumes that ocamldoc libraries are distributed with the stdlib. It would
be cleaner to have an ocamldoc package for them (just like ocamlbuild has a
dummy ocamlfind package indicating the location of its library files), but
it seems that this is not currently the case. It would be nice (but not
super-high priority) to have such a dummy package in ocamlfind in the
future, so that you can just do

  ocamlbuild -use-ocamlfind -package ocamldoc test.cmxs

¹: The most time-consuming part was finding the code of a ocamldoc plugin
to compile, as the documentation examples are incomplete. Next time, feel
free to provide a tarball with a minimal example to reproduce.

On Fri, Dec 18, 2015 at 5:14 PM, Armaël Guéneau <armael.gueneau@ens-lyon.fr>
wrote:

> Hi list,
>
> I'm wondering how one should compile ocamldoc custom generators
> <http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec333> using
> ocamlbuild.
>
> First, the ocamlbuild manual
> (
> <https://github.com/gasche/manual-ocamlbuild/blob/master/manual.md#basic-tags->
> https://github.com/gasche/manual-ocamlbuild/blob/master/manual.md#basic-tags
> -)
> says that the [use_ocamldoc] tag is deprecated; and that a corresponding
> ocamlfind package should be used instead. Is there such a package for
> ocamldoc?
> I did not found one.
>
> Then, I did not manage to build the plugin into .cma/.cmxs files directly
> using
> ocamlbuild. My command line was something along these lines:
>
>    ocamlbuild -use-ocamlfind -tag use_ocamldoc -package compiler-libs
> plugin.cmxs
>
> When trying to build plugin.cma/plugin.cmxs, ocamlbuild complained that
> "Cannot
> find file ocamldoc.cma/ocamldoc.cmxa" (respectively). However, I can build
> plugin.cmo/plugin.cmx using the same command line, then create the
> .cma/.cmxs
> manually using ocamlc/ocamlopt - which I ended up doing.
>
> Is there a better way to do so? If the whole process can be improved
> (how?), I
> would be happy to write the required patches/documentation.
>
> — Armaël
>
>

[-- Attachment #2: Type: text/html, Size: 3787 bytes --]

Re: [Caml-list] OCamldoc plugins & ocamlbuild

[Armaël Guéneau]

[-- Attachment #1: Type: text/plain, Size: 3140 bytes --]

Ok, thanks for the explanations.

As for the ocamldoc package, would a META file along these lines do the 
trick?

# Specification for the "ocamldoc" library
requires = "compiler-libs"
version = "[distributed with Ocaml]"
description = "ocamldoc support library"
directory= "^ocamldoc"
archive(byte) = "ocamldoc.cma"
archive(native) = "ocamldoc.cmxa"

Le 18/12/2015 18:06, Gabriel Scherer a écrit :
> So I just tried¹, and the failure is as follows:  > > $ ocamlbuild -tag use_ocamldoc test.cmxs > + 
/home/gasche/.opam/4.02.3/bin/ocamlopt.opt -shared -I +ocamldoc 
ocamldoc.cmxa test.cmx -o test.cmxs > File "_none_", line 1: > Error: 
Cannot find file ocamldoc.cmxa > > It looks like the tag use_ocamldoc 
expects a file ocamldoc.cmxa to exist, providing library support for 
ocamldoc plugins, and it does not seem to exist -- it seems that the 
preferred way to use ocamldoc plugins is to use "ocamldoc.opt -g 
foo.cmxs", with ocamldoc libraries already linked inside ocamldoc.opt. 
So just using > >   ocamlbuild -cflags -I,+ocamldoc test.cmxs > > works 
and seems to do what you expect. > > It goes without saying that this is 
not a perfect long-term solution, as it assumes that ocamldoc libraries 
are distributed with the stdlib. It would be cleaner to have an ocamldoc 
package for them (just like ocamlbuild has a dummy ocamlfind package 
indicating the location of its library files), but it seems that this is 
not currently the case. It would be nice (but not super-high priority) 
to have such a dummy package in ocamlfind in the future, so that you can 
just do > >   ocamlbuild -use-ocamlfind -package ocamldoc test.cmxs > > 
¹: The most time-consuming part was finding the code of a ocamldoc 
plugin to compile, as the documentation examples are incomplete. Next 
time, feel free to provide a tarball with a minimal example to 
reproduce. > > On Fri, Dec 18, 2015 at 5:14 PM, Armaël Guéneau 
<armael.gueneau@ens-lyon.fr> wrote: > >     Hi list, > >     I'm 
wondering how one should compile ocamldoc custom generators using >     
ocamlbuild. > >     First, the ocamlbuild manual >     
(https://github.com/gasche/manual-ocamlbuild/blob/master/manual.md#basic-tags-) 
 >     says that the [use_ocamldoc] tag is deprecated; and that a 
corresponding >     ocamlfind package should be used instead. Is there 
such a package for ocamldoc? >     I did not found one. > >     Then, I 
did not manage to build the plugin into .cma/.cmxs files directly using 
 >     ocamlbuild. My command line was something along these lines: > 
 >        ocamlbuild -use-ocamlfind -tag use_ocamldoc -package 
compiler-libs plugin.cmxs > >     When trying to build 
plugin.cma/plugin.cmxs, ocamlbuild complained that "Cannot >     find 
file ocamldoc.cma/ocamldoc.cmxa" (respectively). However, I can build 
 >     plugin.cmo/plugin.cmx using the same command line, then create 
the .cma/.cmxs >     manually using ocamlc/ocamlopt - which I ended up 
doing. > >     Is there a better way to do so? If the whole process can 
be improved (how?), I >     would be happy to write the required 
patches/documentation. > >     — Armaël > >



[-- Attachment #2: Type: text/html, Size: 3853 bytes --]

Re: [Caml-list] OCamldoc plugins & ocamlbuild

[Gabriel Scherer]

[-- Attachment #1: Type: text/plain, Size: 3726 bytes --]

There is no ocamldoc.cm{,x}a in  ocamldoc libraries today. We could
probably change ocamldoc's build system to build one, but for now an
ocamldoc package would have no archive(...) field, just the directory. It
is not clear we need an ocamldoc.cm{,x}a archive if all plugins are to be
passed to ocamldoc{,.opt} which is already linked with ocamldoc modules.

On Fri, Dec 18, 2015 at 8:14 PM, Armaël Guéneau <armael.gueneau@ens-lyon.fr>
wrote:

> Ok, thanks for the explanations.
>
> As for the ocamldoc package, would a META file along these lines do the
> trick?
>
> # Specification for the "ocamldoc" library
> requires = "compiler-libs"
> version = "[distributed with Ocaml]"
> description = "ocamldoc support library"
> directory= "^ocamldoc"
> archive(byte) = "ocamldoc.cma"
> archive(native) = "ocamldoc.cmxa"
>
> Le 18/12/2015 18:06, Gabriel Scherer a écrit :
> > So I just tried¹, and the failure is as follows: > > $ ocamlbuild -tag
> use_ocamldoc test.cmxs > + /home/gasche/.opam/4.02.3/bin/ocamlopt.opt
> -shared -I +ocamldoc ocamldoc.cmxa test.cmx -o test.cmxs > File "_none_",
> line 1: > Error: Cannot find file ocamldoc.cmxa > > It looks like the tag
> use_ocamldoc expects a file ocamldoc.cmxa to exist, providing library
> support for ocamldoc plugins, and it does not seem to exist -- it seems
> that the preferred way to use ocamldoc plugins is to use "ocamldoc.opt -g
> foo.cmxs", with ocamldoc libraries already linked inside ocamldoc.opt. So
> just using > >   ocamlbuild -cflags -I,+ocamldoc test.cmxs > > works and
> seems to do what you expect. > > It goes without saying that this is not a
> perfect long-term solution, as it assumes that ocamldoc libraries are
> distributed with the stdlib. It would be cleaner to have an ocamldoc
> package for them (just like ocamlbuild has a dummy ocamlfind package
> indicating the location of its library files), but it seems that this is
> not currently the case. It would be nice (but not super-high priority) to
> have such a dummy package in ocamlfind in the future, so that you can just
> do > >   ocamlbuild -use-ocamlfind -package ocamldoc test.cmxs > > ¹: The
> most time-consuming part was finding the code of a ocamldoc plugin to
> compile, as the documentation examples are incomplete. Next time, feel free
> to provide a tarball with a minimal example to reproduce. > > On Fri, Dec
> 18, 2015 at 5:14 PM, Armaël Guéneau <armael.gueneau@ens-lyon.fr>
> <armael.gueneau@ens-lyon.fr> wrote: > >     Hi list, > >     I'm
> wondering how one should compile ocamldoc custom generators using >
> ocamlbuild. > >     First, the ocamlbuild manual >     (
> https://github.com/gasche/manual-ocamlbuild/blob/master/manual.md#basic-tags-)
> >     says that the [use_ocamldoc] tag is deprecated; and that a
> corresponding >     ocamlfind package should be used instead. Is there such
> a package for ocamldoc? >     I did not found one. > >     Then, I did not
> manage to build the plugin into .cma/.cmxs files directly using >
> ocamlbuild. My command line was something along these lines: > >
> ocamlbuild -use-ocamlfind -tag use_ocamldoc -package compiler-libs
> plugin.cmxs > >     When trying to build plugin.cma/plugin.cmxs, ocamlbuild
> complained that "Cannot >     find file ocamldoc.cma/ocamldoc.cmxa"
> (respectively). However, I can build >     plugin.cmo/plugin.cmx using the
> same command line, then create the .cma/.cmxs >     manually using
> ocamlc/ocamlopt - which I ended up doing. > >     Is there a better way to
> do so? If the whole process can be improved (how?), I >     would be happy
> to write the required patches/documentation. > >     — Armaël > >
>
>
>

[-- Attachment #2: Type: text/html, Size: 4752 bytes --]

Re: [Caml-list] OCamldoc plugins & ocamlbuild

[Armaël Guéneau]

[-- Attachment #1.1: Type: text/plain, Size: 4261 bytes --]

OK. I've attached an attempt of patch to ocamlfind that implements what 
you describe (a META file with just the directory field).
I think it does the right things, but I did not test it extensively.

Le 18/12/2015 22:43, Gabriel Scherer a écrit :
> There is no ocamldoc.cm <http://ocamldoc.cm>{,x}a in  ocamldoc 
> libraries today. We could probably change ocamldoc's build system to 
> build one, but for now an ocamldoc package would have no archive(...) 
> field, just the directory. It is not clear we need an ocamldoc.cm 
> <http://ocamldoc.cm>{,x}a archive if all plugins are to be passed to 
> ocamldoc{,.opt} which is already linked with ocamldoc modules.
>
> On Fri, Dec 18, 2015 at 8:14 PM, Armaël Guéneau 
> <armael.gueneau@ens-lyon.fr <mailto:armael.gueneau@ens-lyon.fr>> wrote:
>
>     Ok, thanks for the explanations.
>
>     As for the ocamldoc package, would a META file along these lines
>     do the trick?
>
>     # Specification for the "ocamldoc" library
>     requires = "compiler-libs"
>     version = "[distributed with Ocaml]"
>     description = "ocamldoc support library"
>     directory= "^ocamldoc"
>     archive(byte) = "ocamldoc.cma"
>     archive(native) = "ocamldoc.cmxa"
>
>     Le 18/12/2015 18:06, Gabriel Scherer a écrit :
>     > So I just tried¹, and the failure is as follows: > > $ ocamlbuild -tag use_ocamldoc test.cmxs > +
>     /home/gasche/.opam/4.02.3/bin/ocamlopt.opt -shared -I +ocamldoc
>     ocamldoc.cmxa test.cmx -o test.cmxs > File "_none_", line 1: >
>     Error: Cannot find file ocamldoc.cmxa > > It looks like the tag
>     use_ocamldoc expects a file ocamldoc.cmxa to exist, providing
>     library support for ocamldoc plugins, and it does not seem to
>     exist -- it seems that the preferred way to use ocamldoc plugins
>     is to use "ocamldoc.opt -g foo.cmxs", with ocamldoc libraries
>     already linked inside ocamldoc.opt. So just using > >   ocamlbuild
>     -cflags -I,+ocamldoc test.cmxs > > works and seems to do what you
>     expect. > > It goes without saying that this is not a perfect
>     long-term solution, as it assumes that ocamldoc libraries are
>     distributed with the stdlib. It would be cleaner to have an
>     ocamldoc package for them (just like ocamlbuild has a dummy
>     ocamlfind package indicating the location of its library files),
>     but it seems that this is not currently the case. It would be nice
>     (but not super-high priority) to have such a dummy package in
>     ocamlfind in the future, so that you can just do > >   ocamlbuild
>     -use-ocamlfind -package ocamldoc test.cmxs > > ¹: The most
>     time-consuming part was finding the code of a ocamldoc plugin to
>     compile, as the documentation examples are incomplete. Next time,
>     feel free to provide a tarball with a minimal example to
>     reproduce. > > On Fri, Dec 18, 2015 at 5:14 PM, Armaël Guéneau
>     <armael.gueneau@ens-lyon.fr> <mailto:armael.gueneau@ens-lyon.fr>
>     wrote: > >     Hi list, > >     I'm wondering how one should
>     compile ocamldoc custom generators using >     ocamlbuild. > >    
>     First, the ocamlbuild manual >    
>     (https://github.com/gasche/manual-ocamlbuild/blob/master/manual.md#basic-tags-)
>     >     says that the [use_ocamldoc] tag is deprecated; and that a
>     corresponding >     ocamlfind package should be used instead. Is
>     there such a package for ocamldoc? >     I did not found one. >
>     >     Then, I did not manage to build the plugin into .cma/.cmxs
>     files directly using >     ocamlbuild. My command line was
>     something along these lines: > >        ocamlbuild -use-ocamlfind
>     -tag use_ocamldoc -package compiler-libs plugin.cmxs > >     When
>     trying to build plugin.cma/plugin.cmxs, ocamlbuild complained that
>     "Cannot >     find file ocamldoc.cma/ocamldoc.cmxa"
>     (respectively). However, I can build >     plugin.cmo/plugin.cmx
>     using the same command line, then create the .cma/.cmxs >    
>     manually using ocamlc/ocamlopt - which I ended up doing. > >    
>     Is there a better way to do so? If the whole process can be
>     improved (how?), I >     would be happy to write the required
>     patches/documentation. > >     — Armaël > >
>
>
>


[-- Attachment #1.2: Type: text/html, Size: 5685 bytes --]

[-- Attachment #2: ocamldoc-META.patch --]
[-- Type: text/x-patch, Size: 1632 bytes --]

diff --git trunk/configure trunk/configure
index 2fef7ad..82f72bd 100755
--- trunk/configure
+++ trunk/configure
@@ -449,6 +449,16 @@ else
     echo "ocamlbuild: not present"
 fi
 
+# Check whether ocamldoc is present
+
+if [ -d "${ocaml_core_stdlib}/ocamldoc" ]; then
+    lodoc=ocamldoc
+    echo "ocamldoc: found"
+else
+    lodoc=""
+    echo "ocamldoc: not present"
+fi
+
 # Check on camlp4:
 
 if [ $with_camlp4 -eq 0 ]; then
@@ -521,7 +531,7 @@ fi
 
 # Generate the META files now.
 
-l="$ldbm dynlink graphics num num-top str threads unix stdlib bigarray $llabltk $lcamlp4 $lobuild $lcomplibs $lbytes"
+l="$ldbm dynlink graphics num num-top str threads unix stdlib bigarray $llabltk $lcamlp4 $lobuild $lodoc $lcomplibs $lbytes"
 
 for dir in site-lib-src/*; do
     # We do not really know if $dir is a directory.
diff --git trunk/findlib.files trunk/findlib.files
index cf2775e..f4b1a29 100644
--- trunk/findlib.files
+++ trunk/findlib.files
@@ -98,6 +98,8 @@ f site-lib-src/unix/interfaces.in
 f site-lib-src/unix/interfaces.out
 d site-lib-src/ocamlbuild
 f site-lib-src/ocamlbuild/META.in
+d site-lib-src/ocamldoc
+f site-lib-src/ocamldoc/META.in
 d site-lib-src/compiler-libs
 f site-lib-src/compiler-libs/META.in
 d site-lib-src/bytes
diff --git trunk/site-lib-src/ocamldoc/META.in trunk/site-lib-src/ocamldoc/META.in
new file mode 100644
index 0000000..3994bec
--- /dev/null
+++ trunk/site-lib-src/ocamldoc/META.in
@@ -0,0 +1,5 @@
+`# Specification for the "ocamldoc" library'
+`requires = "compiler-libs"'
+`version = "[distributed with Ocaml]"'
+`description = "ocamldoc support library"'
+`directory= "^ocamldoc"'