Jonathan M Davis wrote:
> Do _not_ expect your code to work if you compile with ddoc enabled.
>
> 
That's what I was afraid of ;-) The dmd command line interface suggests that you could do so, and so does Visual D. I'd hate to do have to split it into two commands, as this will probably double the compilation time.
>> - after fixing that, the linker complained with this: m:\s\d\dmd2\dmd\src\..\..\lib\phobos.lib(datetime)  Error 162: Bad Type Index reference to type 1003
>>
>> which boiled down to the linker not liking the type information written
>> for "enum DayOfWeek : ubyte". Using int as the base type fixed it, but I
>> guess this is not intended. I could not reproduce the error with a small
>> test file, though. While trying to narrow it down, I had to browse
>> through std.datetime. This is really difficult due to the unittests
>> distracting from the actual code so much. Actually I added a function to
>> visuald to remove them all shrinking the file to a quarter of its size.
>> I'm impressed by the completeness of the tests, but I would prefer to
>> find them in a separate file.
>> 
>
> DayOfWeek is supposed to be ubyte. It doesn't need more space than that. I haven't seen any problem with it before, so I don't know what the problem is there. It _should_ work just fine.
>
> 
It seems I can build phobos with dmd from the master branch and visuald from my branch and the problem goes away, so it's probably one of my debugging patches that causes the problems here.

>> - I'm still using the d_time functions (e.g. std.file.getTimes), but it
>> seems the conversion from SysTime is wrong by a month (plus an hour, but
>> that might be due to wrong timezone settings).
>> 
>
> If you find in any bugs in std.datetime, please report them with as much information as is reasonably possible - including what your local time zone is and what OS you're on (that matters a lot). As far as I know, there are no bugs in std.datetime, so if you find any, they need to be reported.
>
> 
I will try to create a small test tomorrow.

Rainer

I've seen the discussion and have no problem moving std.xml into my project if it gets the axe until it gets a replacement. I've had enough trouble debugging through it (though the worst problems were caused by something else, just triggered by std.xml due to http://d.puremagic.com/issues/show_bug.cgi?id=4298).

Rainer

Jonathan M Davis wrote:
> On Sunday 06 February 2011 16:40:25 Rainer Schuetze wrote:
> 
>> Walter Bright wrote:
>> 
>>> Which patches do you need?
>>> 
>> necessary:
>>
>> http://d.puremagic.com/issues/show_bug.cgi?id=4069
>> std.xml.Document.pretty saves empty elements with spaces and line breaks
>> http://d.puremagic.com/issues/show_bug.cgi?id=4598 std.xml check is too
>> restrictive
>> 
>
> I would point out that std.xml is likely to get the axe pretty quickly here. The consensus seems to be to get rid of it rather than leaving such a poor implementation around for people to complain about (check out the thread "std.xml should just go" on the D newsgroup). So, at minimum, it's going to be deprecated with the next release, and Andrei may even decide to remove it entirely (he did ask whether we should "nuke it" and he hasn't made clear whether that would involve an intermediate deprecated stage). Fortunately, that thread seems to have spurned some discussion on actually, finally creating a proper replacement, and it looks like Tomek Sowi?ski is working on one.
>
> So, I don't know whether std.xml is even going to be in the next release, and it is _not_ going to be high priority to fix any of it, even if it's left in as deprecated. However, given that you have provided patches for those bugs, if std.xml stays in as deprecated, it does seem reasonable that they would be applied.
>
> - Jonathan M Davis
> _______________________________________________
> dmd-beta mailing list
> dmd-beta at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/dmd-beta

On Sunday 06 February 2011 17:08:35 Rainer Schuetze wrote:
> Jonathan M Davis wrote:
> > Do _not_ expect your code to work if you compile with ddoc enabled.
> 
> That's what I was afraid of ;-) The dmd command line interface suggests that you could do so, and so does Visual D. I'd hate to do have to split it into two commands, as this will probably double the compilation time.

There's too much that has to be special cased for ddoc to be used for a normal build. For instance, if you want the documentation to be able to build on multiple platforms (which unfortunately, Phobos wasn't doing, but some of it now is), you _have_ to have a separate version(D_Ddoc) section in many cases. Also, in cases where you want to be able to clean up the documentation (std.algorithm would be a good candidate, for instance), you may be forced to have a separate, simplified version just for ddoc generation. So, ultimately, it just doesn't work to build the documentation as part of a normal build. However, it _is_ a mistake that I expect that many people will make. _I_ made it before I came to better understand the situation. But it quickly becomes obvious once you have code which is OS-specific, and you want to the same docs to be generated on all OSes.

