Add Hacking file

[Drup]

A rendered version is available here.

This adds the beginning of a Hacking file. The goal is to contain the various information needed to start working on the compiler, which means: 1) give the essential commands/tools needed 2) point to the files/give an overview of the organization/provide "meta" consideration (for example, the note on circular dependencies in the type checker).

Most of 1) is done with this PR. However, most of 2) is not done (I simply added notes on the typechecker part). This is on purpose, and I expect people who know the various other parts of the compiler (ie. not me 😞) to fill the gaps (if only to simply say "look at this file first").

What I think is missing, besides the obvious blanks:

• A description of the various phases of the compiler (parsetree -> typedtree -> lambda -> ..). Maybe a pretty diagram.
• A description of the error handling in the compiler (this is why I made a note on Location, but it would deserve a longer description)
• "Bootstraping for dummies beginners"
• Various sections on tools, runtime, maybe pattern matching (since it's distributed in various areas of the compiler).

If this is accepted, I think this should be merged directly. The missing bits can be filled later on.

[bluddy]

I love this. Would it make sense to have a corresponding hacking file in every important directory ie. parsing, typing, bytecomp, asmcomp, byterun, asmrun?

These files could give the overall view of their particular directory in far more detail.

[dbuenzli]

Regarding the configure stuff @lpw25 gave me this tip which you may want to add. It can be in certain cases a bit more convenient than going through opam-compiler-conf.

Configure with --prefix $(pwd)/_install this allows you to make install (in _install) and run the built binaries without them trying to use the runtime system of a current OCaml install that may be in the environment which may or may not error in various funky ways (and that I once confused as a bootstrapping error in trunk).

[Drup]

@dbuenzli I don't understand. Isn't that equivalent to using compiler-conf (and eval $(opam config env --switch ...) in the appropriate terminal) ?

[bobzhang]

is _install handled magically? how is it different from ./configure -prefixpwd

[dbuenzli]

Isn't that equivalent to using compiler-conf (and eval $(opam config env --switch ...) in the appropriate terminal) ?

I don't know, I never used compiler-conf. It's just an easy way to directly hack and tests things in a repo checkout without messing up your context.

is _install handled magically?

I don't think so, could be $(pwd)/zorglub if you wish so.

[Drup]

@dbuenzli that looks pretty much equivalent to compiler-conf, but without the advantage of having an opam switch.

@bluddy Yes, this is a possibility. I put the section about typing/ inline here, because it looked simpler, but I don't really have an opinion.

[dbuenzli]

@dbuenzli that looks pretty much equivalent to compiler-conf, but without the advantage of having an opam switch.

Maybe, I never used compiler-conf. However it is infrastructure wise very lightweight (and you don't have to start peeking in others build dirs when things go wrong).

[Drup]

An improved version was merged. Closing.