Help required with running opam-doc #1

Closed
heidi-ann opened this Issue Aug 13, 2013 · 13 comments

Comments

Projects
None yet
6 participants
Contributor

heidi-ann commented Aug 13, 2013

I'm trying to run opam-doc on core

So far I've:

(1) Generating .cmt[i] amd .cmd[i] files

  • $ opam remote add ocamllabs git@github.com:ocamllabs/opam-repo-dev.git
  • $ opam install bin-doc
  • $ opam switch 4.00.1+bin-doc
  • $ eval opam config env
  • $ PATH=~/.opam/4.01.0dev+trunk/bin/bin-doc:$PATH
  • $ opam install -b core

(2). Generating the HTML

  • $ opam switch 4.01.0dev+trunk
  • eval opam config env
  • $ git clone git@github.com:ocamllabs/opam-doc.git
  • $ cd opam-doc
  • $ opam install cow #and any other dependences that failed
  • $ make
  • $ cd ~/.opam/4.00.1+bin-doc/build/core.109.37.00/_build/lib
  • $ ~/opam-doc/opam-doc --package core *.cmti *cmdi # and may variations on this

But i just can't see produce any actual docs. The best I can get a index.html with gibberish like "„•¦¾��,³› ÐÐÐÐ@ %Clock0Ü;S´¦{¸ö+°M—?³ù� 'mir-doc��@A 'Console0¾‡„f�¦°H‡»�K�"

Can you tell me exactly what to arguments to opam-doc and where to find the resulting html ?

Contributor

vincent-botbol commented Aug 13, 2013

Hi,

You actually need to generate the cmt files with 4.01.0dev+trunk as the typed tree slightly changed.

There is a simple method used in the 4.00.1+bin-doc compiler which is to replace the binaries with a script before calling the real compiler :

  • cd ~/.opam/4.01.0dev+trunk/bin
  • mv ocamlc ocamlc.real
  • touch ocaml
  • put this script inside the newly created ocaml file
#!/bin/bash
which bin-doc &> /dev/null && bin-doc "$@" > /dev/null
ocamlc.real -bin-annot "$@"
  • chmod +x ocamlc

Then, reinstall core and you should be set.

I usually tend to use : opam-doc -p core $(find <core_path>/ -name *.cm[dt]*)

In any case, the program should return an error telling the the cmt version handed is wrong. I'll get this fixed as soon as I can.

Thank you for noticing this.

Owner

samoht commented Aug 13, 2013

Instead of that patch I think we can use the new OCAMLPARAM option. If you have some issues with it, please report on http://caml.inria.fr/mantis/view.php?id=6076 (would be nice to check that this option works as expected before the release of 4.01 though).

Owner

samoht commented Aug 13, 2013

(and if it works we could add that option by default to the compiler description for 4.01)

Member

lpw25 commented Aug 13, 2013

OCAMLPARAM only takes care of adding the "-bin-annot" argument, we also need to run the "bin-doc" command with the same arguments as the compiler.

I hope to add a "-bin-doc" option to the compiler to replace the "bin-doc" command. Once that is done then OCAMLPARAM should be sufficient.

Owner

avsm commented Aug 13, 2013

OCAMLPARAM, not OPAMPARAM

-a

On 13 Aug 2013, at 15:47, Thomas Gazagnaire notifications@github.com wrote:

Instead of that patch I think we can use the new OPAMPARAM option. If you have some issues with it, please report on http://caml.inria.fr/mantis/view.php?id=6076 (would be nice to check that this option works as expected before the release of 4.01 though).


Reply to this email directly or view it on GitHub.

Contributor

heidi-ann commented Aug 14, 2013

Thanks for the feedback

To separate the two issue, I've tried using the pre generated .cm[dt] files in opam-doc/cmt_folder-4.01.0dev+trunk/core_bench.109.34.00 and I'll still not sure if the html is being generated, if I do the following:

  • $ opam switch 4.01.0dev+trunk
  • evalopam config env `
  • $ git clone git@github.com:ocamllabs/opam-doc.git
  • $ cd opam-doc
  • $ opam install cow #and any other dependances that fail
  • $ make
  • $ cd cmt_folder-4.01.0dev+trunk/core_bench.109.34.00
  • ~/opam-doc/opam-doc -p core_bench $(ls *.cm[dt]*)

Then a empty directory called core_bench and a file called opam-doc.idx is created in my working directory, but where are the html files ?

If i add -index ./index.html to the call to oapm-doc, then a index.html is generated containing:

<84><95>¦¾^@^@^@6^@^@^@ ^@^@^@#^@^@^@^_ Ð@ *Bench_main0VÕ^E&e_Õ^Z-q®Ê/.^X^F *core_bench^D^D@A  ^D^C@@

Contributor

heidi-ann commented Aug 14, 2013

@vincent-botbol

Am i right to assume that when you said

touch ocaml
put this script inside the newly created ocaml file

you mean ocamlc instead of ocaml ?

Contributor

heidi-ann commented Aug 14, 2013

Regarding generating cmt files with 4.01.0dev+trun.

@vincent-botbol I've followed the your steps (for cstruct), where can i now find the cm[dt]* files ?

There not in:

  • .opam/4.01.0dev+trunk/build/cstruct.0.7.1/_build/lib
  • .opam/4.01.0dev+trunk/lib/cstruct
  • .opam/4.01.0dev+trunk/doc/cstruct
Contributor

heidi-ann commented Aug 14, 2013

With some help from @lpw25, We have now generated some docs using opam-doc.
For future reference, here are the issues and the solutions:

Problem: I couldn't generate docs from cmt(i) files in opam-doc/cmt_folder-4.01.0dev+trunk
Solution: opam-doc can't generate docs from only cmt(i), it needs the cmd(i) too

Problem: After following @vincent-botbol instruction, I couldn't find the cm[dt]* files
Solution: You need to repeat vincent's instruction for ocamlc.opt, ocamlopt.opt and ocamlopt. as well as ocamlc. The ~/.opam/4.01.0dev+trunk/build//_build/src/

Problem: After generating the HTML, the JavaScript wasn't working in when viewed in a browser
Solution: Make sure that you start at the index.html in the current directory (not the index.html in the new subdirectory called ) and open docs in firefox instead of chrome, as chrome has an issue with AJAX requests from local directories

Owner

avsm commented Aug 28, 2013

Here's my integration of all this into OPAM:

opam remote add opamdoc git://github.com/avsm/opamdoc-dev
opam switch 4.01.0beta1+opamdoc
eval `opam config env`
opam install opamdoc
opamdoc-rebuild
opamdoc-generate
open ~/.opam/4.01.0beta1+opamdoc/opamhtml/index.html
  • opamdoc-rebuild builds a database of cmt/cmd files in ~/.opam/4.01.0beta1+opamdoc/opamdoc.
  • opamdoc-generate builds a package HTML list in ~/.opam/4.01.0beta+opamdoc/opamhtml.

What are the instructions for packagers ? Does this mean that packages themselves should generate and install cmti for each corresponding installed mli file ?

(one small annoyance if you use ocamlbuild is that this makes all your package dependent on 4.01.0 as it's the version that introduces the bin_annot tag to generate cmti files).

Owner

avsm commented Aug 28, 2013

There are no instructions for packagers yet. This is still experimental and gathers up cmt files that are installed via an augmented ocamlc driver.

Owner

samoht commented Dec 19, 2013

I think this is fixed now.

samoht closed this Dec 19, 2013

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment