Get_started.adoc

Get Started

Using existing templates (@since 1.7.4 )

BuckleScript provide some project templates, to help people get started on board as fast as possible.

npm install -g bs-platform && bsb -init hello && cd hello && npm run build

First, it installs bs-platform globally, then we use the command line tool bsb to set up a sample project named hello, then we run the build.

The output project layout is similar as below

hello>tree -d .
.
|---.vscode
├── lib
│   ├── bs
│   │   └── src
│   └── js
│       └── src
├── node_modules
│   └── bs-platform -> ...
└── src

To enter watch mode, you can run npm run watch, then you can edit src/demo.ml and see it compiled on the fly, and changes are updated on lib/js/src/demo.js

If you happen to use VSCode as editor, we provide .vscode/tasks.json as well, type Tasks>build, it will enter watch mode, the great thing is that VSCode comes with a Problems panel which has a much nicer UI.

Currently there are not too many project templates, you can contribute more project templates here here,

First example by hand without samples

• Create a directory called hello and create bsconfig.json and package.json as below:

  bsconfig.json

  {
      "name" : "hello",
      "sources" : { "dir" : "src"}
  }

  package.json

  {
      "dependencies": {
          "bs-platform": "1.7.0" // (1)
      },
      "scripts" : {
          "build" : "bsb",
          "watch" : "bsb -w" // (2)
      }
  }

  1. Version should be updated accordingly

  2. Watch mode when developing

• Create src/main_entry.ml as below:

  src/main_entry.ml

  let () =
    print_endline "hello world"

• Build the app

  npm run build

Now you should see a file called lib/js/src/main_entry.js generated as below:

lib/js/src/main_entry.js

// GENERATED CODE BY BUCKLESCRIPT VERSION 1.0.1 , PLEASE EDIT WITH CARE
'use strict';


console.log("hello world");

/*  Not a pure module */ (1)

1. The compiler detects this module is impure due to the side effect.

User can also run watch mode to see changes instantly while editing.

npm run watch

Tip	The working code is available here:

An example with multiple modules

Now we want to create two modules, one file called fib.ml which exports fib function, the other module called main_entry.ml which will call fib.

• Create a directory fib and create files bsconfig.json and package.json

  bsconfig.json

  {
      "name" : "helo",
      "sources" : { "dir" : "src"}
  }

  package.json

  {
      "dependencies": {
          "bs-platform": "1.7.0"
      },
      "scripts" : {
          "build" : "bsb",
          "watch" : "bsb -w"
      }
  }

• Create file src/fib.ml and file src/main_entry.ml

  src/fib.ml

  let fib n =
    let rec aux n a b =
      if n = 0 then a
      else
        aux (n - 1) b (a+b)
    in aux n 1 1

  src/main_entry.ml

  let () =
    for i = 0 to 10 do
      Js.log (Fib.fib i) (1)
    done

  1. Js module is a built-in module shipped with BuckleScript

• Build the app

  npm install
  npm run build
  node lib/js/src/main_entry.js

If everything goes well, you should see the output as below:

1
1
2
3
5
8
13
21
34
55
89