Getting started

Getting started

This section is about installation and configuration of Opa. If you want to learn more about Opa first, you can safely skip this section and come back later.

And 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.

Binary packages of Opa are available for all major 64-bit architectures: Mac OS X, Linux (Ubuntu/Debian-based). Windows will be back soon, as well as 32-bit architectures. We do not provide binary packages for other Unixes, FreeBSD, but you should be able to build Opa from sources on these systems (see below).

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

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

The easiest solution for installing Opa is to download an installer from our website.

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 Opa:
$ wget http://download.opalang.org/ubuntu/opa_1.0.X%2BbuildXXXX_XXXX.deb
$ sudo dpkg --force-depends -i opa_1.0.X+buildXXXX_XXXX.deb

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

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

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.

Building Opa from the sources -----------------------------

Should you wish to work on an unsupported platform, or to contribute to Opa, you will need to build Opa from sources. This requires a bit more work than the installation, but you should have no major difficulties. You will need:

• git (to download the source)
• ocaml 3.12.0-5 or later
• libgif 4.1 or later (dev version)
• libjpeg 8b-1 or later (dev version)
• libpng 1.2.44 or later (dev version)
• libssl 0.9.8 or later (dev version)
• libxft 2.2.0 or later (dev version)
• m4
• dblatex
• java 1.5 or later
• libx11 1.4.2 or later (dev version)
• zlib 1.2.3.4 or later (dev version)

In addition, if you are using Mac OS X, you will need:

• GNU coreutils, wget, md5sha1sum and gsed (or gnu-sed) available via MacPorts or Homebrew
• The Xcode suite, provided by Apple with your copy of Mac OS X (prior to Mac OS X 10.7 Lion).
• 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.

Once these dependencies are satisfied, take the following steps:

• Grab the sources from GitHub by entering in a terminal:

git clone https://github.com/MLstate/opalang.git

• In the same terminal, enter

cd opalang
./configure -prefix SOME_DIRECTORY
make all install

(You may need root privileges). This will install Opa in directory SOME_DIRECTORY

Do not forget to change your PATH variable if needed after that.

TIP:

We also provide a script that will help you install all dependencies needed for building Opa. In this case, the only dependencies should be (tested on clean Ubuntu 11.10) :

• git (to download the source)
• m4
• libssl 0.9.8 or later (dev version)
• zlib 1.2.3.4 or later (dev version)

In your opalang directory, run: tools/dependencies/installation_helper.sh --prefix SOME_DIRECTORY.

You will need to update your PATH variable after that.

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

SublimeText

This is the most complete IDE for Opa. 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.

The package you installed provides two Opa modes, one for Emacs and one for Vim.

### 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/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.

### 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.