Skip to content

Latest commit

 

History

History
153 lines (104 loc) · 4.99 KB

Dev-mode-How-to.adoc

File metadata and controls

153 lines (104 loc) · 4.99 KB

Contributions

First, thanks for your interest in contributing! There are plenty of ways to make contributions, like blogging, sharing your experience, open sourcing your libraries using BuckleScript. They are all deeply appreciated.

This section will focus on how to contribute to this repo.

Development set-up

  • Having opam installed

    opam switch 4.02.3+buckle-master # use our OCaml compiler
opam install camlp4  (1)

    Camlp4 is used to generate OCaml code for processing large AST. (j.ml file), if you don’t change j.ml (most likely you won’t), so you probably don’t need it

  • Having NodeJS installed

  • Having Make installed

  • OS: Mac/Linux (Note BuckleScript works on Windows, but the dev mode is not tested)

Below assume that you are working in jscomp directory, and that you’ve followed instructions from [Minimal dependencies] to build OCaml.

Contributing to bsb.exe

The build target is

make -C bin bsb.exe

So whenever you change files relevant to the build tool bsb.exe, try it and do some test. If it works, send a pull request!

Note that for most binaries in BuckleScript, we also have a release mode, which will pack all relevant files into a single file. This is important, since it will cut all our dev-dependencies, so the user does not need install those tools.

You can verify it by typing

make snapshotml # see the diffs in jscomp/bin

But please don’t commit those changes in PR, it will cause painful merge conflicts.

Contributing to bsc.exe

make -C bin bsc.exe # build the compiler in dev mode
make libs # build all libs using the dev compiler

There is also a snapshot mode,

make snapshotml

This will actually snapshot your changes into a single ml file and used in npm distribution. But please don’t commit those changes in PR, it will cause painful merge conflicts.

Contributing to the runtime

BuckleScript runtime implementation is currently a mix of OCaml and JavaScript. (jscomp/runtime directory). The JavaScript code is defined in the .ml file using the bs.raw syntax extension.

The goal is to implement the runtime purely in OCaml and you can help contribute.

Each new PR should include appropriate testing.

Currently all tests are in jscomp/test directory and you should either add a new test file or modify an existing test which covers the part of the compiler you modified.

  • Add the filename in jscomp/test/test.mllib

  • Add a suite test

The specification is in jscomp/test/mt.ml

For example some simple tests would be like:

let suites : _ Mt.pair_suites =
   ["hey", (fun _ -> Eq(true, 3 > 2));
       "hi", (fun _ -> Neq(2,3));
       "hello", (fun _ -> Approx(3.0, 3.0));
       "throw", (fun _ -> ThrowAny(fun _ -> raise 3))
       ]
let () = Mt.from_pair_suites __FILE__ suites

  • Run the tests

Suppose you have mocha installed, if not, try npm install mocha

mocha -R list jscomp/test/your_test_file.js

To build libs, tests and run all tests:

make libs && make -C test all && npm test

  • See the coverage

npm run cover

Contributing to the documentation

You’ll need Asciidoctor installed and on your PATH. Go into site/docsource/, modify the section you want, and run build.sh. You can check the build.compile file for debug output.

Contributing to the API reference

The API reference is generated from doc comments in the source code. Here's a good example

Some tips and guidelines:

  • The first sentence or line should be a very short summary. This is used in indexes and by tools like merlin.

  • Ideally, every function should have at least one @example

  • Cross-reference another definition with {! identifier}. But use them sparingly, they’re a bit verbose (currently, at least).

  • Wrap non-cross-referenced identifiers and other code in [ …​ ]

  • Escape {, }, [, ] and @ using \

  • It’s possible to use {%html …​} to generate custom html, but use this very, very sparingly.

  • A number of "documentation tags" are provided that would be nice to use, but unfortunately they’re often not supported for `external`s. Which is of course most of the API.

  • @param usually doesn’t work. Use {b <param>} …​ instead

  • @returns usually doesn’t work. Use {b returns} …​ instead.

  • Always use @deprecated when applicable.

  • Always use @raise when applicable.

  • Always provide a @see tag pointing to MDN for more information when available.

See Ocamldoc documentation for a lot more details.

To generate the html, run make docs in jscomp/.

Html generation uses a custom generator located in odoc_gen/ and custom styles located in docs/api_static.