Build wizardry
--------------

There are two lexers:
- [ml/FStar_Parser_LexFStar.mll] (building F* via OCaml extraction)
- [lex.fsl] (building F* with F#)

The former bundles everything lexing-related into a single file. The latter has
a companion file [lexhelp.fs] that contains various routines.

There is one parser, [parse.mly] written for menhir (enhanced version of ocamnlyacc).
[parse.mly] is then used to produce :
- [ocaml-output/parse.mly] which is the ocamlyacc version of the parser for the ocaml-based F* compiler
- [parse.fsy] which is the fsyacc version of the parser for the F# based F* compiler

Both of these file are generated by [ocaml-output/Makefile] when a valid menhir
version is found, otherwise the build will fail.

If you want to modify the parser, you need a recent version of menhir (at least
december 2016). Also the printer in [src/parser/FStar.Parser.ToDocument.fs] should
be kept up to date with the parser as much as possible since it tries to keep
the same general structure as the parser.


- [parser/parse.fs(i)]; is auto-generated from [parse.fsy] by [fsyacc];
  The fsi is sed-copied as [boot/FStar.Parser.Parse.fsti] when *extracting*
  [lexhelp.fs] so that [lexhelp.fs] has
  something to type-check against; but, it is _not_ used when compiling the
  extracted OCaml code, because the token datatype is directly written out by
  [ocamlyacc] into [parse.ml]; note: this file is checked in to support the
  scenario where someone wants to bootstrap and recompile without an F# setup

If you're adding a new token, you need to edit:
- [lexhelp.fs] to add it to the parser keyword table (F#)
- [ml/FStar_Parser_LexFStar.mll] to add it to the parser keyword table (OCaml)
- [parse.mly] to expose it to the parser, possibly with an adequate precedence

A common workflow for use with Visual Studio is:
 1. edit parse.mly
 2. run make -C src/ocaml-output ../parser/parse.fsy
 3. rebuild in Visual Studio