split HACKING.adoc with parts in {parsing,typing}/HACKING.adoc
In the interest of keeping HACKING.adoc not-too-long and general-purpose, advice on modifying specific sub-systems of the compiler distribution should be moved to the directory of this sub-system. This PR also clarifies the relations between the README, INSTALL, HACKING and CONTRIBUTING documents.master
Gabriel Scherer
parent
237c7d0e84
commit
d7acff30bc
|
|
@ -7,9 +7,17 @@ OCaml distribution. These are just guidelines, not rules, use your
|
|||
best judgment and feel free to propose changes to this document itself
|
||||
in a pull request.
|
||||
|
||||
This document assumes that you already have a patch against the
|
||||
compiler distribution sources that you wish to submit to the OCaml
|
||||
maintainers upstream. If you are looking for a document on how to
|
||||
build the compiler distribution from sources and install it, see
|
||||
[INSTALL.adoc](INSTALL.adoc) instead. If you are looking for
|
||||
a document on how to hack on the compiler distribution sources, see
|
||||
[HACKING.adoc](HACKING.adoc) instead.
|
||||
|
||||
## Contribution
|
||||
|
||||
Adding or modifying code is far from the only way to contribute to the
|
||||
Modifying its sources is far from the only way to contribute to the
|
||||
OCaml distribution. Bug reports (in particular when they come with
|
||||
a reproducible example), simple typos or clarifications in the
|
||||
documentation also help, and help evaluating and integrating existing
|
||||
|
|
@ -18,8 +26,8 @@ forums, or asking the good questions that highlight deficiencies in
|
|||
existing documentations, also help. We currently have more
|
||||
contributors willing to propose changes than contributors willing to
|
||||
review other people's changes, so more eyes on the existing change
|
||||
requests is a good way to increase the integration bandwidth of external
|
||||
contributions.
|
||||
requests is a good way to increase the integration bandwidth of
|
||||
external contributions.
|
||||
|
||||
There are also many valuable ways to contribute to the wider OCaml
|
||||
ecosystem that do not involve changes to the OCaml distribution.
|
||||
|
|
@ -152,7 +160,7 @@ of the OCaml distribution.
|
|||
|
||||
### Changelog
|
||||
|
||||
Any user-visible change should have a Changelog entry:
|
||||
Any user-visible change should have a `Changes` entry:
|
||||
|
||||
- in the right section (named sections if major feature, generic
|
||||
"Bug fixes" and "Feature requests" otherwise)
|
||||
|
|
|
|||
61
HACKING.adoc
61
HACKING.adoc
|
|
@ -5,6 +5,9 @@ information for people willing to inspect or modify the compiler
|
|||
distribution's codebase. Feel free to improve it by sending change
|
||||
proposals for it.
|
||||
|
||||
If you already have a patch that you would like to contribute to the
|
||||
official distribution, please see link:CONTRIBUTING.md[].
|
||||
|
||||
=== Your first compiler modification
|
||||
|
||||
0. Create a new git branch to store your changes.
|
||||
|
|
@ -80,7 +83,7 @@ newcomers. Here are various potential projects:
|
|||
various parts of the compiler from the angle of a specific aspect or
|
||||
feature.
|
||||
|
||||
Again, reviewing small or medium-sized pull requests is accessible
|
||||
Again, reviewing small or medium-sized pull requests is accessible
|
||||
to anyone with OCaml programming experience, and helps maintainers
|
||||
and other contributors. If you also submit pull requets yourself,
|
||||
a good discipline to follow is to review at least as many pull
|
||||
|
|
@ -88,44 +91,34 @@ newcomers. Here are various potential projects:
|
|||
|
||||
== Structure of the compiler
|
||||
|
||||
The compiler code base can be intimidating at first sight. Here are a few pointers to get started.
|
||||
The compiler code base can be intimidating at first sight. Here are
|
||||
a few pointers to get started.
|
||||
|
||||
=== Compilation pipeline
|
||||
|
||||
==== The driver -- link:driver/[]
|
||||
|
||||
==== The frontend -- link:parsing/[] and link:typing/[]
|
||||
The driver contains the "main" function of the compilers that drive
|
||||
compilation. It is in charge of parsing the command-line arguments,
|
||||
and then composing the compiler passes according to the invoked
|
||||
command-line, by calling functions from the various parts of the
|
||||
compiler described below.
|
||||
|
||||
The frontend handles parsing and typing of the OCaml code. It also contains various utilities needed for the later phases of the compiler. Most modules are self contained and straightforward.
|
||||
==== Parsing -- link:parsing/[]
|
||||
|
||||
link:parsing/parsetree.mli[Parsetree] and link:parsing/asttypes.mli[Asttypes]:: Parsetree is an AST of the surface language of OCaml. It is well annotated with examples and is a mandatory read before any further exploration of the compiler.
|
||||
Parses source files and produces an Abstract Syntax Tree (AST)
|
||||
(link:parsing/parsetree.mli[] has lot of helpful comments). See
|
||||
link:parsing/HACKING.adoc[].
|
||||
|
||||
link:parsing/location.mli[Location]:: This module contains utilities related to locations and error handling. In particular, it contains handler that are used for all the error reporting in the compiler.
|
||||
The logic for Camlp4 and Ppx preprocessing is not in link:parsing/[],
|
||||
but in link:driver/[], see link:driver/pparse.mli[],
|
||||
link:driver/pparse.mli[].
|
||||
|
||||
==== The typechecker -- link:typing/[]
|
||||
==== Typing -- link:typing/[]
|
||||
|
||||
The implementation of the OCaml typechecker is complex. Modifying it will need a good understanding of the OCaml type system and type inference. Here is a reading list to ease your discovery of the typechecker:
|
||||
|
||||
http://caml.inria.fr/pub/docs/u3-ocaml/index.html[Using, Understanding, and Unraveling the OCaml Language by Didier Rémy] :: This book provides (among other things) a formal description of parts of the core OCaml language, starting by a simple Core ML.
|
||||
|
||||
http://okmij.org/ftp/ML/generalization.html[Efficient and Insightful Generalization by Oleg Kiselyov] :: This article describes the basis of the algorithm used by the OCaml type checker.
|
||||
|
||||
After that, the best is to dive right in. There is no real "entry point", but understanding of both the parsetree and the typedtree is necessary.
|
||||
|
||||
The datastructures ::
|
||||
link:typing/types.mli[Types] and link:typing/typedtree.mli[Typedtree] are the two main datastructures in the typechecker. They correspond to the surface language annotated with all the information needed for type checking and type inference. link:typing/env.mli[Env] contains all the environments that are used in the typechecker. Each node in the typedtree is annotated with the local environment.
|
||||
|
||||
Core utilities ::
|
||||
link:typing/btype.mli[Btype] and link:typing/ctype.mli[Ctype] contains the various low-level function needed for typing, in particular related to levels, unification and backtracking. link:typing/mtype.mli[Mtype] contains utilities related to modules.
|
||||
|
||||
Inference and checking::
|
||||
The `Type..` modules are related to inference and typechecking, each for a different part of the language: link:typing/typetexp.mli[Typetexp] for type expressions, link:typing/typecore.mli[Typecore] for the core language, link:typing/typecore.mli[Typemod] for modules, link:typing/typedecl.mli[Typedecl] for type declarations and finally link:typeclass.mli[Typeclass] for the object system.
|
||||
|
||||
Inclusion/Module subtyping::
|
||||
Handling of inclusion relations are separated in the `Include...` modules: link:typing/includecore.ml[Includecore] for the type and value declarations, link:typing/includemod.mli[Includemod] for modules and finally link:typing/includeclass.mli[Includeclass] for the object system.
|
||||
|
||||
Note on dependencies between modules::
|
||||
Most of the modules presented above are inter-dependent with each other. Since OCaml prevents circular dependencies between files, the implementation uses forward declarations, implemented with references to functions that are filled later on. An example can be seen in link:typing/typecore.mli[Typecore.type_module], which is filled in link:typing/typecore.mli[Typemod].
|
||||
Type-checks syntactic AST and produces a typed representation
|
||||
(link:parsing/typedtree.mli[] has some helpful comments). See
|
||||
link:typing/HACKING.adoc[].
|
||||
|
||||
==== The bytecode compiler -- link:bytecomp/[]
|
||||
|
||||
|
|
@ -137,13 +130,19 @@ Most of the modules presented above are inter-dependent with each other. Since O
|
|||
|
||||
link:stdlib/[]:: The standard library. Each file is mostly independent and should not need further knowledge.
|
||||
|
||||
link:otherlibs/[]:: External libraries such as `unix`, `threads`, `dynlink`, `str` and `bigarray`.
|
||||
link:otherlibs/[]:: External libraries such as `unix`, `threads`,
|
||||
`dynlink`, `str` and `bigarray`.
|
||||
|
||||
=== Tools
|
||||
|
||||
link:lex/[]:: The `ocamllex` lexer generator.
|
||||
|
||||
link:yacc/[]:: The `ocamlyacc` parser generator. Please consider contributing to link:http://gallium.inria.fr/~fpottier/menhir/[menhir] instead.
|
||||
link:yacc/[]:: The `ocamlyacc` parser generator. We do not recommend
|
||||
using it for user projects in need of a parser generator. Please
|
||||
consider using and contributing to
|
||||
link:http://gallium.inria.fr/~fpottier/menhir/[menhir] instead, which
|
||||
has tons of extra features, lets you write more readable grammars, and
|
||||
has excellent documentation.
|
||||
|
||||
=== Complete file listing
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
= Installing OCaml on a Unix(-like) machine =
|
||||
= Installing OCaml from sources on a Unix(-like) machine =
|
||||
|
||||
== PREREQUISITES
|
||||
|
||||
|
|
|
|||
|
|
@ -113,4 +113,5 @@ using (machine type, etc).
|
|||
|
||||
You can also contact the implementors directly at mailto:caml@inria.fr[].
|
||||
|
||||
For information on contributing to OCaml, see the file link:CONTRIBUTING.md[].
|
||||
For information on contributing to OCaml, see link:HACKING.md[] and
|
||||
link:CONTRIBUTING.md[].
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
link:parsing/parsetree.mli[Parsetree] and link:parsing/asttypes.mli[Asttypes]::
|
||||
Parsetree is an AST of the surface language of OCaml. It is well
|
||||
annotated with examples and is a recommended read before any further
|
||||
exploration of the compiler.
|
||||
|
||||
link:parsing/location.mli[Location]:: This module contains utilities
|
||||
related to locations and error handling. In particular, it contains
|
||||
handler that are used for all the error reporting in the compiler.
|
||||
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
The implementation of the OCaml typechecker is complex. Modifying it
|
||||
will need a good understanding of the OCaml type system and type
|
||||
inference. Here is a reading list to ease your discovery of the
|
||||
typechecker:
|
||||
|
||||
http://caml.inria.fr/pub/docs/u3-ocaml/index.html[Using, Understanding, and Unraveling the OCaml Language by Didier Rémy] ::
|
||||
This book provides (among other things) a formal description of parts
|
||||
of the core OCaml language, starting by a simple Core ML.
|
||||
|
||||
http://okmij.org/ftp/ML/generalization.html[Efficient and Insightful Generalization by Oleg Kiselyov] ::
|
||||
This article describes the basis of the type inference algorithm used
|
||||
by the OCaml type checker. It is a recommended read if you want to
|
||||
understand the type-checker codebase, in particular its handling of
|
||||
polymorphism/generalization.
|
||||
|
||||
After that, the best is to dive right in. There is no real "entry
|
||||
point", but understanding of both the parsetree and the typedtree is
|
||||
necessary.
|
||||
|
||||
The datastructures ::
|
||||
link:typing/types.mli[Types] and link:typing/typedtree.mli[Typedtree]
|
||||
are the two main datastructures in the typechecker. They correspond to
|
||||
the surface language annotated with all the information needed for
|
||||
type checking and type inference. link:typing/env.mli[Env] contains
|
||||
all the environments that are used in the typechecker. Each node in
|
||||
the typedtree is annotated with the local environment.
|
||||
|
||||
Core utilities ::
|
||||
link:typing/btype.mli[Btype] and link:typing/ctype.mli[Ctype] contain
|
||||
the various low-level function needed for typing, in particular
|
||||
related to levels, unification and
|
||||
backtracking. link:typing/mtype.mli[Mtype] contains utilities related
|
||||
to modules.
|
||||
|
||||
Inference and checking::
|
||||
The `Type..` modules are related to inference and typechecking, each
|
||||
for a different part of the language:
|
||||
link:typing/typetexp.mli[Typetexp] for type expressions,
|
||||
link:typing/typecore.mli[Typecore] for the core language,
|
||||
link:typing/typecore.mli[Typemod] for modules,
|
||||
link:typing/typedecl.mli[Typedecl] for type declarations and finally
|
||||
link:typeclass.mli[Typeclass] for the object system.
|
||||
|
||||
Inclusion/Module subtyping::
|
||||
Handling of inclusion relations are separated in the `Include...`
|
||||
modules: link:typing/includecore.ml[Includecore] for the type and
|
||||
value declarations, link:typing/includemod.mli[Includemod] for modules
|
||||
and finally link:typing/includeclass.mli[Includeclass] for the object
|
||||
system.
|
||||
|
||||
Note on dependencies between modules::
|
||||
Most of the modules presented above are inter-dependent with each
|
||||
other. Since OCaml prevents circular dependencies between files, the
|
||||
implementation uses forward declarations, implemented with references
|
||||
to functions that are filled later on. An example can be seen in
|
||||
link:typing/typecore.mli[Typecore.type_module], which is filled in
|
||||
link:typing/typecore.mli[Typemod].
|
||||
Loading…
Reference in New Issue