ocamldoc: use ocamldoc.opt when available to build documentation and manpages by gasche · Pull Request #8837 · ocaml/ocaml

gasche · 2019-07-27T20:09:56Z

This PR tweaks the build system of ocamldoc to use ocamldoc.opt to build documentation when available, and it also tweaks the root Makefile to build manpages (whose compilation time has been a hot topic of discussion in #8835) later in the build, when ocamldoc.opt may be available.

Before that PR, building the manpages takes 14s on my machine (it was 16s before #8836). After that PR, it takes 4s (5s before #8836). All other document targets benefit (html_doc, introduced to test HTML rendering of documentation comments, goes from 36s to 8.5s) but they are not part of the default build.

To check this PR I tried to run all the tests from ocamldoc's Makefile; it looks like some of them have bitrotten away, and I removed one that could not be run at all.

dra27 · 2019-07-27T20:39:50Z

I've never been sure why opam-repository does this, but the ocaml-base-compiler packages all do make world followed by make world.opt - as they stand, they'd fail to take advantage of this change, therefore (hopefully they've just done it that by accident).

dra27

In these autoconf days, it would be good if we were heading towards ./configure && make all && make install - i.e. no more world, opt, opt.opt, world.opt, etc. but configure properly determining what's to be built and then make just doing it. That would certainly make this change simpler, but it's a very clear win - modulo the fix I note.

ocamldoc/Makefile

dra27 · 2019-07-27T20:46:33Z

ocamldoc/Makefile

-  else
-    OCAMLDOC_RUN=$(OCAMLRUN) ./$(OCAMLDOC)
-  endif
+  OCAMLDOC_RUN_BYTE=$(OCAMLRUN) -I $(ROOTDIR)/otherlibs/$(UNIXLIB) -I $(ROOTDIR)/otherlibs/str ./$(OCAMLDOC)


This breaks make world on a --disable-shared build. The issue is that when shared support isn't available, ocamldoc is built with -custom so mustn't be invoked via ocamlrun

Note: I can't find where in the Makefile logic -custom is used in absence of shared libraries (or at all) to compile ocamldoc. (There is logic to that effect in Makefile.tools but as far as I can tell it's not used to build ocamldoc.)

It's done using the "lib_custom" flag in and str.cmo & unix.cmo - on a system without shared linking, using the .cmo forces -custom mode (see https://github.com/ocaml/ocaml/blob/trunk/file_formats/cmo_format.mli#L55 and https://github.com/ocaml/ocaml/blob/trunk/bytecomp/bytelink.ml#L55)

Wow. Thanks. I'll definitely add a comment in the ocamldoc Makefile to point this out.

Makefile

gasche · 2019-07-28T16:13:18Z

@dra27, do you approve of this change? The root-Makefile part of the PR conflicts somewhat with #8839, and I think this one is "more ready", so I would be interested in building on top of it instead of in parallel.

dra27 · 2019-07-28T17:59:15Z

I do entirely approve, but I’d like Sébastien to have a chance to comment, if that’s ok?

gasche · 2019-07-28T19:06:03Z

That's fine with me, thanks.

(Re. make all && make install: it seems like a fine goal, but I'm not volunteering to do the restructuration work. I don't think this PR or the sucessor to #8839 would make it any easier or more difficult, given that they are not invasive -- they don't change the Makefile structure.)

xavierleroy · 2019-07-29T18:31:40Z

Just to annoy everyone: what happens with platforms where ocamlopt is not supported? There was a time when Debian (people who care about man pages) cared about hppa, m68k, and ia64, while ocamlopt support for these platforms was removed. It was important for them that a fully-functional, bytecode-only OCaml system could be built. In all honesty, I don't know if they or anyone else still care.

gasche · 2019-07-30T05:57:38Z

If ocamldoc.opt is not present, then it is not used -- see the logic below.

ifeq "$(wildcard $(OCAMLDOC_OPT))" ""
  OCAMLDOC_RUN=$(OCAMLDOC_RUN_BYTE)
else
  OCAMLDOC_RUN=$(OCAMLDOC_RUN_OPT)
endif

I'm industrializing this technique in #8840.

gasche · 2019-08-09T09:19:25Z

(cc @shindere)

shindere · 2019-08-27T14:48:00Z

Sorry for the delay on this. @gache: would you mind fixing the confilict in Changes, rebase and perhaps cleaning up the history a bit? I would then be happy to approve/merge.

…s builtin

gasche · 2019-08-30T07:58:15Z

Thanks @shindere; I rebased and updated the PR.

Most commits are independent of each other and have their specific purpose, but I merged the Changes-entry commit into the main commit.

The odoc_fhtml file required by this test seems to have been part of the ocamldoc distribution sometime in the distant past (see 27934ab from 2002) but I can't find traces of it in the git history of the compiler distribution.

shindere · 2019-08-30T08:05:06Z

Thanks, @gasche. Waiting for CI to be happy and then either I can merge or any body else includinng you can do so.

shindere · 2019-08-30T12:57:21Z

David Allsopp (2019/08/30 05:42 -0700):

Merged #8837 into trunk.

Thanks a lot @dra27 and thanks for having suggeted to let me review the code!

ocamldoc: use ocamldoc.opt when available to build documentation and manpages (cherry picked from commit 354bf8e)

gasche force-pushed the manpage-ocamldoc.opt branch from 8e4cdf1 to 99e85d5 Compare July 27, 2019 20:12

gasche mentioned this pull request Jul 27, 2019

New configure option to disable building and installing library manpages #8835

Merged

dra27 reviewed Jul 27, 2019

View reviewed changes

Makefile Outdated Show resolved Hide resolved

gasche force-pushed the manpage-ocamldoc.opt branch from 99e85d5 to 591f3f8 Compare July 28, 2019 06:51

dra27 mentioned this pull request Jul 28, 2019

Use ocaml{c,opt}.opt when available to build ocamldoc #8839

Closed

xavierleroy changed the title ~~ocamldoc: use ocamldot.opt when available to build documentation and manpages~~ ocamldoc: use ocamldoc.opt when available to build documentation and manpages Jul 29, 2019

dra27 mentioned this pull request Jul 30, 2019

Test make world on Inria CI #8845

Merged

gasche added 2 commits August 30, 2019 09:57

ocamldoc/Makefile: manpages don't need generators anymore, odoc_man i…

5e53c93

…s builtin

ocamldoc: build manpages explicitly in root Makefile

2bbf7ca

gasche force-pushed the manpage-ocamldoc.opt branch from 212b88b to ab217a7 Compare August 30, 2019 07:57

gasche added 2 commits August 30, 2019 09:59

ocamldoc/Makefile: use ocamldoc.opt when available

bb1be5d

ocamldoc: remove an obsolete test

4cde3f7

The odoc_fhtml file required by this test seems to have been part of the ocamldoc distribution sometime in the distant past (see 27934ab from 2002) but I can't find traces of it in the git history of the compiler distribution.

shindere approved these changes Aug 30, 2019

View reviewed changes

gasche force-pushed the manpage-ocamldoc.opt branch from ab217a7 to 9067d0e Compare August 30, 2019 08:18

explanatory comment on when 'ocamlrun ocamldoc' fails

9067d0e

dra27 merged commit 354bf8e into ocaml:trunk Aug 30, 2019

dra27 mentioned this pull request Feb 26, 2020

Correct implementation of --disable-stdlib-manpages #9335

Merged

dra27 added a commit to dra27/ocaml that referenced this pull request Jul 28, 2024

Merge pull request ocaml#8837 from gasche/manpage-ocamldoc.opt

c179dc7

ocamldoc: use ocamldoc.opt when available to build documentation and manpages (cherry picked from commit 354bf8e)

dra27 added a commit to dra27/ocaml that referenced this pull request Jul 28, 2024

Merge pull request ocaml#8837 from gasche/manpage-ocamldoc.opt

bbc07e5

ocamldoc: use ocamldoc.opt when available to build documentation and manpages (cherry picked from commit 354bf8e)

dra27 added a commit to dra27/ocaml that referenced this pull request Jul 28, 2024

Merge pull request ocaml#8837 from gasche/manpage-ocamldoc.opt

a53bac5

ocamldoc: use ocamldoc.opt when available to build documentation and manpages (cherry picked from commit 354bf8e)

dra27 added a commit to dra27/ocaml that referenced this pull request Jul 28, 2024

Merge pull request ocaml#8837 from gasche/manpage-ocamldoc.opt

6323c6d

ocamldoc: use ocamldoc.opt when available to build documentation and manpages (cherry picked from commit 354bf8e)

dra27 added a commit to dra27/ocaml that referenced this pull request Aug 4, 2024

Merge pull request ocaml#8837 from gasche/manpage-ocamldoc.opt

e57cdb7

ocamldoc: use ocamldoc.opt when available to build documentation and manpages (cherry picked from commit 354bf8e)

dra27 added a commit to dra27/ocaml that referenced this pull request Aug 4, 2024

Merge pull request ocaml#8837 from gasche/manpage-ocamldoc.opt

8918d96

ocamldoc: use ocamldoc.opt when available to build documentation and manpages (cherry picked from commit 354bf8e)

dra27 added a commit to dra27/ocaml that referenced this pull request Aug 4, 2024

Merge pull request ocaml#8837 from gasche/manpage-ocamldoc.opt

74e2708

ocamldoc: use ocamldoc.opt when available to build documentation and manpages (cherry picked from commit 354bf8e)

Conversation

gasche commented Jul 27, 2019

Uh oh!

dra27 commented Jul 27, 2019

Uh oh!

dra27 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dra27 Jul 27, 2019

Choose a reason for hiding this comment

Uh oh!

gasche Jul 28, 2019

Choose a reason for hiding this comment

Uh oh!

dra27 Jul 28, 2019

Choose a reason for hiding this comment

Uh oh!

gasche Jul 28, 2019

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gasche commented Jul 28, 2019

Uh oh!

dra27 commented Jul 28, 2019

Uh oh!

gasche commented Jul 28, 2019

Uh oh!

xavierleroy commented Jul 29, 2019

Uh oh!

gasche commented Jul 30, 2019

Uh oh!

gasche commented Aug 9, 2019

Uh oh!

shindere commented Aug 27, 2019 via email

Uh oh!

gasche commented Aug 30, 2019

Uh oh!

shindere commented Aug 30, 2019 via email

Uh oh!

shindere commented Aug 30, 2019 via email

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants