Create tutorial: Running Commands in an Opam Switch

data/tutorials/platform/bp_09_opam_path.md

@@ -0,0 +1,98 @@
+---
+id: "opam-path"
+title: "Running Commands in an Opam Switch"
+description: |
+  How to use commands installed in an Opam switch
+category: "Best Practices"
+---
+
+Opam is a package manager for OCaml that facilitates the installation and management of OCaml libraries and tools. When working with Opam, it's essential to understand how to run commands within a specific Opam switch. In this tutorial, we'll explore three methods: `opam env`, `opam exec`, and `direnv`.
+
+## Using `opam env`
+
+The `opam env` command is used to set environment variables for a specific Opam switch. This method is useful for configuring your shell environment to work with a particular Opam switch.
+
+Usage:
+```bash
+$ eval $(opam env)
+```
+
+This command evaluates the output of opam env and sets the necessary environment variables for the currently active switch. After running this command, you'll have access to the packages installed in the Opam switch.
+
+## Using `opam exec`
+The opam exec command allows you to run a command in the context of a specific Opam switch without modifying your shell environment.
+
+Usage:
+```bash
+$ opam exec -- <command>
+```
+Replace `<command>` with the actual command you want to run. This ensures that the command is executed within the Opam switch's environment.
+
+Example:
+```bash
+$ opam exec -- ocaml
+```
+
+This will launch the version of the OCaml REPL within the context of the current Opam switch.
+
+## Using `direnv`
+
+[Direnv](https://direnv.net/) is a tool (written in [Go](https://go.dev/)) that allows you to set environment variables based on your current directory. It is especially useful for managing Opam switches and automating the setup of project-specific environments.
+
+1. Install `direnv`
+
+Ensure `direnv` is installed on your system. You can install it using a package manager or follow the instructions on the official website.
+
+2. Setup `direnv` integration
+
+Add the following line to your shell profile (e.g., `~/.bashrc` or `~/.zshrc`):
+```bash
+$ eval $(direnv hook <shell>)
+```
+Replace `<shell>` with your actual shell type (`bash`, `zsh`, `fish`, etc.).
+
+3. Configure Opam with `direnv`
+
+In your OCaml project directory, create a file named `.envrc` and add the following line to automatically load the Opam environment:
+```bash
+eval $(opam env)
+```
+
+4. Allow `direnv`
+
+Navigate to your project directory and run the following command to allow `direnv` to load the environment:
+```bash
+$ direnv allow
+```
+
+This command activates `direnv` for the current directory, ensuring that the Opam switch environment is loaded whenever you enter the directory.
+
+5. Usage
+
+Now, whenever you navigate to your OCaml project directory, `direnv` will automatically activate the Opam switch environment specified in your `.envrc` file. This eliminates the need to manually run `opam env` each time you work on your project.
+
+6. Example
+
+Suppose you have an OCaml project in folder `disco` and local Opam switch is associated to it, and a `.envrc` file in that folder containing the following:
+```bash
+eval $(opam env)
+```
+After running `direnv allow`, `direnv` will handle the Opam switch activation for you whenever you.
+
+7. Messages from `direnv`
+
+Whenever entering or leaving a `direnv` managed folder, you will be informed of the the actions performed.
+
+On entrance:
+```
+direnv: loading ~/caml/ocaml.org/.envrc
+direnv: export ~CAML_LD_LIBRARY_PATH ~MANPATH ~OCAML_TOPLEVEL_PATH ~OPAM_SWITCH_PREFIX ~PATH
+```
+
+On exit:
+```
+direnv: loading ~/.envrc
+direnv: export ~PATH
+```
+
+By using `direnv` in conjunction with Opam, you can streamline your development workflow, ensuring that the correct Opam switch is automatically set up whenever you work on a specific project.