From 06a179df9914b2944a32dfde0e4a825acab19d9c Mon Sep 17 00:00:00 2001 From: Gabriel Scherer Date: Thu, 8 Jun 2017 20:50:58 -0400 Subject: [PATCH] fix README.md Two things: 1. `[relative-path]()` does not work with Github markdown (see: [src/]()), you have to write `[relative-path](relative-path)]` (see: [src/](src/)). (`[relative-path][]` and `` don't work either). 2. places using the org-mode syntax `=foo=` where fixed to use backticks instead --- README.md | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index bb679249..1747cf74 100644 --- a/README.md +++ b/README.md @@ -168,10 +168,9 @@ there only for convenience, for the following reasons: ### How to add a configure step to a jbuilder project? -[example/sample-projects/with-configure-step]() shows one way to do it -that preserves composability; i.e. it doesn't require to manually run -all `./configure` script when working on multiple projects at the same -time. +[example/sample-projects/with-configure-step](example/sample-projects/with-configure-step) shows +one way to do it which preserves composability; i.e. it doesn't require manually +running `./configure` script when working on multiple projects at the same time. ### Can I use topkg with jbuilder? @@ -248,14 +247,14 @@ 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]()) that dumps most of the sources of Jbuilder into a -single =boot.ml= file. This file is built using =ocamlopt= or =ocamlc= +([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. ### OCaml compatibility test Install opam switches for all the entries in the -[jbuild-workspace.dev]() file and run: +[jbuild-workspace.dev](jbuild-workspace.dev) file and run: ```sh $ make all-supported-ocaml-versions @@ -263,13 +262,13 @@ $ 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 +- `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 +- `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 +- `bin/` contains the command line interface +- `doc/` contains the manual and rules to generate the manual pages ### Design @@ -280,23 +279,26 @@ 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= +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](). In the end it makes the +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](). +Lwt/Async-like monad, implemented in [src/future.mli](src/future.mli). #### Code flow -- [src/jbuild.mli]() contains the internal representation of `jbuild` - files and the parsing code -- [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]() contains all the build rules of Jbuilder -- [src/build_system.mli]() contains a trivial implementation of a Build - system. This is what Jenga will provide when implementing the bridge +- [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