Khady
March 31, 2022, 9:45am
1
I have a weird problem with dune build @doc @doc-private which generates nothing. And I’m trying to find a reason why it would behave this way.
After running dune build @doc @doc-private the _build/default/_doc/_html folder is empty. dune rules @doc and dune rules @doc-private don’t display anything. While if I do dune build _build/default/_doc/_html/api/Apicore/index.html the html file is correctly generated.
my lib apicore is public, defined like this
(library
(name apicore)
(public_name api.apicore)
Is it mandatory to build the doc from the root of the dune project? Right now I’m trying to run the build from api which is a subfolder of the project root, because I’d like to build the doc only for that specific project.
I can generate the doc for my whole project with odig without issue. I run it like this, if it makes a difference
dune build @install
odig odoc --doc-dir=_build/install/default/doc --lib-dir=_build/install/default/lib/
Any idea what I could be doing wrongly?
I’m running dune 3.0.3 and (lang dune 3.0).
1 Like
NAlec
January 6, 2024, 7:56pm
2
Any news about this issue. I am facing the same issue (I think).
1 Like
Khady
January 7, 2024, 4:58am
3
Last time I tried the situation was the same. But I know that there are new doc rules in the most recent dune. So maybe things will get better.
NAlec
January 8, 2024, 10:28pm
4
I have the same issue here. Not a single html file appears !
If I start a new library project with dune, with
dune init project --kind=lib Progress
and then put a progress.ml with progress.mli like that :
progress.ml
(** This is the main entry of the progress library *)
let hello msg =
print_endline msg
(** the function uses print_endline *)
and progress.mli
(** This is the description of the Module Progress *)
(** This is the hello function to say hello *)
val hello : string -> unit
(** Nothing special in that function *)
I can add a test :Progress.ml
let () = Progress.hello "Ceci est un test"
Then I build everything with
PS H:\Progress> dune build
PS H:\Progress> dune runtest
Ceci est un test
PS H:\Progress> dune build @doc
PS H:\Progress> tree /A
PS H:\OCaml\Progress> tree /F
[...]
[...]
H:.
│ dune-project
│ Progress.opam
│
├───lib
│ dune
│ progress.ml
│ progress.mli
│
├───test
│ dune
│ Progress.ml
│
└───_build
│ .db
│ .digest-db
│ .filesystem-clock
│ log
│
├───.actions
│ └───default
│ └───test
│ runtest-6e8a4e77c2c4fe157366d918bcf7599d
│
├───default
│ │ META.Progress
│ │ Progress.dune-package
│ │ Progress.install
│ │ Progress.opam
│ │
│ ├───.dune
│ │ configurator
│ │ configurator.v2
│ │
│ ├───lib
│ │ │ Progress.cma
│ │ │ Progress.cmxa
│ │ │ Progress.cmxs
│ │ │ Progress.lib
│ │ │ progress.ml
│ │ │ progress.mli
│ │ │
│ │ ├───.merlin-conf
│ │ │ lib-Progress
│ │ │
│ │ └───.Progress.objs
│ │ ├───byte
│ │ │ progress.cmi
│ │ │ progress.cmo
│ │ │ progress.cmt
│ │ │ progress.cmti
│ │ │
│ │ └───native
│ │ progress.cmx
│ │ progress.obj
│ │
│ └───test
│ │ Progress.exe
│ │ Progress.ml
│ │ Progress.mli
│ │
│ ├───.merlin-conf
│ │ exe-Progress
│ │
│ └───.Progress.eobjs
│ ├───byte
│ │ dune__exe__Progress.cmi
│ │ dune__exe__Progress.cmti
│ │
│ └───native
│ dune__exe__Progress.cmx
│ dune__exe__Progress.obj
│
└───install
└───default
└───lib
└───Progress
dune-package
META
opam
Progress.cma
progress.cmi
progress.cmt
progress.cmti
progress.cmx
Progress.cmxa
Progress.cmxs
Progress.lib
progress.ml
progress.mli
Does the lib/dune file have a public_name clause?
NAlec
January 9, 2024, 10:03am
6
Yes, This is the default setting when you initiate a library project with dune
Envoyé depuis l’application Mail Orange
I tried to build your minimal reproduction (but on linux, apparently you are on windows?) and the html files are correctly generated.
Maybe try with a verbose mode for dune? The part of dune build @doc --verbose that shows odoc invocations for me is:
Running[1]: (cd _build/default && /home/panglesd/.opam/default/bin/odoc support-files -o _doc/_html/odoc.support)
Running[2]: (cd _build/default && /home/panglesd/.opam/default/bin/ocamlc.opt -w @1..3@5..28@30..39@43@46..47@49..57@61..62@67@69-40 -strict-sequence -strict-formats -short-paths -keep-locs -g -bin-annot -I lib/.Progress.objs/byte -no-alias-deps -opaque -o lib/.Progress.objs/byte/progress.cmi -c -intf lib/progress.mli)
Running[3]: (cd _build/default/_doc/_odoc/pkg/Progress && /home/panglesd/.opam/default/bin/odoc compile --pkg Progress -o page-index.odoc ../../../_mlds/Progress/index.mld)
Running[4]: (cd _build/default/lib/.Progress.objs/byte && /home/panglesd/.opam/default/bin/odoc compile -I . -I ../../../_doc/_odoc/pkg/Progress --pkg Progress -o progress.odoc progress.cmti)
Running[5]: (cd _build/default/_doc/_html && /home/panglesd/.opam/default/bin/odoc link -I ../_odoc/pkg/Progress -I ../../lib/.Progress.objs/byte -o ../_odocls/Progress/page-index.odocl ../_odoc/pkg/Progress/page-index.odoc)
Running[6]: (cd _build/default/_doc/_html && /home/panglesd/.opam/default/bin/odoc link -I ../_odoc/pkg/Progress -I ../../lib/.Progress.objs/byte -o ../_odocls/Progress/progress.odocl ../../lib/.Progress.objs/byte/progress.odoc)
Running[7]: (cd _build/default/_doc/_html && /home/panglesd/.opam/default/bin/odoc html-generate -o . --support-uri odoc.support --theme-uri odoc.support ../_odocls/Progress/page-index.odocl)
Running[8]: (cd _build/default/_doc/_html && /home/panglesd/.opam/default/bin/odoc html-generate -o . --support-uri odoc.support --theme-uri odoc.support ../_odocls/Progress/progress.odocl)
1 Like
this might be an issue with case insensitive filesystems? can you try with:
dune init project --kind=lib progress
NAlec
January 9, 2024, 8:23pm
9
I rebuilt my test with your command line, and it did not work. See my answer to @panglesd for the log in verbose mode.
NAlec
January 9, 2024, 8:29pm
10
The verbose mode does not show me all the interresting line as in your invokation. I am indeed running it in windows :
PS H:\OCaml\progress> dune runtest
Ceci est un test 1
PS H:\OCaml\progress> dune build @doc --verbose
Shared cache: disabled
Workspace root: "H:\\OCaml\\progress"
Auto-detected concurrency: 4
Running[0]: C:\Users\XXXX\AppData\Local\Programs\DISKUV~1\usr\bin\ocamlc.opt.exe -config > C:\Users\XXXX\AppData\Local\Temp\dune_6f5f34_output
Dune context:
{ name = "default"
; kind = "default"
; profile = Dev
; merlin = true
; for_host = None
; fdo_target_exe = None
; build_dir = "default"
; toplevel_path = None
; ocaml_bin =
External
"C:\\Users\\XXXX\\AppData\\Local\\Programs\\DISKUV~1\\usr\\bin"
; ocaml =
Ok
External
"C:\\Users\\XXXX\\AppData\\Local\\Programs\\DISKUV~1\\usr\\bin\\ocaml.exe"
; ocamlc =
External
"C:\\Users\\XXXX\\AppData\\Local\\Programs\\DISKUV~1\\usr\\bin\\ocamlc.opt.exe"
; ocamlopt =
Ok
External
"C:\\Users\\XXXX\\AppData\\Local\\Programs\\DISKUV~1\\usr\\bin\\ocamlopt.opt.exe"
; ocamldep =
Ok
External
"C:\\Users\\XXXX\\AppData\\Local\\Programs\\DISKUV~1\\usr\\bin\\ocamldep.opt.exe"
; ocamlmklib =
Ok
External
"C:\\Users\\XXXX\\AppData\\Local\\Programs\\DISKUV~1\\usr\\bin\\ocamlmklib.opt.exe"
; env =
map
{ "CAML_LD_LIBRARY_PATH" :
"H:\\OCaml\\progress\\_build/install/default/lib/stublibs"
; "DUNE_OCAML_HARDCODED" :
"C:\\Users\\XXXX\\AppData\\Local\\Programs\\DISKUV~1\\usr\\lib"
; "DUNE_OCAML_STDLIB" :
"C:/Users/XXXX/AppData/Local/Programs/DISKUV~1/lib/ocaml"
; "DUNE_SOURCEROOT" : "H:\\OCaml\\progress"
; "INSIDE_DUNE" : "H:\\OCaml\\progress\\_build/default"
; "MANPATH" : "H:\\OCaml\\progress\\_build/install/default/bin"
; "OCAML_COLOR" : "always"
; "OCAMLFIND_IGNORE_DUPS_IN" :
"H:\\OCaml\\progress\\_build/install/default/lib"
; "OCAMLPATH" : "H:\\OCaml\\progress\\_build/install/default/lib"
; "OCAMLTOP_INCLUDE_PATH" :
"H:\\OCaml\\progress\\_build/install/default/lib/toplevel"
; "OPAMCOLOR" : "always"
}
; findlib_paths =
[ External
"C:\\Users\\XXXX\\AppData\\Local\\Programs\\DISKUV~1\\usr\\lib"
]
; arch_sixtyfour = true
; natdynlink_supported = true
; supports_shared_libraries = true
; ocaml_config =
{ version = "4.14.0"
; standard_library_default =
"C:/Users/XXXX/AppData/Local/Programs/DISKUV~1/lib/ocaml"
; standard_library =
"C:/Users/XXXX/AppData/Local/Programs/DISKUV~1/lib/ocaml"
; standard_runtime = "the_standard_runtime_variable_was_deleted"
; ccomp_type = "msvc"
; c_compiler = "cl"
; ocamlc_cflags = [ "-nologo"; "-O2"; "-Gy-"; "-MD" ]
; ocamlc_cppflags = [ "-D_CRT_SECURE_NO_DEPRECATE" ]
; ocamlopt_cflags = [ "-nologo"; "-O2"; "-Gy-"; "-MD" ]
; ocamlopt_cppflags = [ "-D_CRT_SECURE_NO_DEPRECATE" ]
; bytecomp_c_compiler =
[ "cl"
; "-nologo"
; "-O2"
; "-Gy-"
; "-MD"
; "-D_CRT_SECURE_NO_DEPRECATE"
]
; bytecomp_c_libraries = [ "advapi32.lib"; "ws2_32.lib"; "version.lib" ]
; native_c_compiler =
[ "cl"
; "-nologo"
; "-O2"
; "-Gy-"
; "-MD"
; "-D_CRT_SECURE_NO_DEPRECATE"
]
; native_c_libraries = [ "advapi32.lib"; "ws2_32.lib"; "version.lib" ]
; native_pack_linker =
[ "link"; "-lib"; "-nologo"; "-machine:AMD64"; "-out:" ]
; cc_profile = []
; architecture = "amd64"
; model = "default"
; int_size = 63
; word_size = 64
; system = "win64"
; asm = [ "ml64"; "-nologo"; "-Cp"; "-c"; "-Fo" ]
; asm_cfi_supported = false
; with_frame_pointers = false
; ext_exe = ".exe"
; ext_obj = ".obj"
; ext_asm = ".asm"
; ext_lib = ".lib"
; ext_dll = ".dll"
; os_type = "Win32"
; default_executable_name = "camlprog.exe"
; systhread_supported = true
; host = "x86_64-pc-windows"
; target = "x86_64-pc-windows"
; profiling = false
; flambda = false
; spacetime = false
; safe_string = true
; exec_magic_number = "Caml1999X031"
; cmi_magic_number = "Caml1999I031"
; cmo_magic_number = "Caml1999O031"
; cma_magic_number = "Caml1999A031"
; cmx_magic_number = "Caml1999Y031"
; cmxa_magic_number = "Caml1999Z031"
; ast_impl_magic_number = "Caml1999M031"
; ast_intf_magic_number = "Caml1999N031"
; cmxs_magic_number = "Caml1999D031"
; cmt_magic_number = "Caml1999T031"
; natdynlink_supported = true
; supports_shared_libraries = true
; windows_unicode = true
}
}
Actual targets:
- alias @@default
PS H:\OCaml\progress>
@NAlec @Khadyold Dune issue . To get around it, use single-quotes anytime you see an @ symbol. For example:
dune build '@doc'
# Note: In later versions of DkML you should be using:
opam exec -- dune build '@doc'
The underlying problem is most OCaml documentation assumes a Unix shell when running commands. In the popular Unix shells the @ symbol does not need to be quoted, but PowerShell uses the @ symbol for arrays (similar to Perl) and will expand to nothing (silently!) when there is no array variable named @doc.
8 Likes
Khady
January 10, 2024, 7:19am
12
Thanks for the advice, but we are running on Linux and using bash/zsh/fish, so this isn’t the cause of the problem.
I never really figured out what the problem was. Something interesting is that if I run dune build @doc in the root directory of my repo I get some html, though incomplete, for the subfolder I’m interested in. While running dune build @doc in the subfolder directly creates nothing.
Oops; replied to wrong person. Edit made!
emillon
January 10, 2024, 9:42am
14
Nice gotcha with the @ sign, thanks, I wasn’t aware of this.
Actual targets:
- alias @@default
It means that dune was asked to build @@default, which is the target when the command line is empty.
NAlec
January 10, 2024, 6:47pm
15
You rock @jbeckford ! Indeed it was it. I now have a documentation.
PS: I do not select this answer as the solution as :
I am not the initial author of the thread
Khady’s issue is then probably different than mine