.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix3-develop" "1" ""
.RS
.PP
\fBWarning\fR 
.br
This program is
.UR @docroot@/development/experimental-features.md#xp-feature-nix-command
\fBexperimental\fR
.UE
and its interface is subject to change.
.RE
.SH Name
.LP
\f(CRnix develop\fR - run a bash shell that provides the build environment of a derivation
.SH Synopsis
.LP
\f(CRnix develop\fR [\fIoption\fR\[u2026]] \fIinstallable\fR
.SH Examples
.IP "\(bu" 3
Start a shell with the build environment of the default package of
the flake in the current directory:
.LP
.EX
# nix develop
.EE
.IP
Typical commands to run inside this shell are:
.LP
.EX
# configurePhase
# buildPhase
# installPhase
.EE
.IP
Alternatively, you can run whatever build tools your project uses
directly, e.g. for a typical Unix project:
.LP
.EX
# ./configure --prefix=$out
# make
# make install
.EE
.IP "\(bu" 3
Run a particular build phase directly:
.LP
.EX
# nix develop --unpack
# nix develop --configure
# nix develop --build
# nix develop --check
# nix develop --install
# nix develop --installcheck
.EE
.IP "\(bu" 3
Start a shell with the build environment of GNU Hello:
.LP
.EX
# nix develop nixpkgs#hello
.EE
.IP "\(bu" 3
Record a build environment in a profile:
.LP
.EX
# nix develop --profile /tmp/my-build-env nixpkgs#hello
.EE
.IP "\(bu" 3
Use a build environment previously recorded in a profile:
.LP
.EX
# nix develop /tmp/my-build-env
.EE
.IP "\(bu" 3
Replace all occurrences of the store path corresponding to
\f(CRglibc.dev\fR with a writable directory:
.LP
.EX
# nix develop --redirect nixpkgs#glibc.dev \(ti/my-glibc/outputs/dev
.EE
.IP
Note that this is useful if you\(cqre running a \f(CRnix develop\fR shell for
\f(CRnixpkgs#glibc\fR in \f(CR\(ti/my-glibc\fR and want to compile another package
against it.
.IP "\(bu" 3
Run a series of script commands:
.LP
.EX
# nix develop --command bash -c \(dqmkdir build && cmake .. && make\(dq
.EE
.SH Description
.LP
\f(CRnix develop\fR starts a \f(CRbash\fR shell that provides an interactive build
environment nearly identical to what Nix would use to build
.UR ./nix.md#installables
\fIinstallable\fR
.UE \c
\&. Inside this shell, environment variables and shell
functions are set up so that you can interactively and incrementally
build your package.
.PP
Nix determines the build environment by building a modified version of
the derivation \fIinstallable\fR that just records the environment
initialised by \f(CRstdenv\fR and exits. This build environment can be
recorded into a profile using \f(CR--profile\fR.
.PP
The prompt used by the \f(CRbash\fR shell can be customised by setting the
\f(CRbash-prompt\fR, \f(CRbash-prompt-prefix\fR, and \f(CRbash-prompt-suffix\fR settings in
\f(CRnix.conf\fR or in the flake\(cqs \f(CRnixConfig\fR attribute.
.SH Flake output attributes
.LP
If no flake output attribute is given, \f(CRnix develop\fR tries the following
flake output attributes:
.IP "\(bu" 3
\f(CRdevShells.<system>.default\fR
.IP "\(bu" 3
\f(CRpackages.<system>.default\fR
.LP
If a flake output \fIname\fR is given, \f(CRnix develop\fR tries the following flake
output attributes:
.IP "\(bu" 3
\f(CRdevShells.<system>.<name>\fR
.IP "\(bu" 3
\f(CRpackages.<system>.<name>\fR
.IP "\(bu" 3
\f(CRlegacyPackages.<system>.<name>\fR
.SH Options
.IP "\(bu" 3
.UR #opt-build
\f(CR--build\fR
.UE
.IP
Run the \f(CRbuild\fR phase.
.IP "\(bu" 3
.UR #opt-check
\f(CR--check\fR
.UE
.IP
Run the \f(CRcheck\fR phase.
.IP "\(bu" 3
.UR #opt-command
\f(CR--command\fR
.UE
/ \f(CR-c\fR \fIcommand\fR \fIargs\fR
.IP
Instead of starting an interactive shell, start the specified command and arguments.
.IP "\(bu" 3
.UR #opt-configure
\f(CR--configure\fR
.UE
.IP
Run the \f(CRconfigure\fR phase.
.IP "\(bu" 3
.UR #opt-ignore-environment
\f(CR--ignore-environment\fR
.UE
/ \f(CR-i\fR
.IP
Clear the entire environment (except those specified with \f(CR--keep\fR).
.IP "\(bu" 3
.UR #opt-install
\f(CR--install\fR
.UE
.IP
Run the \f(CRinstall\fR phase.
.IP "\(bu" 3
.UR #opt-installcheck
\f(CR--installcheck\fR
.UE
.IP
Run the \f(CRinstallcheck\fR phase.
.IP "\(bu" 3
.UR #opt-keep
\f(CR--keep\fR
.UE
/ \f(CR-k\fR \fIname\fR
.IP
Keep the environment variable \fIname\fR.
.IP "\(bu" 3
.UR #opt-phase
\f(CR--phase\fR
.UE
\fIphase-name\fR
.IP
The stdenv phase to run (e.g. \f(CRbuild\fR or \f(CRconfigure\fR).
.IP "\(bu" 3
.UR #opt-profile
\f(CR--profile\fR
.UE
\fIpath\fR
.IP
The profile to operate on.
.IP "\(bu" 3
.UR #opt-redirect
\f(CR--redirect\fR
.UE
\fIinstallable\fR \fIoutputs-dir\fR
.IP
Redirect a store path to a mutable location.
.IP "\(bu" 3
.UR #opt-unpack
\f(CR--unpack\fR
.UE
.IP
Run the \f(CRunpack\fR phase.
.IP "\(bu" 3
.UR #opt-unset
\f(CR--unset\fR
.UE
/ \f(CR-u\fR \fIname\fR
.IP
Unset the environment variable \fIname\fR.
.SS
Common evaluation options
.IP "\(bu" 3
.UR #opt-arg
\f(CR--arg\fR
.UE
\fIname\fR \fIexpr\fR
.IP
Pass the value \fIexpr\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 3
.UR #opt-arg-from-file
\f(CR--arg-from-file\fR
.UE
\fIname\fR \fIpath\fR
.IP
Pass the contents of file \fIpath\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 3
.UR #opt-arg-from-stdin
\f(CR--arg-from-stdin\fR
.UE
\fIname\fR
.IP
Pass the contents of stdin as the argument \fIname\fR to Nix functions.
.IP "\(bu" 3
.UR #opt-argstr
\f(CR--argstr\fR
.UE
\fIname\fR \fIstring\fR
.IP
Pass the string \fIstring\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 3
.UR #opt-debugger
\f(CR--debugger\fR
.UE
.IP
Start an interactive environment if evaluation fails.
.IP "\(bu" 3
.UR #opt-eval-store
\f(CR--eval-store\fR
.UE
\fIstore-url\fR
.IP
The \c
.UR @docroot@/store/types/index.md#store-url-format
URL of the Nix store
.UE
to use for evaluation, i.e. to store derivations (\f(CR.drv\fR files) and inputs referenced by them.
.IP "\(bu" 3
.UR #opt-impure
\f(CR--impure\fR
.UE
.IP
Allow access to mutable paths and repositories.
.IP "\(bu" 3
.UR #opt-include
\f(CR--include\fR
.UE
/ \f(CR-I\fR \fIpath\fR
.IP
Add \fIpath\fR to search path entries used to resolve \c
.UR @docroot@/language/constructs/lookup-path.md
lookup paths
.UE
.IP
This option may be given multiple times.
.IP
Paths added through \f(CR-I\fR take precedence over the \c
.UR @docroot@/command-ref/conf-file.md#conf-nix-path
\f(CRnix-path\fR configuration setting
.UE
and the \c
.UR @docroot@/command-ref/env-common.md#env-NIX_PATH
\f(CRNIX_PATH\fR environment variable
.UE \c
\&.
.IP "\(bu" 3
.UR #opt-override-flake
\f(CR--override-flake\fR
.UE
\fIoriginal-ref\fR \fIresolved-ref\fR
.IP
Override the flake registries, redirecting \fIoriginal-ref\fR to \fIresolved-ref\fR.
.SS
Common flake-related options
.IP "\(bu" 3
.UR #opt-commit-lock-file
\f(CR--commit-lock-file\fR
.UE
.IP
Commit changes to the flake\(cqs lock file.
.IP "\(bu" 3
.UR #opt-inputs-from
\f(CR--inputs-from\fR
.UE
\fIflake-url\fR
.IP
Use the inputs of the specified flake as registry entries.
.IP "\(bu" 3
.UR #opt-no-registries
\f(CR--no-registries\fR
.UE
.IP
Don\(cqt allow lookups in the flake registries.
.RS
.IP
\fBDEPRECATED\fR
.IP
Use \c
.UR #opt-no-use-registries
\f(CR--no-use-registries\fR
.UE
instead.
.RE
.IP "\(bu" 3
.UR #opt-no-update-lock-file
\f(CR--no-update-lock-file\fR
.UE
.IP
Do not allow any updates to the flake\(cqs lock file.
.IP "\(bu" 3
.UR #opt-no-write-lock-file
\f(CR--no-write-lock-file\fR
.UE
.IP
Do not write the flake\(cqs newly generated lock file.
.IP "\(bu" 3
.UR #opt-output-lock-file
\f(CR--output-lock-file\fR
.UE
\fIflake-lock-path\fR
.IP
Write the given lock file instead of \f(CRflake.lock\fR within the top-level flake.
.IP "\(bu" 3
.UR #opt-override-input
\f(CR--override-input\fR
.UE
\fIinput-path\fR \fIflake-url\fR
.IP
Override a specific flake input (e.g. \f(CRdwarffs/nixpkgs\fR). This implies \f(CR--no-write-lock-file\fR.
.IP "\(bu" 3
.UR #opt-recreate-lock-file
\f(CR--recreate-lock-file\fR
.UE
.IP
Recreate the flake\(cqs lock file from scratch.
.RS
.IP
\fBDEPRECATED\fR
.IP
Use \c
.UR @docroot@/command-ref/new-cli/nix3-flake-update.md
\f(CRnix flake update\fR
.UE
instead.
.RE
.IP "\(bu" 3
.UR #opt-reference-lock-file
\f(CR--reference-lock-file\fR
.UE
\fIflake-lock-path\fR
.IP
Read the given lock file instead of \f(CRflake.lock\fR within the top-level flake.
.IP "\(bu" 3
.UR #opt-update-input
\f(CR--update-input\fR
.UE
\fIinput-path\fR
.IP
Update a specific flake input (ignoring its previous entry in the lock file).
.RS
.IP
\fBDEPRECATED\fR
.IP
Use \c
.UR @docroot@/command-ref/new-cli/nix3-flake-update.md
\f(CRnix flake update\fR
.UE
instead.
.RE
.SS
Logging-related options
.IP "\(bu" 3
.UR #opt-debug
\f(CR--debug\fR
.UE
.IP
Set the logging verbosity level to \(oqdebug\(cq.
.IP "\(bu" 3
.UR #opt-log-format
\f(CR--log-format\fR
.UE
\fIformat\fR
.IP
Set the format of log output; one of \f(CRraw\fR, \f(CRinternal-json\fR, \f(CRbar\fR or \f(CRbar-with-logs\fR.
.IP "\(bu" 3
.UR #opt-print-build-logs
\f(CR--print-build-logs\fR
.UE
/ \f(CR-L\fR
.IP
Print full build logs on standard error.
.IP "\(bu" 3
.UR #opt-quiet
\f(CR--quiet\fR
.UE
.IP
Decrease the logging verbosity level.
.IP "\(bu" 3
.UR #opt-verbose
\f(CR--verbose\fR
.UE
/ \f(CR-v\fR
.IP
Increase the logging verbosity level.
.SS
Miscellaneous global options
.IP "\(bu" 3
.UR #opt-help
\f(CR--help\fR
.UE
.IP
Show usage information.
.IP "\(bu" 3
.UR #opt-offline
\f(CR--offline\fR
.UE
.IP
Disable substituters and consider all previously downloaded files up-to-date.
.IP "\(bu" 3
.UR #opt-option
\f(CR--option\fR
.UE
\fIname\fR \fIvalue\fR
.IP
Set the Nix configuration setting \fIname\fR to \fIvalue\fR (overriding \f(CRnix.conf\fR).
.IP "\(bu" 3
.UR #opt-refresh
\f(CR--refresh\fR
.UE
.IP
Consider all previously downloaded files out-of-date.
.IP "\(bu" 3
.UR #opt-repair
\f(CR--repair\fR
.UE
.IP
During evaluation, rewrite missing or corrupted files in the Nix store. During building, rebuild missing or corrupted store paths.
.IP "\(bu" 3
.UR #opt-version
\f(CR--version\fR
.UE
.IP
Show version information.
.SS
Options that change the interpretation of \fBinstallables\fR
.IP "\(bu" 3
.UR #opt-expr
\f(CR--expr\fR
.UE
\fIexpr\fR
.IP
Interpret \c
.UR @docroot@/command-ref/new-cli/nix.md#installables
\fIinstallables\fR
.UE
as attribute paths relative to the Nix expression \fIexpr\fR.
.IP "\(bu" 3
.UR #opt-file
\f(CR--file\fR
.UE
/ \f(CR-f\fR \fIfile\fR
.IP
Interpret \c
.UR @docroot@/command-ref/new-cli/nix.md#installables
\fIinstallables\fR
.UE
as attribute paths relative to the Nix expression stored in \fIfile\fR. If \fIfile\fR is the character -, then a Nix expression will be read from standard input. Implies \f(CR--impure\fR.
.RS
.LP
\fBNote\fR
.PP
See \c
.UR @docroot@/command-ref/conf-file.md#command-line-flags
\f(CRman nix.conf\fR
.UE
for overriding configuration settings with command line flags.
.RE