Michael Tautschnig wrote:

...

Michael Tautschnig wrote:

...

In our Debian package we'd like to get rid of the ocaml depencency which crept in because of the use of ocamldoc, even though we use --enable-interfaces=c,cxx. Could you fix the Makefiles to also take care of that while building the documentation?

Dear Michael,

I think that your problem is due to the fact thatyou are doing `make world' in the `doc' subdirectory. I have already advised against this in

http://www.cs.unipr.it/pipermail/ppl-devel/2008-September/012829.html

The point is that `make world' really means "make world" and the world includes the documentation of the OCaml interface. In case this is not the source of the problem you are observing, please give me more information to reproduce it. All the best,

Oh, yes, I see. So I guess we should build devref-configured and user-configured instead.

user-configured would be enough: devref-configured makes only sense to the PPL developers... inclusion in a binary package is pointless IMHO. Cheers,

Roberto

Michael Tautschnig wrote: [...]

Sorry, there still is an issue here: make user-configured is indeed fine and that stuff is handled nicely in the Makefile, but running make install (in the top-level directory, actually) is troublesome. This causes builds of all the other documents as well, disregarding all the configure stuff. Could you fix that? It might be an option to make the install: target a no-op as well, just as all: is!?

Thanks, Michael

I am not sure I am understanding the issue. Does the problem shows up when you are acting as a "final user" or as a "packager" of the PPL ?

I am asking because yesterday I tried installing the PPL as a final user: I downloaded the latest snapshot, I configured it with all foreign language interfaces _disabled_ (and after having _uninstalled_ ocamldoc, just to be sure) and everything went fine. That is, the manuals that need to be installed by `make install' are already built and distributed in the PPL .tar.gz.

Can you please provide us with the exact sequence of commands leading to the problem?

Thank you in advance, Enea.

Michael Tautschnig wrote:

Hi!

...

Michael Tautschnig wrote: [...]

...

Sorry, there still is an issue here: make user-configured is indeed fine and that stuff is handled nicely in the Makefile, but running make install (in the top-level directory, actually) is troublesome. This causes builds of all the other documents as well, disregarding all the configure stuff. Could you fix that? It might be an option to make the install: target a no-op as well, just as all: is!?

Thanks, Michael

I am not sure I am understanding the issue. Does the problem shows up when you are acting as a "final user" or as a "packager" of the PPL ?

Well, isn't the difference mostly in the prefix where things get installed?

...

I am asking because yesterday I tried installing the PPL as a final user: I downloaded the latest snapshot, I configured it with all foreign language interfaces _disabled_ (and after having _uninstalled_ ocamldoc, just to be sure) and everything went fine. That is, the manuals that need to be installed by `make install' are already built and distributed in the PPL .tar.gz.

Can you please provide us with the exact sequence of commands leading to the problem?

Not exact, but sufficiently close I think:

make distclean ./configure make make -C doc user-configured make install

From what you're telling I believe the problem to be in the make distclean step. I guess it deletes any pre-built docs as well. Well, not a guess only, just confirmed in my build here.

So, what should we conclude with? There's two options here IMHO:

• Have make distclean not delete any pre-built documentation. Consequently, make dist should then actually build the documents to ensure that make dist always ends up with the same tar ball.
• In our debian package, we could first move the pre-built docs to a safe location, and put them in place after make distclean.

What would you consider the preferred way?

Best, Michael

I was able to reproduce the problem and today I will try to implement the solution.

Actually, we have two problems: one is the one you are mentioning, another one is basically related to what is said in Section 27.5 of the automake manual (Files left in build directory after distclean). We have a couple of these bad dependencies of a distributed built file from a non-distributed built file.

Thank you very much for the useful feedback, Enea.

Michael Tautschnig wrote:

Hi!

...

...

Not exact, but sufficiently close I think:

make distclean ./configure make make -C doc user-configured make install

From what you're telling I believe the problem to be in the make distclean step. I guess it deletes any pre-built docs as well. Well, not a guess only, just confirmed in my build here.

So, what should we conclude with? There's two options here IMHO:

• Have make distclean not delete any pre-built documentation. Consequently, make dist should then actually build the documents to ensure that make dist always ends up with the same tar ball.
• In our debian package, we could first move the pre-built docs to a safe location, and put them in place after make distclean.

What would you consider the preferred way?

Best, Michael

I was able to reproduce the problem and today I will try to implement the solution.

Actually, we have two problems: one is the one you are mentioning, another one is basically related to what is said in Section 27.5 of the automake manual (Files left in build directory after distclean). We have a couple of these bad dependencies of a distributed built file from a non-distributed built file.

Is this issue fixed in the pre36 upload? If so, how did you fix it, or rather: Which steps should I take in the Debian package?

Thanks, Michael

Hi Michael.

The problem you were reporting should be fixed (I have tried you sequence of commands and it completed finely).

I am not really sure that we have implemented what is meant to be "The Right Thing". The Automake manual proposes two alternative solutions, each one having its pros and cons: in the future, when we better understand the tradeoffs, we might decide to change the currently adopted solution with the other one.

As for you packaging process .... I don't know whether or not you are doing a VPATH build: if in doubt, I suggest you always opt for a VPATH build.

Ciao, Enea.

[...]

[NOTE: the actual reason I am telling all of this is that I would like to know if there are better ways of solving the issue ...]

I guess I don't really know all of the story, but I simply wonder why you distribute the pre-built docs at all? Why not have them built, just like all the other stuff? To me it seems that building the documentation takes quite some time, but the checks take even more, so why bother?

One other note (I'm not sure whether this still applies to pre36, it was true as of pre35): You overwrite the all target of doc/Makefile by a no-op, which is inconsistent with the other targets, which have their usual meaning. To some extent, it makes sense because you intoduce more targets (like user-configured, etc.). But wouldn't it also be an option to just remove doc from the SUBDIRS entry in the top-level Makefile.am and have users always do the stuff manually in doc/? Which, of course, means that we need to run make -C doc clean, make -C doc install, etc. Just an idea.

Best, Michael

Michael Tautschnig wrote:

...

[...]

...

[NOTE: the actual reason I am telling all of this is that I would like to know if there are better ways of solving the issue ...]

I guess I don't really know all of the story, but I simply wonder why you distribute the pre-built docs at all? Why not have them built, just like all the other stuff? To me it seems that building the documentation takes quite some time, but the checks take even more, so why bother?

We do not want ordinary users to depend on tools such as doxygen, graphviz, etc., in order to obtain the user documentation.

If this is the case, wouldn't it actually make sense to ship a ppl-<version>-doc.tar.gz archive with pre-built documentation? I think it shouldn't be too hard to have "make dist" build an additional archive, and probably you have some script that takes care of uploading the snapshots, so this should also scale.

Not that I'd see a really big problem here, but it would just make things a bit cleaner.

...

One other note (I'm not sure whether this still applies to pre36, it was true as of pre35): You overwrite the all target of doc/Makefile by a no-op, which is inconsistent with the other targets, which have their usual meaning. To some extent, it makes sense because you intoduce more targets (like user-configured, etc.). But wouldn't it also be an option to just remove doc from the SUBDIRS entry in the top-level Makefile.am and have users always do the stuff manually in doc/? Which, of course, means that we need to run make -C doc clean, make -C doc install, etc. Just an idea.

I will have to think a bit more about this last proposal ... and maybe also read some more of the autotools' documentation.

You might want to take a look at the autobook, in case you don't know about it. I guess your knowledge is way beyond of what is presented there, but it really has some nice considerations about the general workflow. It's available online:

http://sources.redhat.com/autobook/

Best, Michael