From 867757d5d82f141323453148e869f15742af6611 Mon Sep 17 00:00:00 2001 From: Sander Date: Sat, 23 Nov 2024 18:12:11 +0400 Subject: [PATCH 1/2] docs: lowercase nav titles --- docs/.pages | 22 +++++++++++----------- docs/guides/.pages | 4 ++-- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/.pages b/docs/.pages index 80a418bec..620f75bcb 100644 --- a/docs/.pages +++ b/docs/.pages @@ -1,8 +1,8 @@ nav: - Home: index.md - Guide: - - Getting Started: getting-started.md - - Files And Variables: files-and-variables.md + - Getting started: getting-started.md + - Files and variables: files-and-variables.md - Writing devenv.nix: - Basics: basics.md - Packages: packages.md @@ -10,30 +10,30 @@ nav: - Tasks: tasks.md - Languages: - Overview: languages.md - - Supported Languages: supported-languages + - Supported languages: supported-languages - Processes: - Overview: processes.md - - Supported Process Managers: supported-process-managers + - Supported process managers: supported-process-managers - Services: - Overview: services.md - - Supported Services: supported-services + - Supported services: supported-services - Containers: containers.md - - Binary Caching: binary-caching.md - - Git Hooks: git-hooks.md + - Binary caching: binary-caching.md + - Git hooks: git-hooks.md - Tests: tests.md - Outputs: outputs.md - - Common Patterns: common-patterns.md + - Common patterns: common-patterns.md - Writing devenv.yaml: - Inputs: inputs.md - Imports: composing-using-imports.md - Overview: - - Automatic Shell Activation: automatic-shell-activation.md - - Garbage Collection: garbage-collection.md + - Automatic shell activation: automatic-shell-activation.md + - Garbage collection: garbage-collection.md - Guides: guides - Integrations: integrations - Tutorial: https://github.com/cachix/nixcon-2024-workshop - Examples: examples.md - - Editor Support: editor-support + - Editor support: editor-support - Roadmap: /blog/2024/10/22/devenv-is-switching-its-nix-implementation-to-tvix - Reference: reference - Blog: blog diff --git a/docs/guides/.pages b/docs/guides/.pages index b3db5af4f..2f3280d14 100644 --- a/docs/guides/.pages +++ b/docs/guides/.pages @@ -1,3 +1,3 @@ nav: - - Using With Flakes: using-with-flakes.md - - Using With flake.parts: using-with-flake-parts.md + - Using with Flakes: using-with-flakes.md + - Using with flake.parts: using-with-flake-parts.md From c41add260f216c19d1914ba65009f45c274604c6 Mon Sep 17 00:00:00 2001 From: Sander Date: Sat, 23 Nov 2024 18:12:35 +0400 Subject: [PATCH 2/2] docs: update flake guides - Put `devenv up` content in its own section - Simplify wording - Fixup examples --- docs/guides/using-with-flake-parts.md | 121 ++++++++++++++++++-------- docs/guides/using-with-flakes.md | 77 ++++++++++------ 2 files changed, 131 insertions(+), 67 deletions(-) diff --git a/docs/guides/using-with-flake-parts.md b/docs/guides/using-with-flake-parts.md index c0f3cf806..69aced5c6 100644 --- a/docs/guides/using-with-flake-parts.md +++ b/docs/guides/using-with-flake-parts.md @@ -1,35 +1,25 @@ If you're familiar with the Nix language and ecosystem, `devenv` can be used without the `devenv` CLI by integrating into [Nix Flakes](https://www.tweag.io/blog/2020-05-25-flakes/) using [flake-parts](https://flake.parts). -Using `devenv` configuration in flakes is useful for projects that need to define other Nix flake features in addition to the development shell. -Additional flake features may include the Nix package for the project or NixOS and Home Manager modules related to the project. +Using a `devenv` configuration in flakes is useful for projects that need to define other Nix flake features in addition to the development shell. +Additional flake features may include the Nix package for the project, or NixOS and Home Manager modules related to the project. Using the same lock file for the development shell and other features ensures that everything is based on the same `nixpkgs`. -A Nix flake needs to consist of at least the input declarations from `devenv.yaml`, as well as the `devenv` configuration that you would usually find in `devenv.nix`. `flake.lock` is the lock file for Nix flakes, the equivalent to `devenv.lock`. +A Nix flake needs to consist of at least the input declarations from `devenv.yaml`, as well as the `devenv` configuration that you would usually find in `devenv.nix`. +`flake.lock` is the lock file for Nix flakes, the equivalent of `devenv.lock`. ## Getting started -To quickly set a project up with Nix flakes, use `nix flake init`: +To quickly set up project with Nix flakes, use `nix flake init`: ```console nix flake init --template github:cachix/devenv#flake-parts ``` -This will create a `flake.nix` file with `devenv` configuration and a `.envrc` file with direnv configuration. +This will create a `flake.nix` file with a basic `devenv` configuration and a `.envrc` file for direnv support. -Open the `devenv` shell using: +## Working with flake shells -```console -nix develop --no-pure-eval -``` - -This will also create a lock file and open a new shell that adheres to the `devenv` configuration contained in `flake.nix`. - -!!! note "Why do I need to use the `--no-pure-eval` flag?" - devenv needs to know the path to the current working directory to create and manage mutable state. - Flakes use "pure evaluation" by default, which prevents devenv from accessing external data, like the `$PWD` environment variable. - The `--no-pure-eval` flag relaxes this restriction. - -## The `flake.nix` file +### The `flake.nix` file Here's an example of a minimal `flake.nix` file that includes `devenv`: @@ -68,21 +58,58 @@ Here's an example of a minimal `flake.nix` file that includes `devenv`: } ``` -Here a single shell is defined for all listed [systems](https://flake.parts/options/flake-parts.html#opt-systems). The shell includes a single `devenv` configuration module, under [`devenv.shells`](https://flake.parts/options/devenv.html#opt-perSystem.devenv.shells), named `default`. +Here a single shell is defined for all listed [systems](https://flake.parts/options/flake-parts.html#opt-systems). +The shell includes a single `devenv` configuration module, under [`devenv.shells`](https://flake.parts/options/devenv.html#opt-perSystem.devenv.shells), named `default`. -Add your `devenv` configuration (usually in the `devenv.nix` file) to this module. See [`devenv.nix` options](../reference/options.md) for more information about configuration options. +Add your `devenv` configuration (usually in the `devenv.nix` file) to this module. +See [`devenv.nix` options](../reference/options.md) for more information about configuration options. -## The direnv extension -To use direnv in your Nix flake project, you'll need [nix-direnv](https://github.com/nix-community/nix-direnv). +### Entering the shell -To configure direnv, ensure your project has a `.envrc` file that includes the following line: +Enter the `devenv` shell using: -```text -use flake . --no-pure-eval +```console +nix develop --no-pure-eval +``` + +This will create a lock file and open a new shell using the `devenv` configuration from your `flake.nix`. + +!!! note "Why do I need to use the `--no-pure-eval` flag?" + Flakes use "pure evaluation" by default, which prevents devenv from figuring out the environment its running in: for example, querying the working directory. + The `--no-pure-eval` flag relaxes this restriction. + + An alternative, and less flexible, workaround is to override the `devenv.root` option to the absolute path to your project directory. + This makes the flake non-portable between machines, but does allow the shell to be evaluated in pure mode. + + +### Launching processes, services, and tests + +Once in the shell, you can launch [processes and services with `devenv up`](/processes). + +```console +$ devenv up +17:34:37 system | run.1 started (pid=1046939) +17:34:37 run.1 | Hello, world! +17:34:37 system | run.1 stopped (rc=0) +``` + +And run [tests with `devenv test`](/tests). + +```console +$ devenv test +Running tasks devenv:enterShell +Succeeded devenv:git-hooks:install 10ms +Succeeded devenv:enterShell 4ms +2 Succeeded 14.75ms +• Testing ... +Running tasks devenv:enterTest +Succeeded devenv:git-hooks:run 474ms +Not implemented devenv:enterTest +1 Skipped, 1 Succeeded 474.62ms ``` -## Import a devenv module +### Import a devenv module You can import a devenv configuration or module, such as `devenv-foo.nix` into an individual shell as follows. @@ -141,15 +168,31 @@ in { } ``` -## Multiple shells +### Automated shell switching + +You can configure your shell to launch automatically when you enter the project directory. + +First, install [nix-direnv](https://github.com/nix-community/nix-direnv). -Depending on the structure of your project, you may want to define multiple development shells using flakes. We'll take a look at two use cases for multiple shells here: A single project with multiple shells and a project with an external flake. +Then add the following line to your `.envrc`: -### Single project with multiple shells +```text +use flake . --no-pure-eval +``` + +Allow `direnv` to evaluate the updated `.envrc`: + +```console +direnv allow +``` -Some projects lend themselves to defining multiple development shells. For instance, you may want to define multiple development shells for different subprojects in a monorepo. You can do this by defining the various development shells in a central `flake.nix` file in the root of the repository. +## Multiple shells -The `flake.nix` file outputs multiple [`devShells`](https://flake.parts/options/flake-parts.html#opt-flake.devShells) when you provide multiple [perSystem.devenv.shells](https://flake.parts/options/devenv.html#opt-perSystem.devenv.shells) definitions. For example: +Some projects lend themselves to defining multiple development shells. For instance, you may want to define multiple development shells for different subprojects in a monorepo. +You can do this by defining the various development shells in a central `flake.nix` file in the root of the repository. + +The `flake.nix` file outputs multiple [`devShells`](https://flake.parts/options/flake-parts.html#opt-flake.devShells) when you provide multiple [perSystem.devenv.shells](https://flake.parts/options/devenv.html#opt-perSystem.devenv.shells) definitions. +For example: ```nix # inside perSystem = { ... }: { @@ -204,24 +247,26 @@ this is project A (devenv) $ ``` -### Projects with an external flake +## External flakes -If you cannot or don't want to add a `flake.nix` file to your project repository, you can refer to external flakes. +If you cannot, or don't want to, add a `flake.nix` file to your project's repository, you can use external flakes instead. -You can create a repository with a `flake.nix` file as in the example above. You can now refer to this flake in a different project: +Create a separate repository with a `flake.nix` file, as in the example above. Then refer to this flake in your project: ```console $ nix develop --no-pure-eval file:/path/to/central/flake#projectA this is project A -(devenv) $ +(devenv) $ ``` -You can also add this to the direnv configuration of the project. Just make sure the following line is in `.envrc`: +You can also add this to the `direnv` configuration of the project. Make sure the following line is in `.envrc`: ```text nix flake --no-pure-eval file:/path/to/central/flake#projectA ``` -Note that instead of referring to a directory on a local file system that includes the `flake.nix`, like `/path/to/central/flake`, it is also possible to use different references to a flake, for instance, `github:` or `git:`. See [Nix flake references](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references) for more information. +External flakes aren't limited to local paths using `file:`. You can refer to flakes on `github:` and generic `git:` repositories. +See [Nix flake references](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references) for more options. -When using this method to refer to external flakes, it's important to remember that there is no lock file, so there is no certainty about which version of the flake is used. A local project flake file will give you more control over which version of the flake is used. +When using this method to refer to external flakes, it's important to remember that there is no lock file, so there is no certainty about which version of the flake is used. +A local project flake file will give you more control over which version of the flake is used. diff --git a/docs/guides/using-with-flakes.md b/docs/guides/using-with-flakes.md index 49964beec..2d9a084c9 100644 --- a/docs/guides/using-with-flakes.md +++ b/docs/guides/using-with-flakes.md @@ -22,26 +22,17 @@ This template will create: * A `flake.nix` file containing a basic devenv configuration. * A `.envrc` file to optionally set up automatic shell activation with direnv. -Open the `devenv` shell with: +## Working with flake shells -```console -nix develop --no-pure-eval -``` - -This will create a `flake.lock` lock file and open a new shell based on the `devenv` configuration stated in `flake.nix`. +### The `flake.nix` file -!!! note "Why do I need to use the `--no-pure-eval` flag?" - devenv needs to know the path to the current working directory to create and manage mutable state. - Flakes use "pure evaluation" by default, which prevents devenv from accessing external data, like the `$PWD` environment variable. - The `--no-pure-eval` flag relaxes this restriction. +Setting up `devenv` inside a flake requires wiring up a few outputs. -## Modifying your `flake.nix` file +Here's a minimal `flake.nix` to start you off that includes: -Here's a minimal `flake.nix` file that includes: - -* A single `devShell` for the `x86_64-linux` system created with `devenv.lib.mkShell`. -* A shell module containing the `devenv` configuration. This is what you'd usually write in `devenv.nix`. +* A `devShell` created with `devenv.lib.mkShell`. See [the reference documentation](/reference/options/) for the possible options to use here. +* Two packages, `devenv-up` and `devenv-test`, that are needed for `devenv up` and `devenv test` to work inside the shell. ```nix { @@ -58,7 +49,6 @@ Here's a minimal `flake.nix` file that includes: outputs = { self, nixpkgs, devenv, ... } @ inputs: let system = "x86_64-linux"; - pkgs = nixpkgs.legacyPackages.${system}; in { @@ -84,6 +74,26 @@ Here's a minimal `flake.nix` file that includes: } ``` +### Entering the shell + +Create and enter the `devenv` shell with: + +```console +nix develop --no-pure-eval +``` + +This will evaluate the inputs to your flake, create a `flake.lock` lock file, and open a new shell using the `devenv` configuration from your `flake.nix`. + +!!! note "Why do I need to use the `--no-pure-eval` flag?" + Flakes use "pure evaluation" by default, which prevents devenv from figuring out the environment its running in: for example, querying the working directory. + The `--no-pure-eval` flag relaxes this restriction. + + An alternative, and less flexible, workaround is to override the `devenv.root` option to the absolute path to your project directory. + This makes the flake non-portable between machines, but does allow the shell to be evaluated in pure mode. + + +### Launching processes, services, and tests + Once in the shell, you can launch [processes and services with `devenv up`](/processes). ```console @@ -94,6 +104,7 @@ $ devenv up ``` And run [tests with `devenv test`](/tests). + ```console $ devenv test Running tasks devenv:enterShell @@ -108,21 +119,26 @@ Not implemented devenv:enterTest ``` -## Automatic shell switching with direnv +### Automated shell switching -Install [nix-direnv](https://github.com/nix-community/nix-direnv) for direnv to work with flakes. +You can configure your shell to launch automatically when you enter the project directory. -Add the following line to your `.envrc`: +First, install [nix-direnv](https://github.com/nix-community/nix-direnv). -```console +The add the following line to your `.envrc`: + +```text use flake . --no-pure-eval ``` -## Multiple shells +Allow `direnv` to evaluate the updated `.envrc`: -Defining multiple development shells using flakes can be useful depending on your project's structure. We will handle two use cases here. +```console +direnv allow +``` -### Single project with multiple shells + +## Multiple shells Some projects lend themselves to defining multiple development shells. For instance, you may want to define multiple development shells for different subprojects in a monorepo. You can do this by defining the various development shells in a central `flake.nix` file in the root of the repository. @@ -144,7 +160,10 @@ The `flake.nix` file contains multiple `devShells`. For example: { packages.${system} = { projectA-devenv-up = self.devShells.${system}.projectA.config.procfileScript; + projectA-devenv-test = self.devShells.${system}.projectA.config.test; + projectB-devenv-up = self.devShells.${system}.projectB.config.procfileScript; + projectB-devenv-test = self.devShells.${system}.projectB.config.test; }; devShells.${system} = { @@ -174,7 +193,7 @@ The `flake.nix` file contains multiple `devShells`. For example: } ``` -Here we define two shells, each with a `devenv` configuration and differently defined `enterShell` command. +Here we've define two shells, each with a separate `devenv` configuration. To enter the shell of `project A`: @@ -192,11 +211,11 @@ this is project B (devenv) $ ``` -### Projects with an external flake +## External flakes -If you cannot or don't want to add a `flake.nix` file to your project's repository, you can refer to external flakes. +If you cannot, or don't want to, add a `flake.nix` file to your project's repository, you can use external flakes instead. -You can create a repository with a `flake.nix` file as in the example above. You can now refer to this flake in a different project: +Create a separate repository with a `flake.nix` file, as in the example above. Then refer to this flake in your project: ```console $ nix develop --no-pure-eval file:/path/to/central/flake#projectA @@ -210,8 +229,8 @@ You can also add this to the `direnv` configuration of the project. Make sure th nix flake --no-pure-eval file:/path/to/central/flake#projectA ``` -Note that instead of referring to a directory on the local file system that includes the `flake.nix` file, like `/path/to/central/flake`, it is also possible to use different references to a flake. -For instance `github:` or `git:`. See [Nix flake references](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references) for more information. +External flakes aren't limited to local paths using `file:`. You can refer to flakes on `github:` and generic `git:` repositories. +See [Nix flake references](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references) for more options. When using this method to refer to external flakes, it's important to remember that there is no lock file, so there is no certainty about which version of the flake is used. A local project flake file will give you more control over which version of the flake is used.