[xpressive] HEAD doc issue
At the moment, CVS HEAD has this in lib/xpressive/doc/Jamfile.v2: xml xpressive : xpressive.qbk : <dependency>autodoc ; What is the reason for <dependency>autodoc here? I don't think that the target is used during generation of xpressive.xml, and I also believe that this change breaks doc build. With it, running bjam in that dir does not work. Without it works. I think this problem exists since the change was committed on 22 Oct 2006. Comments? - Volodya
Vladimir Prus wrote:
At the moment, CVS HEAD has this in lib/xpressive/doc/Jamfile.v2:
xml xpressive : xpressive.qbk : <dependency>autodoc ;
What is the reason for <dependency>autodoc here?
Without it, the qbk -> boostbook -> html translation doesn't happen when doxygen regenerates autodoc.boostbook as a result of a change in one of xpressive's headers. At least, that was the state of things when I added the dependency. I don't think that the target is used during
generation of xpressive.xml, and I also believe that this change breaks doc build. With it, running bjam in that dir does not work.
Works fine for me. What error are you seeing? -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
Vladimir Prus wrote:
At the moment, CVS HEAD has this in lib/xpressive/doc/Jamfile.v2:
xml xpressive : xpressive.qbk : <dependency>autodoc ;
What is the reason for <dependency>autodoc here?
Without it, the qbk -> boostbook -> html translation doesn't happen when doxygen regenerates autodoc.boostbook as a result of a change in one of xpressive's headers. At least, that was the state of things when I added the dependency.
I would expect the following patch to better reflect your intention. After all, the output of quickbook actually does not depend on autodoc at all, it's the output of boostbook that depends on it. Ok to commit?
I don't think that the target is used during
generation of xpressive.xml, and I also believe that this change breaks doc build. With it, running bjam in that dir does not work.
Works fine for me. What error are you seeing?
error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook' How do you initialize quickbook in your user-config.jam? The above error happens when you don't specify quickbook binary and let it be built automatically. - Volodya
Vladimir Prus wrote:
Eric Niebler wrote:
Vladimir Prus wrote:
At the moment, CVS HEAD has this in lib/xpressive/doc/Jamfile.v2:
xml xpressive : xpressive.qbk : <dependency>autodoc ;
What is the reason for <dependency>autodoc here?
Without it, the qbk -> boostbook -> html translation doesn't happen when doxygen regenerates autodoc.boostbook as a result of a change in one of xpressive's headers. At least, that was the state of things when I added the dependency.
I would expect the following patch to better reflect your intention. After all, the output of quickbook actually does not depend on autodoc at all, it's the output of boostbook that depends on it. Ok to commit?
What patch?
I don't think that the target is used during
generation of xpressive.xml, and I also believe that this change breaks doc build. With it, running bjam in that dir does not work.
Works fine for me. What error are you seeing?
error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook'
How do you initialize quickbook in your user-config.jam? The above error happens when you don't specify quickbook binary and let it be built automatically.
Oh, I point my user-config to a pre-built version of quickbook. That's probably it. -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
Works fine for me. What error are you seeing? error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook'
How do you initialize quickbook in your user-config.jam? The above error happens when you don't specify quickbook binary and let it be built automatically.
Oh, I point my user-config to a pre-built version of quickbook. That's probably it.
AFAICT, this is a recent phenomena. I too can't seem to get quickbook auto-built. An email from Volodya suggests that it's a V2 issue. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman wrote:
Eric Niebler wrote:
Works fine for me. What error are you seeing? error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook'
How do you initialize quickbook in your user-config.jam? The above error happens when you don't specify quickbook binary and let it be built automatically.
Oh, I point my user-config to a pre-built version of quickbook. That's probably it.
AFAICT, this is a recent phenomena. I too can't seem to get quickbook auto-built. An email from Volodya suggests that it's a V2 issue.
As I've indicated before "recent" may be "since Oct 22". It's a problem with quickbook.jam, which was there all the time, and while it certainly can be fixed, it's also good to have doc Jamfiles that trigger this problem to be fixed to better express the intentions, first. - Volodya
Eric Niebler wrote:
Vladimir Prus wrote:
Eric Niebler wrote:
Vladimir Prus wrote:
At the moment, CVS HEAD has this in lib/xpressive/doc/Jamfile.v2:
xml xpressive : xpressive.qbk : <dependency>autodoc ;
What is the reason for <dependency>autodoc here?
Without it, the qbk -> boostbook -> html translation doesn't happen when doxygen regenerates autodoc.boostbook as a result of a change in one of xpressive's headers. At least, that was the state of things when I added the dependency.
I would expect the following patch to better reflect your intention. After all, the output of quickbook actually does not depend on autodoc at all, it's the output of boostbook that depends on it. Ok to commit?
What patch?
Doh! Attached now. - Volodya
Vladimir Prus wrote:
Eric Niebler wrote:
Vladimir Prus wrote:
I would expect the following patch to better reflect your intention. After all, the output of quickbook actually does not depend on autodoc at all, it's the output of boostbook that depends on it. Ok to commit?
What patch?
Doh! Attached now.
------------------------------------------------------------------------
? autodoc.boostbook ? html ? xml ? xpressive.diff Index: Jamfile.v2 =================================================================== RCS file: /cvsroot/boost/boost/libs/xpressive/doc/Jamfile.v2,v retrieving revision 1.10 diff -u -p -r1.10 Jamfile.v2 --- Jamfile.v2 22 Oct 2006 03:28:00 -0000 1.10 +++ Jamfile.v2 9 Jan 2007 20:01:43 -0000 @@ -25,8 +25,6 @@ doxygen autodoc xml xpressive : xpressive.qbk - : - <dependency>autodoc ;
boostbook standalone @@ -36,4 +34,5 @@ boostbook standalone <xsl:param>toc.max.depth=3 <xsl:param>toc.section.depth=3 <xsl:param>chunk.section.depth=3 + <dependency>autodoc ;
Wouldn't that only create the necessary dependency when the docs are built "standalone"? This doesn't seem right to me. I think I said what I meant to: that the xml rule invocation depends on the doxygen one. Could you also explain how simply making one rule invocation depend on another breaks the build? Why should that be? And what's up with that error message: error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook' That's awful. How's anyone supposed to make any sense of that? -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
Vladimir Prus wrote:
Eric Niebler wrote:
Vladimir Prus wrote:
I would expect the following patch to better reflect your intention. After all, the output of quickbook actually does not depend on autodoc at all, it's the output of boostbook that depends on it. Ok to commit?
What patch?
Doh! Attached now.
------------------------------------------------------------------------
? autodoc.boostbook ? html ? xml ? xpressive.diff Index: Jamfile.v2 =================================================================== RCS file: /cvsroot/boost/boost/libs/xpressive/doc/Jamfile.v2,v retrieving revision 1.10 diff -u -p -r1.10 Jamfile.v2 --- Jamfile.v2 22 Oct 2006 03:28:00 -0000 1.10 +++ Jamfile.v2 9 Jan 2007 20:01:43 -0000 @@ -25,8 +25,6 @@ doxygen autodoc xml xpressive : xpressive.qbk - : - <dependency>autodoc ;
boostbook standalone @@ -36,4 +34,5 @@ boostbook standalone <xsl:param>toc.max.depth=3 <xsl:param>toc.section.depth=3 <xsl:param>chunk.section.depth=3 + <dependency>autodoc ;
Wouldn't that only create the necessary dependency when the docs are built "standalone"?
Looking at doc/Jamfile.v2, I see: <dependency>../libs/xpressive/doc//autodoc.xml so I suppose everything is in shape.
This doesn't seem right to me. I think I said what I meant to: that the xml rule invocation depends on the doxygen one.
How can it depend if the qbk -> xml process does not use the autodoc result in any way.
Could you also explain how simply making one rule invocation depend on another breaks the build?
Because quickbook.jam has a bug? Which bug certainly can be fixed, but using <dependency> in Jamfile like this does not seem right to me either.
Why should that be? And what's up with that error message:
error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook'
That's awful. How's anyone supposed to make any sense of that?
Just like how anyone is supposed to make any sense of failed assert in a C++ program? Not all errors can be made cristal clear, quickbook.jam in particular is deep wizardy. - Volodya
Vladimir Prus wrote:
Eric Niebler wrote:
Vladimir Prus wrote:
Index: Jamfile.v2 =================================================================== RCS file: /cvsroot/boost/boost/libs/xpressive/doc/Jamfile.v2,v retrieving revision 1.10 diff -u -p -r1.10 Jamfile.v2 --- Jamfile.v2 22 Oct 2006 03:28:00 -0000 1.10 +++ Jamfile.v2 9 Jan 2007 20:01:43 -0000 @@ -25,8 +25,6 @@ doxygen autodoc xml xpressive : xpressive.qbk - : - <dependency>autodoc ;
boostbook standalone @@ -36,4 +34,5 @@ boostbook standalone <xsl:param>toc.max.depth=3 <xsl:param>toc.section.depth=3 <xsl:param>chunk.section.depth=3 + <dependency>autodoc ;
Wouldn't that only create the necessary dependency when the docs are built "standalone"?
Looking at doc/Jamfile.v2, I see:
<dependency>../libs/xpressive/doc//autodoc.xml
so I suppose everything is in shape.
Ah, thanks.
This doesn't seem right to me. I think I said what I meant to: that the xml rule invocation depends on the doxygen one.
How can it depend if the qbk -> xml process does not use the autodoc result in any way.
Understood. But I should be able to make X depend on Y if I feel like it, even if X doesn't actually *use* Y's result, right? Not that I want to do that, I'm just trying to understand.
Could you also explain how simply making one rule invocation depend on another breaks the build?
Because quickbook.jam has a bug? Which bug certainly can be fixed, but using <dependency> in Jamfile like this does not seem right to me either.
OK. I'm still surprised to learn that there is *anything* a Jamfile can do do make it an error to say that X depends on Y. It gets back to our earlier discussion about targets and dependencies. In order for BBv2's <dependency> to work, rule authors must follow a convention, which they can get wrong. I'm guessing that's what happened here.
Why should that be? And what's up with that error message:
error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook'
That's awful. How's anyone supposed to make any sense of that?
Just like how anyone is supposed to make any sense of failed assert in a C++ program? Not all errors can be made cristal clear, quickbook.jam in particular is deep wizardy.
With an assert, at least I have the file and line information. What useful information does this error message give? I go to boost/tools/quickbook and ... what? Look in the Jamfile, I suppose. But nothing there looks wrong. And I can't make any sense of 'object(file-target)@427'. Grepping jamfiles for that won't help, either. And 427 clearly isn't a line number -- quickbook/Jamfile.v2 doesn't have that many lines. OK, I know from previous run-ins with BBv2 that this is probably one of the hidden *actual* targets that BBv2 creates for me behind the scenes. I'm not supposed to know about it, right? ;-) It's times like this that I miss good ol' makefiles, which let me deal *directly* with the abstractions I care about: targets and dependencies. Why is the deep wizardry in quickbook.jam necessary? Or is it? What it's trying to do is quite simple: "I'm about to use tool X. Make sure it's built first." Does that require deep wizardry in BBv2, or is quickbook.jam overly complicated? I'd think it should just be able to add a dependency on the "install dist-bin" rule invocation in tools/quickbook/Jamfile.v2, right? -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
boostbook standalone @@ -36,4 +34,5 @@ boostbook standalone <xsl:param>toc.max.depth=3 <xsl:param>toc.section.depth=3 <xsl:param>chunk.section.depth=3 + <dependency>autodoc ;
Wouldn't that only create the necessary dependency when the docs are built "standalone"?
Looking at doc/Jamfile.v2, I see:
<dependency>../libs/xpressive/doc//autodoc.xml
so I suppose everything is in shape.
Ah, thanks.
So, this change is OK?
This doesn't seem right to me. I think I said what I meant to: that the xml rule invocation depends on the doxygen one.
How can it depend if the qbk -> xml process does not use the autodoc result in any way.
Understood. But I should be able to make X depend on Y if I feel like it, even if X doesn't actually *use* Y's result, right? Not that I want to do that, I'm just trying to understand.
Yes, you're supposed to be able to add <dependency> on random targets to other random targets.
Could you also explain how simply making one rule invocation depend on another breaks the build?
Because quickbook.jam has a bug? Which bug certainly can be fixed, but using <dependency> in Jamfile like this does not seem right to me either.
OK. I'm still surprised to learn that there is *anything* a Jamfile can do do make it an error to say that X depends on Y. It gets back to our earlier discussion about targets and dependencies. In order for BBv2's <dependency> to work, rule authors must follow a convention, which they can get wrong. I'm guessing that's what happened here.
I'm not sure what "convention" you mean. The story is that the building of each type of rule is completely customizable, so to make extreme example, it's possible to write code that will check if there is any <dependency> property, and immediately fail.
Why should that be? And what's up with that error message:
error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook'
That's awful. How's anyone supposed to make any sense of that?
Just like how anyone is supposed to make any sense of failed assert in a C++ program? Not all errors can be made cristal clear, quickbook.jam in particular is deep wizardy.
With an assert, at least I have the file and line information. What useful information does this error message give? I go to boost/tools/quickbook and ... what? Look in the Jamfile, I suppose. But nothing there looks wrong. And I can't make any sense of 'object(file-target)@427'. Grepping jamfiles for that won't help, either. And 427 clearly isn't a line number -- quickbook/Jamfile.v2 doesn't have that many lines.
As I've said, that message is a result of a bug in quickbook.jam. What are you trying to do here? Find and fix that bug? In order to conveniently do that, you must be familiar with Boost.Build internals. Usually, this error is emitted when you mention non-existent file or target in the sources, and never caused confusion to any user. In this case, it's emitted due to quickbook.jam bug, and I don't think there's much point to try making the message more helpful in case of internal bugs, given that to fix such bug you'd need to know a bit of Boost.Build anyway.
OK, I know from previous run-ins with BBv2 that this is probably one of the hidden *actual* targets that BBv2 creates for me behind the scenes. I'm not supposed to know about it, right? ;-) It's times like this that I miss good ol' makefiles, which let me deal *directly* with the abstractions I care about: targets and dependencies.
Why is the deep wizardry in quickbook.jam necessary? Or is it? What it's trying to do is quite simple: "I'm about to use tool X. Make sure it's built first." Does that require deep wizardry in BBv2, or is quickbook.jam overly complicated? I'd think it should just be able to add a dependency on the "install dist-bin" rule invocation in tools/quickbook/Jamfile.v2, right?
I suppose there are some ways how quickbook.jam can be simplified. If you have some concrete proposals, please post them to boost-build list and I hope that João Abecasis, the quickbook.jam author, will comment. Personally, beyond this specific bug, I don't plan to improve quickbook.jam -- after all I don't use quickbook and did introduce quickbook.jam either. - Volodya
Vladimir Prus wrote:
Eric Niebler wrote:
boostbook standalone @@ -36,4 +34,5 @@ boostbook standalone <xsl:param>toc.max.depth=3 <xsl:param>toc.section.depth=3 <xsl:param>chunk.section.depth=3 + <dependency>autodoc ; Wouldn't that only create the necessary dependency when the docs are built "standalone"? Looking at doc/Jamfile.v2, I see:
<dependency>../libs/xpressive/doc//autodoc.xml
so I suppose everything is in shape.
Ah, thanks.
So, this change is OK?
Yes, I committed the change to HEAD yesterday.
Understood. But I should be able to make X depend on Y if I feel like it, even if X doesn't actually *use* Y's result, right? Not that I want to do that, I'm just trying to understand.
Yes, you're supposed to be able to add <dependency> on random targets to other random targets.
Good, thanks.
OK. I'm still surprised to learn that there is *anything* a Jamfile can do do make it an error to say that X depends on Y. It gets back to our earlier discussion about targets and dependencies. In order for BBv2's <dependency> to work, rule authors must follow a convention, which they can get wrong. I'm guessing that's what happened here.
I'm not sure what "convention" you mean. The story is that the building of each type of rule is completely customizable, so to make extreme example, it's possible to write code that will check if there is any <dependency> property, and immediately fail.
The convention I refer to is on http://boost.org/boost-build2/doc/html/bbv2/advanced/targets.html, which states: "Most main target rules in Boost.Build have the same common signature ... Some main target rules have a different list of parameters as explicitly stated in their documentation." It is the convention that most rules take "requirements" as the 3rd parameter, and if they don't, then the <dependency> property won't work. My surprise is regarding how easy it is to intentionally or inadvertently subvert this core abstraction.
error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook'
<snip>
As I've said, that message is a result of a bug in quickbook.jam. What are you trying to do here? Find and fix that bug? In order to conveniently do that, you must be familiar with Boost.Build internals.
Quickbook.jam is part of BBv2, and this is an internal error, and those should never happen. OK, I can accept that. But I don't accept that others will not want to do something similar to what quickbook.jam is doing. There should be a way to do what quickbook.jam is doing without mucking about in Jam's internals and exposing the nasty bits in mysterious error message. That's really all I'm saying.
Why is the deep wizardry in quickbook.jam necessary? Or is it? What it's trying to do is quite simple: "I'm about to use tool X. Make sure it's built first." Does that require deep wizardry in BBv2, or is quickbook.jam overly complicated? I'd think it should just be able to add a dependency on the "install dist-bin" rule invocation in tools/quickbook/Jamfile.v2, right?
I suppose there are some ways how quickbook.jam can be simplified. If you have some concrete proposals, please post them to boost-build list and I hope that João Abecasis, the quickbook.jam author, will comment.
I have occasion to do something like what quickbook.jam is doing. I want to use Wave to preprocess some code before sending it to Doxygen when building some documentation. But I want to make sure the Wave driver is built first. I thought I could just see how quickbook.jam does it, but I was put off by the complexity of it. I probably don't know enough BBv2 to make any useful suggestions, but I can try.
Personally, beyond this specific bug, I don't plan to improve quickbook.jam -- after all I don't use quickbook and did introduce quickbook.jam either.
Quickbook.jam is just one example of the larger need to be able to build a tool before a rule uses it. But I haven't done a lot of experimentation yet, so I don't know if there is an easy way to do this that João overlooked. -- Eric Niebler Boost Consulting www.boost-consulting.com
Vladimir Prus wrote:
error: Unable to find file or target named error: 'object(file-target)@427' error: referred from project at error: '/home/ghost/Work/Boost/boost/tools/quickbook'
[snip]
As I've said, that message is a result of a bug in quickbook.jam. What are you trying to do here? Find and fix that bug? In order to conveniently do that, you must be familiar with Boost.Build internals.
Usually, this error is emitted when you mention non-existent file or target in the sources, and never caused confusion to any user. In this case, it's emitted due to quickbook.jam bug, and I don't think there's much point to try making the message more helpful in case of internal bugs, given that to fix such bug you'd need to know a bit of Boost.Build anyway.
I took an initial look at it and the offending line in quickbook.jam appears to be lines 190-191, which look like this: quickbook-binary-dependencies = [ $(quickbook-main-target).generate $(property-set) ] ; quickbook-main-target is supposed to represent the main target in quickbooks own Jamfile and property-set is an argument for the run rule of the quickbook generator. I don't know how to fix it, yet. Is the problem here that I'm fiddling with the dependencies before they are built? Any ideas on how to circumvent that? I'll try to give it a longer look later... [snip]
Why is the deep wizardry in quickbook.jam necessary? Or is it? What it's trying to do is quite simple: "I'm about to use tool X. Make sure it's built first." Does that require deep wizardry in BBv2, or is quickbook.jam overly complicated? I'd think it should just be able to add a dependency on the "install dist-bin" rule invocation in tools/quickbook/Jamfile.v2, right?
I suppose there are some ways how quickbook.jam can be simplified. If you have some concrete proposals, please post them to boost-build list and I hope that João Abecasis, the quickbook.jam author, will comment.
Well, about the deep wizardry, in the general case where you want to build and use tool X, no, such deep wizardry is not needed. (I'll get back for the simpler alternative) Still, there are some specificities of quickbook that complicate matters a bit. Namely, I wanted the toolset to support on-demand compilation as well as the use of pre-compiled binaries, and I didn't want to assume that quickbook sources would always be available -- after all, this is a toolset for Boost.Build which may live outside of Boost's tree. I don't remember if any of the complexity arised from interfacing with the boostbook toolset from the outside. So, merging the toolsets could be an option to explore. There may be other places where the toolset can be simplified. I'm *not* a Boost.Build wizard and will gladly take suggestions. Anyway, as I said before, there is a simpler alternative. It works for the case where the tool will always be compiled from sources by bjam. This approach is already being used in quickbook's sketchy regression testing system. The relevant file is at boost-root/tools/quickbook/test/quickbook-testing.jam. When I wrote that, I remember looking into simplifying quickbook.jam but I didn't get anywhere... I'm still open to suggestions and comments, though. Cheers! João Abecasis
João Abecasis wrote:
Vladimir Prus wrote:
Hi João,
Anyway, as I said before, there is a simpler alternative. It works for the case where the tool will always be compiled from sources by bjam. This approach is already being used in quickbook's sketchy regression testing system. The relevant file is at boost-root/tools/quickbook/test/quickbook-testing.jam.
While you're at it... the quickbook testing is also broken. Sigh :) (Julio worked-around this issue locally by editing build/v2/tools/testing.jam and commenting out the "targets-to-remove = $(source) ;" line in the capture-rule output.) I'm doing the same. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
participants (4)
-
Eric Niebler -
Joel de Guzman -
João Abecasis -
Vladimir Prus