Newcomers' Guide to GHC Development

[Tobias Dammers]

On Thu, Feb 28, 2019 at 12:43:12PM +0100, Spiwack, Arnaud wrote:
> - The dependencies instruction are too complex and long-winded. I'd start
> by: if you are a nix user, use <Alp's nix derivation>, otherwise you need
> <all this> installed [in particular, no sectioning of the dependencies!],
> see <the relevant place> to find instruction for your particular system.

One consideration with this guide is that we want to reduce the amount
of indirection - the current "getting started" guide is very close to
being just a chaotic collection of links, and if you follow them all to
exhaustion, you will get lost and confused long before you manage to
make your first successful build (I know I did). So we decided to keep
the main narrative entirely in this document, providing links to other
pages and resources only for optional steps or unusual situations.

The nix-based setup is certainly a good idea though, and I do agree that
shortening this section further would be a good thing, so I will
definitely look into it again. Please keep in mind however that we
cannot possibly cater to all potential needs; we need to strike a
balance.

> - The considerations about gitlab are mostly trivial and distract from the
> point (at this point we're trying to build GHC): simply give a git clone
> instruction from the main repository.

This was originally in the document; however, the goal here is not just
to build GHC (there are separate instructions for that), but to actually
issue a MR, and for that, you are supposed to create a fork. So we
instruct people to do that right away, and then clone the fork, rather
than clone the main repo and then modify their working copy to point to
the fork later.

> (also highlight the fact that there
> is a `--recursive`, it's easily missed, and give the `git submodule update
> --init` back up in case it was forgotten, maybe?)

Makes sense, I will add that.

> - Scrap the section called A note on Hadrian. It will just come up as
> scary. The further reading section is sufficient to point to Hadrian issues

The purpose of this is not to scare people off, but to avoid confusion
when running into unexpected issues. Hadrian *is* a complex beast, and
quite new, and experience shows that people still encounter issues. The
intended message here is "if it doesn't work, it may not be your fault".
I will reword.

> - devel2 is a good default flavour, but, when it comes up, you should also
> include a link to a documentation that says: want to do X -> use flavour Y

In the interest of keeping things short, I'm inclined to say let's not
do that, and rely on the links we're already providing. (Those do not
work properly from within the github rendering of this page, but will be
fine if viewed from within gitlab; you should also be able to figure out
what the corresponding wiki pages on the old Trac wiki are).

> - The idiom/stages seems to be a dead link, but maybe it'll work when this
> document is transferred to the wiki?

Yes, it should. I have pushed this page to a development gitlab
instance, and the link seems to work fine there. See above.

> - `git clean` is not sufficient to get to a pristine state, you need `git
> clean -xdf && git submodule foreach 'git clean -xdf'`. It's probably even
> better to just give the following one-liner: `git clean -xdf && git
> submodule foreach 'git clean -xdf' && git submodule update --init`. Maybe
> even even better, build.hs could have an option to call this one-liner?

Not a fan of tying SCM concerns into the build system. Rest seems
reasonable, although choice of git clean details may be up to the
individual (e.g. -f vs. -i).

Anyhow, thanks a lot for your feedback.