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 must be installed before proceeding with the installation of
Beluga:

opam 2.1.4+:             https://opam.ocaml.org/doc/Install.html
GNU Make 4.0+:           https://www.gnu.org/software/make/

Optional dependencies (for improved beli mode):

rlwrap:                  https://github.com/hanslub42/rlwrap


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

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

$ apt-get install opam
$ opam init --bare
# from the Beluga directory
$ make setup-install
$ make install

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
# from the Beluga directory
$ make setup-install
$ make install

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)
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 ./beluga.opam

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 ./beluga.opam

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 built "beluga" executable

$ ./_build/install/default/bin/beluga path/to/program.bel

Use the following command to install Beluga in the current opam switch:

$ make install

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

Running `make clean' will clean the directory of compilation results.
If you installed Beluga in the current opam switch, use `make uninstall` to
remove it.

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

Attempting to build Beluga before installing the prequisites may cause
libraries to be only partially updated. You may receive a new error message
once you've set up the prerequisite 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

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

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

You will need Ruby 1.9 for running the script.

For macOS:
The default version of ruby installed on macOS 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.