Instructions on Getting Started with Windows

[chenglou]

See the post below. If you have new findings, please comment. We'll then integrate your findings into the post and remove the comment to reduce noise. Thanks!

Edit: upon demand, I've cleaned up most of the outdated replies.

[superherointj]

Hello Windows user!

First. A very warm welcome. We're really glad you are here! We've been waiting for you! And I bring you good news:

Reason works 100% on Windows

• BuckleScript (bs-platform) is verified to work well on Windows.
• It's the editor tooling (mainly, Merlin not working in Windows environment with VSCode Reason extension) that's lacking.
  • but there's a working workaround by running Merlin on Windows 10 WSL
    • all features (live errors, code lens, code completion, auto formatting) work as expected.
      • exception is go-to definition/error line in message panel doesn't work yet
        • a very minor thing and it might be fixed eventually
• bsb-native, BuckleScript's bsb build system altered to compile to native code (using ocamlc/ocamlopt), works on windows and can be installed through npm like npm install bsansouci/bsb-native\#2.1.1

Workarounds

Solution 1: Ocaml/Reason on WSL (recommended)

• What running a Reason project on WSL mean?
  Project will live on Windows 10 WSL environment, like a VM, but well integrated into Windows,
  project files are kept in Windows file system (like C:/somewhere/xxx, etc). But project dependencies, tools are linux based and should be installed/built/used on WSL (not Windows Command Prompt). Editing can be done on Windows as usual. Basically, instead of using Windows Command Prompt, you'll be using WSL's Bash.

Install Windows Subsystem for Linux (WSL)

• First. Upgrade Windows 10 to latest version (Fall Creators Update, version 1709 or later).
  • Yes! Do it. WSL version is tied to Windows version. WSL has bugs, some fixed on upgrade.
• If you have already installed WSL, make sure to activate the correct new Ubuntu environment:
  • to list current installed environments: wslconfig /list /all
  • Either:
    • remove legacy environment: lxrun /uninstall /full
    • set the new Ubuntu environment as default: wslconfig /setdefault Ubuntu
    • or scrap current Ubuntu environment: wslconfig /unregister Ubuntu
      • To reinstall, find the distribution in the Windows Store and select "Launch".
• Install WSL's Ubuntu distribution from Microsoft Store, as described in official guide:
  • https://msdn.microsoft.com/en-us/commandline/wsl/install_guide
• Upgrade Ubuntu to a current version:
  • Open Ubuntu's Bash application:
    • sudo apt-get update
    • sudo apt-get dist-upgrade

Install Reason & Tools

Pick between Manual vs Automated option:

Option - Automated NPM Install for OPAM method

• Requires:
  • Node/NPM installed on Windows. If not, install it
• On Windows Command Prompt (not WSL), do:
  npm install -g ocaml-reason-wsl
• Now that it is installed, skip to "Configure Editor" topic bellow.
• Optional:
  • To remove batch shortcuts to solve conflict between unix command versions and windows, like having a Windows native bs-platform in Windows environment (not WSL version), do:
  • npm uninstall -g ocaml-reason-wsl
  • This won't affect Reason/Ocaml installation in WSL because the script has run already. It only removes Windows shortcuts to applications in WSL environment. But then bash -ci is required for executing any application from WSL in Windows Command Prompt.

Option - Manual Install

On WSL (not Windows Command Prompt):

Install NPM/Node

