HACKING.adoc: plenty of changes suggested by David Allsopp's review
Gabriel Scherer
parent
1e8016e67d
commit
b9f9d707c8
|
|
@ -7,13 +7,11 @@ 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.
|
||||
This document assumes that you have a patch against the sources of the
|
||||
compiler distribution, that you wish to submit to the OCaml
|
||||
maintainers upstream. See [INSTALL.adoc](INSTALL.adoc) for details on
|
||||
how to build the compiler distribution from sources. See
|
||||
[HACKING.adoc](HACKING.adoc) for details on how to modify the sources.
|
||||
|
||||
## Contribution
|
||||
|
||||
|
|
|
|||
3
Changes
3
Changes
|
|
@ -62,7 +62,8 @@ Next version (4.05.0):
|
|||
- add a HACKING.adoc file to contain various tips and tricks for
|
||||
people hacking on the repository. See also CONTRIBUTING.md for
|
||||
advice on sending contributions upstream.
|
||||
(Gabriel Scherer and Gabriel Radanne, inspired by John Whitington)
|
||||
(Gabriel Scherer and Gabriel Radanne, review by David Allsopp,
|
||||
inspired by John Whitington)
|
||||
|
||||
### Other libraries:
|
||||
|
||||
|
|
|
|||
80
HACKING.adoc
80
HACKING.adoc
|
|
@ -10,18 +10,16 @@ official distribution, please see link:CONTRIBUTING.md[].
|
|||
|
||||
=== Your first compiler modification
|
||||
|
||||
0. Create a new git branch to store your changes.
|
||||
1. Create a new git branch to store your changes.
|
||||
+
|
||||
----
|
||||
git checkout -b my-modification
|
||||
----
|
||||
|
||||
1. Install https://github.com/gasche/opam-compiler-conf[opam-compiler-conf].
|
||||
|
||||
2. Consult link:INSTALL.adoc[] for build instructions. Here is the gist of it:
|
||||
+
|
||||
----
|
||||
opam compiler-conf configure
|
||||
./configure
|
||||
make world.opt
|
||||
----
|
||||
|
||||
|
|
@ -48,7 +46,9 @@ opam compiler-conf install
|
|||
|
||||
6. You did it, Well done! Consult link:CONTRIBUTING.md[] to send your contribution upstream.
|
||||
|
||||
See our <<Development tips and tricks>> for various helpful details.
|
||||
See our <<Development tips and tricks>> for various helpful details,
|
||||
for example on how to automatically <<opam compiler script,create an
|
||||
opam switch>> from a compiler branch.
|
||||
|
||||
=== What to do
|
||||
|
||||
|
|
@ -64,14 +64,14 @@ newcomers. Here are various potential projects:
|
|||
* The
|
||||
https://github.com/ocamllabs/compiler-hacking/wiki/Things-to-work-on[OCaml
|
||||
Labs compiler-hacking wiki] contains various ideas of changes to
|
||||
propose, some easy, some requiring sensibly more work.
|
||||
propose, some easy, some requiring a fair amount of work.
|
||||
|
||||
* Documentation improvements are always most appreciated, either in
|
||||
the various mli files or in the official manual
|
||||
* Documentation improvements are always much appreciated, either in
|
||||
the various `.mli` files or in the official manual
|
||||
(See link:manual/README.md[]). If you invest effort in understanding
|
||||
a part of the codebase, submitting a pull request that adds
|
||||
clarifying comment can be an excellent contribution to help future
|
||||
you and your peers.
|
||||
clarifying comments can be an excellent contribution to help you,
|
||||
next time, and other code readers.
|
||||
|
||||
* The https://github.com/ocaml/ocaml[github project] contains a lot of
|
||||
pull requests, many of them being in dire need of a review -- we
|
||||
|
|
@ -82,16 +82,15 @@ newcomers. Here are various potential projects:
|
|||
contribution process, and it is also an excellent way to get to know
|
||||
various parts of the compiler from the angle of a specific aspect or
|
||||
feature.
|
||||
|
||||
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
|
||||
requests as you submit.
|
||||
+
|
||||
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 requests yourself, a good
|
||||
discipline is to review at least as many pull requests as you submit.
|
||||
|
||||
== Structure of the compiler
|
||||
|
||||
The compiler code base can be intimidating at first sight. Here are
|
||||
The compiler codebase can be intimidating at first sight. Here are
|
||||
a few pointers to get started.
|
||||
|
||||
=== Compilation pipeline
|
||||
|
|
@ -99,10 +98,9 @@ a few pointers to get started.
|
|||
==== The driver -- link:driver/[]
|
||||
|
||||
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.
|
||||
compilation. It parses the command-line arguments and composes the
|
||||
required compiler passes by calling functions from the various parts
|
||||
of the compiler described below.
|
||||
|
||||
==== Parsing -- link:parsing/[]
|
||||
|
||||
|
|
@ -116,7 +114,7 @@ link:driver/pparse.mli[].
|
|||
|
||||
==== Typing -- link:typing/[]
|
||||
|
||||
Type-checks syntactic AST and produces a typed representation
|
||||
Type-checks the AST and produces a typed representation of the program
|
||||
(link:parsing/typedtree.mli[] has some helpful comments). See
|
||||
link:typing/HACKING.adoc[].
|
||||
|
||||
|
|
@ -128,7 +126,8 @@ link:typing/HACKING.adoc[].
|
|||
|
||||
=== Libraries
|
||||
|
||||
link:stdlib/[]:: The standard library. Each file is mostly independent and should not need further knowledge.
|
||||
link:stdlib/[]:: The standard library. Each file is largely
|
||||
independent and should not need further knowledge.
|
||||
|
||||
link:otherlibs/[]:: External libraries such as `unix`, `threads`,
|
||||
`dynlink`, `str` and `bigarray`.
|
||||
|
|
@ -149,15 +148,15 @@ has excellent documentation.
|
|||
Changes:: what's new with each release
|
||||
configure:: configure script
|
||||
CONTRIBUTING.md:: how to contribute to OCaml
|
||||
HACKING.adoc:: tips for people modifying the code
|
||||
HACKING.adoc:: this file
|
||||
INSTALL.adoc:: instructions for installation
|
||||
LICENSE:: license and copyright notice
|
||||
Makefile:: main Makefile
|
||||
Makefile.nt:: MS Windows Makefile
|
||||
Makefile.nt:: Windows Makefile
|
||||
Makefile.shared:: common Makefile
|
||||
Makefile.tools:: used by manual/ and testsuite/ Makefiles
|
||||
README.adoc:: this file
|
||||
README.win32.adoc:: info on the MS Windows ports of OCaml
|
||||
README.adoc:: general information on the compiler distribution
|
||||
README.win32.adoc:: general information on the Windows ports of OCaml
|
||||
VERSION:: version string
|
||||
asmcomp/:: native-code compiler and linker
|
||||
asmrun/:: native-code runtime library
|
||||
|
|
@ -165,18 +164,18 @@ has excellent documentation.
|
|||
bytecomp/:: bytecode compiler and linker
|
||||
byterun/:: bytecode interpreter and runtime system
|
||||
compilerlibs/:: the OCaml compiler as a library
|
||||
config/:: autoconfiguration stuff
|
||||
config/:: configuration files
|
||||
debugger/:: source-level replay debugger
|
||||
driver/:: driver code for the compilers
|
||||
emacs/:: editing mode and debugger interface for GNU Emacs
|
||||
experimental/:: experiments not built by default
|
||||
flexdll/:: empty (see README.win32.adoc)
|
||||
flexdll/:: git submodule (see link:README.win32.adoc[])
|
||||
lex/:: lexer generator
|
||||
man/:: man pages
|
||||
manual/:: system to generate the manual
|
||||
middle_end/:: the flambda optimisation phase
|
||||
ocamldoc/:: documentation generator
|
||||
otherlibs/:: several external libraries
|
||||
otherlibs/:: several additional libraries
|
||||
parsing/:: syntax analysis
|
||||
stdlib/:: standard library
|
||||
testsuite/:: tests
|
||||
|
|
@ -211,8 +210,13 @@ installation, the following targets may be of use:
|
|||
|
||||
=== Bootstrapping
|
||||
|
||||
The OCaml compiler is bootstrapped. This means that a previous version of the OCaml compiler (along with various tools and a compiled version of the standard library) is included in the repository under the link:boot/[] directory.
|
||||
Details can be found in link:INSTALL.adoc#bootstrap[INSTALL.adoc].
|
||||
The OCaml compiler is bootstrapped. This means that
|
||||
previously-compiled bytecode versions of the compiler, dependency
|
||||
generator and lexer are included in the repository under the
|
||||
link:boot/[] directory. These bytecode images are used once the
|
||||
bytecode runtime (which is written in C) has been built to compile the
|
||||
standard library and then to build a fresh compiler. Details can be
|
||||
found in link:INSTALL.adoc#bootstrap[INSTALL.adoc].
|
||||
|
||||
=== Continuous integration
|
||||
|
||||
|
|
@ -222,15 +226,15 @@ Details can be found in link:INSTALL.adoc#bootstrap[INSTALL.adoc].
|
|||
|
||||
INRIA provides a Jenkins continuous integration service that OCaml
|
||||
uses, see link:https://ci.inria.fr/ocaml/[]. It provides a wider
|
||||
architecture support (MSVC and MingW, a zsystems s390x machine, and
|
||||
architecture support (MSVC and MinGW, a zsystems s390x machine, and
|
||||
various MacOS versions) than the Travis/AppVeyor testing on github,
|
||||
but only runs on commits to the trunk or release branch, not on every
|
||||
but only runs on commits to the trunk or release branches, not on every
|
||||
PR.
|
||||
|
||||
You do not need to be an INRIA employee to open account on this travis
|
||||
service; anyone can create an account there to access build logs,
|
||||
enable email notifications, and manually restart builds. If you would
|
||||
like to do this but have trouble doing it, you may contact Damien
|
||||
You do not need to be an INRIA employee to open an account on this
|
||||
jenkins service; anyone can create an account there to access build
|
||||
logs, enable email notifications, and manually restart builds. If you
|
||||
would like to do this but have trouble doing it, please contact Damien
|
||||
Doligez or Gabriel Scherer.
|
||||
|
||||
==== Running INRIA's CI on a github Pull Request (PR)
|
||||
|
|
|
|||
|
|
@ -1,9 +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:parsetree.mli[Parsetree] and link:asttypes.mli[Asttypes]::
|
||||
Parsetree is an Abstract Syntax Tree (AST) representation of OCaml
|
||||
source code. 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
|
||||
link: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.
|
||||
handlers that are used for all the error reporting in the compiler.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ 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.
|
||||
of the core OCaml language, starting with 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
|
||||
|
|
@ -13,45 +13,46 @@ 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.
|
||||
After that, it is best to dive right in. There is no real "entry
|
||||
point", but an understanding of both the parsetree and the typedtree
|
||||
is necessary.
|
||||
|
||||
The datastructures ::
|
||||
link:typing/types.mli[Types] and link:typing/typedtree.mli[Typedtree]
|
||||
link:types.mli[Types] and link: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.
|
||||
the source code annotated with all the information needed for type
|
||||
checking and type inference. link:env.mli[Env] contains all the
|
||||
environments that are used in the typechecker. Each node in the
|
||||
typedtree is annotated with the local environment in which it was
|
||||
type-checked.
|
||||
|
||||
Core utilities ::
|
||||
link:typing/btype.mli[Btype] and link:typing/ctype.mli[Ctype] contain
|
||||
link:btype.mli[Btype] and link: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
|
||||
backtracking. link: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:typetexp.mli[Typetexp] for type expressions,
|
||||
link:typecore.mli[Typecore] for the core language,
|
||||
link:typemod.mli[Typemod] for modules,
|
||||
link: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
|
||||
modules: link:includecore.ml[Includecore] for the type and
|
||||
value declarations, link:includemod.mli[Includemod] for modules
|
||||
and finally link: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
|
||||
Dependencies between modules::
|
||||
Most of the modules presented above are inter-dependent. Since OCaml
|
||||
does not permit 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].
|
||||
link:typecore.ml[Typecore.type_module], which is filled in
|
||||
link:typemod.ml[Typemod].
|
||||
|
|
|
|||
Loading…
Reference in New Issue