hadrian: introduce make-user-oriented docs

Authored by alpmestan on Dec 13 2018, 9:25 AM.



This commit introduces Hadrian docs specifically
targeted at GHC devs who are used to building GHC with the make
build system, adapting a good chunk of the following quickstart
page we wrote over the last few months:


Diff Detail

rGHC Glasgow Haskell Compiler
Automatic diff as part of commit; lint not applicable.
Automatic diff as part of commit; unit tests not applicable.
alpmestan created this revision.Dec 13 2018, 9:25 AM
snowleopard requested changes to this revision.Dec 14 2018, 5:55 PM

I love the new docs, @alpmestan, thank you! I've left a few comments.


We no longer have the scripts based on the global package database.


GitHub tickets will no longer work. Let's replace #NNN with links to actual issues?


"make" => "Make" (for consistency)


"by" => "during"?


Perhaps, add "OR" to emphasise that only one command needs to be run, i.e. "OR using the actual path".


Perhaps, it's worth to clarify this in a comment too:

# via command-line flag
# OR via environment variable TEST

Same here


I'm curious: is this a frequently used command? If yes, why?


If my understanding is correct, this line is equivalent to the above Make command, but the first one is not. Shall we delete it or alternatively add the corresponding Make equivalent above?

This revision now requires changes to proceed.Dec 14 2018, 5:55 PM

Some of your comments apply to the contents that was already there, and I don't feel like using this diff to freshen up the README entirely. I did remove things that were obviously outdated though. In particular, we haven't migrated some of the issues yet and we therefore don't have a trac ticket to point to yet.


"by the stage 1 compiler" would be the long form. Perhaps it's not clear enough and I should just use the long form?


Indeed, will do.


I just picked an example of a generated file, because so far in the document those have not been covered. They're usually not all that fascinating so I just used the first one that came to my mind.


Well, with Make I think both the stage 1 and 2 compilers use the same platformConstants file, while they can each have their own in hadrian, because of the _build dir's layout.

Some of your comments apply to the contents that was already there, and I don't feel like using this diff to freshen up the README entirely.

I see, but I don't see any harm in doing some quick fixes like dropping the reference to non-existent build.global-db.* from README.

Feel free to do this in a separate patch, of course, but then I hope my comments won't be lost!


"by the stage 1 compiler"

Yep, this is clearer than just "by stage1".

However, I think it would be useful to reinforce the main rule:

Everything built during Stage1 is placed into _build/stage1.

That is, not just files built by the Stage1 compiler.


I see, thanks for clarifying!


Yes, you are right, Make produces only one platformConstants. (Maybe this is what Hadrian should do too.)

alpmestan updated this revision to Diff 19168.Dec 17 2018, 5:38 AM
alpmestan marked 15 inline comments as done.
  • address Andrey's feedback
snowleopard accepted this revision.Dec 17 2018, 6:31 PM

Thanks, Alp! I think this is ready to land.

This revision is now accepted and ready to land.Dec 17 2018, 6:31 PM
This revision was automatically updated to reflect the committed changes.