On the bright side, ddoc builds will generally be faster than other builds because many of the functions will be stubs (at least, if the code in question uses version(D_Ddoc) at all like Phobos does).

- Jonathan M Davis

On Sunday 06 February 2011 17:25:02 Jonathan M Davis wrote:
> On Sunday 06 February 2011 17:08:35 Rainer Schuetze wrote:
> > Jonathan M Davis wrote:
> > > Do _not_ expect your code to work if you compile with ddoc enabled.
> > 
> > That's what I was afraid of ;-) The dmd command line interface suggests that you could do so, and so does Visual D. I'd hate to do have to split it into two commands, as this will probably double the compilation time.
> 
> There's too much that has to be special cased for ddoc to be used for a normal build. For instance, if you want the documentation to be able to build on multiple platforms (which unfortunately, Phobos wasn't doing, but some of it now is), you _have_ to have a separate version(D_Ddoc) section in many cases. Also, in cases where you want to be able to clean up the documentation (std.algorithm would be a good candidate, for instance), you may be forced to have a separate, simplified version just for ddoc generation. So, ultimately, it just doesn't work to build the documentation as part of a normal build. However, it _is_ a mistake that I expect that many people will make. _I_ made it before I came to better understand the situation. But it quickly becomes obvious once you have code which is OS-specific, and you want to the same docs to be generated on all OSes.
> 
> On the bright side, ddoc builds will generally be faster than other builds
> because many of the functions will be stubs (at least, if the code in
> question uses version(D_Ddoc) at all like Phobos does).

I've create an enhancement request for -D to not generae an executable - or at the very least that the dmd documentation would make it clear that -D won't necessarily generate valid code.

- Jonathan m Davis

On Feb 6, 2011, at 6:58 PM, Jonathan M Davis <jmdavisProg at gmx.com> wrote:
> 
> You really shouldn't be compiling with ddoc enabled unless you're building the documentation. There are just too many cases where you need separate declarations for ddoc - often because of differences between OSes. There are cases where the ddoc version is different _on purpose_. In the case of std.file.DirEntry.isDir, it's const on Windows because it can be. But because it can't be on Linux, the ddoc version doesn't list it that way. Now, maybe it's on negligble benefit to have isDir const on Windows given that it can't be on Linux, but there are definitely cases where ddoc is forced to be different from a particular OS' version of a declaration, simply because that declaration is different on different systems.
> 
> Do _not_ expect your code to work if you compile with ddoc enabled.

Such requirements feel like a failure of design. Are there any lessons learned from these kinds of problems? I'm sure Walter did not intend separate ddoc versions.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/dmd-beta/attachments/20110206/ed6e006c/attachment.html>

On Sunday 06 February 2011 17:44:31 Jason House wrote:
> On Feb 6, 2011, at 6:58 PM, Jonathan M Davis <jmdavisProg at gmx.com> wrote:
> > You really shouldn't be compiling with ddoc enabled unless you're building the documentation. There are just too many cases where you need separate declarations for ddoc - often because of differences between OSes. There are cases where the ddoc version is different _on purpose_. In the case of std.file.DirEntry.isDir, it's const on Windows because it can be. But because it can't be on Linux, the ddoc version doesn't list it that way. Now, maybe it's on negligble benefit to have isDir const on Windows given that it can't be on Linux, but there are definitely cases where ddoc is forced to be different from a particular OS' version of a declaration, simply because that declaration is different on different systems.
> > 
> > Do _not_ expect your code to work if you compile with ddoc enabled.
> 
> Such requirements feel like a failure of design. Are there any lessons learned from these kinds of problems? I'm sure Walter did not intend separate ddoc versions.

Then why does version(D_Ddoc) even exist? It's _built in_. And honestly, I don't know how else you could do it. In cases such as when a function only exists on one OS, you _must_ use version(D_Ddoc) if you want it to show up on the documentation when generating it on other OSes. I don't know how it could be designed otherwise without doing something drastically different with ddoc.

Granted, the situation is not entirely ideal, but I don't see any way around it without just plain doing ddoc differently. Fortunately, the need for version(D_Ddoc) blocks is relatively rare, but it definitely happens. And it wouldn't surprise me at all if it happens _more_ in Phobos as Phobos' documentation is fixed so that it builds on _all_ platforms instead of just Windows as it has in the past. So, Phobos at minimum has this problem and can't get around it. A properly documented druntime would be rife with the problem.

