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.