Getting started

Getting started

This section is about installation and configuration of Opa. If you want to learn more about Opa first, please read the online tutorial or the book.

• Get started easily with Vagrant

Or read more to prepare a custom installation of Opa.

• Installing Opa
• Deploying on Cloud Platforms
• Building Opa from the sources
• Setting up your editor
• Troubleshooting

Installing Opa --------------

You can build Opa from source.

Windows

Please consult the dedicated page.

### Mac OS X

• If you have not done so yet, install the Xcode tools, provided by Apple with your copy of Mac OS X. If you do not have Xcode, you can either download Xcode 4 or Xcode 3 (registration required). In addition to general development utilities, this package provides some of the low-level, Mac-specific, tools used by Opa to produce server-side executables.

WARNING:

Starting with Xcode 4.3, Apple does not install command line tools by default anymore, so after Xcode installation, go to Preferences > Downloads > Components > Command Line Tools and click Install. You can also directly download Command Line Tools for Xcode without getting Xcode.

• Download Opa for Mac OS X.
• Once the download is complete, if your browser does not open automatically the file you have just downloaded, go to your Download folder and open this file. This should open a new Finder window containing the Opa installer package.
• Open the Opa installer package by double-clicking on it.
• Follow the instructions on the screen. You will need the password of an administrative account.
• Once the installation is complete, the Opa compiler will be installed in the directory /opt/mlstate and symbolic links will be created in /usr/local/bin hence you should not have to modify your PATH variable to enjoy the Opa compiler and its tools.

### Ubuntu Linux, Debian Linux

The following instructions are also valid for all Debian-based Linux distributions.

• Download the Ubuntu Linux package.
• Once the download is complete, your operating system will offer to install Opa using a tool such as gdebi or kdebi.
• Follow the instructions on the screen. You will need the password of an account with administrative rights.
• Once the installation is complete, the Opa compiler will be installed in the directory /usr/bin and the documentation and examples will be in /usr/share/doc/opa

Alternatively, you can install everything from the command line:

# Install nodejs (which now includes npm) and make:
$ sudo apt-get install python-software-properties make
$ sudo add-apt-repository ppa:chris-lea/node.js
$ sudo apt-get update
$ sudo apt-get install nodejs

# Confirm installs
$ node --version
$ npm --version

# Install required Node modules:
$ sudo npm install -g mongodb formidable nodemailer simplesmtp imap

# Install Opa:
$ wget http://download.opalang.org/ubuntu/opa_1.0.X%2BbuildXXXX_XXXX.deb
$ sudo dpkg -i opa_1.0.X+buildXXXX_XXXX.deb

# Confirm Opa install
$ opa --version

See troubleshooting section below if necessary.

### Arch Linux

Download and run this PKGBUILD. It is not officially supported by us, and we have not tested it, but we are interested in any feedback about it. Alternatively, you can download and run this PKGBUILD. It tries to build the latest git-master version from the source.

### FreeBSD

Follow those instructions.

### SUSE

Copy the link to the Linux package you want to install.

Install Opa:

curl http://download.opalang.org/linux/opa_1.0.X+buildXXXX_XXXX.run > opa.run
chmod a+x opa.run
./opa.run

Install nodejs, npm and make:

zypper ar http://download.opensuse.org/repositories/devel:/languages:/nodejs/openSUSE_XX.X/ NodeJSBuildService
# replace XX.X with your SUSE version
zypper in make nodejs nodejs-devel

Install required modules:

npm -g install mongodb formidable nodemailer simplesmtp imap

Other Linux distribution

To install Opa on Red Hat, Fedora and other Linux distributions which do not use the .deb system, or if you do not have administrative rights on your machine, take the following steps:

• Using your package manager, install packages:

• libssl-devel
• zlib1g-devel

• Or, if these packages do not exist in your distribution, install whichever packages provide

• library libssl.so
• library libz.so

• Download the Linux self-extracting package.

• When prompted by your browser, choose to save the file in a temporary directory, for instance, /tmp.

• To install as a user:

• Set the execution permission on the downloaded program
• Run it and follow the instructions on the screen
• The compiler is installed by default in ~/mlstate-opa/bin

• To install system-wide, open a terminal (if you are using KDE, the terminal is called Konsole)

• In the terminal, write: sudo sh [complete path to the file you have just downloaded]
• Follow the instructions on the screen
• By default, the installation is done in /usr/local

• This installation comes with an un-installation script, in [install prefix]/share/opa/uninstall.sh

### Other Platforms

You can try the packages on other platforms and add a section to this page if you have succeeded.

If necessary, compile and hack Opa from sources. And send a pull-request if you have a fix to share.

Deploying on Cloud Platforms ---------------------------- #### dotCloud

To deploy on dotCloud, clone the Opa on dotCloud configuration example.

#### Heroku