• Check if node is installed: node -v
  • If not, install it:
    • curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -
    • sudo apt-get install -y nodejs
    • [Exit bash and reopen it to refresh session OR NPM won't be found]
• Fix NPM permissions:
  • Make a directory for global installations:
    mkdir ~/.npm-global
  • Configure npm to use the new directory path:
    npm config set prefix '~/.npm-global'
  • Add "export PATH=~/.npm-global/bin:$PATH" to ~/.bashrc:
    • echo export PATH=~\/.npm-global\/bin:\$PATH >> ~/.bashrc
  • Back on the command line, update your system variables:
    source ~/.bashrc
  • [Exit bash and reopen it to refresh session OR NPM global folder won't swap]
• Upgrade NPM version to >= 5.4.2: npm install -g npm # Important!
  • [Exit bash and reopen it to refresh session OR NPM won't be updated]

Install Reason & Reason-Tools (Merlin, Refmt...)

Pick a method "OPAM" or "Reason-CLI". And run commands on WSL:

• Method: Reason-CLI (NPM package)
  • For Reason 3.2.0:
    • npm install -g reason-cli@3.2.0-linux
  • Install missing BuckleScript dependency for this method:
    • sudo apt-get install -y build-essential
• Method: OPAM (ocaml package manager)
  • Install Opam/OCaml:
    • sudo apt-get install -y ocaml-nox opam m4
  • Set-up opam/ocaml:
    • opam init
    • Add "eval $(opam config env)" to ~/.bashrc; it's needed at every shell startup.
      • echo eval \$\(opam config env\) >> ~/.bashrc
    • opam update
    • opam switch 4.02.3
    • eval $(opam config env)
  • Install Reason and Merlin tools using Opam:
    • opam update
    • opam install reason
    • opam install merlin.2.5.4 # For Windows, Merlin 2.5.4 is stable and recommended.

On WSL's Bash, Install BuckleScript globally

• npm install -g bs-platform

Configure Editor

• On Visual Studio Code:
  • Certify VSCode is 64-bit. (In menu, Help -> About -> Architecture x64)
  • Install "OCaml and Reason IDE" extension (publisher freebroccolo / Darin Morrison):
  • Add to VSCode "User Settings":
    • "reason.path.bsb": "bash -ic bsb",
      "reason.path.ocamlfind": "bash -ic ocamlfind",
      "reason.path.ocamlmerlin": "bash -ic ocamlmerlin",
      "reason.path.opam": "bash -ic opam",
      "reason.path.rebuild": "bash -ic rebuild",
      "reason.path.refmt": "bash -ic refmt",
      "reason.path.refmterr": "bash -ic refmterr",
      "reason.path.rtop": "bash -ic rtop"
    • To enable auto-format, add: "editor.formatOnSave": true
    • To enable bucklescript errors, set: "reason.diagnostics.tools": ["merlin", "bsb"]
    • To set bash as default terminal, add: "terminal.integrated.shell.windows": "C:\\WINDOWS\\System32\\bash.exe"

Test It

• Create/choose a folder. An example: C:\projects\
• On WSL:
  • Change directory to folder, like: cd /mnt/c/projects/
  • Then create a sample project:
    • bsb -init demoapp -theme basic-reason
    • cd demoapp
    • npm install
    • npm run start
  • Open VSCode in this new folder: C:\projects\demoapp

Troubleshooting

• Make sure VSCode is 64-bit.
• VSCode is executed in Windows environment and has to be opened on folder location exactly where .merlin file is located. Executing command bsb (like bsb -make-world) generates .merlin file. bsb has to be executed in WSL to create .merlin file with unix path style (instead of Windows style path).
• All project tools/dependencies must be linux based and executed on WSL environment, including installing (npm install), compiling/building (bsb -make-world), tests (jest). Mixing windows and linux environment is not recommended.
• Test Merlin's application:
  • On Windows Command Prompt try command:
    • bash -ci 'ocamlmerlin -version'
      • Output must be:
        • The Merlin toolkit version 2.5.4, for Ocaml 4.02.3
  • On WSL' bash try command:
    • ocamlmerlin -version
      • Output must be:
        • The Merlin toolkit version 2.5.4, for Ocaml 4.02.3
  • If it fails, there is an installation problem.
    • If you have installed ocaml-reason-wsl over Windows's NPM first, make sure to remove it.
      • On CMD (not WSL): npm -g uninstall ocaml-reason-wsl
    • WSL supports multiple environments and you need to make sure you have the correct Ubuntu environment chosen.
      • To check if you have any older / legacy WSL environment active:
        • wslconfig /list /all
      • If Ubuntu isn't default. Pick it as default environment with command:
        • wslconfig /setdefault Ubuntu
    • Optional: To scrap a legacy WSL environment, run:
      • lxrun /uninstall /full
    • Dangerous tip - For the record: Once to workaround some odd errors, like not being able to Launch Ubuntu from Microsoft Store, had to manually remove WSL environment, found it at:
      • C:\Users\%USERNAME%\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\
• Problem: If WSL initially works fine and when running bucklescript on watch mode WSL crashes unexpectedly, or closes or becomes unresponsive, and closing WSL window and reopening won't start the Bash prompt.
  • Workaround: Restart your computer and try to open Bash again.
  • Make sure to keep your Windows and WSL's Ubuntu updated.
    • WSL version is tied to Windows version. For having latest WSL fixes it's necessary Windows insiders build.
  • This problem needs further debug. Known WSL issues, WSL#2613, WSL#2746.
  • There is a campaign to solve root issue. Would be nicer solving root issue instead of workaround of the workaround.

On success

Report it. Come to Discord. Tweet. Spread the word. Show your friends how awesome you are for having the cutting edge Reason working in Windows. Your love is appreciated. S2

On trouble, failure, broken heart

• Come to Discord, and let's talk! We can usually help you out.
  • https://discord.gg/reasonml
    • For Windows WSL issues use #editorsupport channel.

[superherointj]

Ignore this post if you are a newcomer.

Follow first @superherointj post!

This is a development post for keeping notes, tracking issues to when time is due improve official user guide post above. It has been split to lower the noise.

Work In Progress - Current Status

Notes:

• Merlin.2.5.5 is known to work well with old-protocol. Merlin.3.0.5 might work from WSL too but there are issues in Windows native.
• Only a path translation fix for VSCode extension is missing but the update is automatic and the fix is coming next release.

Solution: Windows Native without Merlin w/ BSB errors

How it would work

• Instead of running Merlin on Windows native, it is possible to have BSB errors piped into VSCode, solving the diagnosis part provided by Merlin, but not the autocomplete, jump-to-definition.

• Refmt:

  • For refmt, it is possible to use bsrefmt that comes with bs-platform, under node_modules/bs-platform/bin/bsrefmt. This is BuckleScript's vendor refmt, pinned at 1.13.7 (for the new syntax3, it's node_modules/bs-platform/bin/refmt3.exe. Just make your editor point to it.
  • BuckleScript Refmt3.exe works in Windows native when Path is set in absolute. Like:
    "reason.path.refmt": "C:\\Users\\user\\AppData\\Roaming\\npm\\node_modules\\bs-platform\\lib\\refmt3.exe",

• BSB errors is still on research.

For now, solution for "Windows Native" isn't ready. Because:

• ReasonML's VSCode extension requires Merlin for working. Which leads to the case where either Merlin works on Windows (with windows paths in .merlin file) or Merlin has to be disabled. It's absence is not handled gracefully and shows errors. In a future release Merlin might be optional. Right now on Windows native neither can be done. (Having it working nor disable it.)

• Workaround to using windows native without Merlin and getting rid of Merlin errors in VSCode extension: Setting ocamlmerlin-server to ocamlmerlin app name in VSCode config. It doesn't pop up any errors anywhere. But won't work (autocompletion, code lens, diagnostics) either. But it requires having ocamlmerlin-server (could be installed from Cygwin ENV).

Solution: Docker

Still on Research. Attempts:

• https://gist.github.com/pbiggar/cce9b958704c6cadd9597b717bc18c4d

To-Do

• Update info on Merlin being optional.
• Add new editors
  • Atom
  • Vim (vim-reason-plus on the LanguageClient-Neovim plugin)
• Add how to check for updates & upgrade:
  • wsl environment.
  • merlin
  • reason
  • bs-platform

On Watch

• VSCode extension
  • Merlin being optional working. (There is the optional but it is not known to work as expected. This is required for minimal (without Merlin) Windows native support.)
  • Issue #113 WslMode
    • Automates bash commands definition
    • Fix translating paths between unix/windows (affects jumping to error location/file/position.)

If you know how to make this documentation better, reply here, shout at us or just fix it (if you can).
Thanks in advance for helping us make this documentation better.

[superherointj]

Fundraiser for better Editor Support in Windows (Without WSL)

Join effort! :)
reasonml/reason#1698

[robkuz]

hey,

I am using Reason on Windows 10 (WSL) and I followed the instructions here - at least I think so
but I get this error

0 info it worked if it ends with ok
1 verbose cli [ '/usr/bin/node', '/usr/bin/npm', 'run', 'start' ]
2 info using npm@5.6.0
3 info using node@v8.11.3
4 verbose run-script [ 'prestart', 'start', 'poststart' ]
5 info lifecycle demoapp@0.1.0~prestart: demoapp@0.1.0
6 info lifecycle demoapp@0.1.0~start: demoapp@0.1.0
7 verbose lifecycle demoapp@0.1.0~start: unsafe-perm in lifecycle true
8 verbose lifecycle demoapp@0.1.0~start: PATH:...
9 verbose lifecycle demoapp@0.1.0~start: CWD: reason-test/demoapp
10 silly lifecycle demoapp@0.1.0~start: Args: [ '-c', 'bsb -make-world -w' ]
11 silly lifecycle demoapp@0.1.0~start: Returned: code: 2  signal: null
12 info lifecycle demoapp@0.1.0~start: Failed to exec start script
13 verbose stack Error: demoapp@0.1.0 start: `bsb -make-world -w`
13 verbose stack Exit status 2
13 verbose stack     at EventEmitter.<anonymous> (/usr/lib/node_modules/npm/node_modules/npm-lifecycle/index.js:285:16)
13 verbose stack     at emitTwo (events.js:126:13)
13 verbose stack     at EventEmitter.emit (events.js:214:7)
13 verbose stack     at ChildProcess.<anonymous> (/usr/lib/node_modules/npm/node_modules/npm-lifecycle/lib/spawn.js:55:14)
13 verbose stack     at emitTwo (events.js:126:13)
13 verbose stack     at ChildProcess.emit (events.js:214:7)
13 verbose stack     at maybeClose (internal/child_process.js:925:16)
13 verbose stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:209:5)
14 verbose pkgid demoapp@0.1.0
15 verbose cwd /reason-test/demoapp
16 verbose Linux 4.4.0-17134-Microsoft
17 verbose argv "/usr/bin/node" "/usr/bin/npm" "run" "start"
18 verbose node v8.11.3
19 verbose npm  v5.6.0
20 error code ELIFECYCLE
21 error errno 2
22 error demoapp@0.1.0 start: `bsb -make-world -w`
22 error Exit status 2
23 error Failed at the demoapp@0.1.0 start script.
23 error This is probably not a problem with npm. There is likely additional logging output above.
24 verbose exit [ 2, true ]

Intersting enough I have 2 other machines where this worked w/o problems. Does anybody see the error?

[amsterdamharu]

None of this seems to be needed for Windows.

Just tried on Windows 10:

yarn global add bs-platform
bsb -init my-react-app -theme react
cd my-react-app
yarn install
yarn start

In another command prompt:

yarn run webpack

In vscode pressed control+p and pasted the command:
ext install jaredly.reason-vscode

Looks like it works as it should (did reload the vscode window after installing and setting Reason_language_server values in settings)

[Jonas164]

ocaml 4.02.3 is severly outdated and I require ocaml 4.05 or greater. Is there a known solution to get merlin to work with WSL and VSCode with Ocaml >= 4.05 ? If yes, how? Simply switching to a newer ocaml version does not work.

[robkuz]

I got it running with installing X-Windows and running VSCode on WSL. However you better have a powerful machine. It ain't exactly fast

[Jonas164]

That does not seem much better than just using a Unix-VM. Both, X-Windows and a VM are not enjoyable on my laptop though

[emileber]

@amsterdamharu as the project grows, jaredly.reason-vscode extension will eventually fail with "Command line is too long": jaredly/reason-language-server#262