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

Commit

Permalink
Streamline setup instructions in README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@curiousleo
curiousleo committed Nov 20, 2019
1 parent 41b7ee7 commit 2541e94
Showing 1 changed file with 112 additions and 66 deletions.
178 changes: 112 additions & 66 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,96 +14,135 @@ external dependencies, editor integration, and quick feedback.

lorri supports Linux and macOS.

## 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. **Set up the direnv hook for your shell.** See [this section][direnv-hook]
of the direnv documentation. Note that at this point, we have only tested
lorri with Bash. Please open a feature request if you want to use lorri from
a shell other than Bash and are experiencing issues.

## How To Help
3. **Activate the lorri integration.** Create a file called
[`.envrc`][direnv-usage] in your project directory next to your `shell.nix`
with the following contents:

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.
```bash
eval "$(lorri direnv)"
```

## Install
In your shell, you'll 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.

- 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 the [`contrib`][contrib] directory 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`.

```
$ curl -o direnv.nix -L https://github.com/target/lorri/raw/master/direnv/nix.nix
$ nix-env -if ./direnv.nix
```
Otherwise, we provide [`direnv/nix.nix`][direnv-nix] as a convenient way to
install a compatible version of direnv, no matter which Nixpkgs channel
you are on:

### Enable direnv
```console
$ curl -o direnv.nix -L https://github.com/target/lorri/raw/master/direnv/nix.nix
$ nix-env -if ./direnv.nix
```

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. Note that at this point, we have only tested
lorri with Bash. Please open a feature request if you want to use lorri from
a shell other than Bash and are experiencing issues.

### Installing lorri
5. **Activate the lorri integration.** Create a file called
[`.envrc`][direnv-usage] in your project directory with the following
contents:

Install with nix-env:
```bash
eval "$(lorri direnv)"
```

```
$ nix-env -if https://github.com/target/lorri/archive/rolling-release.tar.gz
```
In your shell, you will see the following message from direnv:

```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.

## 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)"
```
When you stop the daemon, direnv will still load the cached environment when
you enter the directory, but the environment will not reload.

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.
---

In a new terminal:
## Support & Questions

1. enter the project directory
2. run `direnv allow`
3. watch as direnv loads the environment
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.

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

## 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 @@ -113,16 +152,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 @@ -131,7 +170,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 @@ -229,5 +268,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))_

[contrib]: ./contrib
[direnv-2-19-2]: https://github.com/direnv/direnv/releases/tag/v2.19.2
[direnv-setup]: https://direnv.net/index.html#setup
[direnv-hook]: https://direnv.net/docs/hook.html
[direnv-nix]: ./direnv/nix.nix
[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/
[nixos-service]: https://nixos.org/nixos/options.html#services.lorri.enable
[nixos]: https://nixos.org/

0 comments on commit 2541e94

Please sign in to comment.