-
Notifications
You must be signed in to change notification settings - Fork 372
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1567 from OCamlPro/1.2.0-beta3
Update doc, CHANGES and advertise as ~beta3
- Loading branch information
Showing
15 changed files
with
644 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| <h1 id="UsingOPAM">Using OPAM</h1> | ||
| <p>This document covers most of the common OPAM features. If you're looking for a | ||
| quick introduction, check the <a href='Basic_Usage.html'>Basic Usage</a> tutorial first.</p> | ||
| <p>If you are a developper and want to get a project packaged or change an existing | ||
| package, see the step-by-step <a href='Packaging.html'>packaging guide</a></p> | ||
| <p>The full documentation is available inline, using</p> | ||
| <pre><code>opam --help | ||
| opam <command> --help</code></pre> | ||
| <p>This document is intended as a quicker overview, use the above to dig into the | ||
| details.</p> | ||
| <h3 id="opaminit">opam init</h3> | ||
| <p>OPAM needs to initialise its internal state in a <code>~/.opam</code> directory to work. | ||
| This command can also take care of installing a version of OCaml if needed.</p> | ||
| <p>To operate as expected, some variables need to be set in your environment. You | ||
| will be prompted to update your configuration, and given instructions on how | ||
| to proceed manually if you decline.</p> | ||
| <h3 id="opamupdate">opam update</h3> | ||
| <p>This command synchronises OPAM's database with the package repositories. The | ||
| lists of available packages and their details are stored into | ||
| <code>~/.opam/repo/<name></code>. Remember to run this regularly if you want to keep | ||
| up-to-date, or if you are having trouble with a package.</p> | ||
| <h3 id="Lookinguppackages">Looking up packages</h3> | ||
| <p>There are three useful commands for that:</p> | ||
| <ul> | ||
| <li><code>opam list</code> List installed packages, or packages matching a pattern</li> | ||
| <li><code>opam search</code> Search in package descriptions</li> | ||
| <li><code>opam show</code> Print details on a given package.</li> | ||
| </ul> | ||
|
|
||
| <h3 id="opaminstall">opam install</h3> | ||
| <p>This command installs packages along with all their dependencies. You can | ||
| specify one or several packages, along with version constraints. E.g:</p> | ||
| <pre><code>opam install lwt | ||
| opam install ocp-indent ocp-index.1.0.2 | ||
| opam install "ocamlfind>=1.4.0"</code></pre> | ||
| <h3 id="opamupgrade">opam upgrade</h3> | ||
| <p>Will attempt to upgrade the installed packages to their newest versions. You | ||
| should run it after <code>opam update</code>, and may use <code>opam pin</code> to prevent specific | ||
| packages from being upgraded.</p> | ||
| <h3 id="opamswitch">opam switch</h3> | ||
| <p>This command enables the user to have several installations on disk, each with | ||
| their own prefix, set of installed packages, and OCaml version. Use cases | ||
| include having to work or test with different OCaml versions, keeping separate | ||
| development environments for specific projects, etc.</p> | ||
| <p>Use <code>opam switch <version></code> to <em>switch</em> to a different OCaml version, or <code>opam | ||
| switch <name> --alias-of <version></code> to name the new <em>switch</em> as you like. Don't | ||
| forget to run the advertised <code>eval $(opam config env)</code> to update your PATH | ||
| accordingly.</p> | ||
| <p>Creating a new switch requires re-compiling OCaml, unless you make it an alias | ||
| of the "system" switch, relying on the global OCaml installation.</p> | ||
| <p>There are a bunch of specific or experimental OCaml compiler definitions on the | ||
| official repository, list them all with <code>opan switch list --all</code>.</p> | ||
| <h3 id="opampin">opam pin</h3> | ||
| <p>This command allows to pin a package to a specific version, but in fact, as you | ||
| know if you've read the <a href='Packaging.html'>Packaging guide</a>, it can do much more.</p> | ||
| <p>The syntax is</p> | ||
| <pre><code>opam pin add <package name> <target></code></pre> | ||
| <p>Where <code><target></code> may be a version, but also a local path, an http address or | ||
| even a git, mercurial or darcs URL. The package will be kept up-to-date with its | ||
| origin on <code>opam update</code> and when explicitely mentionned in a command, so that | ||
| you can simply run <code>opam upgrade <package name></code> to re-compile it from its | ||
| upstream. If the upstream includes OPAM metadata, that will be used as well.</p> | ||
| <pre><code>opam pin add camlpdf 1.7 # version pin | ||
| opam pin add camlpdf ~/src/camlpdf # path | ||
| opam pin add opam-lib https://github.com/ocaml/opam.git#1.2 # specific branch or commit | ||
| opam pin add opam-lib --dev-repo # upstream repository</code></pre> | ||
| <p>This can be used in conjunction with <code>opam source</code> to start and hack an existing | ||
| package before you know it:</p> | ||
| <pre><code>opam source <package> --dev-repo --pin | ||
| cd <package>; hack hack hack; | ||
| opam upgrade <package></code></pre> | ||
| <h3 id="opamrepo">opam repo</h3> | ||
| <p>OPAM is configured by default to use the community's software repository at | ||
| <a href='https://opam.ocaml.org'>opam.ocaml.org</a>, but this can easily be | ||
| changed at <code>opam init</code> time or later.</p> | ||
| <p><code>opam repo add <name> <address></code> will make OPAM use the definitions of any | ||
| package versions defined at <code><address></code>, falling back to the previously defined | ||
| repositories for those which aren't defined. The <code><address></code> may point to an | ||
| http, local or version-controlled repository.</p> | ||
| <p>Defining your own repository, either locally or online, is quite easy: you can | ||
| start off by cloning <a href='https://github.com/ocaml/opam-repository'>the official | ||
| repository</a> if you intend it as a | ||
| replacement, or just create a new directory with <code>packages</code> and <code>compilers</code> | ||
| sub-directories. See the <a href='Packaging.html'>packaging guide</a> if you need help on | ||
| the package format.</p> | ||
| <p>If your repository is going to be served over HTTP, you should generate an index | ||
| using the <code>opam-admin</code> tool.</p> |
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| <h1 id="LearntouseOPAMin2minutes">Learn to use OPAM in 2 minutes</h1> | ||
| <p>This short tutorial covers the very basic use cases to get you started with | ||
| OPAM. A more lengthy introduction can be found in the | ||
| <a href='Advanced_Usage.html'>Advanced Usage</a> guide.</p> | ||
| <h2 id="InitialisingOPAM">Initialising OPAM</h2> | ||
| <pre><code>opam init</code></pre> | ||
| <p>This will create the <code>~/.opam</code> directory, within which packages will be | ||
| installed and where OPAM will store its data.</p> | ||
| <h2 id="Browsingavailablepackages">Browsing available packages</h2> | ||
| <p>The following commands will enable you to obtain information on available | ||
| packages:</p> | ||
| <pre><code>opam list -a # List all available packages | ||
| opam search QUERY # List packages with QUERY in their name or description | ||
| opam show PACKAGE # Display information about PACKAGE</code></pre> | ||
| <p>You may prefer to <a href='https://opam.ocaml.org/packages'>browse them online</a>. If you | ||
| find a package there but not on your computer, either it has been recently added | ||
| and you should simply run <code>opam update</code>, or it's not available on your system or | ||
| OCaml version -- <code>opam install PACKAGE</code> should give you the reason.</p> | ||
| <h2 id="Installingapackage">Installing a package</h2> | ||
| <p>The two commands you will probably use the most with OPAM are:</p> | ||
| <pre><code>opam update # Update the packages database | ||
| opam install PACKAGE # Download, build and install the latest version of PACKAGE</code></pre> | ||
| <h2 id="Upgradingyourinstalledpackages">Upgrading your installed packages</h2> | ||
| <p>You may want to regularly issue these commands to keep your packages up-to-date:</p> | ||
| <pre><code>opam update # Update the packages database | ||
| opam upgrade # Re-install packages that were updated since last upgrade</code></pre> | ||
| <h2 id="DomorewithOPAM">Do more with OPAM</h2> | ||
| <p>If you need more details and options, OPAM is self-documented through</p> | ||
| <pre><code>opam --help</code></pre> | ||
| <p>To learn how to use more advanced features of OPAM (package pinning, multiple | ||
| repositories, multiple compilers...), move on to the <a href='Advanced_Usage.html'>Advanced | ||
| Usage</a> guide, or the <a href='Packaging.html'>Packaging tutorial</a>.</p> |
Binary file not shown.
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,121 @@ | ||
| <h1 id="OPAMFAQ">OPAM FAQ</h1> | ||
| <h4 id="HowtogetinstallandupgradeOPAM">→ How to get, install and upgrade OPAM ?</h4> | ||
| <p>See the <a href='Quick_Install.html'>Quick install guide</a>.</p> | ||
| <h4 id="Whereisthemanual">→ Where is the manual ?</h4> | ||
| <p>OPAM has git-like, hierarchical manpages. Try <code>opam --help</code> for a starting point.</p> | ||
| <p>Get started with OPAM packages by reading the <a href='Packaging.html'>Packaging Howto</a>.</p> | ||
| <p>See the details on the file formats and more in the <a href='https://github.com/ocaml/opam/blob/master/doc/dev-manual/dev-manual.pdf?raw=true'>Developper | ||
| Guide</a> | ||
| (pdf).</p> | ||
| <h4 id="WhatchangesdoesOPAMdotomyfilesystem">→ What changes does OPAM do to my filesystem ?</h4> | ||
| <p>OPAM is designed to be run strictly as user (non-root), and apart for the | ||
| explicit options provided during <code>opam init</code>, only writes within <code>~/.opam</code> (and | ||
| <code>/tmp</code>). This directory -- the default "OPAM root" -- contains configuration, | ||
| various internal data, a cache of downloaded archives, and your OCaml | ||
| installations.</p> | ||
| <h4 id="Whydoesopaminitneedtoaddstufftomyinitscriptswhyisevalopamconfigenvneeded">→ Why does <code>opam init</code> need to add stuff to my init scripts / why is <code>eval $(opam config env)</code> needed ?</h4> | ||
| <p>You need two things when you install OPAM packages: to have their libraries | ||
| accessible, and to access binary programs. To provide those, OPAM needs to setup | ||
| a few ocaml-related environment variables, and to prepend to your PATH variable.</p> | ||
| <p>Of course, you may choose not to let OPAM change anything at <code>opam init</code>, and | ||
| run <code>eval $(opam config env)</code> yourself whenever you will be needing it.</p> | ||
| <h4 id="Whatisaquotswitchquot">→ What is a "switch" ?</h4> | ||
| <p>An ocaml installation and a set of installed packages within an OPAM | ||
| installation. This can be used to keep different OCaml versions side-by-side, or | ||
| different sets of packages. See the <a href='Advanced_Usage.html#opamswitch'>related | ||
| section</a> in the Advanced usage manual and | ||
| <code>opam switch --help</code>. The "prefix" for a given installation is simply | ||
| <code>~/.opam/<switch-name></code>.</p> | ||
| <p>A switch is either based on a system-wide OCaml installation, or on a local | ||
| installation. In the former case, OPAM will need to recompile all packages when | ||
| your system compiler changes. In the latter case, OCaml will be downloaded and | ||
| compiled on creation of the switch.</p> | ||
| <h4 id="CanIworkondifferentswitchesatthesametimeindifferentshells">→ Can I work on different switches at the same time in different shells ?</h4> | ||
| <p>Yes. Use one of:</p> | ||
| <pre><code>eval $(opam config env --switch <switch>) # for the current shell | ||
| opam config exec --switch <switch> <command> # for one command</code></pre> | ||
| <p>This only affects the environment.</p> | ||
| <h4 id="CanIgetanewswitchwiththesamepackagesinstalled">→ Can I get a new switch with the same packages installed ?</h4> | ||
| <p>Yes. Use:</p> | ||
| <pre><code>opam switch export file.export # from the previous switch | ||
| opam switch <new switch> | ||
| opam switch import file.export</code></pre> | ||
| <p>OPAM might fail if you had packages installed that are not compatible with the | ||
| OCaml version in your new switch. In that case, you'll need to remove them from | ||
| the <code>file.export</code> file by hand (the format is straight-forward, one line per | ||
| package).</p> | ||
| <h4 id="IinstalledapackagebyhandusedocamlfindremovefiddledwiththeinstalledpackagesandOPAMisoutofsyncHelp">→ I installed a package by hand / used <code>ocamlfind remove</code> / fiddled with the installed packages and OPAM is out of sync. Help !</h4> | ||
| <p>Don't panic. OPAM assumes it's controlling what's below <code>~/.opam/<switch></code>, but | ||
| there are several ways you can recover:</p> | ||
| <ul> | ||
| <li><code>opam remove --force</code> will attempt to uninstall even if not registered as | ||
| installed. Then <code>opam install</code></li> | ||
| <li><code>opam reinstall</code> will try to remove an installed package, but go on to | ||
| re-installing even if that fails.</li> | ||
| <li>If all else fails, you can re-install your current set of packages from | ||
| scratch using <code>opam switch reinstall</code></li> | ||
| <li>You can force OPAM to register an installation or removal <em>without actually | ||
| performing anything</em> using <code>opam install|remove --fake</code>. This is not | ||
| recommended though, as your manual install may not be exactly equivalent to | ||
| the one expected by other OPAM packages, and OPAM may later on trigger | ||
| reinstallations or upgrades of the package. Don't complain if you mess up your | ||
| installation using this! If you want to control how a package is installed or | ||
| modify it, the right way is <code>opam pin</code>.</li> | ||
| </ul> | ||
|
|
||
| <h4 id="Whataretheminimumrequirements">→ What are the minimum requirements ?</h4> | ||
| <p>1GB of memory should be all you need. It was reported that you may run into | ||
| problems with 512MB of RAM and no swap. Of course, software packages themselves | ||
| may be more greedy.</p> | ||
| <h4 id="Somepackagefailduringcompilationcomplainingaboutmissingdependenciesquotm4quotquotlibgtkquotetc">→ Some package fail during compilation, complaining about missing dependencies ("m4", "libgtk", etc.)</h4> | ||
| <p>They probably depend on system, non-OCaml libraries: you'll need to install them | ||
| using your system package manager (apt-get, yum, pacman, homebrew, etc.). If you | ||
| have no idea what the missing system package might be:</p> | ||
| <ul> | ||
| <li>Check for hints printed by the failing package</li> | ||
| <li>Check the output of <code>opam list <package> --external</code></li> | ||
| <li>Lookup the development packages corresponding to the error in your system's | ||
| package repositories. If you got to this point and found the appropriate | ||
| packages, we'd be glad if you could tell us your system details and the answer | ||
| in <a href='https://github.com/ocaml/opam-repository/issues'>the opam-repository | ||
| tracker</a>, to save the others | ||
| the trouble of searching. Thanks.</li> | ||
| </ul> | ||
|
|
||
| <h4 id="Ihaveweirdchecksumerrorswheredotheycomefrom">→ I have weird checksum errors: where do they come from ?</h4> | ||
| <p>First of all, you should make sure your repositories are up-to-date:</p> | ||
| <pre><code>opam update</code></pre> | ||
| <p>If this isn't enough, or if you get the checksum errors while running <code>opam | ||
| init</code>, this could be caused by a badly configured proxy cache that is serving | ||
| stale files. To clear your proxy cache, you can use <code>wget --no-cache | ||
| <remote-file></code> and retry.</p> | ||
| <p>As a last resort, you can bypass the checksum checks using <code>--no-checksums</code>.</p> | ||
| <h4 id="OPAMispromptingmetoinstallorupgradepackagesthatIamnotinterestedinordoesn39tinstallthelatestversionbydefaultWhyWhatcanIdo">→ OPAM is prompting me to install or upgrade packages that I am not interested in, or doesn't install the latest version by default. Why ? What can I do ?</h4> | ||
| <ul> | ||
| <li>You can be more explicit in your request (<code>opam upgrade PACKAGES</code>, <code>opam | ||
| install 'PACKAGE>=VERSION' PACKAGE...</code>, etc.)</li> | ||
| <li>Action resolution in a package set is known to be a NP-complete problem; OPAM | ||
| uses state-of-the-art algorithms through an external, dedicated solver: make | ||
| sure you have the latest version of <a href='http://potassco.sourceforge.net/'>aspcud</a> | ||
| installed.</li> | ||
| <li>Another benefit of the external solvers is that they allow to be <a href='Specifying_Solver_Preferences.html'>quite | ||
| expressive</a> on your expectations.</li> | ||
| </ul> | ||
|
|
||
| <h4 id="WheredoIreportBugsIssuesandFeatureRequests">→ Where do I report Bugs, Issues and Feature Requests?</h4> | ||
| <ul> | ||
| <li><p>Bug reports and feature requests for the OPAM tool should be reported on | ||
| <a href='https://github.com/ocaml/opam/issues'>OPAM's issue-tracker</a>.</p> | ||
| </li> | ||
| <li><p>Packaging issues or requests for a new package can be reported on the | ||
| <a href='https://github.com/ocaml/opam-repository/issues'>official repository's | ||
| issue-tracker</a>.</p> | ||
| </li> | ||
| <li><p>General queries for both the tool and the packages can be addressed on the | ||
| <a href='http://lists.ocaml.org/listinfo/platform'>OCaml-platform mailing-list</a> and | ||
| insights and evolution of OPAM internals can discussed on the <a href='http://lists.ocaml.org/listinfo/opam-devel'>OPAM-devel | ||
| mailing-list</a>.</p> | ||
| </li> | ||
| <li><p>You may also try IRC channel <code>#opam</code> on Freenode.</p> | ||
| </li> | ||
| </ul> |
Oops, something went wrong.