Thoughts on the Contributing page

[Tobias Dammers]

On Wed, Jan 30, 2019 at 07:09:25AM +1100, Julian Leviston wrote:
> As a recent newcomer, it’d be nice to have the option there as a link
> with a warning sign “here be dragons, but try this out if you’re
> interested”.  I tried it. It seems better than regular make already (I
> don’t have to guess at appropriate concurrency, for example, I just
> throw -j at it and it works it out assumedly because GHC can work out
> the number of capabilities), and it seems to work out which builds it
> needs to do next automatically.  Both those things - at least - are
> more beginner friendly than manually cloning the mk/build.mk file,
> running ./boot && ./configure && make -j8 then adjusting the
> mk/build.mk file again to get make to be faster.
>
> So, FWIW, I say put the link on the page at the top as an alternative,
> mark it with a warning saying something along the lines of that it
> might not work, but it’s the future, and it’s simpler and easier if it
> does, and feel free to try it out, then fallback to make. There are
> plenty of sharp rocks for beginners, and ironically the existing
> make-based build system is probably one of them. (Having said that,
> it’s very helpful to know the stages of compilation, so hopefully
> whatever docs we arrive at will point the beginner to something
> explaining what’s going on as they do their first bootstrapping build,
> for the curious.

Actually, after talking to both the Simons as well as Alp, one of the
core people in the Hadrian project (if not the mastermind), we
tentatively decided to write the Newcomers' Guide for Hadrian, not Make.
In principle, Hadrian should be able to do everything that is needed for
this, and the "regular" code paths have been tested extensively, and as
you have noticed, it is a lot more user friendly. We may still want to
link to the Make-based build instructions somewhere, but present
Hadrian as the default option.

A short explanation of build stages will of course still be in the Guide
- they are just as relevant to Hadrian as they are to the Make build
system. However, the tutorial is quite long as it is already, so I want
to keep it as short as possible, delegating in-depth explanations to
other (ideally existing) wiki pages.

If you like, you can follow along with my progress:

https://github.com/tdammers/ghc-wiki/blob/wip/newcomers/newcomers-tutorial.md