Skip to content

Commit

Permalink
Update of the installation and init documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@AltGr
AltGr committed Oct 27, 2015
1 parent ac7feea commit 05ad1e3
Show file tree
Hide file tree
Showing 3 changed files with 62 additions and 57 deletions.
2 changes: 1 addition & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ endif
opam-lib.install:
$(MAKE) -C src ../opam-lib.install

libinstall: opam-lib.install
libinstall: opam-lib.install opam-admin.top
$(if $(wildcard src_ext/lib/*),$(error Installing the opam libraries is incompatible with embedding the dependencies. Run 'make clean-ext' and try again))
src/opam-installer $(OPAMINSTALLER_FLAGS) opam-lib.install

Expand Down
107 changes: 54 additions & 53 deletions doc/pages/Install.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,46 @@
# How to install OPAM
# How to install opam

This page describes how to install and configure OPAM and [external
solvers](#Externalsolvers). For further help on how to use OPAM,
This page describes how to install and configure opam and [external
solvers](#Externalsolvers). For further help on how to use opam,
either read `opam --help` or move on to the [Usage](Usage.html) guide.

## Upgrading from a previous version

Generally, you should just reproduce the same installation steps as for the
original installation: upgrade from your system's package manager, or re-run the
binary installer. OPAM will automatically update its internal repository at
binary installer. Opam will automatically update its internal repository at
`~/.opam` on first run if needed (backup that if you may want to rollback the
upgrade without starting over).


## Binary distribution

The quickest way to get the latest opam up and working is to run:
```
wget https://raw.github.com/ocaml/opam/master/shell/opam_installer.sh -O - | sh -s /usr/local/bin/
```

This will simply check your architecture, download and install the proper
pre-compiled binary and run `opam init`.

We provide pre-compiled binaries for:
- Linux i686, amd64 and arm7
- OSX (intel 64 bits)
(other platforms are available using the other methods below)

You can pick your download
[here](https://github.com/ocaml/opam/releases/latest), and simply put it in your
PATH as `opam`, e.g.

```
sudo cp <downloaded file> /usr/local/bin
```


## Using your distribution's package system

This is the recommended way, when available. Here is a list of supported
distributions:
This is generally the recommended way, when available and up-to-date. Here is a
list of supported distributions:

#### Archlinux

Expand All @@ -30,8 +55,9 @@ yaourt -S opam

#### Debian

Binary packages of OPAM are available for the
[testing](http://packages.debian.org/jessie/opam) and
Binary packages of opam are available for the
[stable](http://packages.debian.org/jessie/opam) (a bit outdated),
[testing](http://packages.debian.org/stretch/opam) and
[unstable](http://packages.debian.org/sid/opam) distributions, from the official
repositories. You should be set with:

Expand All @@ -41,7 +67,7 @@ apt-get install opam

There are also unofficial packages from the
[OpenSUSE Build Service](http://software.opensuse.org/download.html?project=home%3Aocaml&package=opam),
for wheezy users or if the latest version isn't yet in the official repository:
for the latest version, when not yet in the Debian repositories:

```
wget http://download.opensuse.org/repositories/home:ocaml/Debian_7.0/Release.key
Expand Down Expand Up @@ -81,7 +107,7 @@ urpmi opam

#### OpenBSD

OPAM builds via sources fine on OpenBSD 5.6 or earlier, and is available in the
Opam builds via sources fine on OpenBSD 5.6 or earlier, and is available in the
ports and packages tree on OpenBSD 5.7 or higher.

```
Expand All @@ -94,7 +120,7 @@ may see some odd upgrade attempts due to the use of the internal solver.

#### OSX

OPAM packages for [homebrew](http://mxcl.github.com/homebrew/) and
Opam packages for [homebrew](http://mxcl.github.com/homebrew/) and
[MacPorts](http://www.macports.org/) are available:

```
Expand All @@ -105,16 +131,16 @@ port install opam # MacPort

See also
[howto setup Emacs.app](https://github.com/ocaml/opam/wiki/Setup-Emacs.app-on-macosx-for-opam-usage)
for OPAM usage.
for Opam usage.

#### Ubuntu

> **Warning**: although there is an OPAM package available officially in
> **Warning**: although there is an opam package available officially in
> "**Utopic**" (14.10), it's currently broken. Don't use it, see the
> [bug report](https://bugs.launchpad.net/ubuntu/+source/opam/+bug/1401346).
> The Ubuntu "Vivid" (15.04) package is fine.
We provide binary package for "Precise" and "Trusty"
We provide binary packages for "Precise" and "Trusty"

```
add-apt-repository ppa:avsm/ppa
Expand All @@ -123,7 +149,7 @@ apt-get install ocaml ocaml-native-compilers camlp4-extra opam
```

There are also PPAs available that are
[pinned to specific revisions](http://launchpad.net/~avsm) of OCaml and OPAM --
[pinned to specific revisions](http://launchpad.net/~avsm) of OCaml and opam --
we use them for our
[automated testing](http://anil.recoil.org/2013/09/30/travis-and-ocaml.html).

Expand All @@ -133,40 +159,15 @@ software-properties-common`. Alternatively, you may manually edit the file
`/etc/apt/sources.list` to add the PPA for your Ubuntu release.


## Binary installer

Pre-compiled versions for most common architectures and OSes are available on
[the Github "releases" page](https://github.com/ocaml/opam/releases/latest). We
also provide a very simple installer script that will automatically download the
right version for you, put it in your binary directory and initialize it.

Download
[opam_installer.sh](https://raw.github.com/ocaml/opam/master/shell/opam_installer.sh)
and run it as follows:

```
sh <path to>/opam_installer.sh /usr/local/bin
```

You can also specify which version of OCaml you want to install:

```
sh ./opam_installer.sh /usr/local/bin 3.12.1 # Install the latest OPAM and OCaml 3.12.1
sh ./opam_installer.sh /usr/local/bin system # Install the latest OPAM using the system compiler (if any)
```

Note that this only gives you the basic `opam` command, not other binaries like
`opam-admin`. You can install those through OPAM afterwards.

## From Sources

#### Getting the Sources

Sources of the latest stable version of OPAM are available on Github:
Sources of the latest stable version of opam are available on Github:

* [OPAM releases on Github](https://github.com/ocaml/opam/releases)
* [Opam releases on Github](https://github.com/ocaml/opam/releases)

You can also download the full archives, including OPAM dependencies (these
You can also download the full archives, including opam dependencies (these
don't require any extra downloads, just the OCaml compiler -- 3.12.1 or later):

* [1.2.2](https://github.com/ocaml/opam/releases/download/1.2.2/opam-full-1.2.2.tar.gz)
Expand All @@ -185,16 +186,16 @@ don't require any extra downloads, just the OCaml compiler -- 3.12.1 or later):
MD5 (opam-full-1.1.0.tar.gz) = d6e2f56b10c0be73b5677963e6659d24

Follow the instructions in the included
[`README.md`](https://github.com/ocaml/opam#readme) to get OPAM built and
[`README.md`](https://github.com/ocaml/opam#readme) to get opam built and
installed from there.


#### Using ocamlbrew

[ocamlbrew](https://github.com/hcarty/ocamlbrew) is a script that can bootstrap
an OCaml environment including OPAM, from source. This option does not require
an existing OCaml installation, or a pre-compiled OPAM binary for your platform.
To bootstrap a new OCaml environment including OPAM, make sure that you have the
an OCaml environment including opam, from source. This option does not require
an existing OCaml installation, or a pre-compiled opam binary for your platform.
To bootstrap a new OCaml environment including opam, make sure that you have the
necessary pre-requisites installed to run ocamlbrew, and then run:

```
Expand All @@ -207,8 +208,8 @@ Resolving package installations in the presence of dependencies and
conflicts is known to be an [NP-complete
problem](https://hal.archives-ouvertes.fr/file/index/docid/149566/filename/ase.pdf).
Thankfully, a big effort has already been put into solving it very
efficiently: OPAM relies on this effort and delegates the solving
process to _external solvers_. OPAM integrates a simple solver, so it
efficiently: opam relies on this effort and delegates the solving
process to _external solvers_. opam integrates a simple solver, so it
can used without any extra dependencies, but for best results you
should have one of those solvers on your system:

Expand All @@ -225,17 +226,17 @@ should have one of those solvers on your system:

We recommend installing one through your packaging system whenever
possible: this should already have been taken care of if you installed
OPAM through your packaging system. If you have trouble installing an
opam through your packaging system. If you have trouble installing an
external solver and have reliable network connectivity,
[Irill](http://www.irill.org/) kindly provides a ["Solver
farm"](http://cudf-solvers.irill.org/) which can be used as a remote
solver by OPAM.
solver by opam.

If you use the internal solver only, the following symptoms may be
sign that you need an external solver: very bad upgrade proposals, or
dependency solving becoming very slow.

OPAM will detect the availability of `aspcud` or `packup` commands on your
Opam will detect the availability of `aspcud` or `packup` commands on your
system and should switch to using them directly. You can explicitly specify
which external solver to use by using the `--solver` command-line argument, the
`$OPAMEXTERNALSOLVER` environment variable, or the `solver:` field in the
Expand All @@ -245,4 +246,4 @@ External solvers also allow to specify [fine-grained
preferences](Specifying_Solver_Preferences.html). `aspcud`
is currently recommended because it supports a richer language of
[solver preferences](Specifying_Solver_Preferences.html#Yestherearedifferentversionsoftheuserpreferencelanguage)
giving OPAM more control over the requested solution.
giving opam more control over the requested solution.
10 changes: 7 additions & 3 deletions src/client/opamClient.ml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1306,10 +1306,14 @@ module API = struct
install the %s command on your system."
msg (OpamConsole.colorise `bold cmd))
unavailable_repos);
if not (check_external_dep "aspcud") then
let external_solvers = ["aspucd"; "packup"; "mccs"] in
if not (List.exists check_external_dep external_solvers) then
OpamConsole.warning
"Recommended external solver %s not found."
(OpamConsole.colorise `bold "aspcud");
"No external solver found, one of %s is recommended (see \
http://opam.ocaml.org/doc/Install.html#ExternalSolvers for \
details)"
(OpamStd.Format.pretty_list ~last:"or"
(List.map (OpamConsole.colorise `bold) external_solvers));
let advised_deps =
[OpamStateConfig.(Lazy.force !r.makecmd); "m4"; "cc"]
in
Expand Down

0 comments on commit 05ad1e3

Please sign in to comment.