Google Summer of Code

[Jonathan M Davis]

On Saturday 05 March 2011 13:06:24 Nick Sabalausky wrote:
> "Regan Heath" <regan at netmail.co.nz> wrote in message
> news:op.vrvpztmj54xghj at regan-pc...
> 
> > On Thu, 03 Mar 2011 20:19:52 -0000, Andrei Alexandrescu
> > 
> > <SeeWebsiteForEmail at erdani.org> wrote:
> >> On 3/3/11 2:08 PM, Walter Bright wrote:
> >>> Regan Heath wrote:
> >>>> Ok, found the original code. How do I go about submitting it to
> >>>> phobos?
> >>> 
> >>> Thanks!
> >>> 
> >>> I suggest:
> >>> 
> >>> 1. Join the phobos mailing list
> >>> 2. Propose package and module names
> >>> 3. Fork https://github.com/D-Programming-Language/phobos
> >>> 4. Check your original code into your fork under those package and
> >>> module names
> >>> 5. Develop them!
> >>> 6. Issue pull requests
> >>> 
> >>> I'm a newbie with github, but I think that is the correct workflow.
> >>> Correct me if I'm wrong!
> >> 
> >> That's the technical part of it. The bulk of the process is making a
> >> proposal on this group and having the design, implementation, and
> >> documentation discussed and improved following feedback.
> >> 
> >> If Regan does not have the time to commit to such, he could donate the
> >> code to someone else to take it through this process. Alternatively, if
> >> some components are small enough and of obvious value they can be
> >> adopted without going through a stringent process.
> >> 
> >> What definitely doesn't scale is Phobos acquiring unfinished pieces of
> >> functionality, knocking them into shape, and subsequently maintaining
> >> them. (Of course, it could happen that someone on the Phobos team does
> >> that, but by doing so the member becomes the virtual owner of that
> >> functionality.)
> > 
> > Ok.. I am on windows.  So, I installed TortoiseGIT and msysgit 1.7.4.
> > Then I worked on the original code, make it compile with the latest D
> > compiler, fixed some big endian issues which were known but never
> > accounted for in the original code, fixed a bug where I was passing a
> > uint[8] and expecting modification to stick, whereas it now requires
> > 'ref' then I started adding comments for ddoc .. and ran into:
> > 
> > http://d.puremagic.com/issues/show_bug.cgi?id=5701
> > 
> > I thought perhaps I could resolve it myself by rebuilding
> > druntime+phobos, and when that made no difference I rebuilt dmd.. also
> > to no avail.  I guess I can downgrade to a previous version and try
> > that, but I have no guarantee that will work.  It's a bit annoying.
> > 
> > Anyway, assuming I have some code and some documentation do I just start
> > a new thread here and ask for comments?
> 
> It's an unintentionally well-kept secret that builing docs needs to be done
> as a separate step from actual compiling (due to version(DDOC) tricks).

Yes. For a variety of reasons, some code _must_ have a separate version for the 
documentation. Phobos has done this for a while, I think, but the amount that 
it's being done has bee increasing, making the odds of running into it higher.

With the next release, Phobos should be using version(StdDoc) to version its 
documentation instead of the standard version(D_Ddoc), so building with -D will 
work for user code again as long as that user code doesn't need to use 
version(D_Ddoc) in a manner which results in unlinkable code. However, druntime 
and Phobos will continue to have their documentation built separately from their 
normal builds, and until the next release, user code will (under some 
circumstances) have to be built without -D if you want it to link.

Personally, I voted for -D not resulting in valid code at all so that it would 
just be blindingly clear that -D shouldn't be done at the same time as code 
generation (kind of like -cov or -unittest, though you do actually run the code 
with those - it's just not exactly normal code). But it was decided that enough 
people wanted to generate documentation at the same time that they generate code 
(without recompiling) and few enough people will have to have version(D_Ddoc) 
blocks which result in unlinkable code that it was better to make it so that 
Phobos and druntime used a different symbol for versioning documenation. It just 
wasn't done in time for the release (and actually Andrei's pull request which 
does it hasn't been pulled in yet, since he has other changes that need to be 
made to it before it gets pulled in, so the git version still uses 
version(D_Ddoc); it won't by the next release though).

So, for the current release, it's not a good idea to use -D when compiling 
actual code (and if you ever use version(D_Ddoc) yourself, it won't be a good 
idea ever), but that will be fixed by the next release. In the meantime, you can 
just skip using -D except when you're specifically generating documentation.

- Jonathan M Davis