Skip to content
This repository has been archived by the owner on Oct 15, 2022. It is now read-only.

Streamline setup instructions #233

Merged
merged 10 commits into from
Nov 27, 2019
Merged

Streamline setup instructions #233

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
2144c29
Streamline setup instructions in README.md
curiousleo Nov 20, 2019
7152835
Remove duplicated instructions
curiousleo Nov 20, 2019
67b5d52
example/ and contrib/ re-org
curiousleo Nov 20, 2019
6476b58
Remove disclaimer about non-Bash shells
curiousleo Nov 25, 2019
a34f17a
Use lorri init
curiousleo Nov 25, 2019
0539bea
Install direnv
curiousleo Nov 25, 2019
f954e48
Lowercase DAEMON.md, EMACS.md
curiousleo Nov 27, 2019
08e05d2
Install direnv from channel or from source
curiousleo Nov 27, 2019
e22487d
Rephrase cached environment paragraph
curiousleo Nov 27, 2019
137d84f
Add stub "Editor integration" section
curiousleo Nov 27, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 113 additions & 66 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,96 +29,137 @@ development environment as `shell.nix` is updated:
</a>
</p>

## Tutorial
## Setup on NixOS or with `home-manager` on Linux

You can find the **lorri tutorial** [in the `./example`
directory](./example). After following this tutorial, you will have
a working setup of `lorri`, `direnv`, and working basic editor
integration into Emacs.
If you are using [NixOS][nixos] or [`home-manager`][home-manager] on Linux and
a Nixpkgs channel at least as recent as `nixos-19.09`, you can get started with
lorri as follows. Otherwise see the next section, [Setup on other
platforms](#setup-on-other-platforms).

## Support & Questions
1. **Enable the daemon service.** Set `services.lorri.enable = true;` in your
NixOS [`configuration.nix`][nixos-service] or your home-manager
[`home.nix`][home-manager-service].

Please use the [issue tracker](https://github.com/target/lorri/issues)
for any problems or bugs you encounter. We are on `#lorri` on
`freenode` ([Webchat][]), though we might not be responsive at all
times.
This will automatically install both the `lorri` command and `direnv`
(both required for the next steps).

[Webchat]: https://kiwiirc.com/nextclient/#irc://irc.freenode.net:+6697/#lorri
2. **Install direnv.** Add `pkgs.direnv` to `environment.systemPackages` in
your NixOS `configuration.nix` or to `home.packages` in your home-manager
`home.nix`.

## How To Help
3. **Set up the direnv hook for your shell.** See [this section][direnv-hook]
of the direnv documentation.

All development on lorri happens on the Github repository, in the
open. You can propose a change in an issue, then create a pull request
after some discussion. Some issues are marked with the “good first
issue” label, those are a good place to start. Just remember to leave
a comment when you start working on something.
4. **Activate the lorri integration.** Run `lorri init` in your project
directory to create a `shell.nix` and [`.envrc`][direnv-usage] file. This
will not overwrite existing files.

## Install
In your shell, you will now see the following message from direnv:

### Install direnv
```console
direnv: error .envrc is blocked. Run `direnv allow` to approve its content.
```

You will need [direnv v2.19.2 or later][direnv-2-19-2].
Activate the integration by running [`direnv allow`][direnv-usage].

#### NixOS
From this point on, lorri monitors your `shell.nix` and its dependencies and
triggers builds as required. Whenever a build succeeds, direnv automatically
reloads your environment.

On NixOS, we have a simple service for installing and enabling the
needed direnv version at [./direnv/nixos.nix](./direnv/nixos.nix).
See [Usage](#usage) for more details.
Profpatsch marked this conversation as resolved.
Show resolved Hide resolved

- Download the file into `/etc/nixos/`:
```
cd /etc/nixos/
wget https://raw.githubusercontent.com/target/lorri/rolling-release/direnv/nixos.nix
## Setup on other platforms

If you are running Nix on a Linux distribution other than NixOS or on macOS,
the following instructions will help you get started with lorri.

1. **Install lorri.** If you are using a Nixpkgs channel at least as recent
as `nixos-19.09`, you can install lorri using `nix-env -i lorri`.

Otherwise, install lorri from the repository as follows:

```console
$ nix-env -if https://github.com/target/lorri/archive/rolling-release.tar.gz
```

- Add `imports = [ ./nixos.nix ];` to your
system's `configuration.nix`. Then run `nixos-rebuild switch` to install and enable it.
2. **Start the daemon.** For testing, you can start the daemon in a separate
terminal by running `lorri daemon`.

#### Nix on Linux (non-NixOS) or macOS
See [`contrib/daemon.md`](contrib/daemon.md) for ways to start the daemon
automatically in the background.

For Nix on Linux or macOS, you can install the needed version of
direnv with:
3. **Install direnv v2.19.2 or later.** If you are using a Nixpkgs channel at
least as recent as `nixos-19.03`, you can install a compatible version of
direnv using `nix-env -i direnv`.
curiousleo marked this conversation as resolved.
Show resolved Hide resolved

```
$ curl -o direnv.nix -L https://github.com/target/lorri/raw/master/direnv/nix.nix
$ nix-env -if ./direnv.nix
```
Otherwise, you can install direnv from source as follows:

### Enable direnv
```console
$ nix-env -if https://github.com/direnv/direnv/archive/master.tar.gz
```
curiousleo marked this conversation as resolved.
Show resolved Hide resolved

Enable direnv according to [its setup instructions][direnv-setup].
4. **Set up the direnv hook for your shell.** See [this section][direnv-hook]
of the direnv documentation.

### Installing lorri
5. **Activate the lorri integration.** Run `lorri init` in your project
directory to create a `shell.nix` and [`.envrc`][direnv-usage] file. This
will not overwrite existing files.

Install with nix-env:
In your shell, you will see the following message from direnv:

```
$ nix-env -if https://github.com/target/lorri/archive/rolling-release.tar.gz
```
```console
direnv: error .envrc is blocked. Run `direnv allow` to approve its content.
```

Activate the integration by running [`direnv allow`][direnv-usage].

From this point on, lorri monitors your `shell.nix` and its dependencies and
triggers builds as required. Whenever a build succeeds, direnv automatically
reloads your environment.

See [Usage](#usage) for more details.
Profpatsch marked this conversation as resolved.
Show resolved Hide resolved

## Usage

Create a file named `.envrc` in your project's root with the contents:
Once the daemon is running and direnv is set up, the daemon process will
continue monitoring and evaluating the Nix expressions in your project's
`shell.nix`, and direnv will automatically reload the environment as it
changes.

```
# content of `.envrc` file:
eval "$(lorri direnv)"
```
direnv will continue to load the *cached environment* when the daemon is not
running. However, the daemon must be running for direnv to reload the
environment based on the current `shell.nix` and its dependencies.


## Editor integration

With the right setup, you can use lorri and direnv to customize your
development environment for each project.

If you use Emacs, our [`direnv-mode` tutorial](./contrib/emacs.md) is there to
help you get started.

This section needs to be fleshed out more
([#244](https://github.com/target/lorri/issues/244)).

---

## Support & Questions

Then, run `lorri daemon`. The first time you run `lorri daemon` on a
project, wait for it to print `Completed` before continuing. Leave
this terminal open.
Please use the [issue tracker](https://github.com/target/lorri/issues)
for any problems or bugs you encounter. We are on `#lorri` on
`freenode` ([Webchat][]), though we might not be responsive at all
times.

In a new terminal:
[Webchat]: https://kiwiirc.com/nextclient/#irc://irc.freenode.net:+6697/#lorri

1. enter the project directory
2. run `direnv allow`
3. watch as direnv loads the environment
## How To Help

The `lorri daemon` process will continue monitoring and evaluating
the Nix expressions, and direnv will automatically reload the
environment as it changes. If you close `lorri daemon`, direnv will
still load the cached environment when you enter the directory,
but the environment will not reload.
All development on lorri happens on the Github repository, in the
open. You can propose a change in an issue, then create a pull request
after some discussion. Some issues are marked with the “good first
issue” label, those are a good place to start. Just remember to leave
a comment when you start working on something.

## Debugging

Expand All @@ -128,16 +169,16 @@ Set these environment variables when debugging:
RUST_LOG=lorri=debug RUST_BACKTRACE=1 lorri watch
```

### `lorri` reevaluates more than expected
### lorri reevaluates more than expected

`lorri` sometimes recursively watches a directory that the user did
lorri sometimes recursively watches a directory that the user did
not expect. This can happen for a number of reasons:

1. When using a local checkout instead of a channel for `nixpkgs`,
`lorri` watches that directory recursively, and will trigger on
lorri watches that directory recursively, and will trigger on
any file change.
2. When specifying `src` via a path, (like the much-used `src = ./.;`)
`lorri` watches that path recursively (see
lorri watches that path recursively (see
https://github.com/target/lorri/issues/6 for details).
To get around this, use a `builtins.filterSource`-based function
to filter `src`, e.g., use
Expand All @@ -146,7 +187,7 @@ not expect. This can happen for a number of reasons:
functions in
[`nixpkgs/lib/sources.nix`](https://github.com/NixOS/nixpkgs/blob/8c1f1b2324bb90f8e1ea33db3253eb30c330ed99/lib/sources.nix)
3. When using a construct like `import ./.` to import a `default.nix`
file, `lorri` watches the current directory recursively. To get
file, lorri watches the current directory recursively. To get
around it, use `import ./default.nix`.

---
Expand Down Expand Up @@ -244,6 +285,12 @@ License: Apache 2.0 (see [`LICENSE` file](./LICENSE))

_([Nix as observed by LORRI on 2015-07-13](https://www.nasa.gov/newhorizons/lorri-gallery))_

[direnv-2-19-2]: https://github.com/direnv/direnv/releases/tag/v2.19.2
[contrib]: ./contrib
[direnv-hook]: https://direnv.net/docs/hook.html
[direnv-setup]: https://direnv.net/index.html#setup
[direnv-usage]: https://direnv.net/man/direnv.1.html#usage
[home-manager-service]: https://rycee.gitlab.io/home-manager/options.html#opt-services.lorri.enable
[home-manager]: https://rycee.gitlab.io/home-manager/
[lorri-blog-post]: https://www.tweag.io/posts/2019-03-28-introducing-lorri.html
[nixos-service]: https://nixos.org/nixos/options.html#services.lorri.enable
[nixos]: https://nixos.org/
103 changes: 5 additions & 98 deletions contrib/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,102 +1,9 @@
# How to start the lorri daemon as a service
# contrib

This guide shows you how to run `lorri daemon` as a service. The exact steps
depend on your operating system and general setup. Currently, we have
instructions for these setups:
This directory contains additional files and guides for integrating lorri into your environment.

- [Run `lorri daemon` on NixOS](#run-lorri-daemon-on-nixos)
- [Run `lorri daemon` on Linux with
home-manager](#run-lorri-daemon-on-linux-with-home-manager)
- [Run `lorri daemon` on Linux with just
systemd](#run-lorri-daemon-on-linux-with-just-systemd)
- [Run `lorri daemon` on macOS with
Nix](#run-lorri-daemon-on-macOS-with-nix)
## Guides

## Run `lorri daemon` on NixOS
[**`daemon.md`**](daemon.md) shows you how to start lorri's daemon process automatically in the background.

Add [`services.lorri.enable =
true;`](https://nixos.org/nixos/options.html#services.lorri.enable) to your
`configuration.nix`, then rebuild your system:

```console
$ sudo nixos-rebuild switch
```

The lorri daemon will now be started on demand by systemd. See [Verify the
setup](#verify-the-setup) to check that everything works as expected.

## Run `lorri daemon` on Linux with home-manager

Add [`services.lorri.enable =
true;`](https://rycee.gitlab.io/home-manager/options.html#opt-services.lorri.enable)
to your `home.nix`, then switch to the new configuration:

```console
$ home-manager switch
```

The lorri daemon will now be started on demand by systemd. See [Verify the
setup](#verify-the-setup) to check that everything works as expected.

## Run `lorri daemon` on Linux with just systemd

Here we'll set up a [systemd] socket and service file manually.

<details>
<summary>What's the purpose of the systemd socket? How does systemd know when
to start the daemon "on demand"?</summary>
<p>lorri clients, like the `direnv` integration, talk to the daemon via a Unix
socket at a well-known location. [`lorri.socket`] tells systemd to start the
systemd service defined in [`lorri.service`] the first time a client attempts
to connect to this socket.</p>
</details>

If your `lorri` binary is not in `~/.nix-profile/bin/lorri`, please change the
`ExecStart=` setting in `lorri.service` to the correct location.

Install [`lorri.socket`] and [`lorri.service`] and make systemd listen on the
daemon socket:

```console
$ mkdir -p ~/.config/systemd/user && \
cp contrib/lorri.{socket,service} ~/.config/systemd/user/ && \
systemctl --user daemon-reload && \
systemctl --user enable --now lorri.socket
```

The lorri daemon will now be started on demand by systemd. See [Verify the
setup](#verify-the-setup) to check that everything works as expected.

## Run `lorri daemon` on macOS with Nix

Please take a look at [@pawlowsklalaex]'s [suggested
`darwin-configuration.nix`](https://github.com/target/lorri/issues/96#issuecomment-545152525).

## Verify the setup

In this section, we'll see how to check that the `lorri daemon` setup actually
works as intended.

### systemd

On a systemd-based system, you should get the following:

```console
$ systemctl --user is-enabled lorri.socket
enabled
$ systemctl --user is-active lorri.socket
active
```

### launchd

On macOS, use this command to check the status of the lorri daemon:

```console
$ launchctl list | grep lorri
```

[systemd]: https://www.freedesktop.org/wiki/Software/systemd/
[`lorri.socket`]: ./lorri.socket
[`lorri.service`]: ./lorri.service
[@pawlowsklalaex]: https://github.com/pawlowskialex
[**`emacs.md`**](emacs.md) shows you how to use direnv to manage project-specific Emacs configuration.
Loading