On Saturday 05 March 2011 13:06:24 Nick Sabalausky wrote: > "Regan Heath" <[email protected]> wrote in message > news:op.vrvpztmj54xghj@regan-pc... > > > On Thu, 03 Mar 2011 20:19:52 -0000, Andrei Alexandrescu > > > > <[email protected]> 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
