INSTALL

========================================================================
Beluga Installation & Configuration Guide
========================================================================

Table of contents:

1. Installation
  1.1 Generic Prerequisites
    1.1.1 Debian/Ubuntu
    1.1.2 macOS
    1.1.3 Windows
      1.1.3.1 Using WSL
      1.1.3.2 Using Cygwin
  1.2 Building
    1.2.1 Compilation Tips
  1.3 Troubleshooting
2. Configuration
  2.1 Running Ruby Script to Convert to New Syntax
  2.2 Beluga-mode for Emacs

=========================
1. Installation
=========================

1.1 Generic Prerequisites
=========================

The following packages must be installed to use Beluga:

ocaml 4.05.0+:           http://caml.inria.fr/download.en.html
extlib:                  http://code.google.com/p/ocaml-extlib/downloads/list
gen:                     https://github.com/c-cube/gen
linenoise:               https://github.com/ocaml-community/ocaml-linenoise
sedlex:                  https://github.com/ocaml-community/sedlex

Optional dependencies (for improved beli mode):

rlwrap:                  http://utopia.knoware.nl/~hlub/uck/rlwrap/


1.1.1 Debian/Ubuntu
-------------------

Under Debian Linux, all the necessary prerequisites can be installed
with just the following command:

$ apt-get install opam
$ opam init --bare
$ opam switch create ocaml-base-compiler.4.09.0
$ eval $(opam env)
# from the Beluga directory
$ opam install --deps-only .

The interactive mode is greatly improved if you have rlwrap installed,
so you might also want to consider:

$ apt-get install rlwrap

These commands may work under other distributions.

1.1.2 macOS
-----------

Under macOS, the easiest way to install the prerequisites is via opam,
and the easiest way to install opam is via Homebrew (https://brew.sh/):

$ brew install opam
$ opam init --bare
$ opam switch create ocaml-base-compiler.4.09.0
$ eval $(opam env)
# from the Beluga directory
$ opam install --deps-only .

The interactive mode is greatly improved if you have rlwrap installed,
so you might also want to consider:

$ brew install rlwrap

1.1.3 Windows
-------------

There are two options for Windows users. If you use Windows 10 or
later versions, Using WSL (Windows Subsystem for Linux) is
recommended.

1.1.3.1 Using WSL

Install WSL (https://docs.microsoft.com/en-us/windows/wsl/install-win10)
first, and follow the right instruction according to your distribution.

In Ubuntu WSL distribution, following the instructions for Debian/Ubuntu
systems will work just as in those systems.

For other WSL distributions, please follow the instruction of opam
(https://opam.ocaml.org/doc/Install.html) to install opam, then execute
the following commands.

$ opam init --bare
$ opam switch create ocaml-base-compiler.4.09.0
$ eval $(opam env)
# from the Beluga directory
$ opam install --deps-only .

For more information about WSL
  https://docs.microsoft.com/en-us/windows/wsl/about

1.1.3.2 Using Cygwin

If you use Windows 8 or earlier versions, you can build and execute
Beluga on Windows through Cygwin. The necessary prerequisites can be installed
using opam for Windows.

1. Download opam for Windows' graphical installer OCaml32/64.exe
  https://fdopen.github.io/opam-repository-mingw/installation/

2. Run OCaml32/64.exe and step through the installation wizard
  Note: if you don't already have Cygwin installed,
  it will be installed for you.

3. Run the following commands from Beluga directory within cygwin terminal.

$ opam switch create ocaml-variants.4.09.0+mingw64c
$ eval $(opam env)
# from the Beluga directory
$ opam install --deps-only .

For more inforamtion about opam for Windows
  https://fdopen.github.io/opam-repository-mingw
For more information about Cygwin
  http://www.cygwin.com/

1.2 Building
============

Compile by running "make" from the Beluga directory.

$ make

You can now run Beluga programs with the newly
"beluga" executable in the "bin" directory

$ ./bin/beluga path/to/program.bel

1.2.1 Compilation Tips
-------------------------

Running `make clean' will clean the directory of compilation results

1.3 Troubleshooting
===================

Attempting to build Beluga before installing the prequisites may cause
libraries to be only partially updated. You may recieve a new error message
once you've set up the prereq packages.

Error: The files [path/to/file]
        and [path/to/file]
        make inconsistent assumptions over interface [library name]

Try cleaning the Beluga directory.

$ make clean all

=========================
2. Configuration
=========================

2.1 Running Ruby Script to Convert to New Syntax
================================================

You will need Ruby 1.9 for running the script.

For MAC OS:
The default version of ruby installed on Mac OS is usually not Ruby 1.9, but
Ruby 1.8. To install the newest version of Ruby, we recommend installing first
RVM, the “Ruby Version Manager. This will make installing Ruby 1.9 easy.
In your home directory, you can say:

$ bash < <(curl -s https://rvm.beginrescueend.com/install/rvm)

rvm is then installed in .rvm/bin.

Then you can say:

$ .rvm/bin/rvm install 1.9.3

Note, you will want to add .rvm/bin to your .bashrc directory, so you will be
able to find rvm without giving the full path.

2.2 Beluga-mode for GNU Emacs
=============================

Beluga includes a major mode for programming in Emacs. The elisp file is
located in the ./tools directory. To configure Beluga-mode:

1. Update your ~/.emacs or ~/.emacs.d/init.el file with the lines written below.
  XEmacs users must update ~/.emacs or ~/.xemacs/init.el with the same text.
  Create any of these files if they do not exist already.

;; You should replace path/to/beluga with the actual path of the Beluga directory.
(add-to-list 'load-path "path/to/beluga/tools/")
(load "beluga-mode.el")

NOTE: Feel free to move the beluga-mode.el file to another directory so long as
you add its location to the Emacs load-path.

2. Restart Emacs.
  Emacs will now launch in Beluga-mode automatically when you open a Beluga
  program.