Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Make Up and Running friendlier for beginners (#548)
Signed-off-by: Christine Rose <[email protected]>
- Loading branch information
1 parent
18cebd1
commit 0d8aa58
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,6 +18,15 @@ reading [OCaml on Windows](/docs/ocaml-on-windows) first. | |
| The following instructions work on Linux, BSD, and macOS. Plus, they also work on Cygwin and | ||
| WSL. | ||
|
|
||
| **Guidelines for following instructions on this page** | ||
|
|
||
| A **shell** is a program you can run that will let you enter commands in a text windows using only your keyboard. When this page asks you to enter commands in your shell: | ||
| * On macOS you will run the `Terminal` app to start a shell | ||
| * On Windows, you can start PowerShell by pressing the Windows key (`⊞`), typing "PowerShell" and then clicking Open `Windows PowerShell`. There is an older shell called "Command Prompt" you can use as well | ||
| * On Linux you are already familiar with a shell (typically bash or zsh) | ||
|
|
||
| The code blocks (in black) on this page show the required commands (the text after `#` gives more information on the following commands). Type each command after the prompt `$`, although it's often represented by a `%`, `>`, or another symbol as well. Ensure you use the exact case and spacing shown, then hit return/enter at the end of every line. For more information on using the CLI, please visit the [Command Line Crash Course video](https://www.youtube.com/watch?v=yz7nYlnXLfE) to learn some basics. | ||
|
|
||
| ## Installing OCaml | ||
|
|
||
| The **platform installer** is currently in active development. It will | ||
|
|
@@ -27,90 +36,125 @@ for the instruction. | |
| Please note that the installer is a work in progress and might not work on your system. | ||
|
|
||
| OCaml is available as a package in most Linux distributions; however, it is | ||
| often outdated. On the contrary, OCaml's official package manager, opam, allows you to | ||
| easily switch between OCaml versions and much more. This is | ||
| especially useful since different projects might require different versions of | ||
| OCaml. | ||
|
|
||
| The best way to install OCaml is with opam, OCaml's pacakge manager. | ||
|
|
||
| ### Installing opam | ||
|
|
||
| Alternatively, you can use the alpha-version platform installer to install opam and the development tools, [see below](#up-and-running-with-the-platform-installer). | ||
|
|
||
| [opam](https://opam.ocaml.org/), the package manager of OCaml, introduces the concept of "switches," consisting of a compiler together with a set of packages (libraries and other files). Switches are used to have independent sets of dependencies in different projects. | ||
|
|
||
| After having installed opam, you will need to initialise it, [see below](#initialize-opam). | ||
|
|
||
| To install opam, you can [use your system package manager](https://opam.ocaml.org/doc/Install.html#Using-your-distribution-39-s-package-system) or download the [binary distribution](https://opam.ocaml.org/doc/Install.html#Binary-distribution). The details are available in the above links, but for convenience, we copy a few of them here: | ||
|
|
||
| **For macOS** | ||
|
|
||
| If you're installing with [Homebrew](https://brew.sh/): | ||
|
|
||
| ```shell | ||
| # With Homebrew: | ||
| $ brew install opam | ||
| ``` | ||
|
|
||
| Or if you're using [MacPorts](https://www.macports.org/): | ||
|
|
||
| ```shell | ||
| # With MacPort: | ||
| $ port install opam | ||
| ``` | ||
|
|
||
| **For Linux** | ||
|
|
||
| It's easy to install opam is with your system's package manager on | ||
This comment has been minimized.
Sorry, something went wrong. |
||
| Linux (e.g., `apt-get install opam` or similar). [Details of all installation | ||
| methods.](https://opam.ocaml.org/doc/Install.html) | ||
|
|
||
|
|
||
| ```shell | ||
| # Ubuntu | ||
| $ add-apt-repository ppa:avsm/ppa | ||
| $ apt update | ||
| $ apt install opam | ||
|
|
||
| # Archlinux | ||
| $ pacman -S opam | ||
|
|
||
| # Debian (stable, testing and unstable) | ||
| $ apt-get install opam | ||
| ``` | ||
|
|
||
| **Binary Distribution** | ||
|
|
||
| Depending on your package manager, you won't get the latest release of opam. If you want the latest release, consider installing it though the binary distribution, as shown below: | ||
|
|
||
| ```shell | ||
| $ bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)" | ||
| ``` | ||
|
|
||
| ### Initialising opam | ||
|
|
||
| It's essential to initialise opam, which will (if needed) install the OCaml compiler. If you already have OCaml installed, opam will use that compiler. | ||
|
|
||
| This step is done automatically by the alpha-version platform installer, [see below](#up-and-running-with-the-platform-installer). | ||
|
|
||
| If you have installed the binary distribution of opam through the install script, this step should already be done. If you have installed it through your system package manager, you must initialise opam by running the following command. This method will fetch and initialize the latest version of opam, directly from the official servers: | ||
This comment has been minimized.
Sorry, something went wrong. 
gasche
Member
|
||
|
|
||
| ```shell | ||
| $ opam init # Can take some time | ||
| $ eval $(opam env) | ||
| ``` | ||
|
|
||
| The first command (`opam init`) initialises the opam state (stored in a hidden folder `.opam` in your home directory). It also creates a first switch, usually called `default`, although this is just a convention. A switch is an independent OCaml environment with its own OCaml compiler, as well as a set of libraries and binares. If you have installed OCaml through your system package manager, the first switch will be set up to use this compiler (it is called a "system switch"). Otherwise, it will build one from source, usually taking the most recent version of OCaml. | ||
This comment has been minimized.
Sorry, something went wrong. |
||
|
|
||
| The second command (`eval $(opam env)`) modifies a few environments variables to make the shell aware of the switch you are using. For instance, it will add what is needed to the `PATH` variable so that typing `ocaml` in the shell runs the OCaml binary of the current switch. | ||
|
|
||
| **Please note:** At the end of the `opam init`, you are asked if you want to add a hook to your shell to best integrate with your system. Indeed, in order for the shell to be aware of the tools available in the current opam switch, a few environments variables need to be modified. For instance, the `PATH` variable has to be expanded so that typing `ocaml` in the shell runs the OCaml binary _of the current switch_. Answering `y` will provide a better user experience. | ||
|
|
||
| Now check the installation by running `opam --version`. You can compare it with the current version on [opam.ocaml.org](https://opam.ocaml.org/). | ||
|
|
||
|
|
||
| ### Creating a New Switch | ||
|
|
||
| If you want a specific version of OCaml, or a new independent environment, you can create a new switch with the `opam switch create` command. Specify which version as shown below (i.e., `opam switch create 5.0.0`). All possible compiler versions can be found with `opam switch list-available`. The most current version can be found at [opam.ocaml.org](https://opam.ocaml.org/packages/ocaml-base-compiler/). | ||
|
|
||
| ```shell | ||
| $ opam switch create 5.0.0 | ||
| $ eval $(opam env) | ||
| ``` | ||
|
|
||
| Check that the installation was succuessful by running `which ocaml` and `ocaml -version`. The line beneath the $ command shows the desired output for both the OCaml version and the toplevel version (installed specifically with the above `switch` command): | ||
This comment has been minimized.
Sorry, something went wrong. |
||
|
|
||
| ```shell | ||
| $ which ocaml | ||
| /Users/frank/.opam/5.0.0/bin/ocaml | ||
|
|
||
| $ ocaml -version | ||
| The OCaml toplevel, version 5.0.0 | ||
| ``` | ||
|
|
||
| We will learn about the OCaml toplevel and other installed tools in the next section. | ||
|
|
||
| In case you are not satisfied with the OCaml version of your system switch, you can change the version with `opam switch create <version_here>`. More information can be found on the [official website](https://opam.ocaml.org/). | ||
|
|
||
|
|
||
| ### The OCaml Base Tools | ||
|
|
||
| OCaml is installed in an opam switch, which, among others, bring the following | ||
| programs: | ||
|
|
||
| - A "toplevel," which can be called with the `ocaml` command. It consists of a read-eval-print loop ([REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)), similar to the `python` or `node` command, and can be handy to quickly try the language. The user interface of OCaml is very basic, but when we install the UTop package in the following section, we'll have an improved and easier-to-use REPL. | ||
|
|
||
| - A compiler to **native code**, called `ocamlopt`. It creates executables that can be executed directly on your system. | ||
|
|
||
| - A compiler to **bytecode**, called `ocamlc`. It creates executables that can be interpreted by a variety of runtime environments, making it more flexible. | ||
|
|
||
| Although this is theoretically all we need to write OCaml code, it is not a complete and comfortable development environment. | ||
|
|
||
| ## Setting Up Development Tools | ||
|
|
||
|
|
@@ -119,23 +163,23 @@ This step is done automatically by the alpha-version platform installer, [see be | |
| We will now install everything we need to get a complete development environment, which includes: | ||
|
|
||
| - Dune, a fast and full-featured build system for OCaml | ||
| - Merlin (the backend) and `ocaml-lsp-server` (OCaml's Language Server Protocol) to provide editors with many useful features such as "jump to definition" | ||
| - `odoc` to generate documentation from OCaml code | ||
| - OCamlformat to automatically format OCaml code | ||
| - UTop, an improved REPL | ||
| - `dune-release` to release code to `opam-repository`, the package base for opam. | ||
|
|
||
| All these tools can be installed in your current switch (remember that opam groups installed packages in independent switches) using the following command: | ||
|
|
||
| ```shell | ||
| $ opam install dune merlin ocaml-lsp-server odoc ocamlformat utop dune-release | ||
| ``` | ||
|
|
||
| Now that the tools are installed, it remains to understand how to use them. Most of them will be driven either by the editor or by Dune, but UTop is handy to try OCaml or a specific library. | ||
|
|
||
| ## Up and Running with the Platform Installer | ||
|
|
||
| A different way to install opam and the OCaml Platform is with the platform installer, which is a work in progress. You can follow its development and | ||
| report issues on [the repository](https://github.com/tarides/ocaml-platform-installer/). | ||
|
|
||
| Please note that the installer might not work on your system. If that's the | ||
|
|
@@ -145,7 +189,7 @@ The installer is not in any package manager yet, but it can be installed using | |
| this script, which will install both opam and OCaml Platform`: | ||
|
|
||
| ```shell | ||
| $ sudo bash < <(curl -sL https://github.com/tarides/ocaml-platform-installer/releases/latest/download/installer.sh) | ||
| ``` | ||
|
|
||
| This downloads a script from the web and executes it as root. You are | ||
|
|
@@ -154,7 +198,7 @@ encouraged to have a look at what it does first. | |
| Once this step is done, setup the environment with: | ||
|
|
||
| ```shell | ||
| $ ocaml-platform | ||
| ``` | ||
|
|
||
| This will initialise opam and install the development tools, which might take | ||
|
|
@@ -170,7 +214,9 @@ opam switch for example. | |
|
|
||
| ## Using the OCaml Toplevel with UTop | ||
|
|
||
| UTop is a nice toplevel for OCaml. Unlike the standard toplevel with the `ocaml` command, UTop features history, tab completion, line edition, and the ability to load a package installed in your switch. One of the things that makes OCaml so efficient is because it compiles while you code, allowing for iteration. | ||
|
|
||
| By running the `utop` command, it will print out something similar to what you see below. After the horizontal line, you will see a new prompt `utop #`. Here is where you type your expressions. In this case `1 + 2 * 3;;`. After you press Enter, the following line shown is the desired output. | ||
|
|
||
| ``` | ||
| $ utop | ||
|
|
@@ -211,57 +257,66 @@ While a toplevel is great for interactively trying out the language, we will sho | |
|
|
||
| OCaml has plugins for many editors, but the most actively maintained are for Visual Studio Code, Emacs, and Vim. | ||
|
|
||
| For **Visual Studio Code**, install the [OCaml Platform Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform) from the Visual | ||
| Studio Marketplace. | ||
|
|
||
| Upon first loading an OCaml source file, you may be prompted to select the | ||
| toolchain in use: pick the version of OCaml you are using, e.g., 5.0.0 | ||
| from the list. Now, help is available by hovering over symbols in your program: | ||
|
|
||
|  | ||
|
|
||
| **For Vim and Emacs** we won't use the LSP server but rather directly talk to Merlin. | ||
|
|
||
| When we installed Merlin above, instructions were printed on how to link Merlin with your editor. If you do not have them visible, the short way is just to run: | ||
|
|
||
| ```shell | ||
| $ opam user-setup install | ||
| ``` | ||
|
|
||
| ## Starting a New Project | ||
|
|
||
| Let's begin the simplest project with Dune and OCaml, "Hello World," just to see how it works. | ||
| Navigate into a practice directory, as we'll be creating new projects below. | ||
|
|
||
| First, we ask `dune` to | ||
| initialize a new project, and then change into the created directory. As usual, | ||
| the line beneath the command is the desired output: | ||
|
|
||
| ```shell | ||
| $ dune init project helloworld | ||
| Success: initialized project component named helloworld | ||
| $ cd helloworld | ||
| ``` | ||
|
|
||
| All the metadata of your project is available in the file `dune-project`. Edit it to match your specific project. | ||
|
|
||
| We can build our program with `dune build`, which creates an executable file: | ||
|
|
||
| ```shell | ||
| $ dune build | ||
| ``` | ||
|
|
||
| When we change our program, we can type `dune build` again to make a new | ||
| executable. To run the program, we can use: | ||
|
|
||
| ```shell | ||
| $ dune exec bin/main.exe | ||
| Hello, World! | ||
| ``` | ||
|
|
||
| Or, alternatively, | ||
|
|
||
| ```shell | ||
| $ dune exec helloworld | ||
| Hello, World! | ||
| ``` | ||
|
|
||
| Let's look at the contents of our new directory: | ||
|
|
||
| ```shell | ||
| $ ls | ||
| bin _build dune-project helloworld.opam lib test | ||
| ``` | ||
|
|
||
| All the build outputs generated by Dune go in the `_build` directory. The | ||
|
|
@@ -282,29 +337,29 @@ Moreover, since different versions of OCamlformat will vary in formatting, it | |
| is good practice to enforce the one you are using. Doing: | ||
|
|
||
| ```shell | ||
| $ echo "version = 0.22.4" > .ocamlformat | ||
| ``` | ||
|
|
||
| This will enforce that only OCamlformat version 0.22.4 can format the files of the project. | ||
| Note that a `.ocamlformat` file is _needed_, but an empty file is accepted. | ||
|
|
||
| In addition to the editor, Dune is also able to drive OCamlformat. Running | ||
| this command will automatically format all files from your codebase: | ||
|
|
||
| ```shell | ||
| $ dune fmt | ||
| ``` | ||
|
|
||
| ### `odoc` for Documentation Generation | ||
|
|
||
| `odoc` is a tool that is not meant to be used by hand, just as compilers are | ||
| not meant to be run manually in complex projects. Dune can drive `odoc` to | ||
| generate, from the docstrings and interface of the modules of the project, a | ||
| hierarchised documentation. | ||
|
|
||
| The following command will generate the documentation as HTML: | ||
|
|
||
| ```shell | ||
| $ dune build @doc | ||
| $ open _build/default/_doc/_html/index.html | ||
| ``` | ||
there is an extra "is" here