Add 'nix develop' and `nix print-dev-env' manpages

This commit is contained in:
Eelco Dolstra 2020-12-08 21:52:22 +01:00
parent e9de689a6e
commit 42cc98f8d6
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
3 changed files with 121 additions and 30 deletions

View file

@ -385,30 +385,11 @@ struct CmdDevelop : Common, MixEnvironment
return "run a bash shell that provides the build environment of a derivation"; return "run a bash shell that provides the build environment of a derivation";
} }
Examples examples() override std::string doc() override
{ {
return { return
Example{ #include "develop.md"
"To get the build environment of GNU hello:", ;
"nix develop nixpkgs#hello"
},
Example{
"To get the build environment of the default package of flake in the current directory:",
"nix develop"
},
Example{
"To store the build environment in a profile:",
"nix develop --profile /tmp/my-shell nixpkgs#hello"
},
Example{
"To use a build environment previously recorded in a profile:",
"nix develop /tmp/my-shell"
},
Example{
"To replace all occurences of a store path with a writable directory:",
"nix develop --redirect nixpkgs#glibc.dev ~/my-glibc/outputs/dev"
},
};
} }
void run(ref<Store> store) override void run(ref<Store> store) override
@ -495,14 +476,11 @@ struct CmdPrintDevEnv : Common
return "print shell code that can be sourced by bash to reproduce the build environment of a derivation"; return "print shell code that can be sourced by bash to reproduce the build environment of a derivation";
} }
Examples examples() override std::string doc() override
{ {
return { return
Example{ #include "print-dev-env.md"
"To apply the build environment of GNU hello to the current shell:", ;
". <(nix print-dev-env nixpkgs#hello)"
},
};
} }
Category category() override { return catUtility; } Category category() override { return catUtility; }

94
src/nix/develop.md Normal file
View file

@ -0,0 +1,94 @@
R""(
# Examples
* Start a shell with the build environment of the default package of
the flake in the current directory:
```console
# nix develop
```
Typical commands to run inside this shell are:
```console
# configurePhase
# buildPhase
# installPhase
```
Alternatively, you can run whatever build tools your project uses
directly, e.g. for a typical Unix project:
```console
# ./configure --prefix=$out
# make
# make install
```
* Run a particular build phase directly:
```console
# nix develop --configure
# nix develop --build
# nix develop --check
# nix develop --install
# nix develop --installcheck
```
* Start a shell with the build environment of GNU Hello:
```console
# nix develop nixpkgs#hello
```
* Record a build environment in a profile:
```console
# nix develop --profile /tmp/my-build-env nixpkgs#hello
```
* Use a build environment previously recorded in a profile:
```cosnole
# nix develop /tmp/my-build-env
```
* Replace all occurences of the store path corresponding to
`glibc.dev` with a writable directory:
```console
# nix develop --redirect nixpkgs#glibc.dev ~/my-glibc/outputs/dev
```
Note that this is useful if you're running a `nix develop` shell for
`nixpkgs#glibc` in `~/my-glibc` and want to compile another package
against it.
# Description
`nix develop` starts a `bash` shell that provides an interactive build
environment nearly identical to what Nix would use to build
*installable*. Inside this shell, environment variables and shell
functions are set up so that you can interactively and incrementally
build your package.
Nix determines the build environment by building a modified version of
the derivation *installable* that just records the environment
initialised by `stdenv` and exits. This build environment can be
recorded into a profile using `--profile`.
The prompt used by the `bash` shell can be customised by setting the
`bash-prompt` and `bash-prompt-suffix` settings in `nix.conf` or in
the flake's `nixConfig` attribute.
# Flake output attributes
If no flake output attribute is given, `nix run` tries the following
flake output attributes:
* `devShell.<system>`
* `defaultPackage.<system>`
)""

19
src/nix/print-dev-env.md Normal file
View file

@ -0,0 +1,19 @@
R""(
# Examples
* Apply the build environment of GNU hello to the current shell:
```console
# . <(nix print-dev-env nixpkgs#hello)
```
# Description
This command prints a shell script that can be sourced by `b`ash and
that sets the environment variables and shell functions defined by the
build process of *installable*. This allows you to get a similar build
environment in your current shell rather than in a subshell (as with
`nix develop`).
)""