[Docs] Unify contribution instructions a little more

chenglou · chenglou · commit c9bfcc1e723f · 2018-04-09T17:38:54.000-07:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -50,8 +50,8 @@ npm run build
 And whenever you modify a file in bucklescript, run this inside `jscomp/`:
 
 ```
-make ../lib/bsc.exe && ./install-bsc.sh
-make ../lib/bsb.exe && ./install-bsb.sh
+make ../lib/bsc.exe && ./install-bsc.sh # build the compiler and make it available globally
+make ../lib/bsb.exe && ./install-bsb.sh # build the build system and make it available globally
 ```
 
 This will substitute the global `bsc.exe` & `bsb.exe` you just installed with the newly built one. Then run `npm build again` in the dummy project and see the changes! The iteration cycle for testing these should be around 2 seconds =).
@@ -61,16 +61,15 @@ This will substitute the global `bsc.exe` & `bsb.exe` you just installed with th
 Did any of the above step not work?
 
 - If you get compilation errors even from a supposedly clean compilation, you might have skipped the opam reinstall step above: `opam switch reinstall 4.02.3+buckle-master`
-
 - Make sure you did "eval `opam config env`" In your CLI/bashrc/zshrc
-
 - **If the vendored ocaml changed between when you last iterated on the repo and now**, you probably skipped the `opam switch reinstall 4.02.3+buckle-master` part. You'll have to do `git clean -xdf` and then restart with the build instructions. Careful, as `git clean` removes your uncommitted changes.
-
 - **If these fail too**, make sure you do have the correct `ocamlopt` in your environment: `which ocamlopt` should show an `opam` path, not `reason-cli` path. If you see the latter, this means it overrode the global `ocamlopt` BuckleScript needed. In this case, either temporarily uninstall reason-cli or make sure your opam PATH overrides the reason-cli PATH (and not the other way around) in your bashrc/zshrc.
 
-## Special Iteration Workflow
+Whenever there are dependencies changes: do `make depend` in the specific directory, when available. This allows the makefile to track new dependencies.
+
+## Change the Vendored OCaml Compiler
 
