From 19ab289a7d86dcd5194995dfedd624dbbc0828dd Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 16:24:03 +0100 Subject: [PATCH 01/28] Remove Reason Associaton & Hemnet from users of reason The Reason Association is using ReScript, and Hemnet needs to be taken down for legal / copyright reasons (wanted to aid @believer in getting this change upstream) --- website/siteConfig.js | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/website/siteConfig.js b/website/siteConfig.js index 5c7751fbc9..60c06d5306 100644 --- a/website/siteConfig.js +++ b/website/siteConfig.js @@ -9,11 +9,6 @@ const users = [ image: "img/logos/messenger.svg", infoLink: "https://messenger.com", }, - { - caption: "Reason Association", - image: "img/logos/reason-association.svg", - infoLink: "https://www.reason-association.org", - }, { caption: "OneGraph", image: "img/logos/onegraph.svg", @@ -279,11 +274,6 @@ const users = [ image: "img/logos/wolt.svg", infoLink: "https://wolt.com/" }, - { - name: "Hemnet", - image: "img/logos/hemnet.svg", - infoLink: "https://hemnet.se", - }, { name: "Atvero", image: "img/logos/atvero.svg", From 2b1a53e9d7597c2191db1edef681543830414538 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 16:38:14 +0100 Subject: [PATCH 02/28] Update landing page - Update marketing blocks - Remove ReScript related quick start - Remove unrelated examples section (these are all outdated ReScript projects) --- website/i18n/en.json | 4 ++-- website/pages/en/index.js | 35 ++--------------------------------- 2 files changed, 4 insertions(+), 35 deletions(-) diff --git a/website/i18n/en.json b/website/i18n/en.json index e2aaa5e7bf..5b94087a1b 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -185,8 +185,8 @@ "Try Online|no description given": "Try Online", "Types without hassle|no description given": "Types without hassle", "Powerful, safe type inference means you rarely have to annotate types, but everything gets checked for you.|no description given": "Powerful, safe type inference means you rarely have to annotate types, but everything gets checked for you.", - "Easy JavaScript interop|no description given": "Easy JavaScript interop", - "Use packages from NPM/Yarn with minimum hassle, or even drop in a snippet of raw JavaScript while you're learning!|no description given": "Use packages from NPM/Yarn with minimum hassle, or even drop in a snippet of raw JavaScript while you're learning!", + "Use the power of the OCaml ecosystem|no description given": "Use the power of the OCaml ecosystem", + "Get access to the powerful systems programming language OCaml with an easier to learn syntax.|no description given": "Get access to the powerful systems programming language OCaml with an easier to learn syntax.", "Flexible & Fun|no description given": "Flexible & Fun", "Make websites, animations, games, servers, cli tools, and more! Take a look at these examples to get inspired.|no description given": "Make websites, animations, games, servers, cli tools, and more! Take a look at these examples to get inspired.", "QuickStart|no description given": "QuickStart", diff --git a/website/pages/en/index.js b/website/pages/en/index.js index 4bc066b91a..2a8f68a9ca 100755 --- a/website/pages/en/index.js +++ b/website/pages/en/index.js @@ -152,45 +152,14 @@ class Index extends React.Component { content: Powerful, safe type inference means you rarely have to annotate types, but everything gets checked for you., }, { - title: Easy JavaScript interop, - content: Use packages from NPM/Yarn with minimum hassle, or even drop in a snippet of raw JavaScript while you're learning!, - }, - { - title: Flexible & Fun, - content: Make websites, animations, games, servers, cli tools, and more! Take a look at these examples to get inspired., + title: Use the power of the OCaml ecosystem, + content: Get access to the powerful systems programming language OCaml with an easier to learn syntax., }, ]} layout="threeColumn" /> - -
-

QuickStart

- - {quickStart} - -

- It runs in watch mode, so any changes to files will be picked up and compiled. - Read more here! -

-
-
-

Examples

- ({ - title: example.name, - image: `${siteConfig.baseUrl}${example.image}`, - imageLink: example.link, - imageAlign: "top", - content: "", - }))} - /> -
- -

Users of Reason From af887243b778190db5f5466c201f574547cd4782 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 17:04:44 +0100 Subject: [PATCH 03/28] Update Installation instructions Remove outdated and wrong installation instructions and add an esy / hello-reason quickstart example. --- docs/installation.md | 50 ++++++++++++++++---------------------------- 1 file changed, 18 insertions(+), 32 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 4eaca89d6f..8aab373390 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,50 +2,36 @@ title: Installation --- -Reason comes by default in [BuckleScript](https://bucklescript.github.io/), a compiler that turns Reason code into JavaScript code. +> **Important:** In case you are looking for BuckleScript + Reason instructions, please note that BuckleScript has rebranded to ReScript and comes with its own syntax, that's very similar to Reason. Please refer to the [ReScript website](https://rescript-lang.org) for more infos. -**Prerequisite**: either NPM (comes with [node](https://nodejs.org/en/)) or [Yarn](https://yarnpkg.com/en/). +Reason comes with an npm like package manager called [esy](https://esy.sh): -To install BuckleScript & Reason globally: - -```sh -yarn global add bs-platform ``` - -(or `npm install -g bs-platform` for npm). - -## New Project - -The global installation comes with a simple project generator. Try: - -```sh -bsb -init my-new-project -theme basic-reason +npm install -g esy ``` -To compile & run the project you just created: +To create your first Reason native CLI program, run the following commands: -```sh -cd my-new-project -yarn build # or npm run build, for npm -node src/Demo.bs.js ``` +git clone https://github.com/esy-ocaml/hello-reason.git +cd hello-reason -That uses BuckleScript to compile Reason to JavaScript, then uses NodeJS to run the JavaScript. Feel free to use the generated JS files in whichever way you'd like, as if they're hand-written by you. - -During development, instead of running `npm run build` each time to compile, run `npm run start` to start a watcher that recompiles automatically after file changes. +# Install all dependencies (might take a while in the first run) +esy -By default, the `basic-reason` theme configures BuckleScript to output the generated JS files alongside the Reason files they were produced from. [There's a reason why this is helpful](https://bucklescript.github.io/docs/en/build-overview#tips-tricks). If you prefer to keep the generated files somewhere else, edit `bsconfig.json` to set `in-source` to `false`; the JS files will then be output to the `lib/js` directory instead. +# Compile and run Hello.exe +esy x Hello +``` -Alternatively, **to start a [ReasonReact](https://reasonml.github.io/reason-react/docs/en/installation.html) app**, follow the instructions [here](https://reasonml.github.io/reason-react/docs/en/installation). +Reason native development is essentially OCaml development. From here on, you want to read up following websites to get to understand the ecosystem: -## Existing Project +- **esy**: The `esy` package manager is designed to manage your npm and opam dependencies and efficiently caches & sandboxes your project compiler and dependencies. Check out the [esy website](https://esy.sh) to find out how to install dependencies, setting up package resolutions, and executing compiled programs. +- **opam**: The [opam package index](https://opam.ocaml.org/packages/) lists all available packages available in the OCaml ecosystem +- **dune**: [`dune`](https://github.com/ocaml/dune) is the official build system in the OCaml ecosystem. Check out the [manual](https://dune.readthedocs.io/en/latest/) for more details on how to set up your project. -You can install the toolchain locally to an existing project, through the familiar command: +All your packages are managed in your `package.json` file. Usually you will find a `dune` file in each source code directory (such as `bin/` and `lib/`) for all the build system settings as well. -```sh -yarn add --dev bs-platform -``` -(or `npm install --save-dev bs-platform` for npm). +## What Next? -The rest is the same as above. +After you have successfully compiled your first example, it's time to [set up your editor](editor-plugins.md). Later on we recommend to explore the [language basics](overview.md) to get a feeling for the Reason syntax. From 685ddebbad463a16b15caf48e1fdd30b7fb6c0c8 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 17:31:25 +0100 Subject: [PATCH 04/28] Update installation instructions --- docs/installation.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 8aab373390..9811f85eb7 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,9 +2,9 @@ title: Installation --- -> **Important:** In case you are looking for BuckleScript + Reason instructions, please note that BuckleScript has rebranded to ReScript and comes with its own syntax, that's very similar to Reason. Please refer to the [ReScript website](https://rescript-lang.org) for more infos. +> **Important:** In case you are looking for BuckleScript + Reason instructions, please note that BuckleScript has rebranded to ReScript and with its own syntax (it's very similar to Reason that is targeted more towards JS development needs). Please refer to the [ReScript website](https://rescript-lang.org) for more infos. -Reason comes with an npm like package manager called [esy](https://esy.sh): +Reason comes with its own "npm like" package manager called [esy](https://esy.sh): ``` npm install -g esy @@ -32,6 +32,21 @@ Reason native development is essentially OCaml development. From here on, you wa All your packages are managed in your `package.json` file. Usually you will find a `dune` file in each source code directory (such as `bin/` and `lib/`) for all the build system settings as well. -## What Next? +## Compiling to JavaScript -After you have successfully compiled your first example, it's time to [set up your editor](editor-plugins.md). Later on we recommend to explore the [language basics](overview.md) to get a feeling for the Reason syntax. +Reason + OCaml both leverage the [js_of_ocaml (JSOO)](https://ocsigen.org/js_of_ocaml/3.7.0/manual/overview) compiler to compile from bytecode to JavaScript. + +To get started with Reason + esy + JSOO, check out this [`hello-jsoo-esy`](https://github.com/jchavarri/hello-jsoo-esy) template: + +``` +git clone https://github.com/jchavarri/hello-jsoo-esy.git +cd hello-jsoo-esy +esy + +yarn +yarn webpack +``` + +## What's Next? + +After you have successfully compiled your first example, it's time to [set up your editor](editor-plugins.md) to get access to all the nice features such as auto-completion. After the editor setup, it's time to start with the [language basics](overview.md) to get a basic understanding of all the Reason language constructs. From 87b4867653e283b2e2e0ace4e605154ddae017e5 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 17:31:36 +0100 Subject: [PATCH 05/28] Update editor plugins --- docs/editor-plugins.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/editor-plugins.md b/docs/editor-plugins.md index e4709dbaad..eb17a31e50 100644 --- a/docs/editor-plugins.md +++ b/docs/editor-plugins.md @@ -13,17 +13,14 @@ Reason's nature lends itself to great editor support. Most of our editor plugins And other features. -## BuckleScript Development: +## Editor Plugins & Language Server -- [VSCode](https://github.com/jaredly/reason-language-server): **Recommended**. Use [reason-vscode](https://marketplace.visualstudio.com/items?itemName=jaredly.reason-vscode) from the extensions marketplace. -- [Atom](https://github.com/reasonml-editor/atom-ide-reason) -- [Vim/Neovim](https://github.com/reasonml-editor/vim-reason-plus) -- [Sublime Text](https://github.com/reasonml-editor/sublime-reason) -- [IDEA](https://github.com/reasonml-editor/reasonml-idea-plugin) -- [Emacs](https://github.com/reasonml-editor/reason-mode): **Currently unmaintained**. We'd like to upgrade it to [reason-language-server](https://github.com/jaredly/reason-language-server) one day. Contributions welcome! +Since Reason is just an alternative syntax for OCaml, we integrate seamlessly into the official OCaml editor toolchain as well. -## Native Project Development (Community Supported): +- For VSCode, we recommend using the [vscode-ocaml-platform](https://github.com/ocamllabs/vscode-ocaml-platform) plugin, which offers OCaml & Reason support out of the box. +- For other editors, we recommend using a language server client plugin of your choice, and pairing it with the [`ocaml-lsp`](https://github.com/ocaml/ocaml-lsp). Check out the respective README's to get started. + +**Other:** -- [VSCode](https://marketplace.visualstudio.com/items?itemName=freebroccolo.reasonml): Use [vscode-reasonml](https://marketplace.visualstudio.com/items?itemName=freebroccolo.reasonml) from the extensions marketplace. (Mac, Linux). - [Vim/Neovim](https://github.com/reasonml-editor/vim-reason-plus): Make sure to use [ocaml-language-server](https://www.npmjs.com/package/ocaml-language-server) for native development as suggested. (Mac, Linux): `npm install -g ocaml-language-server` -- [vim-reasonml](https://github.com/jordwalke/vim-reasonml): For use with native [esy](https://esy.sh/), Reason, and Merlin (not LSP based). (Mac, Linux, Windows). +- [vim-reasonml](https://github.com/jordwalke/vim-reasonml): For use with [esy](https://esy.sh/), Reason, and Merlin (not LSP based). (Mac, Linux, Windows). From ae730bc147fb9799324e4a38bc44a9cfb7202f20 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 17:31:50 +0100 Subject: [PATCH 06/28] Extra goodies: remove mention of bsb-native --- docs/extra-goodies.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/extra-goodies.md b/docs/extra-goodies.md index 8b5f649d4e..cd15109d5f 100644 --- a/docs/extra-goodies.md +++ b/docs/extra-goodies.md @@ -17,7 +17,3 @@ https://sketch.sh/ ## Redex [Redex](https://redex.github.io): the Reason packages registry. - -## Bsb-native - -[Bsb-native](https://github.com/bsansouci/bsb-native) is a tiny fork of our `bsb` build system (used by Reason and BuckleScript) that compiles to native assembly code through the familiar setup you've been using. From 45dfd05b00366c58aea988368e9b14ed972000a5 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 17:34:34 +0100 Subject: [PATCH 07/28] Remove newcomer-examples / project-structure These two pages were almost exclusively targeted to old BuckleScript conventions, that aren't even up to date. Removing this info will help not mixing up BuckleScript'isms with native development. --- docs/newcomer-examples.md | 71 --------------------------------------- docs/project-structure.md | 57 ------------------------------- website/i18n/en.json | 12 ------- website/sidebars.json | 4 +-- 4 files changed, 1 insertion(+), 143 deletions(-) delete mode 100644 docs/newcomer-examples.md delete mode 100644 docs/project-structure.md diff --git a/docs/newcomer-examples.md b/docs/newcomer-examples.md deleted file mode 100644 index 718d28e56f..0000000000 --- a/docs/newcomer-examples.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Newcomer Examples ---- - -An example is worth a thousand words. - -This section is dedicated to newcomers trying to figure out general idioms & conventions in Reason and BuckleScript. If you're a beginner who's got a good idea for an example, please suggest an edit! - -## Using the `option` type - -`option` is a [variant](variant.md) that comes with the [standard library](/api/index.html). It obviates the need for null values in other languages. - -```reason -let possiblyNullValue1 = None; -let possiblyNullValue2: option(string) = Some("Hello@"); - -switch (possiblyNullValue2) { -| None => print_endline("Nothing to see here.") -| Some(message) => print_endline(message) -}; -``` - -## Creating a parametrized type - -```reason -type universityStudent = {gpa: float}; - -type response('studentType) = { - status: int, - student: 'studentType -}; - -let result: response(universityStudent) = fetchDataFromServer(); -``` - -## Creating a JS Object - -Assuming you're compiling to JavaScript. - -```reason -type payload = { - name: string, - age: int -}; - -let student1 = { - name: "John", - age: 30, -}; -/* Compiles to a JS object with the above fields */ -``` - -## Modeling a JS Module with Default Export - -See [here](https://bucklescript.github.io/docs/en/import-export.html#import-a-default-value). - -## Checking for JS nullable types using the `option` type - -For a function whose argument is passed a JavaScript value that's potentially `null` or `undefined`, it's idiomatic to convert it to a Reason `option`. The conversion is done through the helper functions in Bucklescript's [`Js.Nullable`](http://bucklescript.github.io/bucklescript/api/Js.html#TYPEnullable) module. In this case, `toOption`: - -```reason -let greetByName = (possiblyNullName) => { - let optionName = Js.Nullable.toOption(possiblyNullName); - switch (optionName) { - | None => "Hi" - | Some(name) => "Hello " ++ name - } -}; -``` - -This check compiles to `possiblyNullName == null` in JS, so checks for the presence of `null` or `undefined`. diff --git a/docs/project-structure.md b/docs/project-structure.md deleted file mode 100644 index 531c74cddd..0000000000 --- a/docs/project-structure.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Project Structure ---- - -These are the existing, non-codified community practices that are currently propagated through informal agreement. We might remove some of them at one point, and enforce some others. Right now, they're just recommendations for ease of newcomers. - -## File Casing - -Capitalized file names (aka first letter upper-cased). - -**Justification**: Module names can only be capitalized. Newcomers often ask how a file maps to a module, and why `draw.re` maps to the module `Draw`, and sometimes try to refer to a module through uncapitalized identifiers. Using `Draw.re` makes this mapping more straightforward. It also helps certain file names that'd be awkward in uncapitalized form: `uRI.re`. - -## Ignore `.merlin` File - -This is generated by the build system (at least for the JS workflow) and you should not have to manually edit it. Don't check it into the repo. - -**Justification**: `.merlin` is for Merlin to understand the project layout and to provide editor tooling. The file contains absolute paths, which are also not cross-platform (e.g. Windows paths are different). - -## Folders - -Try not to have too many nested folders. Keep your project flat, and have fewer files (reminder: you can use nested modules). - -**Justification**: The file system is a _tree_, but your code's dependencies are a _graph_. Because of that, any file & folder organization is usually imperfect. While it's still valuable to group related files together in a folder, the time wasted debating & getting decision paralysis over these far outweight their benefits. We'll always recommend you to Get Work Done instead of debating about these issues. - -## Third-party Dependencies - -Keep them to a minimum. - -**Justification**: A compiled, statically typed language cannot model its dependencies easily by muddling along like in a dynamic language, especially when we're still piggy-backing on NPM/Yarn (to reduce learning overhead in the medium-term), both not made with Reason/BuckleScript in mind. Keeping dependencies simple & lean helps reduce possibility of conflicts (e.g. two diamond dependencies, or clashing interfaces). - -Model third-party code as `dependencies`, not `peerDependencies`. - -**Justification**: you should spiritually treat them as implementation details that might be swapped out one day. - -## Documentation - -Have them. Spend more effort making them great (examples, pitfalls) and professional rather than _just_ fancy-looking. Do use examples, and avoid using names such as `foo` and `bar`. There's always more concrete names (it's an example, no need to be abstract/generalized just yet. The API docs will do this plentily). For blog posts, don't repeat the docs themselves, describe the _transition_ from old to new, and why (e.g. "it was a component, now it's a function, because ..."). - -**Justification**: It's hard for newcomers to distinguish between a simple/decent library and one that's fancy-looking. For the sake of the community, don't try too hard to one-up each other's libraries. Do spread the words, but use your judgement too. - -## PPX & Other Meta-tools - -Keep them to a minimum. PPX, unless used in renown cases (printer, accessors and serializer/deserializer generation), can cause big learning churn for newcomers; on top of the syntax, semantics, types, build tool & FFI that they already have to learn, learning per-library custom transformations of the code is an extra step. More invasive macros makes the code itself less semantically meaningful too, since the essence would be hiding somewhere else. - -## Paradigm - -Don't abuse overly fancy features. Do leave some breathing room for future APIs but don't over-architect things. - -**Justification**: Simple code helps newcomers understand and potentially contribute to your code. Contributing is the best way for them to learn. The extra help you receive might also surpass the gain of using a slightly more clever language trick. But do try new language tricks in some of more casual projects! You might discover new ways of architecting code. - -## Publishing - -If it's a wrapper for a JS library, don't publish the JS artifacts. If it's a legit library, publish the artifacts in lib/js if you think JS consumers might use it. This is especially the case when you gradually convert a JS lib to Reason + BuckleScript while not breaking existing JS consumers. - -Do put the keywords `"reason"` and `"bucklescript"` in your package.json `keywords` field. This allows us to find the library much more easily for future purposes. - -**Justification**: Be nice to JS consumers of your library. They're your future Reasoners. diff --git a/website/i18n/en.json b/website/i18n/en.json index 5b94087a1b..ba23966807 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -95,9 +95,6 @@ "native": { "title": "Native" }, - "newcomer-examples": { - "title": "Newcomer Examples" - }, "null-undefined-option": { "title": "Null, Undefined & Option" }, @@ -119,9 +116,6 @@ "primitives": { "title": "Primitives" }, - "project-structure": { - "title": "Project Structure" - }, "promise": { "title": "Promise" }, @@ -187,12 +181,6 @@ "Powerful, safe type inference means you rarely have to annotate types, but everything gets checked for you.|no description given": "Powerful, safe type inference means you rarely have to annotate types, but everything gets checked for you.", "Use the power of the OCaml ecosystem|no description given": "Use the power of the OCaml ecosystem", "Get access to the powerful systems programming language OCaml with an easier to learn syntax.|no description given": "Get access to the powerful systems programming language OCaml with an easier to learn syntax.", - "Flexible & Fun|no description given": "Flexible & Fun", - "Make websites, animations, games, servers, cli tools, and more! Take a look at these examples to get inspired.|no description given": "Make websites, animations, games, servers, cli tools, and more! Take a look at these examples to get inspired.", - "QuickStart|no description given": "QuickStart", - "It runs in watch mode, so any changes to files will be picked up and compiled.|no description given": "It runs in watch mode, so any changes to files will be picked up and compiled.", - "Read more here!|no description given": "Read more here!", - "Examples|no description given": "Examples", "Users of Reason|no description given": "Users of Reason", "See Full List|no description given": "See Full List", "Here are some of the folks successfully using Reason and BuckleScript in production, today!|no description given": "Here are some of the folks successfully using Reason and BuckleScript in production, today!", diff --git a/website/sidebars.json b/website/sidebars.json index f029c8f93c..1f0de6f4c4 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -44,9 +44,7 @@ ], "Extra": [ "faq", - "extra-goodies", - "newcomer-examples", - "project-structure" + "extra-goodies" ] }, "community": { From 27e04632c372ea84b7334208cea63b16afec2746 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 18:31:21 +0100 Subject: [PATCH 08/28] Merge native sections with installation --- docs/installation.md | 22 +++++++++++++++++ docs/native.md | 14 ----------- docs/quickstart-ocaml.md | 53 ---------------------------------------- 3 files changed, 22 insertions(+), 67 deletions(-) delete mode 100644 docs/native.md delete mode 100644 docs/quickstart-ocaml.md diff --git a/docs/installation.md b/docs/installation.md index 9811f85eb7..8393e2dbec 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -32,6 +32,28 @@ Reason native development is essentially OCaml development. From here on, you wa All your packages are managed in your `package.json` file. Usually you will find a `dune` file in each source code directory (such as `bin/` and `lib/`) for all the build system settings as well. +### Some `esy` Tips + +**Adding dependencies:** + +To add Reason / OCaml packages that happen to be hosted on npm, run `esy add npm-package-name`. + +``` +esy add refmterr +``` + +**Opam integration:** + +`esy` treats the npm scope `@opam` specially. `esy` will install any package name with the `@opam` scope directly from [opam](https://opam.ocaml.org/packages/). This is the only scope with special meaning. All other package names are assumed to be hosted on npm. + +``` +esy add @opam/bos +``` + +**Advanced esy configuration:** + +See the [configuration](https://esy.sh/docs/en/configuration.html) section from the complete `esy` docs. + ## Compiling to JavaScript Reason + OCaml both leverage the [js_of_ocaml (JSOO)](https://ocsigen.org/js_of_ocaml/3.7.0/manual/overview) compiler to compile from bytecode to JavaScript. diff --git a/docs/native.md b/docs/native.md deleted file mode 100644 index 44539631ef..0000000000 --- a/docs/native.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Native ---- - -[Bsb-native](https://github.com/bsansouci/bucklescript) is a fork of BuckleScript's bsb that compiles to native OCaml instead. - -[Esy](https://esy.sh) is a project package manager for native Reason. -- Esy can install packages from [opam](https://opam.ocaml.org/packages/). -- Esy lets you install esy packages from npm and publish `esy` packages to npm.. - -> **Note**: Esy works on all three platforms (OSX, Linux, Windows) but Windows support is still -> considered "beta". - -There is not much support for combining these two workflows. `esy` begins with a "native-first" workflow, and `bsb-native` begins with a "bucklescript first" workflow - the main difference being that `esy` has tighter integration with the existing native ecosystem, and `bsb-native` has tighter integration with the bucklescript ecosystem. diff --git a/docs/quickstart-ocaml.md b/docs/quickstart-ocaml.md deleted file mode 100644 index 82d42e440e..0000000000 --- a/docs/quickstart-ocaml.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Native Quickstart ---- - -## [esy](http://esy.sh) - -Esy (pronounced "easy") is a package manager for native Reason applications. It allows you to consume opam packages, and publish your own native packages to npm. - -**Install esy:** - -```sh -npm install -g esy -``` - -> **Note:** Make sure you have the latest `esy` installed. If in doubt, run `npm remove -g esy && npm install -g esy@latest`. - -**Using esy:** - -Clone any esy project and run the `esy` command inside of it. This will install all dependencies and build everything. - -``` -git clone git@github.com:esy-ocaml/hello-reason.git -cd hello-reason -esy -``` - -**Adding dependencies:** - -To add native Reason packages that happen to be hosted on npm, run `esy add npm-package-name`. - -``` -esy add refmterr -``` - -**Opam integration:** - -`esy` treats the npm scope `@opam` specially. `esy` will install any package name with the `@opam` scope directly from [opam](https://opam.ocaml.org/packages/). This is the only scope with special meaning. All other package names are assumed to be hosted on npm. - -``` -esy add @opam/bos -``` - -**Advanced esy configuration:** - -See the [configuration](https://esy.sh/docs/en/configuration.html) section from the complete `esy` docs. - -**Editor support:** - -See the [native project](https://reasonml.github.io/docs/en/editor-plugins#native-project-development-community-supported) section of the Reason editor support doc. - -**Compatibility:** - -In addition to supporting `esy` specific packages hosted on npm, `esy` also supports any opam package or ocaml native compiler. It [can also be used](https://esy.sh/docs/en/node-compatibility.html) to develop JavaScript npm projects that are compatible with [Yarn Plug'n'Play](https://yarnpkg.com/lang/en/docs/pnp/) (that includes most JS projects). [This Github issue](https://github.com/BuckleScript/bucklescript/issues/3276) is tracking the required bucklescript features to enable support for managing BuckleScript projects using `esy`. From 849f7538c73ff0bfb2e2abac02566d715911f4d4 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 18:31:59 +0100 Subject: [PATCH 09/28] Fine tune frontpage copy --- website/i18n/en.json | 11 ++--------- website/pages/en/index.js | 2 +- website/sidebars.json | 6 +----- 3 files changed, 4 insertions(+), 15 deletions(-) diff --git a/website/i18n/en.json b/website/i18n/en.json index ba23966807..23f34b0cd8 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -92,9 +92,6 @@ "mutation": { "title": "Mutation" }, - "native": { - "title": "Native" - }, "null-undefined-option": { "title": "Null, Undefined & Option" }, @@ -122,9 +119,6 @@ "quickstart-javascript": { "title": "Quickstart" }, - "quickstart-ocaml": { - "title": "Native Quickstart" - }, "record": { "title": "Records" }, @@ -169,8 +163,7 @@ "Setup": "Setup", "Language Basics": "Language Basics", "Advanced Features": "Advanced Features", - "JavaScript": "JavaScript", - "Native": "Native", + "JavaScript (obsolete)": "JavaScript (obsolete)", "Extra": "Extra", "Community": "Community" } @@ -180,7 +173,7 @@ "Types without hassle|no description given": "Types without hassle", "Powerful, safe type inference means you rarely have to annotate types, but everything gets checked for you.|no description given": "Powerful, safe type inference means you rarely have to annotate types, but everything gets checked for you.", "Use the power of the OCaml ecosystem|no description given": "Use the power of the OCaml ecosystem", - "Get access to the powerful systems programming language OCaml with an easier to learn syntax.|no description given": "Get access to the powerful systems programming language OCaml with an easier to learn syntax.", + "Get access to the powerful systems programming language OCaml with an easier to learn syntax. Use js_of_ocaml to compile to JavaScript!|no description given": "Get access to the powerful systems programming language OCaml with an easier to learn syntax. Use js_of_ocaml to compile to JavaScript!", "Users of Reason|no description given": "Users of Reason", "See Full List|no description given": "See Full List", "Here are some of the folks successfully using Reason and BuckleScript in production, today!|no description given": "Here are some of the folks successfully using Reason and BuckleScript in production, today!", diff --git a/website/pages/en/index.js b/website/pages/en/index.js index 2a8f68a9ca..c034872f7b 100755 --- a/website/pages/en/index.js +++ b/website/pages/en/index.js @@ -153,7 +153,7 @@ class Index extends React.Component { }, { title: Use the power of the OCaml ecosystem, - content: Get access to the powerful systems programming language OCaml with an easier to learn syntax., + content: Get access to the powerful systems programming language OCaml with an easier to learn syntax. Use js_of_ocaml to compile to JavaScript!, }, ]} layout="threeColumn" diff --git a/website/sidebars.json b/website/sidebars.json index 1f0de6f4c4..fd00920108 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -30,7 +30,7 @@ "exception", "object" ], - "JavaScript": [ + "JavaScript (obsolete)": [ "interop", "syntax-cheatsheet", "pipe-first", @@ -38,10 +38,6 @@ "libraries", "converting-from-js" ], - "Native": [ - "native", - "quickstart-ocaml" - ], "Extra": [ "faq", "extra-goodies" From 1a7fa6ddfd37a5ff43814c3142e18393113fd660 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 18:38:43 +0100 Subject: [PATCH 10/28] Update FAQ --- docs/faq.md | 54 +++++++++-------------------------------------------- 1 file changed, 9 insertions(+), 45 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 7a443c46ce..45b18422a8 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -3,57 +3,21 @@ title: Frequently Asked Questions --- ### I'm not sure what to do with Reason -Think of what project you'd usually make if it was pure JavaScript; try porting/writing that in Reason + BuckleScript instead! We recommend trying to make concrete, end-user projects (e.g. a little command line util) rather than infra-level projects (e.g. a boilerplate generator). The latter category requires expertise and understanding idiomatic Reason code. -### What's the relation between Reason, BuckleScript and OCaml? -Reason's a syntax for OCaml and supports all its features. BuckleScript compiles OCaml/Reason code into JavaScript. +You can do all the things you'd usually do with OCaml! OCaml is an incredible useful language for systems programming, while still being able to compile to pretty type safe JS with the aid of the `js_of_ocaml` compiler. -### Where do all these `print_endline`, `string_of_int` functions come from? -They're from the standard library, pre-`open`ed during the compilation of your file. This is why you see them in scope. +Natively compiled CLI's are also known to be really fast (like... C-like fast), and since the language is garbage collected, you will find yourself in a very nice spot of not having to worry about borrow-checking like in Rust and you don't have to deal with verbose non-ML languages like Go. -You can read more about the Pervasives library in the api documentation: +### What is BuckleScript and ReScript, and why is it mentioned in so many Reason related resources? -https://reasonml.github.io/api/Pervasives.html +Reason used to be tightly coupled to "BuckleScript", which used to be a OCaml-to-JS compiler like JSOO, but with different tweaks to get different JS output. -### Can I have a function to print arbitrary data structures? -If you're compiling to JavaScript through BuckleScript, you can use the JS `console.log` through [`Js.log`](https://bucklescript.github.io/bucklescript/api/Js.html#VALlog). +On [July 1st](https://rescript-lang.org/blog/bucklescript-8-1-new-syntax), the Reason and BuckleScript leadership decided to part in different directions due to lack of common goals, and ReScript implemented its own syntax (also called ReScript) to cater a more fine-tuned experience to their JS developers. More infos on the BuckleScript -> ReScript rebranding can be found in the [official announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding). -### Why is there a + for adding ints and +. for adding floats, etc.? -See [here](integer-and-float.md#design-decisions). +Reason continues its promise to be 100% compatible with OCaml semantics, therefore will change its focus on `js_of_ocaml` centered workflows for a streamlined JS compilation story. -### Does library ___ work with Reason? -Most JS libraries should easily work under Reason + BuckleScript. +ReScript will continue to support Reason `v3.6` for backwards compatibility, but will not ship any other future Reason versions. -### What's the server-side story? Should I compile to native or to JS and use node.js? -At this time, we recommend compiling to JS through BuckleScript and use the JS wrappers at [reasonml-community](https://github.com/reasonml-community) or somewhere else. +If you are already using BuckleScript + Reason, we recommend to either upgrade to the ReScript syntax, or alternatively, consider migrating your codebase to `js_of_ocaml` to keep 100% compatibility with the OCaml platform and runtime semantics. -### What's BuckleScript's async story? -If you're not interfacing with any library that uses promises, you can simply use callbacks. Everyone gets them and they're performant. - -If you need to bind to a JS library that uses promises, or communicate with such library, you can use BS's [Js.Promise](http://bucklescript.github.io/bucklescript/api/Js.Promise.html). - -### What's the (unit) test story? -Some of OCaml's language features (not just types) might be able to defer the need for unit testing until later. In the meantime, for compilation to JS, we're working on [Jest wrapper](https://github.com/BuckleTypes/bs-jest). We'll look into using Jest for native too, if Jest is written using Reason in the future (no concrete plan yet). [OUnit](http://ounit.forge.ocamlcore.org) is a good, small native OCaml testing library right now. - -### What's the `.merlin` file at the root of my project? -That's the metadata file for [editor support](editor-plugins.md). This is usually generated for you; You don't need to check that into your version control and don't have to manually modify it. - -### I don't see any `import` or `require` in my file; how does module resolution work? -Reason/OCaml doesn't require you to write any import; modules being referred to in the file are automatically searched in the project. Specifically, a module `Hello` asks the compiler to look for the file `hello.re` or `hello.ml` (and their corresponding [interface file](module.md#signatures), `hello.rei` or `hello.mli`, if available). - -A module name is the file name, capitalized. It has to be unique per project; this abstracts away the file system and allows you to move files around without changing code. - -### Is `Some | None`, `contents`, `Array`, `List` and all of these special? Where do they come from? -They're ordinary variants/records/module definitions that come with the [standard library](/api/index.html), `open`ed by default during compilation out of convenience. - -### What does an argument with a prepended underscore (e.g. `_` or `_foo`) mean? -Say you have `List.map(item => 1, myList);`. The argument `item` isn't used and will generate a compiler warning. Using `_ => 1` instead indicates that you're intentionally receiving and ignoring the argument, therefore bypassing the warning. Alternatively, `_item => 1` has the same effect, but indicates more descriptively what you're ignoring. - -### What's this `MyModule.t` I keep seeing? -Assuming `MyModule` is a module's name, `t` is a community convention that indicates "the type that represents that module, whatever that means". For example, for the [`Js.String`](http://bucklescript.github.io/bucklescript/api/Js.String.html) module, [`String.t`](http://bucklescript.github.io/bucklescript/api/Js.String.html#TYPEt) is the type carried around and representing "a string". - -### Why is there a [`Js_promise`](http://bucklescript.github.io/bucklescript/api/Js_promise.html) and then a [`Js.Promise`](http://bucklescript.github.io/bucklescript/api/Js.Promise.html)? What about [`Js_array`](http://bucklescript.github.io/bucklescript/api/Js_array.html), [`Js_string`](http://bucklescript.github.io/bucklescript/api/Js_string.html) and whatever else? -As a convention, `Js_foo` is the actual module, and `Js.Foo` is just an alias for it. They're [equivalent](https://github.com/bloomberg/bucklescript/blob/7bc37f387a726ba1ae4afeefe02b9c82577d9e10/jscomp/runtime/js.ml#L124-L138). Prefer `Js.Foo`, because that's the official, public module name. - -### Why are BuckleScript and bsb so fast? -Software should at least be this fast. +ReScript kept the [`< 8.2.0` docs](https://rescript-lang.org/docs/manual/v8.0.0/introduction) in Reason syntax to allow easy reading during the Reason -> ReScript transition. From 74d9a16fcf70823c02d20ddec47bf06cc18ababe Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 18:38:56 +0100 Subject: [PATCH 11/28] Update articles and videos --- docs/articles-and-videos.md | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/docs/articles-and-videos.md b/docs/articles-and-videos.md index 9dc2ccf9be..6ddb86bff6 100644 --- a/docs/articles-and-videos.md +++ b/docs/articles-and-videos.md @@ -2,25 +2,9 @@ title: Articles & Videos --- -## BuckleScript - -- [BuckleScript Documentation](https://bucklescript.github.io): the official documentations for our JavaScript backend. -- [BuckleScript JS API docs](http://bucklescript.github.io/bucklescript/api/index.html) -- [BuckleScript build system schema](https://bucklescript.github.io/docs/en/build-overview.html): comprehensive resource on `bsb`'s configuration. -- [BuckleScript Cookbook](https://github.com/glennsl/bucklescript-cookbook) -- [Unit Testing in ReasonML](https://jaketrent.com/post/unit-testing-in-reasonml/) - -## ReasonReact - -- [Documentation](//reasonml.github.io/reason-react/) -- [Interactive ReasonReact Tutorial](https://jaredforsyth.com/2017/07/05/a-reason-react-tutorial/): features runnable code and type hint on hover! -- [Deploying ReasonReact with Docker](https://medium.com/@anirudhmurali/how-i-deployed-a-reasonml-react-app-with-docker-29dd2ce6de82) -- [Building a Marvel Heroes App using ReasonReact](https://medium.com/oke-software-poland/reasonml-marvel-tutorial-part-0-e38e1bfe1866) - ## Videos - [React To The Future - ReasonConf 2019](https://www.youtube.com/watch?v=5fG_lyNuEAw) -- [Community-maintained Reason talks playlist](https://www.youtube.com/playlist?list=PLYU6eGtVFu8ZG3yh1FfLrqHBMUXj80wgK) - [ReasonML: Hype or next big thing?](https://www.youtube.com/watch?v=bqNploxWpjA&t): October 2017 - [The Why and How of ReasonML](https://www.youtube.com/watch?v=j5mlMUzpE5g): October 2017 - [Critical ReasonML'ing](https://www.youtube.com/watch?v=k77aR_JyvEE): October 2017 @@ -39,15 +23,6 @@ title: Articles & Videos - [C# and F# approaches to illegal states](http://enterprisecraftsmanship.com/2015/09/28/c-and-f-approaches-to-illegal-states/): F# is a cousin of Reason. Great article on F#'s equivalent of variants - [The algebra (and calculus!) of algebraic data types](https://codewords.recurse.com/issues/three/algebra-and-calculus-of-algebraic-data-types) -## Coding Philosophy - -A few articles we find interesting, or agree with. Not to be taken as literal truth. - -- [Write dumb code](https://matthewrocklin.com/blog//work/2018/01/27/write-dumb-code) -- [Not Explicit](https://boats.gitlab.io/blog/post/2017-12-27-things-explicit-is-not/) -- [Always start with simple solution](http://buklijas.info/blog/2018/01/01/always-start-with-simple-solution/) -- [The Pony Philosophy](https://www.ponylang.org/discover/#the-pony-philosophy) - ## Pro Links The more dated they look, the richer the content =P From 386ea40b23d3e1486fda1537ed5c7d87d862bfdb Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 18:44:44 +0100 Subject: [PATCH 12/28] Remove community examples Like the landing page, the examples are terribly outdated and don't reflect modern Reason at all. --- docs/community-examples.md | 30 ------------------------------ 1 file changed, 30 deletions(-) delete mode 100644 docs/community-examples.md diff --git a/docs/community-examples.md b/docs/community-examples.md deleted file mode 100644 index da844ba7f9..0000000000 --- a/docs/community-examples.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Examples ---- - -
- - Gravitron -
Gravitron
- - - Reason Maze -
Reason Maze
- - - Mareo: Mario + Reason -
Mareo: Mario + Reason
- - - ReasonReact Hacker News -
ReasonReact Hacker News
- - - Reason snake -
Reason snake
- - - TodoMVC -
TodoMVC
- -
From 0300f96e7533f7fefe88f9b4c9ce185e71de5835 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 18:45:20 +0100 Subject: [PATCH 13/28] Remove roadmap page This page is terribly outdated as well --- docs/roadmap.md | 15 --------------- 1 file changed, 15 deletions(-) delete mode 100644 docs/roadmap.md diff --git a/docs/roadmap.md b/docs/roadmap.md deleted file mode 100644 index 3391b20c2d..0000000000 --- a/docs/roadmap.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Roadmap & Contribution ---- - -Wanna help? - -- Please help us improve the Windows tooling support whenever you can! -- [Improve the documentation and website](https://github.com/reasonml/reasonml.github.io/issues). -- [Help us translate the docs!](https://github.com/reasonml/reasonml.github.io/issues/3) -- [Suggest better error messages](https://github.com/reasonml-community/error-message-improvement/issues) -- Contribute to [your favorite editor plugin for Reason](editor-plugins.md#officially-supported-editors) -- Come up with more [project names starting with "re"](https://github.com/reasonml/ideas-for-project-names-starting-with-re) -- Whatever project you'd normally do in JavaScript, try it in Reason + BuckleScript! -- Talk about Reason and BuckleScript! -- Ping @chenglou on [Forum](https://reasonml.chat) and on [Discord](https://discord.gg/reasonml) for more tasks. From 41d118fa7a5a33d1dd7a7545bad697b8f31aa4a1 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 18:46:05 +0100 Subject: [PATCH 14/28] Remove dead links on community events page --- docs/events.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/events.md b/docs/events.md index 4e8ce54d21..c1988944a3 100644 --- a/docs/events.md +++ b/docs/events.md @@ -5,27 +5,16 @@ title: Events There are a Reason meetups all around the world, among others: - [Alicante](https://www.meetup.com/Alicante-Frontend/events/256373865/) -- [Budapest](https://www.meetup.com/ReasonML-Budapest/) -- [Brussels](https://www.meetup.com/ReasonML-BXL/) - [Chicago](https://www.meetup.com/Chicago-ReasonML/) - [Copenhagen](https://www.meetup.com/ReasonML-CPH) ([Twitter](https://twitter.com/ReasonMLCPH)) - [Göteborg](https://www.meetup.com/got-lambda/) - [Lisbon](https://www.meetup.com/ReasonML-Lisbon) -- [London](https://www.meetup.com/ReasonLDN/) ([Twitter](https://twitter.com/reasonldn)) - [Montreal](https://www.meetup.com/ReasonMTL/) -- [Munich](https://www.meetup.com/Munich-ReasonML-Meetup) -- [New York](https://www.meetup.com/ReasonML-NYC/) ([Twitter](https://twitter.com/nycreasonml)) -- [Oslo](https://www.meetup.com/Reason-Oslo/) ([Twitter](http://twitter.com/reasonoslo/)) - [Paris](https://www.meetup.com/ReasonML-Paris/) - [Phoenix](https://www.meetup.com/Phoenix-Reason) -- [Portland](https://www.meetup.com/Portland-ReasonML/) ([Twitter](https://twitter.com/ReasonPDX)) - [Prague](https://www.meetup.com/Reason-Prague/) ([Twitter](https://twitter.com/ReasonPrague)) - [San Francisco](https://www.meetup.com/sv-ocaml/) - [Seattle](https://www.meetup.com/Seattle-ReasonML-OCaml-Meetup/) -- [Singapore](https://www.meetup.com/SG-OCaml/) - [Stockholm](https://www.meetup.com/ReasonSTHLM/) -- [Sydney](https://www.meetup.com/reason-sydney/) -- [Vancouver](https://www.meetup.com/Reason-Vancouver/) -- [Vienna](https://www.meetup.com/Reason-Vienna/) ([Twitter](https://twitter.com/reasonvienna)) If you don't find your local area's Reason meetup, search on https://meetup.com or start one! From 9d4389aa0fa6b3e944798e7753a1467204eac916 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 18:47:37 +0100 Subject: [PATCH 15/28] Update sidebar for community pages --- website/i18n/en.json | 6 ------ website/sidebars.json | 4 +--- 2 files changed, 1 insertion(+), 9 deletions(-) diff --git a/website/i18n/en.json b/website/i18n/en.json index 23f34b0cd8..5ad35305d4 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -14,9 +14,6 @@ "boolean": { "title": "Boolean" }, - "community-examples": { - "title": "Examples" - }, "community": { "title": "Community" }, @@ -128,9 +125,6 @@ "regular-expression": { "title": "Regular Expression" }, - "roadmap": { - "title": "Roadmap & Contribution" - }, "string-and-char": { "title": "String & Character" }, diff --git a/website/sidebars.json b/website/sidebars.json index fd00920108..3a8b683738 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -47,9 +47,7 @@ "Community": [ "community", "articles-and-videos", - "roadmap", - "events", - "community-examples" + "events" ] } } From b67a12c6623e527bcd12fc56f10d7e24dd8b97f8 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 19:01:45 +0100 Subject: [PATCH 16/28] Fix typo in installation --- docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index 8393e2dbec..4e3914c4b7 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,7 +2,7 @@ title: Installation --- -> **Important:** In case you are looking for BuckleScript + Reason instructions, please note that BuckleScript has rebranded to ReScript and with its own syntax (it's very similar to Reason that is targeted more towards JS development needs). Please refer to the [ReScript website](https://rescript-lang.org) for more infos. +> **Important:** In case you are looking for BuckleScript + Reason instructions, please note that BuckleScript has rebranded to ReScript and created its own syntax (it's very similar to Reason that is targeted more towards JS development needs). Please refer to the [ReScript website](https://rescript-lang.org) for more infos. Reason comes with its own "npm like" package manager called [esy](https://esy.sh): From f5c30d7434e0f9fa42bee591d1814190ed92073b Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 19:15:29 +0100 Subject: [PATCH 17/28] add faq link in installation --- docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index 4e3914c4b7..26ee01164c 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,7 +2,7 @@ title: Installation --- -> **Important:** In case you are looking for BuckleScript + Reason instructions, please note that BuckleScript has rebranded to ReScript and created its own syntax (it's very similar to Reason that is targeted more towards JS development needs). Please refer to the [ReScript website](https://rescript-lang.org) for more infos. +> **Important:** In case you are looking for BuckleScript + Reason instructions, please note that BuckleScript has rebranded to ReScript and created its own syntax (it's very similar to Reason that is targeted more towards JS development needs). Please refer to the [ReScript website](https://rescript-lang.org) or our [FAQ](http://localhost:3000/docs/en/faq#what-is-bucklescript-and-rescript-and-why-is-it-mentioned-in-so-many-reason-related-resources) for more infos. Reason comes with its own "npm like" package manager called [esy](https://esy.sh): From c2417409fe9282b566364c687c10e8bc8843c784 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sat, 2 Jan 2021 19:15:36 +0100 Subject: [PATCH 18/28] Improve FAQ copy --- docs/faq.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 45b18422a8..512f45491d 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -10,14 +10,12 @@ Natively compiled CLI's are also known to be really fast (like... C-like fast), ### What is BuckleScript and ReScript, and why is it mentioned in so many Reason related resources? -Reason used to be tightly coupled to "BuckleScript", which used to be a OCaml-to-JS compiler like JSOO, but with different tweaks to get different JS output. +Reason originally shipped as the user-facing syntax for BuckleScript (ReScript), a compiler toolchain to compile OCaml to efficient JS code. -On [July 1st](https://rescript-lang.org/blog/bucklescript-8-1-new-syntax), the Reason and BuckleScript leadership decided to part in different directions due to lack of common goals, and ReScript implemented its own syntax (also called ReScript) to cater a more fine-tuned experience to their JS developers. More infos on the BuckleScript -> ReScript rebranding can be found in the [official announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding). +On [July 1st](https://rescript-lang.org/blog/bucklescript-8-1-new-syntax), the Reason and BuckleScript teams decided to split up due to different goals / roadmaps. BuckleScript was renamed to ReScript and shipped its own syntax (also called ReScript) to provide a more fine-tuned experience for their JS focused users (while dropping native compilation support). More infos on the BuckleScript -> ReScript rebrand can be found in the [official rebranding announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding). -Reason continues its promise to be 100% compatible with OCaml semantics, therefore will change its focus on `js_of_ocaml` centered workflows for a streamlined JS compilation story. +Reason continues its promise to be 100% compatible with OCaml semantics, therefore will change its focus on `js_of_ocaml` centered workflows for a streamlined cross-platform compilation story (native / js). -ReScript will continue to support Reason `v3.6` for backwards compatibility, but will not ship any other future Reason versions. +ReScript will continue to support Reason `v3.6` for backwards compatibility, but will not ship any other future Reason versions. The ReScript website also kept the [`< 8.2.0` docs](https://rescript-lang.org/docs/manual/v8.0.0/introduction) in Reason syntax to allow easy usage during the Reason -> ReScript migration. -If you are already using BuckleScript + Reason, we recommend to either upgrade to the ReScript syntax, or alternatively, consider migrating your codebase to `js_of_ocaml` to keep 100% compatibility with the OCaml platform and runtime semantics. - -ReScript kept the [`< 8.2.0` docs](https://rescript-lang.org/docs/manual/v8.0.0/introduction) in Reason syntax to allow easy reading during the Reason -> ReScript transition. +If you are already using BuckleScript + Reason, we recommend to either upgrade your existing code to ReScript syntax, or alternatively, consider migrating to a `js_of_ocaml` based setup to keep 100% compatibility with the OCaml platform and runtime semantics. From a8dc6bdac7a79f74311a7bf674a26f8a268ee6a2 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sun, 3 Jan 2021 09:30:01 +0100 Subject: [PATCH 19/28] Update faq --- docs/faq.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 512f45491d..b91b6b4fdc 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -8,11 +8,13 @@ You can do all the things you'd usually do with OCaml! OCaml is an incredible us Natively compiled CLI's are also known to be really fast (like... C-like fast), and since the language is garbage collected, you will find yourself in a very nice spot of not having to worry about borrow-checking like in Rust and you don't have to deal with verbose non-ML languages like Go. +Reason also gives access to the declarative UI framework [revery-ui](https://github.com/revery-ui/revery) to build native applications with a ReactJS like paradigm (+ JSX). + ### What is BuckleScript and ReScript, and why is it mentioned in so many Reason related resources? -Reason originally shipped as the user-facing syntax for BuckleScript (ReScript), a compiler toolchain to compile OCaml to efficient JS code. +Reason was originally bundled with BuckleScript (ReScript) as its user-facing syntax to provide a single toolchain for Reason JS / ReactJS development. -On [July 1st](https://rescript-lang.org/blog/bucklescript-8-1-new-syntax), the Reason and BuckleScript teams decided to split up due to different goals / roadmaps. BuckleScript was renamed to ReScript and shipped its own syntax (also called ReScript) to provide a more fine-tuned experience for their JS focused users (while dropping native compilation support). More infos on the BuckleScript -> ReScript rebrand can be found in the [official rebranding announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding). +On [July 1st 2020](https://rescript-lang.org/blog/bucklescript-8-1-new-syntax), the Reason and BuckleScript teams decided to split up due to different goals / roadmaps. BuckleScript was renamed to ReScript and shipped its own syntax variant (called ReScript) to provide a more fine-tuned experience for their JS focused users (while dropping native compilation support). More infos on the BuckleScript -> ReScript rebrand can be found in the [official rebranding announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding). Reason continues its promise to be 100% compatible with OCaml semantics, therefore will change its focus on `js_of_ocaml` centered workflows for a streamlined cross-platform compilation story (native / js). From 758372fa2e7ea915f9f88968c595d458b68ec0b4 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sun, 3 Jan 2021 09:30:10 +0100 Subject: [PATCH 20/28] Update installation --- docs/installation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 26ee01164c..129a134d01 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,7 +2,7 @@ title: Installation --- -> **Important:** In case you are looking for BuckleScript + Reason instructions, please note that BuckleScript has rebranded to ReScript and created its own syntax (it's very similar to Reason that is targeted more towards JS development needs). Please refer to the [ReScript website](https://rescript-lang.org) or our [FAQ](http://localhost:3000/docs/en/faq#what-is-bucklescript-and-rescript-and-why-is-it-mentioned-in-so-many-reason-related-resources) for more infos. +> **Important:** If you are looking for ReScript (formerly BuckleScript) installation instructions, please refer to the [ReScript website](https://rescript-lang.org/docs/manual/latest/installation). Reason comes with its own "npm like" package manager called [esy](https://esy.sh): @@ -65,10 +65,10 @@ git clone https://github.com/jchavarri/hello-jsoo-esy.git cd hello-jsoo-esy esy -yarn -yarn webpack +npm install +npm run webpack ``` ## What's Next? -After you have successfully compiled your first example, it's time to [set up your editor](editor-plugins.md) to get access to all the nice features such as auto-completion. After the editor setup, it's time to start with the [language basics](overview.md) to get a basic understanding of all the Reason language constructs. +After you have successfully compiled your first example, it's time to [set up your editor](editor-plugins.md) to get access to all the nice features such as auto-completion. Later on you can check out the [language basics](overview.md) to get a basic understanding of all the Reason language constructs. From 5e53b2e15952691d0f758679e08a71e96f12935f Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sun, 3 Jan 2021 09:45:54 +0100 Subject: [PATCH 21/28] Update JSX docs - Added note on ReScript JSX docs for ReasonReact usage - Removed ReasonReact / BuckleScript mentions - Added ReveryUI as a framework using the JSX semantics --- docs/jsx.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/jsx.md b/docs/jsx.md index 41afbb4690..03dcdb5c0d 100644 --- a/docs/jsx.md +++ b/docs/jsx.md @@ -2,12 +2,12 @@ title: JSX --- +> **Note:** If you are looking for ReasonReact specific JSX infos, please refer to the [ReScript JSX docs](https://rescript-lang.org/docs/manual/v8.0.0/jsx) instead. + Would you like some HTML syntax in your Reason? If not, quickly skip over this section and pretend you didn't see anything! Reason supports the JSX syntax, with some slight differences compared to the one in [ReactJS](https://facebook.github.io/react/docs/introducing-jsx.html). Reason JSX isn't tied to ReactJS; they translate to normal function calls: -**Note** for [ReasonReact](//reasonml.github.io/reason-react/) readers: this isn't what ReasonReact turns JSX into, in the end. See Usage section for more info. - ## Capitalized Tag ```reason @@ -56,8 +56,6 @@ This is the syntax for passing a list of two items, `foo` and `bar`, to the chil ([@JSX] MyComponent.createElement(~children=[foo, bar], ())); ``` -**Note** again that this isn't the transform for ReasonReact; ReasonReact turns the final list into an array. But the idea still applies. - So naturally, ` foo ` desugars to `([@JSX] MyComponent.createElement(~children=[foo], ()))`. I.e. whatever you do, the arguments passed to the children position will be wrapped in a list. What if you don't want that? **What if you want to directly pass `foo` without an extra wrapping**? #### Children Spread @@ -68,13 +66,13 @@ To solve the above problem, we've introduced ...foo ``` -This passes the value `foo` _without_ wrapping it in a list (or array, in the case of ReasonReact). Aka, this desugars to: +This passes the value `foo` _without_ wrapping it in a list. Aka, this desugars to: ```reason ([@JSX] MyComponent.createElement(~children=foo, ())); ``` -This is extra useful in the cases where you are handled `foo` that is already a list of things, and want to forward that without wrapping it an extra time (which would be a type error) \*. It also allows you to pass arbitrary data structures at `children` position (remember, JSX `children` is really just a totally normal prop): +This is extra useful in the cases where you are handled `foo` that is already a list of things, and want to forward that without wrapping it an extra time (which would be a type error). It also allows you to pass arbitrary data structures at `children` position (remember, JSX `children` is really just a totally normal prop): ```reason ...((theClassName) =>
) ; @@ -83,8 +81,6 @@ This is extra useful in the cases where you are handled `foo` that is already a ## Usage -See [ReasonReact](//reasonml.github.io/reason-react/docs/jsx) for an example application of JSX, which transforms the above calls into a ReasonReact-specific call. - Here's a JSX tag that shows most of the features. ```reason @@ -94,7 +90,7 @@ Here's a JSX tag that shows most of the features. intAttribute=1 forcedOptional=?{Some("hello")} onClick={send(handleClick)}> -
{ReasonReact.stringToElement("hello")}
+
{"hello"}
``` @@ -118,11 +114,16 @@ Consequently, a Reason JSX component can cram in a few more props before reachin **Note** that this is a departure from ReactJS JSX, which does **not** have punning. ReactJS' `` desugars to ``, in order to conform to DOM's idioms and for backward compatibility. +## Frameworks using JSX + +- [**ReveryUI**](https://www.outrunlabs.com/revery/api/revery/#Overview): A ReactJS-like UI framework for building cross-platform GUI applications + + ## Tip & Tricks For library authors wanting to take advantage of the JSX: the `[@JSX]` attribute above is a hook for potential ppx macros to spot a function wanting to format as JSX. Once you spot the function, you can turn it into any other expression. -This way, everyone gets to benefit the JSX syntax without needing to opt into a specific library using it, e.g. ReasonReact. +This way, everyone gets to benefit the JSX syntax without needing to opt into a specific library using it. JSX calls supports the features of [labeled functions](function.md#labeled-arguments): optional, explicitly passed optional and optional with default. @@ -131,5 +132,3 @@ JSX calls supports the features of [labeled functions](function.md#labeled-argum The way we designed this JSX is related to how we'd like to help the language evolve. See the section "What's the point?" in [this blog post](https://medium.com/@chenglou/cool-things-reason-formatter-does-9e1f79e25a82). The ability to have macros in the language + the library-agnostic JSX syntax allows every library to potentially have JSX without hassle. This way, we add some visual familiarities to the underlying OCaml language without compromising on its semantics (aka how it executes). One big goal of Reason is to let more folks take advantage of the beautiful language that is OCaml, while discarding the time-consuming debates around syntax and formatting. - -\* You might wonder why you never needed such children spread in ReactJS; ReactJS uses some special runtime logic + special syntax transforms + variadic argument detection & marking to avoid most of these cases ([see here](https://github.com/facebook/react/blob/9b36df86c6ccecb73ca44899386e6a72a83ad445/packages/react/src/ReactElement.js#L207)). Such dynamic usage complexifies the type system detection _quite a bit_. Since we control the whole syntax and ReasonReact, we decided to introduce children spread to disambiguate between the case of wrapping vs not wrapping, without compile-time & runtime cost! From 5ccbfdc55d93a83a5c8378d08ff5d6217caa9ab6 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sun, 3 Jan 2021 09:50:53 +0100 Subject: [PATCH 22/28] Update external docs --- docs/external.md | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/docs/external.md b/docs/external.md index 85f5119e40..fe265955e5 100644 --- a/docs/external.md +++ b/docs/external.md @@ -10,23 +10,10 @@ Imagine writing a let binding, but with its body omitted and its (mandatory) typ external myCFunction: int => string = "theCFunction"; ``` -```reason -[@bs.val] external getElementsByClassName: string => array(Dom.element) = - "document.getElementsByClassName"; -``` - -(The above is a [BuckleScript](https://bucklescript.github.io/docs/en/intro-to-external.html)-specific external that binds to a JavaScript function of the same name.) - **Note**: `external`s can only be at the top level, or inside a module definition. You can't declare them in e.g. a function body. ## Usage You'd use an external value/function as if it was a normal let binding. -## Tips & Tricks - -If you come from a JavaScript background: **do take some time to learn about the [BuckleScript externals](https://bucklescript.github.io/docs/en/intro-to-external.html)**! In the beginning, you'll likely encounter quite a few `external`s before you get to write 100% pure idiomatic Reason code. - -## Design Decisions - -Reason takes interoperating with existing code very seriously. Our type system has very strong guarantees. However, such strong feature also means that, without a great interop system, it'd be very hard to gradually convert a codebase over to Reason. Fortunately, the FFI allows us to cooperate very well with [dirty, existing code](converting-from-js.md). The combination of a sound type system + great interop means that we get the benefits of a traditional gradual type system regarding incremental codebase coverage & conversion, without the downside of such gradual type system: complex features to support existing patterns, slow analysis, diminishing return in terms of type coverage, etc. +For more infos on how to link up your C functions within your Reason application, have a look at the [Dealing with foreign libraries](https://dune.readthedocs.io/en/stable/foreign-code.html?highlight=foreign) section in the `dune` build system docs. From 6c69f8767a8c8da77e8751e52130fd04b50461ae Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sun, 3 Jan 2021 10:04:59 +0100 Subject: [PATCH 23/28] Make FAQ leaner --- docs/faq.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index b91b6b4fdc..d0553121d3 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,10 +14,6 @@ Reason also gives access to the declarative UI framework [revery-ui](https://git Reason was originally bundled with BuckleScript (ReScript) as its user-facing syntax to provide a single toolchain for Reason JS / ReactJS development. -On [July 1st 2020](https://rescript-lang.org/blog/bucklescript-8-1-new-syntax), the Reason and BuckleScript teams decided to split up due to different goals / roadmaps. BuckleScript was renamed to ReScript and shipped its own syntax variant (called ReScript) to provide a more fine-tuned experience for their JS focused users (while dropping native compilation support). More infos on the BuckleScript -> ReScript rebrand can be found in the [official rebranding announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding). - -Reason continues its promise to be 100% compatible with OCaml semantics, therefore will change its focus on `js_of_ocaml` centered workflows for a streamlined cross-platform compilation story (native / js). - -ReScript will continue to support Reason `v3.6` for backwards compatibility, but will not ship any other future Reason versions. The ReScript website also kept the [`< 8.2.0` docs](https://rescript-lang.org/docs/manual/v8.0.0/introduction) in Reason syntax to allow easy usage during the Reason -> ReScript migration. - -If you are already using BuckleScript + Reason, we recommend to either upgrade your existing code to ReScript syntax, or alternatively, consider migrating to a `js_of_ocaml` based setup to keep 100% compatibility with the OCaml platform and runtime semantics. +On [July 1st 2020](https://rescript-lang.org/blog/bucklescript-8-1-new-syntax), the Reason and BuckleScript teams decided to split up due to different goals / roadmaps: +- BuckleScript was renamed to ReScript and shipped its own syntax variant (called ReScript) to provide a more fine-tuned experience for their JS focused users. More on that in their [official rebranding announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding). +- Reason / ReasonML continues its promise to be 100% compatible with OCaml semantics, therefore will change its focus on `js_of_ocaml` centered workflows for a streamlined cross-platform compilation story (native / js). From fc65dad26685d46d5f04911aa4344e0496e9f7f6 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sun, 3 Jan 2021 10:05:54 +0100 Subject: [PATCH 24/28] Remove note on object page to non-existing section --- docs/object.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/object.md b/docs/object.md index b00dfa4450..c7bba676cb 100644 --- a/docs/object.md +++ b/docs/object.md @@ -4,8 +4,6 @@ title: Object Most of time in Reason, you'd be using record to group named values together. In certain niche situations, however, you might want to use a similar feature called object; they're a bit more flexible and come with different tradeoffs. -**If you come from JavaScript**, you're mostly likely **not** looking for plain Reason objects. Skip right to the Tip & Tricks section below. - ## Usage ### Type Declaration From 800d32fa6b890ad824c767acf1c8287317058489 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sun, 3 Jan 2021 10:26:22 +0100 Subject: [PATCH 25/28] Remove broken links in "users-of-reason" Some companies seem to be gone, and I couldn't find any sign of being renamed / being acquired, so I removed them. --- website/siteConfig.js | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/website/siteConfig.js b/website/siteConfig.js index 60c06d5306..868f2a3938 100644 --- a/website/siteConfig.js +++ b/website/siteConfig.js @@ -24,11 +24,6 @@ const users = [ image: "img/logos/beop.svg", infoLink: "https://beop.io", }, - { - caption: "Mesopo", - image: "img/logos/mesopo.svg", - infoLink: "https://mesopo.ai", - }, { caption: "Social Tables", image: "img/logos/socialtables.svg", @@ -229,11 +224,6 @@ const users = [ image: "img/logos/cutii.svg", infoLink: "https://www.cutii.io/en" }, - { - caption: "Velvon", - image: "img/logos/velvon.svg", - infoLink: "https://velvon.com/en/home/" - }, { caption: "Band Protocol", image: "img/logos/band-protocol.svg", From 2e6b374bf1d09c068094a026fed754804835a51f Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Sun, 3 Jan 2021 10:28:46 +0100 Subject: [PATCH 26/28] Undo (obsolete) addition for JavaScript --- website/sidebars.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/sidebars.json b/website/sidebars.json index 3a8b683738..fd2b039f6e 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -30,7 +30,7 @@ "exception", "object" ], - "JavaScript (obsolete)": [ + "JavaScript": [ "interop", "syntax-cheatsheet", "pipe-first", From acf2fd95dab04a51cb67acb7bf27b6e2a49904e4 Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Tue, 5 Jan 2021 09:42:58 +0100 Subject: [PATCH 27/28] Less detailed faq --- docs/faq.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index d0553121d3..174002d32f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -12,8 +12,6 @@ Reason also gives access to the declarative UI framework [revery-ui](https://git ### What is BuckleScript and ReScript, and why is it mentioned in so many Reason related resources? -Reason was originally bundled with BuckleScript (ReScript) as its user-facing syntax to provide a single toolchain for Reason JS / ReactJS development. +Reason was originally bundled with BuckleScript (JS compiler) to provide a single toolchain for JS / ReactJS development. -On [July 1st 2020](https://rescript-lang.org/blog/bucklescript-8-1-new-syntax), the Reason and BuckleScript teams decided to split up due to different goals / roadmaps: -- BuckleScript was renamed to ReScript and shipped its own syntax variant (called ReScript) to provide a more fine-tuned experience for their JS focused users. More on that in their [official rebranding announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding). -- Reason / ReasonML continues its promise to be 100% compatible with OCaml semantics, therefore will change its focus on `js_of_ocaml` centered workflows for a streamlined cross-platform compilation story (native / js). +In July 2020, BuckleScript released its own syntax and rebranded to ReScript to be its own language. More infos can be found in their [official rebranding announcement](https://rescript-lang.org/blog/bucklescript-is-rebranding). From 851772eb0656a1ace3e6f21129cf1ba75666edcf Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Tue, 5 Jan 2021 09:51:32 +0100 Subject: [PATCH 28/28] Update en.json --- website/i18n/en.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/i18n/en.json b/website/i18n/en.json index 5ad35305d4..21f88f1933 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -157,7 +157,7 @@ "Setup": "Setup", "Language Basics": "Language Basics", "Advanced Features": "Advanced Features", - "JavaScript (obsolete)": "JavaScript (obsolete)", + "JavaScript": "JavaScript", "Extra": "Extra", "Community": "Community" }