From 4759ededdf0c456754051f365d302c4be4a7b7bf Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Wed, 21 Mar 2018 00:06:51 +0800 Subject: [PATCH] Move hacking to its own page --- HACKING.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 70 ------------------------------------------------------ 2 files changed, 69 insertions(+), 70 deletions(-) create mode 100644 HACKING.md diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 00000000..a83b3618 --- /dev/null +++ b/HACKING.md @@ -0,0 +1,69 @@ +# Hacking on Dune + +This section is for people who want to work on Jbuilder itself. + +## Bootstrap + +In order to build itself, Jbuilder uses an OCaml script +([bootstrap.ml](bootstrap.ml)) that dumps most of the sources of Jbuilder into a +single `boot.ml` file. This file is built using `ocamlopt` or `ocamlc` +and used to build everything else. + +Note that we don't include all of the sources in boot.ml. We skip a +few parts to speed up the build. In particular: +- vendored libraries are replaced by simpler implementations taken + from `vendor/boot` +- a few files in `src` have an alternative version. These alternatives + versions are named `XXX.boot.EXT`. For instance: `glob_lexer.boot.ml` + +## OCaml compatibility test + +Install opam switches for all the entries in the +[jbuild-workspace.dev](jbuild-workspace.dev) file and run: + +```sh +$ make all-supported-ocaml-versions +``` + +## Repository organization + +- `vendor/` contains dependencies of Jbuilder, that have been vendored +- `plugin/` contains the API given to `jbuild` files that are OCaml + scripts +- `src/` contains the core of `Jbuilder`, as a library so that it can + be used to implement the Jenga bridge later +- `bin/` contains the command line interface +- `doc/` contains the manual and rules to generate the manual pages + +## Design + +Jbuilder was initially designed to sort out the public release of Jane +Street packages which became incredibly complicated over time. It is +still successfully used for this purpose. + +One necessary feature to achieve this is the ability to precisely +report the external dependencies necessary to build a given set of +targets without running any command, just by looking at the source +tree. This is used to automatically generate the `.opam` +files for all Jane Street packages. + +To implement this, the build rules are described using a build arrow, +which is defined in [src/build.mli](src/build.mli). In the end it makes the +development of the internal rules of Jbuilder very composable and +quite pleasant. + +To deal with process multiplexing, Jbuilder uses a simplified +Lwt/Async-like monad, implemented in [src/future.mli](src/future.mli). + +## Code flow + +- [src/jbuild.mli](src/jbuild.mli) contains the internal representation + of `jbuild` files and the parsing code +- [src/jbuild_load.mli](src/jbuild_load.mli) contains the code to scan + a source tree and build the internal database by reading + the `jbuild` files +- [src/gen_rules.mli](src/gen_rules.mli) contains all the build rules + of Jbuilder +- [src/build_system.mli](src/build_system.mli) contains a trivial + implementation of a Build system. This is what Jenga will provide + when implementing the bridge diff --git a/README.md b/README.md index 38927787..cf91d7b2 100644 --- a/README.md +++ b/README.md @@ -148,73 +148,3 @@ Status Jbuilder is now in beta testing stage. Once a bit more testing has been done, it will be released in 1.0. -Implementation details ----------------------- - -This section is for people who want to work on Jbuilder itself. - -### Bootstrap - -In order to build itself, Jbuilder uses an OCaml script -([bootstrap.ml](bootstrap.ml)) that dumps most of the sources of Jbuilder into a -single `boot.ml` file. This file is built using `ocamlopt` or `ocamlc` -and used to build everything else. - -Note that we don't include all of the sources in boot.ml. We skip a -few parts to speed up the build. In particular: -- vendored libraries are replaced by simpler implementations taken - from `vendor/boot` -- a few files in `src` have an alternative version. These alternatives - versions are named `XXX.boot.EXT`. For instance: `glob_lexer.boot.ml` - -### OCaml compatibility test - -Install opam switches for all the entries in the -[jbuild-workspace.dev](jbuild-workspace.dev) file and run: - -```sh -$ make all-supported-ocaml-versions -``` - -### Repository organization - -- `vendor/` contains dependencies of Jbuilder, that have been vendored -- `plugin/` contains the API given to `jbuild` files that are OCaml - scripts -- `src/` contains the core of `Jbuilder`, as a library so that it can - be used to implement the Jenga bridge later -- `bin/` contains the command line interface -- `doc/` contains the manual and rules to generate the manual pages - -### Design - -Jbuilder was initially designed to sort out the public release of Jane -Street packages which became incredibly complicated over time. It is -still successfully used for this purpose. - -One necessary feature to achieve this is the ability to precisely -report the external dependencies necessary to build a given set of -targets without running any command, just by looking at the source -tree. This is used to automatically generate the `.opam` -files for all Jane Street packages. - -To implement this, the build rules are described using a build arrow, -which is defined in [src/build.mli](src/build.mli). In the end it makes the -development of the internal rules of Jbuilder very composable and -quite pleasant. - -To deal with process multiplexing, Jbuilder uses a simplified -Lwt/Async-like monad, implemented in [src/future.mli](src/future.mli). - -#### Code flow - -- [src/jbuild.mli](src/jbuild.mli) contains the internal representation - of `jbuild` files and the parsing code -- [src/jbuild_load.mli](src/jbuild_load.mli) contains the code to scan - a source tree and build the internal database by reading - the `jbuild` files -- [src/gen_rules.mli](src/gen_rules.mli) contains all the build rules - of Jbuilder -- [src/build_system.mli](src/build_system.mli) contains a trivial - implementation of a Build system. This is what Jenga will provide - when implementing the bridge