-This section is reserved for when you're making a change to the vendored ocaml compiler itself, in vendor/ocaml, and then testing on super-errors changes at the same time. If you're doing this for whatever reason, then the previous quick iteration workflow wouldn't work. Here's what you have to do after each change:
+This section is reserved for when you're making a change to the vendored ocaml compiler itself, in `vendor/ocaml`, and then testing on super-errors changes at the same time. If you're doing this for whatever reason, then the previous quick iteration workflow wouldn't work. Here's what you have to do after each change:
 
 ```
 # at project root
@@ -121,27 +120,16 @@ The API reference is generated from doc comments in the source code.
 Some tips and guidelines:
 
 - The first sentence or line should be a very short summary. This is used in indexes and by tools like merlin.
-
 - Ideally, every function should have **at least one** `@example`.
-
 - Cross-reference another definition with `{! identifier}`. But use them sparingly, they’re a bit verbose (currently, at least).
-
 - Wrap non-cross-referenced identifiers and other code in `[ ... ]`.
-
 - Escape `{`, `}`, `[`, `]` and `@` using `\`.
-
 - It’s possible to use `{%html ...}` to generate custom html, but use this very, very sparingly.
-
 - A number of "documentation tags" are provided that would be nice to use, but unfortunately they’re often not supported for \`external\`s. Which is of course most of the API.
-
 - `@param` usually doesn’t work. Use `{b <param>} ...` instead
-
 - `@returns` usually doesn’t work. Use `{b returns} ...` instead.
-
 - Always use `@deprecated` when applicable.
-
 - Always use `@raise` when applicable.
-
 - Always provide a `@see` tag pointing to MDN for more information when available.
 
 See [Ocamldoc documentation](http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec333) for more details.
@@ -151,6 +139,59 @@ To generate the html, run `make docs` in `jscomp/`.
 Html generation uses a custom generator located in `odoc_gen/` and
 custom styles located in `docs/api_static`.
 
+## Make a Release
+
+In release mode, assuming you have NodeJS and OCaml compiler with the right version installed:
+
+```sh
+node scripts/install.js
+```
+
+The build process will generate configure file with correct `LIBDIR` path,
+build all binaries and libraries and
+install the binaries into `bin` and lib files into `lib`.
+
+First it will try to generate `bin/config_whole_compiler.ml` based on existing
+OCaml installation, if it fails, it will try to invoke `buildocaml.sh` to
+install an OCaml compiler from scratch, and retry again.
+
+### Publish Process
+
+- Run `make force-snapshotml`
+- Bump the compiler version
+
+## Code structure
+
+The highlevel architecture is illustrated as below:
+
+```
+Lambda IR (OCaml compiler libs) ---+
+  |   ^                            |
+  |   |                     Lambda Passes (lam_* files)
+  |   |             Optimization/inlining/dead code elimination
+  |   \                            |
+  |    \ --------------------------+
+  |
+  |  Self tail call elimination
+  |  Constant folding + propagation
+  V
+JS IR (J.ml)  ---------------------+
+  |   ^                            |
+  |   |                     JS Passes (js_* files)
+  |   |            Optimization/inlining/dead code elimination
+  |   \                            |
+  |    \  -------------------------+
+  |
+  |  Smart printer includes scope analysis
+  |
+  V
+Javascript Code
+```
+
+Note that there is one design goal to keep in mind, never introduce
+any meaningless symbol unless real necessary, we do optimizations,
+however, it should also compile readable output code.
+
 ## Contribution Licensing
 
 Since BuckleScript is distributed under the terms of the [LGPL Version 3](LICENSE), contributions that you make
diff --git a/jscomp/README.md b/jscomp/README.md
@@ -1,137 +1,10 @@
-# Build Instructions
+Hello! This is the main directory for BuckleScript. `jscomp` is just a name that mirrors OCaml's own `bytecomp` and `asmcomp` (bytecode compilation and native compilation logic respectively). For building it, please see [CONTRIBUTING.md](../CONTRIBUTING.md).
 
-## Release mode
+Extra info:
 
-In release mode, assume you have NodeJS and
-OCaml compiler  with the right version installed:
+## Rebuilding the browser-based playground
 
-```sh
-node scripts/install.js
-```
-
-The build process will generate configure file with correct `LIBDIR` path,
-build all binaries and libraries and
-install the binaries into `bin` and lib files into `lib`.
-
-First it will try to generate `bin/config_whole_compiler.ml` based on existing
-OCaml installation, if it fails, it will try to invoke `buildocaml.sh` to
-install an OCaml compiler from scratch, and retry again
-
-
-## Dev mode
-
-### Setup
-
-#### Use the correct opam switch for working on BuckleScript
-```sh
-opam update
-opam switch 4.02.3+buckle-master
-opam switch reinstall 4.02.3+buckle-master # do this if you get errors even from a clean compilation
-opam install camlp4 cppo
-eval `opam config env`
-```
-
-#### build BuckleScript's forked OCaml
-```sh
-cd vendor/ocaml
-./configure -prefix `pwd`
-make world.opt
-make install
-```
-
-#### build all of Bucklescript
-```sh
-cd ../../
-make world
-```
-
-### build the compiler (bsc.exe)
-
-If you don't change the type definition of JS IR, i.e, [j.ml](./j.ml),
-then the only dependency is the build tool:
-`make`
-
-```sh
-rm -rf core/js_map.ml core/js_fold.ml && make core/js_map.ml core/js_fold.ml ../lib/bsc.exe
-```
-
-If you do want to change the JS IR, you also need
-[camlp4](https://github.com/ocaml/camlp4), note that the version does
-not need match the exact the same version of compiler.
-
-### build the build system (bsb.exe)
-
-```sh
-make ../lib/bsb.exe && make ../lib/bsb_helper.ml && make ../lib/bsb_helper.exe
-```
-
-Generate packed ML files for PR: `make force-snapshotml`
-
-### build the runtime
-
-```sh
-cd ./runtime; make all
-```
-
-### build the stdlib
-
-```sh
-cd ./stdlib; make all
-```
-
-Several useful targets
-
-- `make depend` generates the `.depend` files used by make to build things in the correct order
-- `make check`  builds and runs the tests
-- `make libs` builds the JS runtime
-
-### Publish process
-- Run `make force-snapshotml`
-- Bump the compiler version
-- Build the JS playground
-  * Generate js_compiler.ml
-  * Generate cmj data sets
-  * Generate preload.js
-  * Make sure AMDJS are up to date
-
-
-
-
-## Code structure
-
-The highlevel architecture is illustrated as below:
-
-```
-Lambda IR (OCaml compiler libs) ---+
-  |   ^                            |
-  |   |                     Lambda Passes (lam_* files)
-  |   |             Optimization/inlining/dead code elimination
-  |   \                            |
-  |    \ --------------------------+
-  |
-  |  Self tail call elimination
-  |  Constant folding + propagation
-  V
-JS IR (J.ml)  ---------------------+
-  |   ^                            |
-  |   |                     JS Passes (js_* files)
-  |   |            Optimization/inlining/dead code elimination
-  |   \                            |
-  |    \  -------------------------+
-  |
-  |  Smart printer includes scope analysis
-  |
-  V
-Javascript Code
-```
-
-Note that there is one design goal to keep in mind, never introduce
-any meaningless symbol unless real necessary, we do optimizations,
-however, it should also compile readable output code.
-
-# Rebuilding the browser-based playground
-
-## Get `js_of_ocaml` from the normal switch
+### Get `js_of_ocaml` from the normal switch
 
 ```
 opam switch 4.02.3
@@ -140,7 +13,7 @@ opam install js_of_ocaml
 which js_of_ocaml # symlink this into your $PATH, maybe /usr/local/bin or something
 ```
 
-## Do everything else from the bucklescript switch
+### Do everything else from the bucklescript switch
 
 ```
 opam switch 4.02.3+buckle-master
@@ -150,9 +23,9 @@ opam install camlp4 ocp-ocamlres
 (cd jscomp && BS_RELEASE_BUILD=true BS_PLAYGROUND=../../bucklescript-playground node repl.js)
 ```
 
-# Sub directories
+## Sub directories
 
-## [stdlib](./stdlib)
+### [stdlib](./stdlib)
 
 A copy of standard library from OCaml distribution(4.02) for fast development,
 so that we don't need bootstrap compiler, everytime we deliver a new feature.
