Convert all the mentions of bsc and bsb (#342)

Author: chenglou

pages/docs/gentype/latest/getting-started.mdx

@@ -39,13 +39,12 @@ For running `gentype` with ReScript via `npm` workflow, add following script in
 
 ```
 scripts: {
-  "build": "bsb -make-world",
-  "clean": "bsb -clean-world"
+  "build": "rescript",
+  "clean": "rescript clean"
 }
 ```
 
-> **Note:** `bsb` will automatically
-> detect your installed `genType` version.
+> **Note:** `rescript` will automatically detect your installed `genType` version.
 
 ## Configuration
 
@@ -84,7 +83,7 @@ Configure your shim files within `"gentypeconfig"` in your [`bsconfig.json`](htt
 
 Open any relevant `*.res` file and add `@genType` annotations to any bindings / values / functions to be used from JavaScript. If an annotated value uses a type, the type must be annotated too. See e.g.  [Hooks.res](https://github.com/reason-association/genType/blob/master/examples/typescript-react-example/src/Hooks.res).
 
-Save the file and rebuild the project via `npm run bs:build` or similar. You should now see a `*.gen.tsx` (for TypeScript, or `*.gen.js` for Flow) file with the same name (e.g. `MyComponent.res` -> `MyComponent.gen.tsx`).  
+Save the file and rebuild the project via `npm run bs:build` or similar. You should now see a `*.gen.tsx` (for TypeScript, or `*.gen.js` for Flow) file with the same name (e.g. `MyComponent.res` -> `MyComponent.gen.tsx`).
 
 Any values exported from `MyComponent.res` can then be imported from JS. For example:
 

pages/docs/manual/latest/build-configuration.mdx

@@ -178,7 +178,7 @@ The warning number are shown in the build output when they're triggered. The com
 
 ## bsc-flags
 
-Extra flags to pass to the underlying `bsc` call. Notably: `["-bs-super-errors"]` for turning on cleaner error output. No need to pass this flag for a new ReScript project; it's enabled by default.
+Extra flags to pass to the compiler. For advanced usages.
 
 ## Environment Variables
 
@@ -192,4 +192,4 @@ When `NINJA_ANSI_FORCED` is set to `1`: `rescript` produces color.
 When `NINJA_ANSI_FORCED` is set to `0`: `rescript` doesn't produce color.
 When `NINJA_ANSI_FORCED` is not set: `rescript` might or might not produce color, depending on a smart detection of where it's outputted.
 
-> Note that bsc, the barebone compiler, will always be passed `-color always`. See more details in [this issue](https://github.com/rescript-lang/rescript-compiler/issues/2984#issuecomment-410669163).
+> Note that the underlying compiler will always be passed `-color always`. See more details in [this issue](https://github.com/rescript-lang/rescript-compiler/issues/2984#issuecomment-410669163).

pages/docs/manual/latest/build-overview.mdx

@@ -7,41 +7,66 @@ canonical: "/docs/manual/latest/build-overview"
 
 # Build System Overview
 
-ReScript comes with a build system, bsb, that's meant to be fast, lean and used as the authoritative build system of the community.
+ReScript comes with a build system, [`rescript`](https://www.npmjs.com/package/rescript), that's fast, lean and used as the authoritative build system of the community.
 
-The build description file is called `bsconfig.json`. Every ReScript project needs one.
+Every ReScript project needs a build description file, `bsconfig.json`.
 
-## Build Project 
+## Options
+
+See `rescript -help`:
+
+```
+❯ rescript -help
+Available flags
+-v, -version  display version number
+-h, -help     display help
+Subcommands:
+    build
+    clean
+    format
+    convert
+    help
+Run rescript subcommand -h for more details,
+For example:
+    rescript build -h
+    rescript format -h
+The default `rescript` is equivalent to `rescript build` subcommand
+```
+
+## Build Project
 
 Each build will create build artifacts from your project's source files.
 
 **To build a project (including its dependencies / pinned-dependencies)**, run:
 
 ```sh
-bsb -make-world
+rescript
 ```
 
-Add `-w` to keep the built-in watcher running. Any new file change will be picked up and the build will re-run.
+Which is an alias for `rescript build`.
 
-**Note**: third-party libraries (in `node_modules`, or via `pinned-dependencies`) aren't watched, as doing so may exceed the node.js watcher count limit.
+To keep a build watcher, run:
 
-**Note 2**: In case you want to set up a project in a JS-monorepo-esque approach (`yarn workspaces` / `lerna`) where changes in your sub packages should be noticed by the compiler (`bsb -make-world`), you will need to define pinned dependencies in your main project's `bsconfig.json`. More details [here](./build-pinned-dependencies).
+```sh
+rescript build -w
+```
 
-**To build only your project's files (without dependencies)**, run:
+Any new file change will be picked up and the build will re-run.
 
+**Note**: third-party libraries (in `node_modules`, or via `pinned-dependencies`) aren't watched, as doing so may exceed the node.js watcher count limit.
 
-```sh
-bsb
-```
+**Note 2**: In case you want to set up a project in a JS-monorepo-esque approach (`npm` and `yarn` workspaces) where changes in your sub packages should be noticed by the build, you will need to define pinned dependencies in your main project's `bsconfig.json`. More details [here](./build-pinned-dependencies).
 
 ## Clean Project
 
 If you ever get into a stale build for edge-case reasons, use:
 
 ```sh
-bsb -clean-world
+rescript clean
 ```
 
-This will clean all your project's build artifacts, including those in your dependencies. Alternatively you can run `bsb -clean` to clean your project's build artifacts only.
+This will clean your own project's build artifacts. To also clean the dependencies' artifacts:
 
-For more infos, run `bsb -help` to see all the available options.
+```sh
+rescript clean -with-deps
+```

pages/docs/manual/latest/build-performance.mdx

@@ -7,7 +7,7 @@ canonical: "/docs/manual/latest/build-performance"
 
 # Build Performance
 
-ReScript considers performance at install time, build time and run time as a serious feature. Here are some more info, and tips on keeping the build fast. **Feel free to skip this section** if you're just starting out.
+ReScript considers performance at install time, build time and run time as a serious feature; it's one of those things you don't notice until you realize it's missing.
 
 ## Profile Your Build
 
@@ -25,62 +25,58 @@ import Image from "src/components/Image";
 
 ## Under the Hood
 
-ReScript itself uses a build system under the hood, called [Ninja](https://ninja-build.org). Ninja is like Make, but cross-platform, minimal, focuses in perf and destined to be more of a low-level building block than a full-blown build system. In this regard, Ninja's a great implementation detail for bsb.
+ReScript itself uses a build system under the hood, called [Ninja](https://ninja-build.org). Ninja is like Make, but cross-platform, minimal, focuses in perf and destined to be more of a low-level building block than a full-blown build system. In this regard, Ninja's a great implementation detail for `rescript`.
 
-ReScript reads into `bsconfig.json` and generates the Ninja build file in `lib/bs`. The file contains the low-level `bsc`-related commands, namespacing rules, intermediate artifacts generation & others. It then runs `ninja` for the actual build.
+ReScript reads into `bsconfig.json` and generates the Ninja build file in `lib/bs`. The file contains the low-level compiler commands, namespacing rules, intermediate artifacts generation & others. It then runs `ninja` for the actual build.
 
 ## The JS Wrapper
 
-`bsb` itself is a Node.js wrapper which takes care of some miscellaneous tasks, plus the watcher. The lower-level, watcher-less, true `bsb` is called `bsb.exe`. It can be located in the same directory as where `bsb` is found:
+`rescript` itself is a Node.js wrapper which takes care of some miscellaneous tasks, plus the watcher. The lower-level, watcher-less, fast native `rescript` is called `rescript.exe`. It's located at `node_modules/rescript/{your-platform}/rescript.exe`.
 
-```sh
-> bsb -where
-/usr/local/lib/node_modules/bs-platform/lib
-```
-
-The path varies across systems.
-
-If you don't need the watcher, you can run said `bsb.exe`: `/usr/local/lib/node_modules/bs-platform/lib/bsb.exe`. This side-steps the node.js startup time, which can be big (in the order of `100ms`).
+If you don't need the watcher, you can run said `rescript.exe`. This side-steps Node.js' long startup time, which can be in the order of `100ms`. Our editor plugin finds and uses this native `rescript.exe` for better performance.
 
 ## Numbers
 
-Raw `bsb.exe` build on a small project should be around `70ms`. This doubles when you use the more common `bsb` wrapper which comes with a watcher, which is practically faster since you don't manually run the build at every change (though you should opt for the raw `bsb.exe` for programmatic usage, e.g. inserting bsb into your existing JS build pipeline).
+Raw `rescript.exe` build on a small project should be around `70ms`. This doubles when you use the JS `rescript` wrapper which comes with a watcher, which is practically faster since you don't manually run the build at every change (though you should opt for the raw `rescript.exe` for programmatic usage, e.g. inserting rescript into your existing JS build pipeline).
 
 No-op build (when no file's changed) should be around `15ms`. Incremental rebuild (described soon) of a single file in a project is around `70ms` too.
 
 Cleaning the artifacts should be instantaneous.
 
 ### Extreme Test
 
-We've stress-tested bsb on a big project of 10,000 files (2 directories, 5000 files each, first 5000 no dependencies, last 5000 10 dependencies on files from the former directory) using https://github.com/ocaml-omake/omake/blob/perf-test/performance/generate.ml, on Retina Macbook Pro Early 2015 (3.1 GHz Intel Core i7).
+We've stress-tested `rescript.exe` on a big project of 10,000 files (2 directories, 5000 files each, first 5000 no dependencies, last 5000 10 dependencies on files from the former directory) using https://github.com/rescript-lang/build-benchmark, on a Retina Macbook Pro Early 2015 (3.1 GHz Intel Core i7).
 
 <!-- TODO: better repro -->
 
 - No-op build of 10k files: `800ms` (the minimum amount of time required to check the mtimes of 10k files).
 - Clean build: <3 minutes.
 - Incremental build: depends on the number of the dependents of the file. No dependent means `1s`.
 
-Note that bsb is a file-based build system. We don't do in-memory build, even if that speeds up the build a lot. In-memory builds risk memory leaks, out-of-memory errors and others. The bsb watcher, on the other hand, can stay open for days.
+### Stability
 
-## Incrementality
+`rescript` is a file-based build system. We don't do in-memory build, even if that speeds up the build a lot. In-memory builds risk memory leaks, out-of-memory errors, corrupt halfway build and others. Our watcher mode stays open for days or months with no leak.
+
+The watcher is also just a thin file watcher that calls `rescript.exe`. We don't like babysitting daemon processes.
+
+## Incrementality & Correctness
 
 ReScript doesn't take whole seconds to run every time. The bulk of the build performance comes from incremental build, aka re-building a previously built project when a few files changed.
 
-In short, thanks to our bsc compiler and bsb build system's architecture, we're able to **only build what's needed**. E.g. if `MyFile.res` isn't changed, then it's not recompiled. You can roughly emulate such incrementality in languages like JavaScript, but the degree of correctness is unfortunately low. For example, if you rename or move a JS file, then the watcher might get confused and not pick up the "new" file or fail to clean things up correctly, resulting in you needing to clean your build and restart anew, which defeats the purpose.
+In short, thanks to our compiler and the build system's architecture, we're able to **only build what's needed**. E.g. if `MyFile.res` isn't changed, then it's not recompiled. You can roughly emulate such incrementalism in languages like JavaScript, but the degree of correctness is unfortunately low. For example, if you rename or move a JS file, then the watcher might get confused and not pick up the "new" file or fail to clean things up correctly, resulting in you needing to clean your build and restart anew, which defeats the purpose.
+
+Say goodbye to stale build from your JavaScript ecosystem!
 
 ## Speed Up Incremental Build
 
 ReScript uses the concept of interface files (`.resi`) (or, equivalently, [module signatures](module.md#signatures)). Exposing only what you need naturally speeds up incremental builds. E.g. if you change a `.res` file whose corresponding `.resi` file doesn't expose the changed part, then you've reduced the amount of dependent files you have to rebuild.
 
-<!-- TODO: validate this -->
-
 ## Programmatic Usage
 
 Unfortunately, JS build systems are usually the bottleneck for building a JS project nowadays. Having parts of the build blazingly fast doesn't matter much if the rest of the build takes seconds or literally minutes. Here are a few suggestions:
 
 - Convert more files into ReScript =). Fewer files going through fewer parts of the JS pipeline helps a ton.
-- Careful with bringing in more dependencies: libraries, syntax transforms, build step loaders, etc. The bulk of these dragging down the editing & building experience might out-weight the API benefits they provide.
-- Wait for us to create our own super fast linker (aka bundler).
+- Careful with bringing in more dependencies: libraries, syntax transforms (e.g. the unofficially supported PPX), build step loaders, etc. The bulk of these dragging down the editing & building experience might out-weight the API benefits they provide.
 
 ## Hot Reloading
 

pages/docs/manual/latest/build-pinned-dependencies.mdx

@@ -11,8 +11,7 @@ canonical: "/docs/manual/latest/build-pinned-dependencies"
 
 Usually we'd recommend to use ReScript in a single-codebase style by using one `bsconfig.json` file for your whole codebase.
 
-There are scenarios where you still want to connect and build multiple independent ReScript packages for one main project though (`yarn workspaces`-like "monorepos"). This is where `pinned-dependencies` come into play.
-
+There are scenarios where you still want to connect and build multiple independent ReScript packages for one main project though (`npm` workspaces-like "monorepos"). This is where `pinned-dependencies` come into play.
 
 ## Package Types
 
@@ -22,7 +21,7 @@ Before we go into detail, let's first explain all the different package types re
 - Pinned dependencies (these are your local packages that should always rebuild when you build your toplevel, those should be listed in `bs-dependencies` and `pinned-dependencies`)
 - Normal dependencies (these are packages that are consumed from npm and listed via `bs-dependencies`)
 
-Whenever a package is being built (`bsb -make-world`), the build system will build the toplevel package with its pinned-dependencies. So any changes made in a pinned dependency will automatically be reflected in the final app.
+Whenever a package is being built (`rescript build`), the build system will build the toplevel package with its pinned-dependencies. So any changes made in a pinned dependency will automatically be reflected in the final app.
 
 ## Build System Package Rules
 
@@ -108,7 +107,6 @@ Our `app` folder would be our toplevel package, consuming our `common` and `mypl
 }
 ```
 
-Now, whenever we are running `npx bsb -make-world` within our `app` package, the compiler would always rebuild any changes within its pinned dependencies as well.
-
-**Important:** ReScript will not rebuild any `pinned-dependencies` in watch mode! This is due to the complexity of file watching, so you'd need to set up your own file-watcher process that runs `bsb -make-world` on specific file changes. E.g. you could use [`watchman-make`](https://facebook.github.io/watchman/docs/watchman-make.html) to automatically run the build task when a file in `common` or `myplugin` has been changed.
+Now, whenever we are running `rescript build` within our `app` package, the compiler would always rebuild any changes within its pinned dependencies as well.
 
+**Important:** ReScript will not rebuild any `pinned-dependencies` in watch mode! This is due to the complexity of file watching, so you'd need to set up your own file-watcher process that runs `rescript build` on specific file changes.

pages/docs/manual/latest/converting-from-js.mdx

@@ -153,7 +153,7 @@ let queryResult = (usePayload, payload) => {
 
 </CodeTab>
 
-Format the code: `./node_modules/.bin/bsc -format src/Main.res`.
+Format the code: `./node_modules/.bin/rescript format src/Main.res`.
 
 We have a type error: "The record field student can't be found". That's fine! **Always ensure your code is syntactically valid first**. Fixing type errors comes later.