It's quite possible (even likely) that most D projects won't have the problem, because they won't be writing functions which are OS-specific, and they won't be trying to massage their documentation to look better in version(D_Ddoc) blocks, but there _will_ be projects with the problem. druntime (assuming that it was properly documented - which it isn't) and Phobos definitely have the problem.

So, yes, perhaps it's a design flaw in ddoc. But I don't know how it would be fixed. On the whole, it works quite well, and while it's not exactly great that building with -D doesn't necessarily generate valid code and so you need two separate builds for  the code and the documenation, I don't think that it's all that big a deal. D builds quickly, and other documentation systems such as doxygen already have to be done as separate builds. The fact that ddoc is built into the compiler is a big boon, even if you really should be running the ddoc build as a separate build.

- Jonathan M Davis

On 2/6/11 8:08 PM, Rainer Schuetze wrote:
> Jonathan M Davis wrote:
>> Do _not_ expect your code to work if you compile with ddoc enabled.
>>
> That's what I was afraid of ;-) The dmd command line interface suggests that you could do so, and so does Visual D.

We could allow that if we replaced version(D_Ddoc) with version(D_PhobosDoc) or something.

Andrei

Again, all we need to do is use a different macro than the default one. In hindsight, using D_Ddoc is a mistake as the user does not want to generate docs for Phobos but she does want to import stuff from it.

Andrei

On 2/6/11 8:44 PM, Jason House wrote:
> On Feb 6, 2011, at 6:58 PM, Jonathan M Davis <jmdavisProg at gmx.com <mailto:jmdavisProg at gmx.com>> wrote:
>>
>> You really shouldn't be compiling with ddoc enabled unless you're
>> building the
>> documentation. There are just too many cases where you need separate
>> declarations for ddoc - often because of differences between OSes.
>> There are
>> cases where the ddoc version is different _on purpose_. In the case of
>> std.file.DirEntry.isDir, it's const on Windows because it can be. But
>> because it
>> can't be on Linux, the ddoc version doesn't list it that way. Now,
>> maybe it's on
>> negligble benefit to have isDir const on Windows given that it can't
>> be on Linux,
>> but there are definitely cases where ddoc is forced to be different
>> from a
>> particular OS' version of a declaration, simply because that
>> declaration is
>> different on different systems.
>>
>> Do _not_ expect your code to work if you compile with ddoc enabled.
>
> Such requirements feel like a failure of design. Are there any lessons learned from these kinds of problems? I'm sure Walter did not intend separate ddoc versions.
>
>
>
> _______________________________________________
> dmd-beta mailing list
> dmd-beta at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/dmd-beta

On 2/6/11 9:01 PM, Jonathan M Davis wrote:
> Then why does version(D_Ddoc) even exist? It's _built in_.

It's good for one's own projects to detect whether documentation is being generated.

> And honestly, I don't
> know how else you could do it. In cases such as when a function only exists on
> one OS, you _must_ use version(D_Ddoc) if you want it to show up on the
> documentation when generating it on other OSes. I don't know how it could be
> designed otherwise without doing something drastically different with ddoc.
>
> Granted, the situation is not entirely ideal, but I don't see any way around it without just plain doing ddoc differently.

See my other emails. It's a really simple problem.


Andrei

On Sunday 06 February 2011 18:05:27 Andrei Alexandrescu wrote:
> Again, all we need to do is use a different macro than the default one. In hindsight, using D_Ddoc is a mistake as the user does not want to generate docs for Phobos but she does want to import stuff from it.

So, essentially we decide to treat druntime and Phobos differently with regards to documentation by using a different macro on the assumption that no one wants to build their ddoc documentation normally?

I'm not sure how this really solves the problem. Anyone who is building their own code with version(D_Ddoc) blocks will find the problem relatively quickly but they at least will then know how to fix it (don't build your code with -D and generate your documentation separately). For projects that _don't_ have that problem but use druntime and Phobos, wouldn't they either just use prebuilt libraries for them or use druntime and Phobos' makefiles when building them, at which point whether they use -D on their project or not has nothing to do with druntime or Phobos.

Or am I missing something here? Are people building druntime and Phobos without their makefiles? Then again, I'm not entirely clear how Rainer ran into this problem in the first place.

I would expect this to be a problem when you're building code with -D _and_ that code uses version(D_Ddoc) _and_ you want to build the code, not the documentation. Other than that, I don't see how it would be a problem. That being the case, if people either use the released binaries for druntime or phobos, or if they use the makefiles that come with them (as you'd expect), then there is no problem. Unless they're building druntime and/or phobos _with_ the documentation with the idea that they'd _also_ use the binaries, but that seems unlikely to me.

- Jonathan M Davis