To deploy on Heroku, use the Opa buildpack to create a Heroku application in your Opa project's root directory.

   $ heroku create --stack cedar --buildpack https://github.com/tsloughter/heroku-buildpack-opa.git

This requires you have an opa.conf, Makefile, Procfile and package.json file. For an example see the Opa hello_chat for Heroku example updated to run on Heroku.

#### Cloud Foundry (and other)

Opa applications run on top of Node.js and MongoDB. So any platform supporting these technologies should work. Here is an example to access to environment variables in Opa:

import-plugin unix

get_env = %% BslSys.get_env_var %%
port = Int.of_string(Option.default("8080", get_env("VCAP_APP_PORT")))

Server.start({ Server.http with ~port }, { ~custom })

Then you can use the --bundle option at compile-time to check the dependencies and bundle all the Opa libraries required by your application:

opa --bundle myapp.tar.gz myapp.opa 

You can add a package.json in the archive to declare the extra node modules dependencies available on npm: some cloud providers will use it. Or add them in the node_modules directory of the archive with npm install mongodb formidable nodemailer simplesmtp imap.

Setting up your editor ----------------------

Opa is supported by several IDEs and text editors, including Sublime Text, Atom, VSCode, Eclipse, Emacs and Vim.

SublimeText

Sublime support for Opa is pretty good and used daily by Opa developers. The Opa mode offers:

• Syntax highlighting
• Build system
• Save and build automatically
• Code completion
• Contextual access to the online API documentation
• Snippets
• Tutorials

You can download and try SublimeText for free.

Atom

You can install the language-opa-ocaml package that enables OPA classic (OCAML-like) syntax highlighting in Atom.

Feel free to improve this package.

Visual Studio Code

You can install the language-opa-ocaml-vscode package that enables OPA classic (OCAML-like) syntax highlighting in Visual Studio Code.

Emacs

On Mac OS X, either you're using Aquamacs and the package installation took care of it, or you should add the following line to your configuration file (which might be ~/.emacs).

(autoload 'opa-classic-mode "/Library/Application Support/Emacs/site-lisp/opa-mode/opa-mode.el" "Opa CLASSIC editing mode." t)
(autoload 'opa-js-mode "/Library/Application Support/Emacs/site-lisp/opa-mode/opa-js-mode.el" "Opa JS editing mode." t)
(add-to-list 'auto-mode-alist '("\\.opa$" . opa-js-mode))
(add-to-list 'auto-mode-alist '("\\.js\\.opa$" . opa-js-mode))
(add-to-list 'auto-mode-alist '("\\.classic\\.opa$" . opa-classic-mode))

On Linux, add the following lines to your configuration file:

(autoload 'opa-js-mode "/usr/share/opa/emacs/opa-js-mode.el" "Opa JS editing mode." t)
(autoload 'opa-classic-mode "/usr/share/opa/emacs/opa-mode.el" "Opa CLASSIC editing mode." t)
(add-to-list 'auto-mode-alist '("\\.opa$" . opa-js-mode)) ;; <-- Set the default mode here
(add-to-list 'auto-mode-alist '("\\.js\\.opa$" . opa-js-mode))
(add-to-list 'auto-mode-alist '("\\.classic\\.opa$" . opa-classic-mode))

This allows for both Opa syntaxes, JavaScript-like and the Classic mode. You can have both in the same editor but not in the same buffer. Use the line shown here to set the default mode.

TIP:

You may want to activate spell-checking on Opa comments and strings. To do so, type the command M-x flyspell-prog-mode within emacs.

And if you want this functionality activated each time you open an Opa file, you just need to add the following lines to your configuration file:

 (defun enable_flyspell ()
   (ispell-change-dictionary "american")
   (flyspell-prog-mode)
 )

 ;; Enable spell-checking on Opa comments and strings
 (add-hook 'opa-mode-hook 'enable_flyspell)

### Vim

If you are running Linux (resp. Mac OS X), copy files /usr/local/share/opa/vim/{ftdetect,syntax}/opa.vim (resp. /opt/mlstate/share/opa/vim/{ftdetect,syntax}/opa.vim) to your .vim directory, keeping the directory structure.

TIP:

Instead of copying you can create a symbolic link. This will let you be automatically up-to-date with the latest mode every time you install a new version of Opa.

### Eclipse

An experimental Eclipse plugin is available from GitHub. It is not fully functional, but it is good start, and we hope that the open source community can help us.

### Gedit (GtkSourceView) You can use [OpaGtkSourceView](https://bitbucket.org/florent_k/opagtksourceview). ### BBEdit Try this [basic mode](https://github.com/hbbio/BBEOpa). ### Other editors

Although we do not provide configuration files for other editors yet, we would be very happy to hear about it.

Troubleshooting ---------------

If you have some errors, the dedicated troubleshooting page may help.

Last, but not least: This whole manual is a wiki, which means that if you find a typo, any error or missing information, you can update it! Thank you in advance for your contribution to the project.