From 9609d063f45f7e1d5e5d5b2200a4231df0b5bbaf Mon Sep 17 00:00:00 2001 From: Zach Mitchell Date: Tue, 26 Aug 2025 13:24:26 -0600 Subject: [PATCH 1/5] refactor: reorganize site --- .../flox-vs-containers.md | 0 docs/{concepts => explanations}/activation.md | 0 docs/{concepts => explanations}/builds.md | 0 .../{concepts => explanations}/composition.md | 0 .../environments.md | 0 docs/{concepts => explanations}/floxhub.md | 0 .../{concepts => explanations}/generations.md | 0 .../manifest-builds.md | 0 .../nix-expression-builds.md | 0 .../organizations.md | 0 .../packages-and-catalog.md | 0 docs/{concepts => explanations}/publishing.md | 0 docs/{concepts => explanations}/services.md | 0 .../getting-started}/creating-environments.md | 0 .../customizing-environments.md | 0 .../getting-started}/default-environment.md | 0 .../multi-arch-environments.md | 0 .../getting-started}/sharing-environments.md | 0 .../going-deeper}/build-and-publish.md | 0 .../going-deeper}/ci-cd.md | 0 .../going-deeper}/composition.md | 0 .../layering-multiple-environments.md | 0 docs/{cookbook => }/languages/c.md | 0 docs/{cookbook => }/languages/go.md | 0 docs/{cookbook => }/languages/jvm.md | 0 docs/{cookbook => }/languages/nodejs.md | 0 docs/{cookbook => }/languages/python.md | 0 docs/{cookbook => }/languages/ruby.md | 0 docs/{cookbook => }/languages/rust.md | 0 docs/man/flox-activate.md | 222 ++++++ docs/man/flox-auth.md | 44 ++ docs/man/flox-build-clean.md | 57 ++ docs/man/flox-build.md | 211 +++++ docs/man/flox-config.md | 144 ++++ docs/man/flox-containerize.md | 190 +++++ docs/man/flox-delete.md | 66 ++ docs/man/flox-edit.md | 106 +++ docs/man/flox-envs.md | 59 ++ docs/man/flox-gc.md | 41 + docs/man/flox-generations-history.md | 60 ++ docs/man/flox-generations-list.md | 58 ++ docs/man/flox-generations-rollback.md | 69 ++ docs/man/flox-generations-switch.md | 68 ++ docs/man/flox-include-upgrade.md | 61 ++ docs/man/flox-init.md | 73 ++ docs/man/flox-install.md | 122 +++ docs/man/flox-list.md | 68 ++ docs/man/flox-publish.md | 141 ++++ docs/man/flox-pull.md | 90 +++ docs/man/flox-push.md | 73 ++ docs/man/flox-search.md | 82 ++ docs/man/flox-services-logs.md | 107 +++ docs/man/flox-services-restart.md | 91 +++ docs/man/flox-services-start.md | 96 +++ docs/man/flox-services-status.md | 81 ++ docs/man/flox-services-stop.md | 89 +++ docs/man/flox-show.md | 72 ++ docs/man/flox-uninstall.md | 67 ++ docs/man/flox-update.md | 91 +++ docs/man/flox-upgrade.md | 76 ++ docs/man/flox.md | 141 ++++ docs/man/manifest.toml.md | 736 ++++++++++++++++++ docs/{tutorials => }/migrations/homebrew.md | 0 docs/{tutorials => }/migrations/nvm.md | 0 mkdocs.yml | 44 +- sitemap_old.xml | 323 ++++++++ 66 files changed, 4097 insertions(+), 22 deletions(-) rename docs/{concepts => comparisons}/flox-vs-containers.md (100%) rename docs/{concepts => explanations}/activation.md (100%) rename docs/{concepts => explanations}/builds.md (100%) rename docs/{concepts => explanations}/composition.md (100%) rename docs/{concepts => explanations}/environments.md (100%) rename docs/{concepts => explanations}/floxhub.md (100%) rename docs/{concepts => explanations}/generations.md (100%) rename docs/{concepts => explanations}/manifest-builds.md (100%) rename docs/{concepts => explanations}/nix-expression-builds.md (100%) rename docs/{concepts => explanations}/organizations.md (100%) rename docs/{concepts => explanations}/packages-and-catalog.md (100%) rename docs/{concepts => explanations}/publishing.md (100%) rename docs/{concepts => explanations}/services.md (100%) rename docs/{tutorials => guides/getting-started}/creating-environments.md (100%) rename docs/{tutorials => guides/getting-started}/customizing-environments.md (100%) rename docs/{tutorials => guides/getting-started}/default-environment.md (100%) rename docs/{tutorials => guides/getting-started}/multi-arch-environments.md (100%) rename docs/{tutorials => guides/getting-started}/sharing-environments.md (100%) rename docs/{tutorials => guides/going-deeper}/build-and-publish.md (100%) rename docs/{tutorials => guides/going-deeper}/ci-cd.md (100%) rename docs/{tutorials => guides/going-deeper}/composition.md (100%) rename docs/{tutorials => guides/going-deeper}/layering-multiple-environments.md (100%) rename docs/{cookbook => }/languages/c.md (100%) rename docs/{cookbook => }/languages/go.md (100%) rename docs/{cookbook => }/languages/jvm.md (100%) rename docs/{cookbook => }/languages/nodejs.md (100%) rename docs/{cookbook => }/languages/python.md (100%) rename docs/{cookbook => }/languages/ruby.md (100%) rename docs/{cookbook => }/languages/rust.md (100%) create mode 100644 docs/man/flox-activate.md create mode 100644 docs/man/flox-auth.md create mode 100644 docs/man/flox-build-clean.md create mode 100644 docs/man/flox-build.md create mode 100644 docs/man/flox-config.md create mode 100644 docs/man/flox-containerize.md create mode 100644 docs/man/flox-delete.md create mode 100644 docs/man/flox-edit.md create mode 100644 docs/man/flox-envs.md create mode 100644 docs/man/flox-gc.md create mode 100644 docs/man/flox-generations-history.md create mode 100644 docs/man/flox-generations-list.md create mode 100644 docs/man/flox-generations-rollback.md create mode 100644 docs/man/flox-generations-switch.md create mode 100644 docs/man/flox-include-upgrade.md create mode 100644 docs/man/flox-init.md create mode 100644 docs/man/flox-install.md create mode 100644 docs/man/flox-list.md create mode 100644 docs/man/flox-publish.md create mode 100644 docs/man/flox-pull.md create mode 100644 docs/man/flox-push.md create mode 100644 docs/man/flox-search.md create mode 100644 docs/man/flox-services-logs.md create mode 100644 docs/man/flox-services-restart.md create mode 100644 docs/man/flox-services-start.md create mode 100644 docs/man/flox-services-status.md create mode 100644 docs/man/flox-services-stop.md create mode 100644 docs/man/flox-show.md create mode 100644 docs/man/flox-uninstall.md create mode 100644 docs/man/flox-update.md create mode 100644 docs/man/flox-upgrade.md create mode 100644 docs/man/flox.md create mode 100644 docs/man/manifest.toml.md rename docs/{tutorials => }/migrations/homebrew.md (100%) rename docs/{tutorials => }/migrations/nvm.md (100%) create mode 100644 sitemap_old.xml diff --git a/docs/concepts/flox-vs-containers.md b/docs/comparisons/flox-vs-containers.md similarity index 100% rename from docs/concepts/flox-vs-containers.md rename to docs/comparisons/flox-vs-containers.md diff --git a/docs/concepts/activation.md b/docs/explanations/activation.md similarity index 100% rename from docs/concepts/activation.md rename to docs/explanations/activation.md diff --git a/docs/concepts/builds.md b/docs/explanations/builds.md similarity index 100% rename from docs/concepts/builds.md rename to docs/explanations/builds.md diff --git a/docs/concepts/composition.md b/docs/explanations/composition.md similarity index 100% rename from docs/concepts/composition.md rename to docs/explanations/composition.md diff --git a/docs/concepts/environments.md b/docs/explanations/environments.md similarity index 100% rename from docs/concepts/environments.md rename to docs/explanations/environments.md diff --git a/docs/concepts/floxhub.md b/docs/explanations/floxhub.md similarity index 100% rename from docs/concepts/floxhub.md rename to docs/explanations/floxhub.md diff --git a/docs/concepts/generations.md b/docs/explanations/generations.md similarity index 100% rename from docs/concepts/generations.md rename to docs/explanations/generations.md diff --git a/docs/concepts/manifest-builds.md b/docs/explanations/manifest-builds.md similarity index 100% rename from docs/concepts/manifest-builds.md rename to docs/explanations/manifest-builds.md diff --git a/docs/concepts/nix-expression-builds.md b/docs/explanations/nix-expression-builds.md similarity index 100% rename from docs/concepts/nix-expression-builds.md rename to docs/explanations/nix-expression-builds.md diff --git a/docs/concepts/organizations.md b/docs/explanations/organizations.md similarity index 100% rename from docs/concepts/organizations.md rename to docs/explanations/organizations.md diff --git a/docs/concepts/packages-and-catalog.md b/docs/explanations/packages-and-catalog.md similarity index 100% rename from docs/concepts/packages-and-catalog.md rename to docs/explanations/packages-and-catalog.md diff --git a/docs/concepts/publishing.md b/docs/explanations/publishing.md similarity index 100% rename from docs/concepts/publishing.md rename to docs/explanations/publishing.md diff --git a/docs/concepts/services.md b/docs/explanations/services.md similarity index 100% rename from docs/concepts/services.md rename to docs/explanations/services.md diff --git a/docs/tutorials/creating-environments.md b/docs/guides/getting-started/creating-environments.md similarity index 100% rename from docs/tutorials/creating-environments.md rename to docs/guides/getting-started/creating-environments.md diff --git a/docs/tutorials/customizing-environments.md b/docs/guides/getting-started/customizing-environments.md similarity index 100% rename from docs/tutorials/customizing-environments.md rename to docs/guides/getting-started/customizing-environments.md diff --git a/docs/tutorials/default-environment.md b/docs/guides/getting-started/default-environment.md similarity index 100% rename from docs/tutorials/default-environment.md rename to docs/guides/getting-started/default-environment.md diff --git a/docs/tutorials/multi-arch-environments.md b/docs/guides/getting-started/multi-arch-environments.md similarity index 100% rename from docs/tutorials/multi-arch-environments.md rename to docs/guides/getting-started/multi-arch-environments.md diff --git a/docs/tutorials/sharing-environments.md b/docs/guides/getting-started/sharing-environments.md similarity index 100% rename from docs/tutorials/sharing-environments.md rename to docs/guides/getting-started/sharing-environments.md diff --git a/docs/tutorials/build-and-publish.md b/docs/guides/going-deeper/build-and-publish.md similarity index 100% rename from docs/tutorials/build-and-publish.md rename to docs/guides/going-deeper/build-and-publish.md diff --git a/docs/tutorials/ci-cd.md b/docs/guides/going-deeper/ci-cd.md similarity index 100% rename from docs/tutorials/ci-cd.md rename to docs/guides/going-deeper/ci-cd.md diff --git a/docs/tutorials/composition.md b/docs/guides/going-deeper/composition.md similarity index 100% rename from docs/tutorials/composition.md rename to docs/guides/going-deeper/composition.md diff --git a/docs/tutorials/layering-multiple-environments.md b/docs/guides/going-deeper/layering-multiple-environments.md similarity index 100% rename from docs/tutorials/layering-multiple-environments.md rename to docs/guides/going-deeper/layering-multiple-environments.md diff --git a/docs/cookbook/languages/c.md b/docs/languages/c.md similarity index 100% rename from docs/cookbook/languages/c.md rename to docs/languages/c.md diff --git a/docs/cookbook/languages/go.md b/docs/languages/go.md similarity index 100% rename from docs/cookbook/languages/go.md rename to docs/languages/go.md diff --git a/docs/cookbook/languages/jvm.md b/docs/languages/jvm.md similarity index 100% rename from docs/cookbook/languages/jvm.md rename to docs/languages/jvm.md diff --git a/docs/cookbook/languages/nodejs.md b/docs/languages/nodejs.md similarity index 100% rename from docs/cookbook/languages/nodejs.md rename to docs/languages/nodejs.md diff --git a/docs/cookbook/languages/python.md b/docs/languages/python.md similarity index 100% rename from docs/cookbook/languages/python.md rename to docs/languages/python.md diff --git a/docs/cookbook/languages/ruby.md b/docs/languages/ruby.md similarity index 100% rename from docs/cookbook/languages/ruby.md rename to docs/languages/ruby.md diff --git a/docs/cookbook/languages/rust.md b/docs/languages/rust.md similarity index 100% rename from docs/cookbook/languages/rust.md rename to docs/languages/rust.md diff --git a/docs/man/flox-activate.md b/docs/man/flox-activate.md new file mode 100644 index 00000000..e4a7b9d0 --- /dev/null +++ b/docs/man/flox-activate.md @@ -0,0 +1,222 @@ +--- +title: flox activate +description: Command reference for the `flox activate` command. +--- + +# `flox activate` command + +## NAME + +flox-activate - activate environments + +## SYNOPSIS + + flox [] activate + [-d= | -r=/] + [-t] + [--print-script] + [-s] + [-m=(dev|run)] + [-- []] + +## DESCRIPTION + +Configures a shell with everything defined by the environment: + +- Downloads packages and adds their `bin` directories to your `$PATH`. +- Sets environment variables and aliases. +- Runs hooks. +- Starts services (if `--start-services` is specified). + +`flox activate` may run in one of three modes: + +- interactive: `flox activate` when invoked from an interactive shell + Launches an interactive sub-shell. The shell to be launched is + determined by `$FLOX_SHELL` or `$SHELL`. +- command: `flox activate -- CMD` + Executes `CMD` in the same environment as if run inside an interactive + shell produced by an interactive `flox activate` The shell `CMD` is + run by is determined by `$FLOX_SHELL` or `$SHELL`. +- in-place: `flox activate` when invoked from a non-interactive shell + with it’s `stdout` redirected e.g. `eval "$(flox activate)"` + Produces commands to be sourced by the parent shell. Flox will + determine the parent shell from `$FLOX_SHELL` or otherwise + automatically determine the parent shell and fall back to `$SHELL`. + +`flox activate` currently supports `bash`, `fish`, `tcsh`, and `zsh` +shells for any of the detection mechanisms described above. + +When invoked interactively, the shell prompt will be modified to display +the active environments, as shown below: + + flox [env1 env2 env3] + +When multiple environments are activated each of their shell hooks +(`profile` and `hook` scripts) are executed in the context of the +environment that they come from. This means that for each shell hook +various environment variables such as `PATH`, `MANPATH`, +`PKG_CONFIG_PATH`, `PYTHONPATH`, etc, are set to the appropriate values +for the environment in which the shell hook was defined. See +[`manifest.toml(5)`](./manifest.toml.md) for more details on shell +hooks. + +## OPTIONS + +### Activate Options + +`-- []` +Command to run in the environment. Spawns the command in a subshell that +does not leak into the calling process. + +`-t`, `--trust` +Trust a remote environment for this activation. Activating an +environment executes a shell hook which may execute arbitrary code. This +presents a security risk, so you will be prompted whether to trust the +environment. Environments owned by the current user and Flox are always +trusted. You may set certain environments to always be trusted using the +config key `trusted_environments."" = (trust | deny)`, or +via the following command: +`flox config --set trusted_environments.\"\" trust`. + +`--print-script` +Prints an activation script to `stdout` that’s suitable for sourcing in +a shell rather than activation via creating a subshell. `flox` +automatically knows when to print the activation script to `stdout`, so +this command is just a debugging aid for users. + +`-s`, `--start-services` +Start the services listed in the manifest when activating the +environment. If no services are running, the services from the manifest +will be started, otherwise a warning will displayed and activation will +continue. + +This flag is currently incompatible with “in-place” activations, but +this feature will be added in the future. + +The services started with this flag will be cleaned up once the last +activation of this environment terminates. + +A remote environment can only have a single set of running services, +regardless of how many times the environment is activated concurrently. + +`-m (dev|run)`, `--mode (dev|run)` +Activate the environment in either “dev” or “run” mode. Overrides the +`options.activate.mode` setting in the manifest. See +[`manifest.toml(5)`](./manifest.toml.md) for more details on activation +modes. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## ENVIRONMENT VARIABLES + +### Variables set by `flox activate` + +`$FLOX_ENV` +Contains the path to the built environment. This directory contains a +merged set of `bin`, `lib`, etc directories for all the packages in the +environment. + +`$FLOX_PROMPT_ENVIRONMENTS` +Contains a space-delimited list of the active environments, +e.g. `owner1/foo owner2/bar local_env`. If, `hide_default_prompt` is set +to `true`, environments named `default` are excluded. + +`$FLOX_ENV_CACHE` +`activate` sets this variable to a directory that can be used by an +environment’s hook to store transient files. These files will persist +for environments used locally, but they will not be pushed, and they +will not persist when using a remote environment with `-r`. + +`$FLOX_ENV_PROJECT` +`activate` sets this variable to the directory of the project using the +Flox environment. For environments stored locally, this is the directory +containing the environment. When running `flox activate -r`, this is set +to the current working directory. This variable can be used to find +project files in environment hooks. + +`$FLOX_ENV_DESCRIPTION` +`activate` sets this variable to the project name of the environment. It +can be used to identify or construct messages about the environment. + +`$_FLOX_ACTIVE_ENVIRONMENTS` +A JSON array containing one object per active environment. This is +currently an implementation detail and its contents are subject to +change. + +`$FLOX_ACTIVATE_START_SERVICES` +`"true"` if this activation started services, `"false"` otherwise. + +### Variables used by `flox activate` + +`$FLOX_SHELL`, `$SHELL` +When activating an environment Flox will either launch a sub-shell or +emit commands to configure an already-running (parent) shell. In both of +these cases Flox needs to know which shell to use, and these variables +are used to control the selection process. + +- interactive and command modes: When launching a sub-shell Flox will + invoke the shell specified in `$FLOX_SHELL` if set or fall back to + invoke `$SHELL` by default. + +- in-place mode: When performing an “in place” activation Flox will + attempt to detect its parent shell type unless overridden by the + `$FLOX_SHELL` variable, and if it cannot detect its parent shell type + then will produce a script with syntax determined by `$SHELL`. + +`$FLOX_PROMPT_COLOR_{1,2}` +Flox adds text to the beginning of the shell prompt to indicate which +environments are active. A set of default colors are used to color this +prompt, but the colors may be overridden with the `$FLOX_PROMPT_COLOR_1` +and `$FLOX_PROMPT_COLOR_2` environment variables. + +The values of these variables should be integers chosen from the +256-color palette as described in the [xterm-256color +chart](https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg). + +## EXAMPLES: + +Activate an environment stored in the current directory: + + $ flox activate + +Activate an environment `some_user/myenv` that’s been pushed to FloxHub: + + $ flox activate -r some_user/myenv + +Invoke a command inside an environment without entering its subshell: + + $ flox activate -- cmd --some-arg arg1 arg2 + +Activate `default` Flox environment only within the current shell (add +to the relevant “rc” file, e.g. `~/.bashrc` or `~/.zprofile`): + + $ eval "$(flox activate)" + +## SEE ALSO + +[`flox-push(1)`](./flox-push.md), [`flox-pull(1)`](./flox-pull.md), +[`flox-edit(1)`](./flox-edit.md), [`flox-delete(1)`](./flox-delete.md) diff --git a/docs/man/flox-auth.md b/docs/man/flox-auth.md new file mode 100644 index 00000000..b0a8a271 --- /dev/null +++ b/docs/man/flox-auth.md @@ -0,0 +1,44 @@ +--- +title: flox auth +description: Command reference for the `flox auth` command. +--- + +# `flox auth` command + +## NAME + +flox-auth - FloxHub authentication commands + +## SYNOPSIS + + flox [] auth + (login | logout | status) + +## DESCRIPTION + +Authenticate with FloxHub so that you can push and pull environments. + +## OPTIONS + +### `login` + +Logs in to FloxHub. + +Required to interact with environments on FloxHub via `flox push`, +`flox pull`, and `flox activate -r`. Authenticating also automatically +trusts your personal environments. + +Prompts you to enter a one-time code at a specified URL. If called +interactively it can open the browser for you if you press ``. + +See also: [`flox-push(1)`](./flox-push.md), +[`flox-pull(1)`](./flox-pull.md), +[`flox-activate(1)`](./flox-activate.md) + +### `logout` + +Logs out from FloxHub. + +### `status` + +Print your current login status diff --git a/docs/man/flox-build-clean.md b/docs/man/flox-build-clean.md new file mode 100644 index 00000000..e9d0bb5b --- /dev/null +++ b/docs/man/flox-build-clean.md @@ -0,0 +1,57 @@ +--- +title: flox build clean +description: Command reference for the `flox build clean` command. +--- + +# `flox build clean` command + +## NAME + +flox-build-clean - Clean the build directory + +## SYNOPSIS + + flox [] build clean + [-d=] + []... + +## DESCRIPTION + +Remove the build artifacts for `` from the environment in +``. Without `` specified clean up all packages and +build-related temporary data. + +## OPTIONS + +`` +The package(s) to clean. Possible values are all keys under the `build` +attribute in the environment’s `manifest.toml`. If omitted, will clean +all build related data. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-build(1)`](./flox-build.md) +[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/man/flox-build.md b/docs/man/flox-build.md new file mode 100644 index 00000000..1616da83 --- /dev/null +++ b/docs/man/flox-build.md @@ -0,0 +1,211 @@ +--- +title: flox build +description: Command reference for the `flox build` command. +--- + +# `flox build` command + +## NAME + +flox-build - Build packages with Flox + +## SYNOPSIS + + flox [] build + [-d=] + [--stability ] + []... + +## DESCRIPTION + +Build the specified `` from the environment in ``, and +the output at `result-` adjacent to the environment. + +### Manifest-defined packages + +Possible values for `` are all keys under the `build` attribute +in the `manifest.toml`. If no `` is specified, Flox will +attempt to build all packages that are defined in the `manifest.toml`. + +Packages are built by running the script defined in +`build..command` within a `bash` subshell. The shell will +behave as if `flox activate` was run immediately prior to running the +build script. + +#### Pure and impure builds + +Builds can be performed in a sandbox for the sake of reproducibility. By +default this sandbox is turned off and the build is run in the root of +the repository. This allows you to perform incremental builds using +existing caches and intermediate build artifacts. We call this an +“impure” build. With the sandbox disabled, building is similar to +running the build script manually within a shell created by +`flox activate`. + +Pure builds are run in a temporary directory with the sandbox enabled. +The sandbox can be enabled by setting +`build..sandbox = "pure"`. Only files tracked by `git` are +copied into the temporary build directory. This ensures that the build +doesn’t accidentally depend on untracked files. + +For this kind of “sandboxed” build, access to untracked files and files +outside of the repository are restricted to provide a reproducible build +environment. Sandboxed builds on Linux additionally are restricted from +accessing the network, but the sandboxing mechanisms on macOS are +somewhat limited and thus pure builds on macOS *will be able to access +the network*. + +#### Referring to other builds + +Any build can access the *results* of other builds (including +non-sandboxed ones) by referring to their name via `${}`. This +allows multi-stage builds. In the example below, the `app` package +depends on the `dep` package by using `${deps}/node_modules`. + +#### Build outputs + +`flox build` creates a temporary directory for the build script to +output built packages to. The environment variable `out` is set to this +directory, and the build script is expected to copy or move packages to +`$out`. + +Upon completion of the build, the build result will be symlinked to +`result-` adjacent to the `.flox` directory that defines the +package. + +#### Metadata + +Specifying the `build..description>` and +`build..version` fields of the build provide extra metadata +that can be used by `flox install`, `flox search`, and `flox show` +commands if the build is later published. + +The `build..version` field can be specified in one of the +following ways: + +1. **as a string**: `version = "0.0.1"` +2. **as read from a file**: `version.file = ""` +3. **as returned by a command**: `version.command = " "` + +## OPTIONS + +`` +The package(s) to build. Possible values are all keys under the `build` +attribute in the environment’s `manifest.toml`. + +`--stability ` +Perform a nix expression build using a base package set of the given +stability as tracked by the catalog server. Can not be used with +manifest base builds. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES + +### Building a simple pure package + +1. Add build instructions to the manifest: + +``` toml +## file: .flox/env/manifest.toml + +... +[build] +hello.command = ''' +## produce something and move it to $out +mkdir -p $out +echo "hello world" >> $out/hello.txt +''' +description = "Produces a file containing 'hello world'" +version = "0.0.0" +``` + +2. Build the package and verify its contents: + + + + $ flox build hello + $ ls ./result-hello + hello.txt + $ cat ./result-hello/hello.txt + hello, world + +### Building a simple multi-stage app + +Assume a simple `nodejs` project + + . + ├── .git/ + ├── package-lock.json + ├── package.json + ├── public/ + ├── README.md + ├── src/ + ... + +1. Initialize a Flox environment + +``` shell +$ flox init +``` + +2. Install dependencies and add build instructions + +``` toml +## file: .flox/env/manifest.toml +version = 1 + +[install] +nodejs.pkg-path = "nodejs" +rsync.pkg-path = "rsync" + +## install node dependencies using npm +## disable the sandbox to allow access to the network +[build] +deps.command = ''' +npm ci +mkdir -p $out +mv node_modules $out/node_modules +''' +deps.sandbox = "off" + +## build the application using previously fetched dependencies +app.command = ''' +rsync -lr ${deps}/node_modules ./ +npm run build +mv dist $out/ +''' +``` + +3. Verify the result + +``` shell +$ npx serve result-app +``` + +## SEE ALSO + +[`flox-build-clean(1)`](./flox-build-clean.md) +[`flox-activate(1)`](./flox-activate.md) +[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/man/flox-config.md b/docs/man/flox-config.md new file mode 100644 index 00000000..1ec23b21 --- /dev/null +++ b/docs/man/flox-config.md @@ -0,0 +1,144 @@ +--- +title: flox config +description: Command reference for the `flox config` command. +--- + +# `flox config` command + +## NAME + +flox-config - view and set configuration options + +## SYNOPSIS + + flox [] config + [-l | + -r | + --set | + --delete=] + +## DESCRIPTION + +Without any flags or when `-l` is passed, `flox config` shows all +options with their computed value. + +Config values are read from the following sources in order of descending +priority: + +1. Environment variables. All config options may be set by prefixing + with `FLOX_` and using SCREAMING_SNAKE_CASE. For example, + `disable_metrics` may be set with `FLOX_DISABLE_METRICS=true`. +2. User customizations from `$FLOX_CONFIG_DIR/flox.toml` if set, + otherwise `flox/flox.toml` in `$XDG_CONFIG_HOME` or any of + `$XDG_CONFIG_DIRS`, wherever it is found first. +3. System settings from `/etc/flox.toml` or + `FLOX_SYSTEM_CONFIG_DIR/flox.toml`. +4. `flox` provided defaults. + +`flox config` commands that mutate configuration always write to the +user config file determined in step 2. + +### Key Format + +`` supports dot-separated queries for nested values, for example: + + flox config --set 'trusted_environments."owner/name"' trust + +## OPTIONS + +### Config Options + +`-l`, `--list` +List the current values of all options. + +`-r`, `--reset` +Reset all options to their default values without confirmation. + +`--set ` +Set ` = ` for a config key + +`--delete ` +Delete config key + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SUPPORTED CONFIGURATION OPTIONS + +`config_dir` +Directory where Flox should load its configuration file (default: +`$XDG_CONFIG_HOME/flox`). This option will only take effect if set with +`$FLOX_CONFIG_DIR`. `config_dir` is ignored. + +`cache_dir` +Directory where Flox should store ephemeral data (default: +`$XDG_CACHE_HOME/flox`). + +`data_dir` +Directory where Flox should store persistent data (default: +`$XDG_DATA_HOME/flox`). + +`disable_metrics` +Disable collecting and sending usage metrics. + +`floxhub_token` +Token to authenticate on FloxHub. + +`hide_default_prompt` +Hide environments named ‘default’ from the shell prompt, and don’t add +environments named ‘default’ to `$FLOX_PROMPT_ENVIRONMENTS` (default: +true). + +`installer_channel` +Release channel to use when checking for updates to Flox. Valid values +are `stable`, `nightly`, or `qa`. (default: `stable`) + +`search_limit` +How many items `flox search` should show by default. + +`set_prompt` +Set shell prompt when activating an environment (default: true). + +`shell_prompt` - DEPRECATED +Rule whether to change the shell prompt in activated environments +(default: “show-all”). This has been deprecated in favor of `set_prompt` +and `hide_default_prompt`. Possible values are \* “show-all”: shows all +active environments \* “hide-all”: disables the modification of the +shell prompt \* “hide-default”: filters out environments named ‘default’ +from the shell prompt + +`state_dir` +Directory where Flox should store data that’s not critical but also +shouldn’t be able to be freely deleted like data in the cache directory. +(default: `$XDG_STATE_HOME/flox` e.g. `~/.local/state/flox`) + +`trusted_environments` +Remote environments that are trusted for activation. Contains keys of +the form `"/"` that map to either `"trust"` or `"deny"`. + +`upgrade_notifications` +Print notification if upgrades are available on `flox activate`. The +notification message is: + + Upgrades are available for packages in 'environment-name'. + Use 'flox upgrade --dry-run' for details. + +(default: true) + +## ENVIRONMENT VARIABLES + +`$FLOX_DISABLE_METRICS` +Variable for disabling the collection/sending of metrics data. If set to +`true`, prevents Flox from submitting basic metrics information such as +a unique token and the subcommand issued. diff --git a/docs/man/flox-containerize.md b/docs/man/flox-containerize.md new file mode 100644 index 00000000..df72ebbb --- /dev/null +++ b/docs/man/flox-containerize.md @@ -0,0 +1,190 @@ +--- +title: flox containerize +description: Command reference for the `flox containerize` command. +--- + +# `flox containerize` command + +## NAME + +flox-containerize - export an environment as a container image + +## SYNOPSIS + + flox [] containerize + [-d= | -r=] + [-f=] [--runtime=] + [--tag=] + +## DESCRIPTION + +Export a Flox environment as a container image. The image can be written +to a container runtime registry, a file, or another process. + +**Note**: Exporting a container from macOS requires a supported runtime +because a proxy container is used to build the environment and image. +You may be prompted for permissions to share files into the proxy +container. Files used in the proxy container are cached using a `docker` +or `podman` volume named `flox-nix`. It can safely be removed any time a +`flox containerize` command is not running using either +`docker volume rm flox-nix` or `podman volume rm flox-nix`. + +Running the container will behave like running `flox activate`. Running +the container interactively with `docker run -it `, will +launch a bash subshell in the container with all your packages and +variables set after running the activation hook. This is akin to +`flox activate`. + +Running the container non-interactively with `docker run ` +allows you to run a command within the container without launching a +subshell, similar to `flox activate --`. + +## OPTIONS + +`-f`, `--file` +File to write the container image to. `-` to write to stdout. Defaults +to `{name}-container.tar` if `--runtime` isn’t specified or detected. + +`--runtime` +Container runtime to store the image (when `--file` is not specified) or +build the image (when on macOS). Defaults to detecting the first +available on PATH. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## MANIFEST CONFIGURATION + +Configuration for the container image produced by `flox containerize` +may be specified in a `[containerize.config]` table in the environment +manifest. + +> **Warning:** `containerize.config` is **experimental**, and its +> behaviour is subject to change + +The following options from the OCI spec are supported, specified in +`kebab-case` rather than `PascalCase`: + + ContainerizeConfig ::= { + user = null | + , exposed-ports = null | [, ...] + , cmd = null | [, ...] + , volumes = null | [, ...] + , working-dir = null | + , labels = null | Map[STRING, STRING] + , stop-signal = null | + } + +`user` +The username or UID which is a platform-specific structure that allows +specific control over which user the process run as. This acts as a +default value to use when the value is not specified when creating a +container. For Linux based systems, all of the following are valid: +`user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. If +`group`/`gid` is not specified, the default group and supplementary +groups of the given `user`/`uid` in `/etc/passwd` and `/etc/group` from +the container are applied. If `group`/`gid` is specified, supplementary +groups from the container are ignored. This will add an entry to +/etc/passwd and /etc/groups inside the container, so no manual useradd +is required. + +`exposed-ports` +A set of ports to expose from a container running this image. Its values +can be in the format of: `port/tcp`, `port/udp`, `port` with the default +protocol being `tcp` if not specified. These values act as defaults and +are merged with any specified when creating a container. + +`cmd` +Default arguments to the entrypoint of the container. These values act +as defaults and may be replaced by any specified when creating a +container. Flox sets an entrypoint to activate the containerized +environment, and `cmd` is then run inside the activation, similar to +`flox activate -- cmd`. + +`volumes` +A set of directories describing where the process is likely to write +data specific to a container instance. + +`working-dir` +Sets the current working directory of the entrypoint process in the +container. This value acts as a default and may be replaced by a working +directory specified when creating a container. + +`labels` +This field contains arbitrary metadata for the container. This property +MUST use the [annotation +rules](https://github.com/opencontainers/image-spec/blob/main/annotations.md#rules). + +`stop-signal` +This field contains arbitrary metadata for the container. This property +MUST use the [annotation +rules](https://github.com/opencontainers/image-spec/blob/main/annotations.md#rules). + +## EXAMPLES + +Create a container image file and load it into Docker: + + $ flox containerize -f ./mycontainer.tar + $ docker load -i ./mycontainer.tar + +Load the image into Docker: + + $ flox containerize --runtime docker + + # or through stdout e.g. if `docker` is not in `PATH`: + + $ flox containerize -f - | /path/to/docker + +Run the container interactively: + + $ flox init + $ flox install hello + $ flox containerize -f - | docker load + $ docker run --rm -it + [floxenv] $ hello + Hello, world! + +Run a specific command from within the container, but do not launch a +subshell. + + $ flox init + $ flox install hello + $ flox containerize -f - | docker load + $ docker run hello + Hello, world + +Create a container with a specific tag: + + $ flox init + $ flox install hello + $ flox containerize --tag 'v1' -f - | docker load + $ docker run --rm -it :v1 + [floxenv] $ hello + Hello, world! + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) \[`docker-load(1)`\] diff --git a/docs/man/flox-delete.md b/docs/man/flox-delete.md new file mode 100644 index 00000000..87584141 --- /dev/null +++ b/docs/man/flox-delete.md @@ -0,0 +1,66 @@ +--- +title: flox delete +description: Command reference for the `flox delete` command. +--- + +# `flox delete` command + +## NAME + +flox-delete - delete an environment + +## SYNOPSIS + + flox [] delete + [-f] + [-d=] + +## DESCRIPTION + +Deletes all data pertaining to an environment. By default, only the +environment in the current directory is deleted, but environments in +other directories may be deleted via the `-d` flag. + +By default, you will be prompted for a confirmation before deleting the +environment. The `-f` flag skips the confirmation dialog and is required +for non-interactive use. + +## OPTIONS + +### Delete Options + +`-f`, `--force` +Delete the environment without confirmation. + + + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## See Also + +[`flox-init(1)`](./flox-init.md) [`flox-push(1)`](./flox-push.md), +[`flox-pull(1)`](./flox-pull.md) diff --git a/docs/man/flox-edit.md b/docs/man/flox-edit.md new file mode 100644 index 00000000..a8437cd3 --- /dev/null +++ b/docs/man/flox-edit.md @@ -0,0 +1,106 @@ +--- +title: flox edit +description: Command reference for the `flox edit` command. +--- + +# `flox edit` command + +## NAME + +flox-edit - edit the declarative environment configuration + +## SYNOPSIS + + flox [] edit + [-d= | -r=] + [[-f=] | -n= | --sync | --reset] + +## DESCRIPTION + +### Transactionally edit the environment manifest. + +By default, invokes an editor with a copy of the local manifest for the +user to interactively edit. The editor is found by querying `$EDITOR`, +`$VISUAL`, and then by looking for common editors in `$PATH`. The +manifest of an environment on FloxHub or in a different directory can be +edited via the `-r` or `-d` flags respectively. See +[`manifest.toml(5)`](./manifest.toml.md) for more details on the +manifest format. + +Once the editor is closed the environment is built in order to validate +the edit. If the build fails you are given a change to continue editing +the manifest, and if you decline, the edit is discarded. This +transactional editing prevents an edit from leaving the environment in a +broken state. One exception is the `-n` flag, which renames a local +environment but does not rebuild it. + +The environment can be edited non-interactively via the `-f` flag, which +replaces the contents of the manifest with those of the provided file. + +### Sync the local manifest with the current generation. + +When using environments that were pushed to or pulled from FloxHub, +changes to the local manifest in `.flox/env/manifest.toml` will block +the use of the environment commands +`flox {install, uninstall, edit, upgrade}`. To proceed, you can run +either: + +- `flox edit --sync` to commit your local changes to a new generation +- `flox edit --reset` to discard your local changes and reset to the + latest generation + +## OPTIONS + +### Edit Options + +`-f`, `--file` +Replace environment manifest with that in ``. If `` is `-`, +reads from stdin. + +`-n`, `--name` +Rename the environment to ``. Only works for local environments. + +`-s`, `--sync` +Create a new generation from the current local environment (Only +available for managed environments) + +`-r`, `--reset` +Reset the environment to the current generation (Only available for +managed environments) + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## ENVIRONMENT VARIABLES + +`$EDITOR`, `$VISUAL` +Override the default editor used for editing environment manifests and +commit messages. + +## SEE ALSO + +[`flox-push(1)`](./flox-push.md), [`flox-pull(1)`](./flox-pull.md), +[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/man/flox-envs.md b/docs/man/flox-envs.md new file mode 100644 index 00000000..c56a704d --- /dev/null +++ b/docs/man/flox-envs.md @@ -0,0 +1,59 @@ +--- +title: flox envs +description: Command reference for the `flox envs` command. +--- + +# `flox envs` command + +## NAME + +flox-envs - show active and available environments + +## SYNOPSIS + + flox [] envs + [--active] + [--json] + +## DESCRIPTION + +This command can be used to list available environments on the local +machine. When one or more environments are active, the last activated +environment will be listed first and printed in **bold**. + +Whenever an environment is used with any `flox` command it is registered +to a user specific global registry. `flox envs` will list all +environments known to it through the registry. Environments that are +present on the local system may not show up until they are used the +first time. Similarly, if an environment is changed (e.g. deleted and +replaced by an environment with different metadata), the change may not +show until the new environment is used. + +## OPTIONS + +### Edit Options + +`--active` +Show only active environments + +`--json` +Format the output as JSON + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-init(1)`](./flox-init.md), [`flox-pull(1)`](./flox-pull.md), +[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/man/flox-gc.md b/docs/man/flox-gc.md new file mode 100644 index 00000000..e1836b94 --- /dev/null +++ b/docs/man/flox-gc.md @@ -0,0 +1,41 @@ +--- +title: flox gc +description: Command reference for the `flox gc` command. +--- + +# `flox gc` command + +## NAME + +flox-gc - Garbage collection + +## SYNOPSIS + + flox [] gc + +## DESCRIPTION + +Garbage collects any data for deleted environments. + +This both deletes data managed by Flox and runs garbage collection on +the Nix store. + +## OPTIONS + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-envs(1)`](./flox-envs.md), diff --git a/docs/man/flox-generations-history.md b/docs/man/flox-generations-history.md new file mode 100644 index 00000000..03c8974a --- /dev/null +++ b/docs/man/flox-generations-history.md @@ -0,0 +1,60 @@ +--- +title: flox generations history +description: Command reference for the `flox generations history` command. +--- + +# `flox generations history` command + +## NAME + +flox-generations-history - Show the change log for the current +environment + +## SYNOPSIS + + flox [] generations history + [-d= | -r=] + +## DESCRIPTION + +Show the change log for the current environment. + +For environments pushed to FloxHub, every modification to the +environment creates a new generation of the environment. It’s also +possible to change the current generation by using +`flox generations switch` or `flox generations rollback`. + +`flox generations history` prints what generation has been the current +generation over time. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-generations-list(1)`](./flox-generations-list.md) +[`flox-generations-rollback(1)`](./flox-generations-rollback.md) +[`flox-generations-switch(1)`](./flox-generations-switch.md) diff --git a/docs/man/flox-generations-list.md b/docs/man/flox-generations-list.md new file mode 100644 index 00000000..918b8e38 --- /dev/null +++ b/docs/man/flox-generations-list.md @@ -0,0 +1,58 @@ +--- +title: flox generations list +description: Command reference for the `flox generations list` command. +--- + +# `flox generations list` command + +## NAME + +flox-generations-list - show all environment generations that you can +switch to + +## SYNOPSIS + + flox [] generations list + [-d= | -r=] + +## DESCRIPTION + +Show all environment generations that you can switch to. + +For environments pushed to FloxHub, every modification to the +environment creates a new generation of the environment. + +`flox generations list` prints all generations of the environment, +including which generation is currently live. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-generations-history(1)`](./flox-generations-history.md) +[`flox-generations-rollback(1)`](./flox-generations-rollback.md) +[`flox-generations-switch(1)`](./flox-generations-switch.md) diff --git a/docs/man/flox-generations-rollback.md b/docs/man/flox-generations-rollback.md new file mode 100644 index 00000000..85d38932 --- /dev/null +++ b/docs/man/flox-generations-rollback.md @@ -0,0 +1,69 @@ +--- +title: flox generations rollback +description: Command reference for the `flox generations rollback` command. +--- + +# `flox generations rollback` command + +## NAME + +flox-generations-rollback - switch to the previous live generation + +## SYNOPSIS + + flox [] generations rollback + [-d= | -r=] + +## DESCRIPTION + +Switch to the previous live generation of the environment. + +Rolling back to the previous generation restores the environment’s +manifest and lockfile to the state of the previous generation, sets it +as the live generation, and adds an entry to generation history. + +The previously live generation isn’t always N-1. If you’ve previously +rolled back from generation 3 -\> 2 then rolling back again will take +you from generation 2 -\> 3. Similarly if you’ve switched from +generation 3 -\> 1 then rolling back will take you from generation 1 -\> +3. + +Generations don’t always have a linear history. If you create generation +2 by installing a package, rollback to generation 1 and create +generation 3 by installing another package, then generation 3 won’t +contain the package from generation 2. + +[`flox-generations-history(1)`](./flox-generations-history.md) can be +used to see the relationships between generations. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-generations-history(1)`](./flox-generations-history.md) +[`flox-generations-list(1)`](./flox-generations-list.md) +[`flox-generations-switch(1)`](./flox-generations-switch.md) diff --git a/docs/man/flox-generations-switch.md b/docs/man/flox-generations-switch.md new file mode 100644 index 00000000..56e76e5f --- /dev/null +++ b/docs/man/flox-generations-switch.md @@ -0,0 +1,68 @@ +--- +title: flox generations switch +description: Command reference for the `flox generations switch` command. +--- + +# `flox generations switch` command + +## NAME + +flox-generations-switch - switch to the provided generation + +## SYNOPSIS + + flox [] generations switch + [-d= | -r=] + + +## DESCRIPTION + +Switch to the provided generation of the environment. + +Generation numbers can be found with +[`flox-generations-history(1)`](./flox-generations-history.md) or +[`flox-generations-list(1)`](./flox-generations-list.md). + +Switching generation restores the environment’s manifest and lockfile to +the state of the specified generation, sets it as the live generation, +and adds an entry to generation history. + +Generations don’t always have a linear history. If you create generation +2 by installing a package, rollback to generation 1 and create +generation 3 by installing another package, then generation 3 won’t +contain the package from generation 2. + +[`flox-generations-history(1)`](./flox-generations-history.md) can be +used to see the relationships between generations. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-generations-history(1)`](./flox-generations-history.md) +[`flox-generations-list(1)`](./flox-generations-list.md) +[`flox-generations-rollback(1)`](./flox-generations-rollback.md) diff --git a/docs/man/flox-include-upgrade.md b/docs/man/flox-include-upgrade.md new file mode 100644 index 00000000..f0367dfc --- /dev/null +++ b/docs/man/flox-include-upgrade.md @@ -0,0 +1,61 @@ +--- +title: flox include upgrade +description: Command reference for the `flox include upgrade` command. +--- + +# `flox include upgrade` command + +## NAME + +flox-include-upgrade - upgrade an environment with latest changes to its +included environments + +## SYNOPSIS + + flox [] include upgrade + [-d= | -r=] + []... + +## DESCRIPTION + +Get the latest contents of included environments and merge them with the +composing environment. + +If the names of specific included environments are provided, only +changes for those environments will be fetched. If no names are +provided, changes will be fetched for all included environments. + +## OPTIONS + +`` +Name of included environment to check for changes + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`manifest-toml`(5)](./manifest.toml.md), diff --git a/docs/man/flox-init.md b/docs/man/flox-init.md new file mode 100644 index 00000000..63da0c10 --- /dev/null +++ b/docs/man/flox-init.md @@ -0,0 +1,73 @@ +--- +title: flox init +description: Command reference for the `flox init` command. +--- + +# `flox init` command + +## NAME + +flox-init - initialize a Flox environment + +## SYNOPSIS + + flox [] init + [-n ] + [-d ] + [--auto-setup] + +## DESCRIPTION + +Create a new empty environment in the current directory. + +The name of the environment will be the basename of the current +directory or `default` if the current directory is `$HOME`. The `--name` +flag can be used to give the environment a specific name. + +By default, the environment will be created in the current directory. +Flox will add a directory `$PWD/.flox` containing all relevant +environment metadata. The `--dir` flag can be used to create an +environment in another location. + +If an environment already exists in the current directory, or the path +specified using `--dir` exists, an error is returned. + +`init` will try to detect languages being used in the containing +directory, and it will prompt with suggestions for packages or +activation scripts to be added to the environment. These suggestions can +be taken without prompting by passing `--auto-setup`. The suggestions +can be accepted but then edited using `flox edit`. Currently, +suggestions are made for Python and Nodejs. + +## OPTIONS + +### Init Options + +`-n `, `--name ` +What to name the new environment (default: current directory). + +`-d `, `--dir ` +Directory to create the environment in (default: current directory). + +`--auto-setup` +Apply Flox recommendations for the environment based on what languages +are being used in the containing directory. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md), +[`flox-install(1)`](./flox-install.md), diff --git a/docs/man/flox-install.md b/docs/man/flox-install.md new file mode 100644 index 00000000..3c1bd4e3 --- /dev/null +++ b/docs/man/flox-install.md @@ -0,0 +1,122 @@ +--- +title: flox install +description: Command reference for the `flox install` command. +--- + +# `flox install` command + +## NAME + +flox-install - install packages to an environment + +## SYNOPSIS + + flox [] install + [-i ] + [[-i ] ] ... + +## DESCRIPTION + +Install packages to an environment. + +Package installation is transactional. During an installation attempt +the environment is built in order to validate that the environment isn’t +broken (for example, in rare cases packages may provide files that +conflict). If building the environment fails, including any of the +constituent packages, the attempt is discarded and the environment is +unmodified. If the build succeeds, the environment is atomically +updated. + +If a requested package is already installed, nothing is done. If +multiple packages are requested and some of them are already installed, +only the new packages are installed and the transaction will still +succeed as long as the build succeeds. + +You may also specify packages to be installed via +[`flox-edit(1)`](./flox-edit.md), which allows specifying a variety of +options for package installation. See +[`manifest-toml(1)`](./manifest.toml.md) for more details on the +available options. + +### Install ID + +The name of a package as it exists in the manifest is referred to as the +“install ID”. This ID is separate from the pkg-path and provides a +shorthand for packages with long names such as `python310Packages.pip`. +Install IDs also provide a way to give packages more semantically +meaningful, convenient, or aesthetically pleasing names in the manifest +(e.g. `node21` instead of `nodejs_21`). When not explicitly provided, +the install ID is inferred based on the pkg-path. For pkg-paths that +consist of a single attribute (e.g. `ripgrep`) the install ID is set to +that attribute. For pkg-paths that consist of multiple attributes +(e.g. `python310Packages.pip`) the install ID is set to the last +attribute in the pkg-path (e.g. `pip`). + +As an advanced feature, a Nix flake installable may be specified instead +of a pkg-path, and in this case the install ID is inferred from the +attribute path specified, or if no attribute path is provided, the +install ID is inferred from the flake reference. + +### Package names + +Packages are organized in a hierarchical structure such that certain +packages are found at the top level (e.g. `ripgrep`), and other packages +are found under package sets (e.g. `python310Packages.pip`). We call +this location within the catalog the “pkg-path”. + +The pkg-path is searched when you execute a `flox search` command. The +pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears +in your manifest after a `flox install`. + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +## OPTIONS + +### Install Options + +`-i`, `--id` +The install ID of the package as it will appear in the manifest + +`` +The pkg-path of the package to install as shown by ‘flox search’ Append +`@` to specify a version requirement. + +Alternatively, an arbitrary Nix flake installable, or store path may be +specified. See [`manifest-toml(1)`](./manifest.toml.md) for more +details. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +### SEE ALSO + +[`flox-uninstall(1)`](./flox-uninstall.md), +[`flox-edit(1)`](./flox-edit.md), +[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/man/flox-list.md b/docs/man/flox-list.md new file mode 100644 index 00000000..368771cc --- /dev/null +++ b/docs/man/flox-list.md @@ -0,0 +1,68 @@ +--- +title: flox list +description: Command reference for the `flox list` command. +--- + +# `flox list` command + +## NAME + +flox-list - list packages installed in an environment + +## SYNOPSIS + + flox [] list + [-d= | -r=] + [-e | -c | -n | -a] + +## DESCRIPTION + +List packages installed in an environment. The options `-n`, `-e`, and +`-a` exist to provide varying levels of detail in the output. + +## OPTIONS + +### List Options + +`-e`, `--extended` +Show the install ID, pkg-path, and version of each package (default). + +`-c`, `--config` +Show the raw contents of the manifest. When using composition, the +merged manifest will be shown without any commented lines. + +`-n`, `--name` +Show only the install ID of each package. + +`-a`, `--all` +Show all available package information including priority and license. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-install(1)`](./flox-install.md) diff --git a/docs/man/flox-publish.md b/docs/man/flox-publish.md new file mode 100644 index 00000000..1d000534 --- /dev/null +++ b/docs/man/flox-publish.md @@ -0,0 +1,141 @@ +--- +title: flox publish +description: Command reference for the `flox publish` command. +--- + +# `flox publish` command + +## NAME + +flox-publish - Publish packages for Flox + +## SYNOPSIS + +``` bash +flox [] publish + [-d=] + [-o=] + [--signing-private-key ] + [--stability ] + []... +``` + +## DESCRIPTION + +Publish the specified `` from the environment in ``, +uploading package metadata and copying the packages so that it is +available in the Flox Catalog. + +### Preconditions + +Flox makes some assertions before publishing, specifically: + +- The Flox environment used to build the package is tracked as a git + repository. +- Tracked files in the repository are all clean. +- The repository has a remote defined and the current revision has been + pushed to it. +- The build environment must have at least one package installed. + +These conditions ensure that the package being built can be located, +built, and reproduced in the future. + +### Publishing process + +Possible values for `` are all keys under the `build` attribute +in `manifest.toml`. If only one build is defined in `manifest.toml`, +specifying the `` is unnecessary. If there are multiple builds +defined, you may only publish a single package at a time and must +specify the name when calling `flox publish`. + +Flox will then perform a clone of the repository to a temporary location +and perform a clean `flox build` operation. This ensures that all files +required to build the package are included in the git repository. + +When publishing a package, metadata is sent to Flox servers so that +information about the package can be made available in `flox install`, +`flox search`, and `flox show`. The package itself, along with any other +packages it depends on, are uploaded to the Catalog’s configured Catalog +Store. By default, Flox provides and configures a Catalog Store, but you +may optionally provide your own Catalog Store. Contact Flox directly if +you’re interested in this option. + +Finally, the package is uploaded to the default Catalog, which is named +after your user, but you may specify the catalog to publish to via the +`--catalog` option. + +### After publishing + +After the package is published, it will be available to the +`flox install`, `flox search`, and `flox show` commands. The package +will appear with a name of the form `/` where `` +is the name of the catalog it was published to, and `` is the name +of the package as it was defined in the `[build]` section of the +manifest. The `` name is either your user name or the name of +the organization that owns the Catalog. + +For instance, if a user `myuser` published a package called `hello` to +their personal Catalog, the package would appear in `flox search` as +`myuser/hello`. + +When installing the package, it is downloaded directly from the Catalog +Store that it was published to. + +### Sharing published packages + +a package published to an individual user’s Catalog may only be seen and +installed by that user. In order to share packages with other users you +must create an organization. See +https://flox.dev/docs/concepts/organizations/ for more details on +organizations and how to create them. Note that this is a paid feature +available with Flox for Teams. + +## OPTIONS + +`` +The package to publish. Possible values are all keys under the `build` +attribute in the environment’s `manifest.toml`. + +`-o, --org ` +Specify the organization to which an artifact should be published to. +Takes precedence over the default value of the user’s GitHub handle. + +`--signing-private-key ` +The private key to use in signing the package during upload. This is a +local file path. This option is only necessary when using a Catalog +Store not provided by Flox. Takes precedence over the value of +`publish.signing_private_key` from ‘flox config’. + +`--stability ` +Perform a nix expression build using a base package set of the given +stability as tracked by the catalog server. Can not be used with +manifest base builds. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-build(1)`](./flox-build.md) +[`flox-activate(1)`](./flox-activate.md) +[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/man/flox-pull.md b/docs/man/flox-pull.md new file mode 100644 index 00000000..8f8e4fbd --- /dev/null +++ b/docs/man/flox-pull.md @@ -0,0 +1,90 @@ +--- +title: flox pull +description: Command reference for the `flox pull` command. +--- + +# `flox pull` command + +## NAME + +flox-pull - pull environment from FloxHub + +## SYNOPSIS + + flox [] pull + [-d=] + [-r=/ | / | [-f]] + [-f] + [-c] + +## DESCRIPTION + +Pull an environment from FloxHub and create a local reference to it, or, +if an environment has already been pulled, retrieve any updates. + +When pulling an environment for the first time, `-d` specifies the +directory in which to create that environment. The remote environment is +specified in the form `/`. It may optionally be preceded by +`-r`, but `-r` is not necessary and is accepted simply for consistency +with other environment commands. + +When pulling an environment that has already been pulled, `-d` specifies +which environment to sync. If `-d` is not specified and the current +directory contains an environment, that environment is synced. `-f` may +be specified in this case, forcibly updating the environment locally +even if there are local changes not reflected in the remote environment. +`/` may be specified in this case and will replace the +environment with the specified environment. + +A remote environment may not support the architecture or operating +system of the local system pulling the environment, in which case `-f` +may be passed to forcibly add the current system to the environment’s +manifest. This may create a broken environment that cannot be pushed +back to FloxHub until it is repaired with +[`flox-edit(1)`](./flox-edit.md). See +[`manifest.toml(5)`](./manifest.toml.md) for more on multi-system +environments. + +## OPTIONS + +### Pull Options + +`-d`, `--dir` +Directory to pull an environment into, or directory that contains an +environment that has already been pulled (default: current directory). + +`-r /`, `--remote /` +ID of the environment to pull. + +`/` +ID of the environment to pull. + +`-f`, `--force` +Forcefully overwrite the local copy of the environment, and accept any +kind of modification and possibly incompatible results that have to be +addressed manually. + +`-c`, `--copy` +Create a local copy of an environment by removing the connection to the +upstream environment on FloxHub. When pulling a new environment this +creates a new environment that can be used locally or pushed to FloxHub +under a new user or name. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-push(1)`](./flox-push.md) [`flox-edit(1)`](./flox-edit.md) +[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/man/flox-push.md b/docs/man/flox-push.md new file mode 100644 index 00000000..d13eb530 --- /dev/null +++ b/docs/man/flox-push.md @@ -0,0 +1,73 @@ +--- +title: flox push +description: Command reference for the `flox push` command. +--- + +# `flox push` command + +## NAME + +flox-push - send environment to FloxHub + +## SYNOPSIS + + flox [] push + [-d=] + [-o=] + [-f] + +## DESCRIPTION + +Move an environment’s manifest to FloxHub or sync local changes to an +environment to FloxHub. + +After pushing, the remote environment can be referred to as +`/`. + +A path environment contains a manifest file and lock file which are +stored locally and possibly committed to version control. Pushing the +environment moves the manifest and lock file to FloxHub, leaving a +reference to the revision of the environment stored locally. + +Once the environment has been pushed, it can be used directly with the +`--remote` option, or it can be used and edited locally before syncing +with `flox push`. See [`flox-edit(1)`](./flox-edit.md), +[`flox-install(1)`](./flox-install.md), and +[`flox-uninstall(1)`](./flox-uninstall.md) for editing the environment. + +In the same way as a git repo, local changes to an environment that has +been pushed may diverge from the environment on FloxHub if `flox push` +is run from a different host. Passing `--force` to `flox push` will +cause it to overwrite any changes on FloxHub with local changes to the +environment. + +## OPTIONS + +### Push Options + +`-d`, `--dir` +Directory to push the environment from (default: current directory). + +`-o`, `--owner`, `--org` +FloxHub owner to push environment to (default: current FloxHub user). + +`-f`, `--force` +Forcibly overwrite the remote copy of the environment. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-pull(1)`](./flox-pull.md) diff --git a/docs/man/flox-search.md b/docs/man/flox-search.md new file mode 100644 index 00000000..9cd5468b --- /dev/null +++ b/docs/man/flox-search.md @@ -0,0 +1,82 @@ +--- +title: flox search +description: Command reference for the `flox search` command. +--- + +# `flox search` command + +## NAME + +flox-search - search for packages + +## SYNOPSIS + + flox [] search + [--json] + [-a] + + +## DESCRIPTION + +Search for available packages. + +A limited number of search results are reported by default for brevity. +The full result set can be returned via the `-a` flag. + +Only the package name and description are shown by default. Structured +search results can be returned via the `--json` flag. More specific +information for a single package is available via the +[`flox-show(1)`](./flox-show.md) command. + +### Package names + +Packages are organized in a hierarchical structure such that certain +packages are found at the top level (e.g. `ripgrep`), and other packages +are found under package sets (e.g. `python310Packages.pip`). We call +this location within the catalog the “pkg-path”. + +The pkg-path is searched when you execute a `flox search` command. The +pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears +in your manifest after a `flox install`. + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +### Fuzzy search + +`flox search` uses a fuzzy search mechanism that tries to match either +some portion of the pkg-path or description. + +## OPTIONS + +### Search Options + +`` +The package name to search for. + +`--json` +Display the search results in JSON format. + +`-a`, `--all` +Display all search results (default: at most 10). + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-show(1)`](./flox-show.md) diff --git a/docs/man/flox-services-logs.md b/docs/man/flox-services-logs.md new file mode 100644 index 00000000..e153762e --- /dev/null +++ b/docs/man/flox-services-logs.md @@ -0,0 +1,107 @@ +--- +title: flox services logs +description: Command reference for the `flox services logs` command. +--- + +# `flox services logs` command + +## NAME + +flox-services-logs - show logs of services + +## SYNOPSIS + + flox [] services logs + [-d= | -r=] + [--follow] + [-n=] + [] ... + +## DESCRIPTION + +Display the logs of the specified services. + +If no services are specified, then the `--follow` flag is required and +logs from all services will be printed in real time. + +One or more service names specified with the `--follow` flag will follow +the logs for the specified services. + +If a service name is supplied without the `--follow` flag then all of +the available logs are displayed for that service. If specified with the +`-n` flag then only the most recent `` lines from that service are +displayed. + +An error will be returned if a specified service does not exist. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`--follow` +Follow log output for the specified services. Required when no service +names are supplied. + +`-n`, `--tail` +Display only the last `` lines from the logs of the specified +services. + +`` +Which service(s) to display logs for. When omitted logs from all +services will be displayed but the `--follow` flag is required. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Follow logs for all services: + + $ flox services logs --follow + service1: hello + service2: hello + ... + +Follow logs for a subset of services: + + $ flox services logs --follow service1 service3 + service1: hello + service3: hello + ... + +Display all available logs for a single service: + + $ flox services logs myservice + starting... + running... + stopping... + completed + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) +[`flox-services-start(1)`](./flox-services-start.md) diff --git a/docs/man/flox-services-restart.md b/docs/man/flox-services-restart.md new file mode 100644 index 00000000..524b046e --- /dev/null +++ b/docs/man/flox-services-restart.md @@ -0,0 +1,91 @@ +--- +title: flox services restart +description: Command reference for the `flox services restart` command. +--- + +# `flox services restart` command + +## NAME + +flox-services-restart - restart running services + +## SYNOPSIS + + flox [] services restart + [-d= | -r=] + [] ... + +## DESCRIPTION + +Restarts the specified services. + +If no services are specified, stops all running services and starts new +services using the latest build of the environment. If one or more +services are running, then the specified services are started using the +service config that the running services were started with. + +If one or more services are running, the specified services will be +started using the service config that the running services were started +with. + +When all services are restarted, they are started from an ephemeral +activation that uses the latest build of the environment. This may not +be the build of the environment that your shell has activated, so the +environment variables present for services may be different from the +ones in your shell. To ensure that your shell and the services have the +same environment, reactivate your environment after making edits to the +manifest. + +An error is displayed if the specified service does not exist. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`` +The name(s) of the services to restart. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Restart a single service: + + $ flox services restart myservice + ✅ Service 'myservice' restarted. + +Restart all services: + + $ flox services restart + ✅ Service 'service1' restarted. + ✅ Service 'service2' restarted. + ✅ Service 'service3' restarted. + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/man/flox-services-start.md b/docs/man/flox-services-start.md new file mode 100644 index 00000000..d11aa023 --- /dev/null +++ b/docs/man/flox-services-start.md @@ -0,0 +1,96 @@ +--- +title: flox services start +description: Command reference for the `flox services start` command. +--- + +# `flox services start` command + +## NAME + +flox-services-start - start services + +## SYNOPSIS + + flox [] services start + [-d= | -r=] + [] ... + +## DESCRIPTION + +Starts the specified services. + +If any services are currently running, a warning will be displayed for +each specified service that is already running, but the command will +still succeed. If a specified service does not exist, an error will be +displayed and no services will be started. + +If no services are currently running, then the services will be started +from an ephemeral activation in order to use the most recent build of +the environment. This may be different from the build of the environment +that the current shell has activated, so the services and your shell may +have different environment variables or values. To ensure that your +shell and the services have the same environment, reactivate your +environment after making edits to the manifest. + +A remote environment can only have a single set of running services, +regardless of how many times the environment is activated concurrently. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`` +The name(s) of the services to start. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Start a service named ‘server’: + + $ flox services start server + +Start all services: + + $ flox services start + +Attempt to start a service that doesn’t exist: + + $ flox services start myservice doesnt_exist + ❌ ERROR: Service 'doesnt_exist' not found. + +Attempt to start a service that is already running: + + $ flox services start running not_running + ✅ Service 'not_running' started + ⚠️ Service 'running' is already running + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) +[`flox-services-stop(1)`](./flox-services-stop.md) diff --git a/docs/man/flox-services-status.md b/docs/man/flox-services-status.md new file mode 100644 index 00000000..f90078f5 --- /dev/null +++ b/docs/man/flox-services-status.md @@ -0,0 +1,81 @@ +--- +title: flox services status +description: Command reference for the `flox services status` command. +--- + +# `flox services status` command + +## NAME + +flox-services-status - display the status of services + +## SYNOPSIS + + flox [] services status + [-d= | -r=] + [--json] + [] ... + +## DESCRIPTION + +Displays the status of one or more services. + +If no services are specified, then all services will be displayed. If no +services have been started for this environment, an error will be +displayed. An error will also be displayed if one of the specified +services does not exist. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`--json` +Print statuses formatted as JSON. Each service is printed as a single +JSON object on its own line. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Display statuses for all services: + + $ flox services status + NAME STATUS PID + sleeping Running 89718 + myservice Running 12345 + +Display the status of a single service: + + $ flox services status myservice + NAME STATUS PID + myservice Running 12345 + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) +[`flox-services-start(1)`](./flox-services-start.md) diff --git a/docs/man/flox-services-stop.md b/docs/man/flox-services-stop.md new file mode 100644 index 00000000..26a77ccb --- /dev/null +++ b/docs/man/flox-services-stop.md @@ -0,0 +1,89 @@ +--- +title: flox services stop +description: Command reference for the `flox services stop` command. +--- + +# `flox services stop` command + +## NAME + +flox-services-stop - stop running services + +## SYNOPSIS + + flox [] services stop + [-d= | -r=] + [] ... + +## DESCRIPTION + +Stops the specified running services. + +If no services are specified, then all services will be stopped. If any +of the specified services are not currently running, a warning will be +displayed and the remaining services will be stopped. + +If any of the specified services do not exist, an error will be returned +and no services will be stopped. If an error is encountered while +stopping one of the specified services, the remaining services will +still be stopped a warning will be displayed for the services that +failed to stop, and a non-zero exit code will be returned. + +## OPTIONS + +`-d`, `--dir` +Path containing a .flox/ directory. + +`` +The name(s) of the services to stop. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES: + +Stop a running service named ‘server’: + + $ flox services stop server + +Stop all running services: + + $ flox services stop + +Attempt to stop a service that doesn’t exist: + + $ flox services stop myservice doesnt_exist + ❌ ERROR: Service 'doesnt_exist' not found. + +Attempt to stop a service that isn’t running: + + $ flox services stop running not_running + ⚠️ Service 'not_running' is not running + ✅ Service 'running' stopped + +## SEE ALSO + +[`flox-activate(1)`](./flox-activate.md) diff --git a/docs/man/flox-show.md b/docs/man/flox-show.md new file mode 100644 index 00000000..e057a6cf --- /dev/null +++ b/docs/man/flox-show.md @@ -0,0 +1,72 @@ +--- +title: flox show +description: Command reference for the `flox show` command. +--- + +# `flox show` command + +## NAME + +flox-show - show detailed information about a single package + +## SYNOPSIS + + flox [] show + +## DESCRIPTION + +Show detailed information about a single package. + +The default output includes the package description, name, and version. + +### Package names + +Packages are organized in a hierarchical structure such that certain +packages are found at the top level (e.g. `ripgrep`), and other packages +are found under package sets (e.g. `python310Packages.pip`). We call +this location within the catalog the “pkg-path”. + +The pkg-path is searched when you execute a `flox search` command. The +pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears +in your manifest after a `flox install`. + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +## OPTIONS + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +### Show Options + +`` +Package name to show details for. + +## EXAMPLES: + +Display detailed information about the `ripgrep` package: + + $ flox show ripgrep + ripgrep - A utility that combines the usability of The Silver Searcher with the raw speed of grep + ripgrep@13.0.0 + ripgrep@14.1.0 + +## SEE ALSO + +[`flox-search(1)`](./flox-search.md), +[`flox-install(1)`](./flox-install.md) diff --git a/docs/man/flox-uninstall.md b/docs/man/flox-uninstall.md new file mode 100644 index 00000000..6555b0a7 --- /dev/null +++ b/docs/man/flox-uninstall.md @@ -0,0 +1,67 @@ +--- +title: flox uninstall +description: Command reference for the `flox uninstall` command. +--- + +# `flox uninstall` command + +## NAME + +flox-uninstall - remove packages from an environment + +## SYNOPSIS + + flox [] (uninstall|rm) + [-d= | -r=] + + +## DESCRIPTION + +Uninstall packages from an environment. + +Just like package installation, package uninstallation is transactional. +See [`flox-install(1)`](./flox-install.md) for more details on +transactions. Requesting to uninstall multiple packages where at least +one of them was not previously installed will cause the transaction to +fail and no packages will be uninstalled. + +## OPTIONS + +### Remove Options + +`` +The install IDs or package paths of the packages to remove. If the +manifest contains both an install ID and a package with matching package +path, the install ID takes precedence. If the same package path is +installed under different install IDs, an error is returned. A package +path can optionally contain the original version constraint. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-install(1)`](./flox-install.md) diff --git a/docs/man/flox-update.md b/docs/man/flox-update.md new file mode 100644 index 00000000..5551202f --- /dev/null +++ b/docs/man/flox-update.md @@ -0,0 +1,91 @@ +--- +title: flox update +description: Command reference for the `flox update` command. +--- + +# `flox update` command +--- +title: flox update +description: Command reference for the `flox update` command. +--- + +# `flox update` command +--- +title: flox update +description: Command reference for the `flox update` command. +--- + +# `flox update` command + +> **Warning:** This command is **deprecated** and no longer supported + +## NAME + +flox-update - update the global base catalog or an environment’s base +catalog + +## SYNOPSIS + + flox [] update + [--global | (-d= | -r=/)] + +## DESCRIPTION + +Update an environment’s base catalog, or update the global base catalog +if `--global` is specified. + +The base catalog is a collection of packages used by various Flox +subcommands. + +The global base catalog provides packages for +[`flox-search(1)`](./flox-search.md) and +[`flox-show(1)`](./flox-show.md) when not using an environment, and it +is used to initialize an environment’s base catalog. + +An environment’s base catalog provides packages for +[`flox-search(1)`](./flox-search.md) and +[`flox-show(1)`](./flox-show.md) when using that environment, and it +provides packages for [`flox-install(1)`](./flox-install.md) and +[`flox-upgrade(1)`](./flox-upgrade.md). + +Note that updating an environment’s base catalog and upgrading packages +are two separate options. Upgrading packages will usually require +running an update command followed by a +[`flox-upgrade`](./flox-upgrade.md). + +## OPTIONS + +### Update Options + +`--global` +Update the global base catalog + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`flox-upgrade(1)`](./flox-upgrade.md) diff --git a/docs/man/flox-upgrade.md b/docs/man/flox-upgrade.md new file mode 100644 index 00000000..f4b9c3ec --- /dev/null +++ b/docs/man/flox-upgrade.md @@ -0,0 +1,76 @@ +--- +title: flox upgrade +description: Command reference for the `flox upgrade` command. +--- + +# `flox upgrade` command + +## NAME + +flox-upgrade - upgrade packages in an environment + +## SYNOPSIS + + flox [] upgrade + [-d= | -r=/] + [--dry-run] + []... + +## DESCRIPTION + +Upgrade packages in the environment. + +When no arguments are specified, all packages in the environment are +upgraded if possible. A package is upgraded if its version, build +configuration, or dependency graph changes. + +Packages to upgrade can be specified by group name. Packages without a +specified pkg-group in the manifest are placed in a group named +‘toplevel’. The packages in that group can be upgraded without updating +any other groups by passing ‘toplevel’ as the group name. + +A single package can only be specified to upgrade by ID if it is not in +a group with any other packages. + +See [`manifest.toml(5)`](./manifest.toml.md) for more on using +pkg-groups. + +## OPTIONS + +### Upgrade Options + +`--dry-run` +Show available upgrades but do not apply them. + +`` +Install ID or pkg-group to upgrade. + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--remote` +A remote environment on FloxHub, specified in the form `/`. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## SEE ALSO + +[`manifest.toml(5)`](./manifest.toml.md) diff --git a/docs/man/flox.md b/docs/man/flox.md new file mode 100644 index 00000000..4087f298 --- /dev/null +++ b/docs/man/flox.md @@ -0,0 +1,141 @@ +--- +title: flox +description: Command reference for the `flox` command. +--- + +# `flox` command + +## NAME + +flox - developer environments you can take with you + +## SYNOPSIS + + flox [] + [] + [] ... + +## DESCRIPTION + +Flox is a virtual environment and package manager all in one. + +With Flox you create environments that layer and provide dependencies +just where it matters, making them portable across the full software +lifecycle. + +### Command Line Completions + +Flox ships with command line completions for `bash`, `fish` and `zsh`. +These completions are installed alongside Flox. + +## OPTIONS + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +### Flox Options + +`--version` +Print `flox` version. + +## COMMANDS + +Flox commands are grouped into categories pertaining to local +development, sharing environments, and administration. + +### Local Development Commands + +`init` +Create an environment in the current directory. + +`activate` +Enter the environment, type `exit` to leave. + +`search` +Search for system or library packages to install. + +`show` +Show details about a single package. + +`install`, `i` +Install packages into an environment. + +`uninstall` +Uninstall installed packages from an environment. + +`edit` +Edit the declarative environment configuration file. + +`list`, ‘l’ +List packages installed in an environment. + +`delete` +Delete an environment. + +### Sharing Commands + +`push` +Send an environment to FloxHub. + +`pull` +Pull an environment from FloxHub. + +### Additional Commands + +`update` +Update an environment’s base catalog or update the global base catalog. + +`upgrade` +Upgrade packages in an environment. + +`config` +View and set configuration options. + +`auth` +FloxHub authentication commands. + +## ENVIRONMENT VARIABLES + +`$FLOX_DISABLE_METRICS` +Variable for disabling the collection/sending of metrics data. If set to +`true`, prevents Flox from submitting basic metrics information such as +a unique token and the subcommand issued. + +`$EDITOR`, `$VISUAL` +Override the default editor used for editing environment manifests and +commit messages. + +`$SSL_CERT_FILE`, `$NIX_SSL_CERT_FILE` +If set, overrides the path to the default Flox provided SSL certificate +bundle. Set `NIX_SSL_CERT_FILE` to only override packages built with +Nix, and otherwise set `SSL_CERT_FILE` to override the value for all +packages. + +See also: [Nix environment variables - +`NIX_SSL_CERT_FILE`](https://nixos.org/manual/nix/stable/installation/env-variables.html#nix_ssl_cert_file) + +## SEE ALSO + +[`flox-init`(1)](./flox-init.md), +[`flox-activate`(1)](./flox-activate.md), +[`flox-install`(1)](./flox-install.md), +[`flox-uninstall(1)`](./flox-uninstall.md), +[`flox-upgrade`(1)](./flox-upgrade.md), +[`flox-search`(1)](./flox-search.md), [`flox-show(1)`](./flox-show.md), +[`flox-edit`(1)](./flox-edit.md), +[`manifest-toml`(5)](./manifest.toml.md), +[`flox-list`(1)](./flox-list.md), [`flox-auth(1)`](./flox-auth.md), +[`flox-push`(1)](./flox-push.md), [`flox-pull`(1)](./flox-pull.md), +[`flox-delete`(1)](./flox-delete.md), +[`flox-config`(1)](./flox-config.md) diff --git a/docs/man/manifest.toml.md b/docs/man/manifest.toml.md new file mode 100644 index 00000000..7a47d92a --- /dev/null +++ b/docs/man/manifest.toml.md @@ -0,0 +1,736 @@ +--- +title: manifest.toml +description: Reference for the manifest.toml format. +--- + +# `manifest.toml` + +## NAME + +manifest.toml - declarative environment configuration format + +## SYNOPSIS + +The `manifest.toml` file is a declarative format for specifying the +packages installed in an environment, environment variables to make +available to the environment, a shell script to run upon activation of +the environment, and other options to change the behavior of the +environment. + +## DESCRIPTION + +Flox environments come with a declarative manifest in [TOML +format](https://toml.io/en/v1.0.0). An environment can be defined +entirely by this one file. The file is divided into just a few sections +that are represented as TOML tables: + +- [`[install]`](#install) +- [`[vars]`](#vars) +- [`[hook]`](#hook) +- [`[profile]`](#profile) +- [`[services]`](#services) +- [`[include]`](#include) +- [`[build]`](#build) +- [`[options]`](#options) +- \[`containerize`\] - see + [`flox-containerize(1)`](./flox-containerize.md) + +### `[install]` + +The `[install]` table is the core of the environment, specifying which +packages you’d like installed in the environment. An example of the +`[install]` table is shown below: + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +Since this is TOML, equivalent ways of writing this would be + +``` toml +[install] +ripgrep = { pkg-path = "ripgrep" } +pip = { pkg-path = "python310Packages.pip" } +``` + +or + + [install.ripgrep] + pkg-path = "ripgrep" + + [install.pip] + pkg-path = "python310Packages.pip" + +Flox will use the first format by default when automatically editing the +manifest. + +#### Package names + + + +Packages are organized in a hierarchical structure such that certain +packages are found at the top level (e.g. `ripgrep`), and other packages +are found under package sets (e.g. `python310Packages.pip`). We call +this location within the catalog the “pkg-path”. + +The pkg-path is searched when you execute a `flox search` command. The +pkg-path is what’s shown by `flox show`. Finally, the pkg-path appears +in your manifest after a `flox install`. + +``` toml +[install] +ripgrep.pkg-path = "ripgrep" +pip.pkg-path = "python310Packages.pip" +``` + +#### Package descriptors + +Each entry in the `[install]` table is a key-value pair. The key in the +key-value pair (e.g. `ripgrep`, `pip`) is referred to as an “install +ID”, and represents the name by which you will refer to a particular +package e.g. if you wanted to uninstall or upgrade the package. Install +IDs are inferred from the last attribute in the pkg-path, but may also +be specified either at install-time via the `-i` option or interactively +via [`flox-edit(1)`](./flox-edit.md). + +The value in the key-value pair is called a “package descriptor”. A +package is specified by a number of available options which are separate +from the install ID, so you are free to change them independently of one +another. This allows you to change package details while keeping a +stable install ID, for example upgrading from `gcc.pkg-path = "gcc12"` +to `gcc.pkg-path = "gcc13"`. + +Most package descriptors will be catalog descriptors, which allow +specifying packages from the Flox catalog. A second format, flake +descriptors, is also supported, which allows specifying software to +install from an arbitrary Nix flake. + +##### Catalog descriptors + +The full list of catalog descriptor options is: + + Descriptor ::= { + pkg-group = null | + , version = null | + , systems = null | [, ...] + , pkg-path = + , priority = null | + } + +Only `pkg-path` is required. + +By specifying some of these options you create a set of requirements +that the installed program must satisfy, otherwise installation will +fail. + +By default, all packages belong to the same `pkg-group`, which means +providing specific versions for two different packages can quickly lead +to installation failures. To avoid such failures, either give a looser +`version` constraint, or move one of the packages to a different package +group. + +Each option is described below: + +`pkg-group` +Marks a package as belonging to a pkg-group. + +The pkg-group is a collection of software that is known to work together +at a point in time. Adding packages to a pkg-group enables packages in +the pkg-group to share the same libraries and dependencies, which +ensures maximum compatibility and minimizes the size of the environment. + +Packages are marked as belonging to a pkg-group simply by setting this +option to the name of the pkg-group. Packages that do not have a +pkg-group specified belong to the same group. + +Multiple pkg-groups may resolve to the same version of the catalog. +Pkg-groups are upgraded as a unit, ensuring that the packages within the +pkg-group continue to work together. See +[`flox-upgrade(1)`](./flox-upgrade.md) for more details on how +pkg-groups and packages interact during upgrades. + +`version` +Requires that the package match either an exact version or a semver +range. + +The semantic version can be specified with the typical qualifiers such +as `^`, `>=`, etc. Semantic versions that do not specify all three +fields (`MAJOR.MINOR.PATCH`) will treat the unspecified fields as +wildcards. This instructs Flox to find the latest versions for those +fields. For example `version = "1.2"` would select the latest version in +the `1.2.X` series. + +`systems` +A list of systems on which to install this package. When omitted this +defaults to the same systems that the manifest specifies that it +supports via `options.systems`. + +`pkg-path` +The abbreviated location of a package within a catalog. A pkg-path is a +sequence of one or more attributes joined by a delimiter. For example, +both `ripgrep` and `python310Packages.pip` are pkg-paths. A pkg-path +that contains more than one attribute can be represented as either a +single string that contains a ‘.’-delimited sequence of the attributes, +or it can be represented as a TOML array of strings where each string is +an attribute. For example, both `"python310Packages.pip"` and +`["python310Packages", "pip"]` are equivalent for the `pkg-path` option. + +`priority` +A priority used to resolve file conflicts where lower values indicate +higher priority. + +Each package internally has `/bin`, `/man`, `/include`, and other +directories for the files they provide. These directories from all +packages in the environment are merged when building the environment. +Two packages that provide the same `/bin/foo` file cause a conflict, and +it’s ambiguous which file should ultimately be placed into the +environment. Such conflicts can be resolved by assigning different +priorities to the conflicting packages. + +The default priority is 5. Packages with a lower `priority` value will +take precedence over packages with higher `priority` values. + +##### Flake descriptors + +Flake descriptors allow installing software from an arbitrary Nix flake. + +The full list of flake descriptor options is: + + Descriptor ::= { + flake = + , systems = null | [, ...] + , priority = null | + } + +Only `flake` is required. `systems` and `priority` behave the same as +described above for catalog descriptors, and `flake` is described below: + +`flake` +Specifies a Nix flake installable, which Nix refers to as a flake output +attribute and documents at +https://nix.dev/manual/nix/2.17/command-ref/new-cli/nix#flake-output-attribute. +Flake installables are of the form `flakeref[#attrpath]`, where flakeref +is a flake reference and attrpath is an optional attribute path. + +Flox tries to use the same fallback behavior as Nix; if no attrpath is +specified, the flake is checked for containing +`packages.$system.default` or `defaultPackage.$system`. If an attrpath +is specified, it is checked whether `packages.$system.$attrpath` or +`legacyPackages.$system.$attrpath` exist. + +##### Store paths + +Store path descriptors allow installing software from an arbitrary Nix +store path. + +The full list of store path descriptor options is: + + Descriptor ::= { + store-path = STRING + , systems = null | [, ...] + , priority = null | + } + +Only `store-path` is required. `priority` behaves the same as described +above for catalog descriptors and flake installables, and `store-path` +is described below: + +`store-path` +Specifies a nix store path, i.e. a nix built package in `/nix/store`. +This can be the result of a native Nix operations such as `nix build`, +`nix copy`, etc. The store path has to be available on the current +system in order to build the environment. The environment will fail to +build on other systems without first distributing the store path via Nix +tooling. As such, this feature is most suitable for local experiments +and ad-hoc interoperability with Nix. + +`system` +Behaves equally to the system attribute of catalog descriptors and +flakes installables. Unlike the former, users are encouraged to specify +it, because store paths are generally system dependent. + +### `[vars]` + +The `[vars]` section allows you to define environment variables for your +environment that are set during environment activation. The environment +variables specified here cannot reference one another. The names and +values of the environment variables are copied verbatim into the +activation script, so capitalization will be preserved. + +Example: + +``` toml +[vars] +DB_URL = "http://localhost:2000" +SERVER_PORT = "3000" +``` + +### `[hook]` + +The `on-activate` script in the `[hook]` section is useful for +performing initialization in a predictable Bash shell environment. + +#### `on-activate` + +The `on-activate` script is sourced from a **bash** shell, and it can be +useful for spawning processes, dynamically setting environment +variables, and creating files and directories to be used by the +subsequent profile scripts, commands, and shells. + +Hook scripts inherit environment variables set in the `[vars]` section, +and variables set here will in turn be inherited by the `[profile]` +scripts described below. + +Any output written to `stdout` in a hook script is redirected to +`stderr` to avoid it being mixed with the output of profile section +scripts that write to `stdout` for “in-place” activations. + +``` toml +[hook] +on-activate = """ + # Interact with the tty as you would in any script + echo "Starting up $FLOX_ENV_DESCRIPTION environment ..." + read -e -p "Favourite colour or favorite color? " value + + # Set variables, create files and directories + venv_dir="$(mktemp -d)" + export venv_dir + + # Perform initialization steps, e.g. create a python venv + python -m venv "$venv_dir" + + # Invoke apps that configure the environment via stdout + eval "$(ssh-agent)" +""" +``` + +The `on-activate` script is not re-run when multiple activations are run +at the same time; for instance, if `flox activate` is run in two +different shells, the first activation will run the hook, but the second +will not. After all activations exit, the next `flox activate` will once +again run the hook. Currently, environment variables set by the first +run of the `on-activate` script are captured and then set by activations +that don’t run `on-activate`, but this behavior may change. + +The `on-activate` script may be re-run by other `flox` commands; we may +create ephemeral activations and thus run the script multiple times for +commands such as `services start`. For this reason, it’s best practice +to make `on-activate` idempotent. However, the environment of your +current shell is only affected by the initial run of the script for the +first activation for your shell. + +It’s also best practice to write hooks defensively, assuming the user is +using the environment from any directory on their machine. + +#### `script` - DEPRECATED + +This field was deprecated in favor of the `profile` section. + +### `[profile]` + +Scripts defined in the `[profile]` section are sourced by *your shell* +and inherit environment variables set in the `[vars]` section and by the +`[hook]` scripts. The `profile.common` script is sourced for every +shell, and special care should be taken to ensure compatibility with all +shells, after which exactly one of `profile.{bash,fish,tcsh,zsh}` is +sourced by the corresponding shell. + +These scripts are useful for performing shell-specific customizations +such as setting aliases or configuring the prompt. + +``` toml +[profile] +common = """ + echo "it's gettin' flox in here" +""" +bash = """ + source $venv_dir/bin/activate + alias foo="echo bar" + set -o vi +""" +zsh = """ + source $venv_dir/bin/activate + alias foo="echo bar" + bindkey -v +""" +fish = """ + source $venv_dir/bin/activate.fish + alias foo="echo bar" + fish_vi_key_bindings +""" +``` + +Profile scripts are re-run for nested activations. A nested activation +can occur when an environment is already active and either +`eval "$(flox activate)"` or `flox activate -- CMD` is run. In this +scenario, profile scripts are run a second time. Re-running profile +scripts allows aliases to be set in subshells that inherit from a parent +shell with an already active environment. + +### `[services]` + +The `[services]` section of the manifest allows you to describe the +services you would like to run as part of your environment e.g. a web +server or a database. The services you define here use the packages +provided by the `[install]` section and any variables you’ve defined in +the `[vars]` section or `hook.on-activate` script. + +The `[services]` section is a table of key-value pairs where the keys +determine the service names, and the values (service descriptors) +determine how to configure and run the services. + +An example service definition is shown below: + +``` toml +[services.database] +command = "postgres start" +vars.PGUSER = "myuser" +vars.PGPASSWORD = "super-secret" +vars.PGDATABASE = "mydb" +vars.PGPORT = "9001" +``` + +This would define a service called `database` that configures and starts +a PostgreSQL database. + +The full set of options is show below: + + ServiceDescriptor ::= { + command = STRING + , vars = null | Map[STRING, STRING] + , is-daemon = null | BOOL + , shutdown = null | Shutdown + , systems = null | [, ...] + } + + Shutdown ::= { + command = STRING + } + +`command` +The command to run (interpreted by a Bash shell) to start the service. +This command can use any environment variables that were set in the +`[vars]` section, the `hook.on-activate` script, or the service-specific +`vars` table. + +`vars` +A table of environment variables to set for the invocation of this +specific service. Nothing outside of this service will observe these +environment variables. + +`is-daemon` +Whether this service spawns a daemon when it starts. Some commands start +a background process and then terminate instead of themselves running +for an extended period of time. The underlying process manager cannot +track the PID of the daemon that is spawned, only the PID of the process +that *spawned* the daemon. For this reason you must set the `is-daemon` +option to `true`, otherwise `flox services status` will show that the +service has terminated even though the daemon may still be running. +Furthermore, since the process manager doesn’t know the PID of the +daemon itself, it cannot deliver a shutdown signal to the daemon. For +this reason you must *also* provide the `shutdown.command` option so +that the process manager knows what command to run to shut down the +daemon. Failure to set both `is-daemon` and `shutdown.command` will +allow the daemon to continue running even after running +`flox services stop` or exiting the last activation of the environment. + +`shutdown.command` +A command to run to shut down the service instead of delivering the +SIGTERM signal to the process. Some programs require special handling to +shut down properly e.g. a program that spawns a server process and uses +a client to tell the server to shut down. Sending a SIGTERM to a client +in that case may not shut down the server. In those cases you may +provide a specific shutdown command to run instead of relying on the +default behavior of sending a SIGTERM to the service. This field is +required if the `is-daemon` field is `true`. + +`systems` +An optional list of systems on which to run this service. If omitted, +the service is not restricted. + +### `[include]` + +The `[include]` section of the manifest describes other environments +that you’d like to merge with the current manifest in order to compose +them into a single environment. + +The list of environments to include is specified by the +`include.environments` array. The order of the “include descriptors” in +this array specifies the priority that should be used when merging the +manifests. Descriptors later in the array take higher priority than +those earlier in the array, and manifest fields in the composing +manifest take the highest priority. + +The merged manifest can be viewed with `flox list --config`. + +#### Syntax + +An example `[include]` section is shown below: + +``` toml +[include] +environments = [ + { dir = "../path/to/env" }, + { dir = "../path/to/other/env", name = "myenv" } +] +``` + +As mentioned above, you include other environments my listing them as an +array of tables in the `include.environments` array. The schema for +these “include descriptors” is shown below: + + IncludeDescriptor ::= LocalIncludeDescriptor | RemoteIncludeDescriptor + + LocalIncludeDescriptor :: = { + dir = STRING + , name = null | STRING + } + + RemoteIncludeDescriptor :: = { + remote = STRING + , name = null | STRING + } + +The fields in these include descriptors are as follows: + +`dir` +The local path to the environment to include. This has the same +semantics as the `--dir` flag passed to many Flox commands. + +`remote` +The remote name of an environment to include. This has the same +semantics as the `--remote` flag passed to many Flox commands. + +`name` +An optional override to the name of the included environment. This is +useful when you are including multiple environments that have the same +name, or when you want to provide a more convenient name for the +included environment. + +Changes to the included environments aren’t automatically reflected in +the composing environment. You control when updates are pulled in by +using [`flox include upgrade`](./flox-include-upgrade.md). + +#### Merge semantics + +When merging manifests, different sections have different merge +semantics. As mentioned above, the order in which include descriptors +are listed in the `include.environments` array determines the priority +of the manifests, with the composing manifest having the highest +priority. In the following discussion we refer to “lower priority +manifests” and “higher priority manifests” as those being listed earlier +or later in the array, respectively. + +As of right now there is no way to *remove* something from a lower +priority manifest, but things can be overridden or added by higher +priority manifests. + +`[install]` +Package descriptors are overwritten entirely by a higher priority +manifest. + +`[vars]` +Variables are overwritten entirely by a higher priority manifest. + +`[hook]` +The scripts in `hook` are appended to one another with a newline in +between. Scripts from higher priority manifests come after those from +lower priority manifests. + +`[profile]` +The scripts in the `profile` section are appended in the same way that +they are for `hook`. + +`[services]` +Service descriptors are entirely overwritten by higher priority +manifests + +`[include]` +The `include` section is omitted from merged manifests, so no merging of +the `include` section ever happens. + +`[containerize]` +The `containerize.config` field is deep merged, meaning that individual +fields of `containerize.config` are merged rather than +`containerize.config` being completely overwritten. The fields within +`containerize.config` are merged as follows: `user`, `cmd`, +`working_dir`, and `stop_signal` are overwritten; `labels` and +`exposed_ports` are merged via the union of the values in the high +priority and low priority manifests. + +`[options]` +The `options` section is also deep merged, meaning that individual +fields of the `options` section are merged rather than being completely +overwritten. All of the fields in the `options` section are individually +overwritten by higher priority manifests e.g. `options.allow.broken` is +individually overwritten by a higher priority manifest, as is +`options.allow.licenses`, etc. + +This has implications for the activation mode of a composed environment. +Since the default activation mode is `dev`, it is not present in the +manifest by default. This means that if one included environment sets +`options.activate.mode` to `run`, the merged manifest will also have +`options.activate.mode = run` unless a higher priority manifest +explicitly sets `options.activate.mode = dev`. + +### `[build]` + +The `[build]` section of the manifest allows you to describe build +instructions for custom packages that can be built using `flox build`. + +The build commands use the packages provided by the `[install]` section +and any variables defined in the `[vars]` section or `hook.on-activate` +script. + +The `[build]` section is a table of key-value pairs where the keys +determine the package names, and the values (build descriptors) +determine how to build the package. + +An example build definition is shown below: + +``` toml +[build.hello] +command = ''' +mkdir -p $out +echo 'Hello, World!' >> $out/hello.txt +''' +``` + +This would define a package called `hello` that produces a single file +`hello.txt` containing the string `"Hello, World!"`. See `flox-build(1)` +for more details. + +The full set of options is shown below: + + BuildDescriptor ::= { + command = STRING + , sandbox = null | ("off" | "pure") + , version = null | STRING | VersionFile | VersionCommand + , description = null | STRING + , runtime-packages = null | [, ...] + } + + VersionFile ::= { + file = STRING + } + + VersionCommand ::= { + command = STRING + } + +`command` +The command to run (interpreted by a Bash shell) to build the package. +This command can use any environment variables that were set in the +`[vars]` section, or the `hook.on-activate` script. + +`sandbox` +The level of sandboxing applied to the build. When set to `"off"`, the +build is executed in a subshell of the current shell and is similar to +running the commands manually in a subshell created by `flox activate`. +When set to `"pure"`, the build will be unable to make network +connections and can only access to the files currently under version +control. Consequently, `"pure"` builds require your project to be under +`git` version control. + +`version` +The version to attach to this build artifact. This may be specifed in +one of the following ways: + +1. **as a string**: `version = "0.0.1"` +2. **as read from a file**: `version.file = ""` +3. **as returned by a command**: `version.command = " "` + +`description` +The description string to attach to this build artifact. + +`runtime-packages` +A list of install IDs from the `[install]` section of the manifest, used +to restrict what dependencies are provided to the built package at +runtime. By default all packages from the default package group are +included as runtime dependencies. If this option is specified, only the +listed packages are included. + +### `[options]` + +The `[options]` section of the manifest details settings for the +environment itself. + +The full set of options are listed below: + + Options ::= { + systems = null | [, ...] + , activate = null | Activate + , allow = null | Allows + , semver = null | Semver + , cuda-detection = null | + } + + Activate ::= { + mode = null | 'dev' | 'run' + } + + Allows ::= { + unfree = null | + , broken = null | + , licenses = null | [, ...] + } + + Semver ::= { + allow-pre-releases = + } + +`systems` +The allowlist of systems that this environment supports. Valid values +are `x86_64-linux`, `aarch64-linux`, `x86_64-darwin`, and +`aarch64-darwin`. [`flox init`](./flox-init.md) automatically populates +this list with the current system type. A user that attempts to pull an +environment from FloxHub when their environment isn’t explicitly +supported will be prompted whether to automatically add their system to +this list. See [`flox-pull(1)`](./flox-pull.md) for more details. + +`activate.mode` +Whether to activate in “dev” (default) or “run” mode. This value can be +overridden with `flox activate --mode`. + +In “dev” mode a package, all of its development dependencies, and +language specific environment variables are made available. As the name +implies, this is useful at development time. However, this may causes +unexpected failures when layering environments or when activating an +environment system-wide. + +In “run” mode only the requested packages are made available in `PATH` +(and their man pages made available). This behavior is more in line with +what you would expect from a system-wide package manager like `apt`, +`yum`, or `brew`. + +`allow.unfree` +Allows packages with unfree licenses to be installed and appear in +search results. The default is `false`. + +`allow.broken` +Allows packages that are marked `broken` in the catalog to be installed +and appear in search results. The default is `false`. + +`allow.licenses` +An allowlist of software licenses to allow in search results in +installs. Valid entries are [SPDX +Identifiers](https://spdx.org/licenses). An empty list allows all +licenses. + +`semver.allow-pre-releases` +Whether to allow pre-release software for package installations. The +default is `false`. Setting this value to `true` would allow a package +version `4.2.0-pre` rather than `4.1.9`. + +`cuda-detection` +Whether to detect CUDA libraries and provide them to the environment. +The default is `true`. When enabled, Flox will detect if you have an +Nvidia device and attempt to locate `libcuda` in well-known paths. + +## SEE ALSO + +[`flox-init(1)`](./flox-init.md), +[`flox-install(1)`](./flox-install.md), [`flox-edit(1)`](./flox-edit.md) +[`flox-build(1)`](./flox-build.md) diff --git a/docs/tutorials/migrations/homebrew.md b/docs/migrations/homebrew.md similarity index 100% rename from docs/tutorials/migrations/homebrew.md rename to docs/migrations/homebrew.md diff --git a/docs/tutorials/migrations/nvm.md b/docs/migrations/nvm.md similarity index 100% rename from docs/tutorials/migrations/nvm.md rename to docs/migrations/nvm.md diff --git a/mkdocs.yml b/mkdocs.yml index fa3cc4c3..1d0074fc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -37,20 +37,21 @@ nav: - Install: install-flox/install.md - Uninstall: install-flox/uninstall.md - Flox in 5 minutes: flox-5-minutes.md - - Tutorials: - - Creating environments: tutorials/creating-environments.md - - The default environment: tutorials/default-environment.md - - Sharing environments: tutorials/sharing-environments.md - - Layering multiple environments: tutorials/layering-multiple-environments.md - - Customizing the shell environment: tutorials/customizing-environments.md - - Designing multi-arch environments: tutorials/multi-arch-environments.md - - Building and publishing packages: tutorials/build-and-publish.md - - Running Flox in CI/CD: tutorials/ci-cd.md - - Designing cross-platform environments: tutorials/multi-arch-environments.md - - Reusing and combining developer environments: tutorials/composition.md - - Migration guides: - - ... | flat | tutorials/migrations/* - - Concepts: + - Guides: + - Getting started: + - Creating environments: tutorials/creating-environments.md + - The default environment: tutorials/default-environment.md + - Sharing environments: tutorials/sharing-environments.md + - Customizing the shell environment: tutorials/customizing-environments.md + - Designing cross-platform environments: tutorials/multi-arch-environments.md + - Going deeper: + - Layering multiple environments: tutorials/layering-multiple-environments.md + - Building and publishing packages: tutorials/build-and-publish.md + - Running Flox in CI/CD: tutorials/ci-cd.md + - Reusing and combining developer environments: tutorials/composition.md + - Languages: + - ... | flat | cookbook/languages/* + - Explanations: - Environments: concepts/environments.md - Activating environments: concepts/activation.md - FloxHub: concepts/floxhub.md @@ -63,14 +64,13 @@ nav: - Manifest builds: concepts/manifest-builds.md - Nix expression builds: concepts/nix-expression-builds.md - Publishing: concepts/publishing.md - - Flox vs. container workflows: concepts/flox-vs-containers.md - - Cookbook: - - Languages: - - ... | flat | cookbook/languages/* - - Reference: - - Flox manual: - - reference/command-reference/flox.md - - ... | flat | reference/command-reference/* + - Comparisons: + - Containers: concepts/flox-vs-containers.md + - Migration guides: + - ... | flat | tutorials/migrations/* + - Manual pages: + - reference/command-reference/flox.md + - ... | flat | reference/command-reference/* strict: true validation: diff --git a/sitemap_old.xml b/sitemap_old.xml new file mode 100644 index 00000000..902ab3f7 --- /dev/null +++ b/sitemap_old.xml @@ -0,0 +1,323 @@ + + + + https://flox.dev/docs/ + 2025-06-13 + daily + + + https://flox.dev/docs/flox-5-minutes/ + 2025-06-13 + daily + + + https://flox.dev/docs/install-flox/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/activation/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/composition/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/environments/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/flox-vs-containers/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/floxhub/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/generations/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/manifest-builds/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/organizations/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/packages-and-catalog/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/publishing/ + 2025-06-13 + daily + + + https://flox.dev/docs/concepts/services/ + 2025-06-13 + daily + + + https://flox.dev/docs/cookbook/languages/c/ + 2025-06-13 + daily + + + https://flox.dev/docs/cookbook/languages/go/ + 2025-06-13 + daily + + + https://flox.dev/docs/cookbook/languages/jvm/ + 2025-06-13 + daily + + + https://flox.dev/docs/cookbook/languages/nodejs/ + 2025-06-13 + daily + + + https://flox.dev/docs/cookbook/languages/python/ + 2025-06-13 + daily + + + https://flox.dev/docs/cookbook/languages/ruby/ + 2025-06-13 + daily + + + https://flox.dev/docs/cookbook/languages/rust/ + 2025-06-13 + daily + + + https://flox.dev/docs/cookbook/publish/catalog-store/ + 2025-06-13 + daily + + + https://flox.dev/docs/cookbook/publish/signing-keys/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-activate/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-auth/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-build-clean/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-build/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-config/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-containerize/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-delete/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-edit/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-envs/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-gc/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-include-upgrade/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-init/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-install/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-list/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-publish/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-pull/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-push/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-search/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-services-logs/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-services-restart/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-services-start/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-services-status/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-services-stop/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-show/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-uninstall/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-update/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox-upgrade/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/flox/ + 2025-06-13 + daily + + + https://flox.dev/docs/reference/command-reference/manifest.toml/ + 2025-06-13 + daily + + + https://flox.dev/docs/snippets/paid-feature/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/build-and-publish/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/ci-cd/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/composition/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/creating-environments/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/customizing-environments/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/default-environment/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/layering-multiple-environments/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/multi-arch-environments/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/sharing-environments/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/migrations/homebrew/ + 2025-06-13 + daily + + + https://flox.dev/docs/tutorials/migrations/nvm/ + 2025-06-13 + daily + + \ No newline at end of file From 6db88e63d646535893fd2b5169985c75ab26d749 Mon Sep 17 00:00:00 2001 From: Zach Mitchell Date: Tue, 26 Aug 2025 13:52:39 -0600 Subject: [PATCH 2/5] wip: fix sidebar links --- mkdocs.yml | 52 ++++++++++++++++++++++++++-------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 1d0074fc..59715f30 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,38 +39,38 @@ nav: - Flox in 5 minutes: flox-5-minutes.md - Guides: - Getting started: - - Creating environments: tutorials/creating-environments.md - - The default environment: tutorials/default-environment.md - - Sharing environments: tutorials/sharing-environments.md - - Customizing the shell environment: tutorials/customizing-environments.md - - Designing cross-platform environments: tutorials/multi-arch-environments.md + - Creating environments: guides/getting-started/creating-environments.md + - The default environment: guides/getting-started/default-environment.md + - Sharing environments: guides/getting-started/sharing-environments.md + - Customizing the shell environment: guides/getting-started/customizing-environments.md + - Designing cross-platform environments: guides/getting-started/multi-arch-environments.md - Going deeper: - - Layering multiple environments: tutorials/layering-multiple-environments.md - - Building and publishing packages: tutorials/build-and-publish.md - - Running Flox in CI/CD: tutorials/ci-cd.md - - Reusing and combining developer environments: tutorials/composition.md + - Layering multiple environments: guides/going-deeper/layering-multiple-environments.md + - Building and publishing packages: guides/going-deeper/build-and-publish.md + - Running Flox in CI/CD: guides/going-deeper/ci-cd.md + - Reusing and combining developer environments: guides/going-deeper/composition.md - Languages: - - ... | flat | cookbook/languages/* + - ... | flat | languages/* - Explanations: - - Environments: concepts/environments.md - - Activating environments: concepts/activation.md - - FloxHub: concepts/floxhub.md - - Generations: concepts/generations.md - - Catalog and Packages: concepts/packages-and-catalog.md - - Services: concepts/services.md - - Composing environments: concepts/composition.md - - Organizations: concepts/organizations.md - - Builds: concepts/builds.md - - Manifest builds: concepts/manifest-builds.md - - Nix expression builds: concepts/nix-expression-builds.md - - Publishing: concepts/publishing.md + - Environments: explanations/environments.md + - Activating environments: explanations/activation.md + - FloxHub: explanations/floxhub.md + - Generations: explanations/generations.md + - Catalog and Packages: explanations/packages-and-catalog.md + - Services: explanations/services.md + - Composing environments: explanations/composition.md + - Organizations: explanations/organizations.md + - Builds: explanations/builds.md + - Manifest builds: explanations/manifest-builds.md + - Nix expression builds: explanations/nix-expression-builds.md + - Publishing: explanations/publishing.md - Comparisons: - - Containers: concepts/flox-vs-containers.md + - Containers: comparisons/flox-vs-containers.md - Migration guides: - - ... | flat | tutorials/migrations/* + - ... | flat | migrations/* - Manual pages: - - reference/command-reference/flox.md - - ... | flat | reference/command-reference/* + - man/flox.md + - ... | flat | man/* strict: true validation: From f72b69055cf52035afeb4a99d35274bd87b6825c Mon Sep 17 00:00:00 2001 From: Zach Mitchell Date: Tue, 26 Aug 2025 13:31:19 -0600 Subject: [PATCH 3/5] fix: links to man pages --- docs/comparisons/flox-vs-containers.md | 14 +++++----- docs/explanations/activation.md | 8 +++--- docs/explanations/builds.md | 2 +- docs/explanations/environments.md | 20 +++++++------- docs/explanations/floxhub.md | 14 +++++----- docs/explanations/generations.md | 8 +++--- docs/explanations/manifest-builds.md | 4 +-- docs/explanations/nix-expression-builds.md | 2 +- docs/explanations/packages-and-catalog.md | 8 +++--- docs/explanations/publishing.md | 10 +++---- docs/explanations/services.md | 2 +- docs/flox-5-minutes.md | 24 ++++++++--------- .../getting-started/creating-environments.md | 12 ++++----- .../customizing-environments.md | 6 ++--- .../getting-started/default-environment.md | 6 ++--- .../multi-arch-environments.md | 10 +++---- .../getting-started/sharing-environments.md | 10 +++---- docs/guides/going-deeper/build-and-publish.md | 14 +++++----- docs/guides/going-deeper/ci-cd.md | 2 +- docs/guides/going-deeper/composition.md | 10 +++---- .../layering-multiple-environments.md | 8 +++--- docs/index.md | 26 +++++++++---------- docs/migrations/homebrew.md | 12 ++++----- docs/migrations/nvm.md | 2 +- 24 files changed, 117 insertions(+), 117 deletions(-) diff --git a/docs/comparisons/flox-vs-containers.md b/docs/comparisons/flox-vs-containers.md index 8d0379b1..dd95c7d5 100644 --- a/docs/comparisons/flox-vs-containers.md +++ b/docs/comparisons/flox-vs-containers.md @@ -439,13 +439,13 @@ you need to build a container so that it can be deployed. --- -[init]: ../reference/command-reference/flox-init.md -[edit]: ../reference/command-reference/flox-edit.md -[install]: ../reference/command-reference/flox-install.md -[push]: ../reference/command-reference/flox-push.md -[containerize]: ../reference/command-reference/flox-containerize.md -[activate]: ../reference/command-reference/flox-activate.md -[services-start]: ../reference/command-reference/flox-services-start.md +[init]: ../man/flox-init.md +[edit]: ../man/flox-edit.md +[install]: ../man/flox-install.md +[push]: ../man/flox-push.md +[containerize]: ../man/flox-containerize.md +[activate]: ../man/flox-activate.md +[services-start]: ../man/flox-services-start.md [services]: ../concepts/services.md [manifest]: ../concepts/environments.md#manifesttoml [early]: https://flox.dev/early/ diff --git a/docs/explanations/activation.md b/docs/explanations/activation.md index c0b26f03..e26d693d 100644 --- a/docs/explanations/activation.md +++ b/docs/explanations/activation.md @@ -310,7 +310,7 @@ attach to this new version of the environment. ## Development vs. runtime mode -See the [`options.activate.mode`](../reference/command-reference/manifest.toml.md#options) option in the manifest. +See the [`options.activate.mode`](../man/manifest.toml.md#options) option in the manifest. ## Conclusion @@ -329,6 +329,6 @@ that prepare your environment just how you like them. [environment-concept]: ./services.md [bash-func-export]: https://www.gnu.org/software/bash/manual/html_node/Bourne-Shell-Builtins.html#index-export -[vars-section]: ../reference/command-reference/manifest.toml.md#vars -[hook-section]: ../reference/command-reference/manifest.toml.md#hook -[profile-section]: ../reference/command-reference/manifest.toml.md#profile +[vars-section]: ../man/manifest.toml.md#vars +[hook-section]: ../man/manifest.toml.md#hook +[profile-section]: ../man/manifest.toml.md#profile diff --git a/docs/explanations/builds.md b/docs/explanations/builds.md index 5af89062..7207d351 100644 --- a/docs/explanations/builds.md +++ b/docs/explanations/builds.md @@ -42,5 +42,5 @@ One way to accomplish this is to run your builds in [CI][flox-ci-cd]. [manifest-builds-concept]: ./manifest-builds.md [nix-expression-builds-concept]: ./nix-expression-builds.md -[flox-build]: ../reference/command-reference/flox-build.md +[flox-build]: ../man/flox-build.md [flox-ci-cd]: ../tutorials/ci-cd.md diff --git a/docs/explanations/environments.md b/docs/explanations/environments.md index e9e99acc..8ee2be82 100644 --- a/docs/explanations/environments.md +++ b/docs/explanations/environments.md @@ -110,21 +110,21 @@ version. Flox manages this file for you. } ``` -[flox_init]: ../reference/command-reference/flox-init.md -[flox_show]: ../reference/command-reference/flox-show.md -[flox_edit]: ../reference/command-reference/flox-edit.md -[flox_install]: ../reference/command-reference/flox-install.md -[flox_search]: ../reference/command-reference/flox-search.md -[flox_edit]: ../reference/command-reference/flox-edit.md -[flox_push]: ../reference/command-reference/flox-push.md -[flox_pull]: ../reference/command-reference/flox-pull.md -[flox_activate]: ../reference/command-reference/flox-activate.md +[flox_init]: ../man/flox-init.md +[flox_show]: ../man/flox-show.md +[flox_edit]: ../man/flox-edit.md +[flox_install]: ../man/flox-install.md +[flox_search]: ../man/flox-search.md +[flox_edit]: ../man/flox-edit.md +[flox_push]: ../man/flox-push.md +[flox_pull]: ../man/flox-pull.md +[flox_activate]: ../man/flox-activate.md [sharing_guide]: ../tutorials/sharing-environments.md [create_guide]: ../tutorials/creating-environments.md [customizing_environments_guide]: ../tutorials/customizing-environments.md [generation_concept]: ./generations.md [floxhub_concept]: ./floxhub.md [discourse]: https://discourse.flox.dev/ -[manifest]: ../reference/command-reference/manifest.toml.md +[manifest]: ../man/manifest.toml.md [nix-expression-builds-concept]: ./nix-expression-builds.md [toml_spec]: https://toml.io/en/v1.0.0 diff --git a/docs/explanations/floxhub.md b/docs/explanations/floxhub.md index 948a3f8a..bfbd7162 100644 --- a/docs/explanations/floxhub.md +++ b/docs/explanations/floxhub.md @@ -97,13 +97,13 @@ flox pull example-owner/example-env Run the [`flox auth logout`][flox_auth] command. [flox_website]: https://flox.dev -[flox_push]: ../reference/command-reference/flox-push.md -[flox_pull]: ../reference/command-reference/flox-pull.md -[flox_activate]: ../reference/command-reference/flox-activate.md -[flox_auth]: ../reference/command-reference/flox-auth.md -[flox_edit]: ../reference/command-reference/flox-edit.md -[flox_install]: ../reference/command-reference/flox-install.md -[flox_uninstall]: ../reference/command-reference/flox-uninstall.md +[flox_push]: ../man/flox-push.md +[flox_pull]: ../man/flox-pull.md +[flox_activate]: ../man/flox-activate.md +[flox_auth]: ../man/flox-auth.md +[flox_edit]: ../man/flox-edit.md +[flox_install]: ../man/flox-install.md +[flox_uninstall]: ../man/flox-uninstall.md [generation_concept]: ../concepts/generations.md [manifest_concept]: ../concepts/environments.md#manifesttoml [environments_concept]: ../concepts/environments.md diff --git a/docs/explanations/generations.md b/docs/explanations/generations.md index 6209e147..64b763c8 100644 --- a/docs/explanations/generations.md +++ b/docs/explanations/generations.md @@ -79,9 +79,9 @@ This allows this environment to advance to newer generations explicitly on the next [`flox pull`][flox_pull]. [floxhub_concept]: .//floxhub.md -[flox_push]: ../reference/command-reference/flox-push.md -[flox_install]: ../reference/command-reference/flox-install.md -[flox_edit]: ../reference/command-reference/flox-edit.md -[flox_pull]: ../reference/command-reference/flox-pull.md +[flox_push]: ../man/flox-push.md +[flox_install]: ../man/flox-install.md +[flox_edit]: ../man/flox-edit.md +[flox_pull]: ../man/flox-pull.md [sharing_guide]: ../tutorials/sharing-environments.md [environment_guide]: ../tutorials/creating-environments.md diff --git a/docs/explanations/manifest-builds.md b/docs/explanations/manifest-builds.md index ff57f98b..bfa649b1 100644 --- a/docs/explanations/manifest-builds.md +++ b/docs/explanations/manifest-builds.md @@ -190,11 +190,11 @@ Each language guide in the Languages section of the Cookbook contains an example For example, [this section][go-example] contains an example build for the Go language. [builds-concept]: ./builds.md -[manifest-reference]: ../reference/command-reference/manifest.toml.md#build +[manifest-reference]: ../man/manifest.toml.md#build [services-concept]: ./services.md [publish-concept]: ./publishing.md [fhs-docs]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard -[pkg-groups]: ../reference/command-reference/manifest.toml.md#package-descriptors +[pkg-groups]: ../man/manifest.toml.md#package-descriptors [grpc]: https://grpc.io/ [organizations-concept]: ./organizations.md [go-example]: ../cookbook/languages/go.md#build-with-flox diff --git a/docs/explanations/nix-expression-builds.md b/docs/explanations/nix-expression-builds.md index 80820f10..b8082d6c 100644 --- a/docs/explanations/nix-expression-builds.md +++ b/docs/explanations/nix-expression-builds.md @@ -242,4 +242,4 @@ error: hash mismatch in fixed-output derivation '/nix/store/srm7s6pyckifs52ikyfa [builds-concept]: ./builds.md [manifest-builds-concept]: ./manifest-builds.md -[pkg-groups]: ../reference/command-reference/manifest.toml.md#package-descriptors +[pkg-groups]: ../man/manifest.toml.md#package-descriptors diff --git a/docs/explanations/packages-and-catalog.md b/docs/explanations/packages-and-catalog.md index 1bb81476..d41e993b 100644 --- a/docs/explanations/packages-and-catalog.md +++ b/docs/explanations/packages-and-catalog.md @@ -38,10 +38,10 @@ Source by the Open Source Initiative (OSI). * **broken**: indicates if the package is marked as broken in [nixpkgs][nixpkgs]. -[flox_search]: ../reference/command-reference/flox-search.md -[flox_show]: ../reference/command-reference/flox-show.md -[flox_install]: ../reference/command-reference/flox-install.md -[flox_update]: ../reference/command-reference/flox-update.md +[flox_search]: ../man/flox-search.md +[flox_show]: ../man/flox-show.md +[flox_install]: ../man/flox-install.md +[flox_update]: ../man/flox-update.md [manifest_concept]: ./environments.md#manifesttoml [nixpkgs]: https://github.com/NixOS/nixpkgs [builds]: ./builds.md diff --git a/docs/explanations/publishing.md b/docs/explanations/publishing.md index a2f1c8ba..31f34b8a 100644 --- a/docs/explanations/publishing.md +++ b/docs/explanations/publishing.md @@ -75,9 +75,9 @@ This means that individual users will not be able to share packages they've publ [builds-concept]: ./builds.md [catalog-concept]: ./packages-and-catalog.md -[flox-build]: ../reference/command-reference/flox-build.md -[flox-publish]: ../reference/command-reference/flox-publish.md -[flox-search]: ../reference/command-reference/flox-search.md -[flox-show]: ../reference/command-reference/flox-show.md -[flox-install]: ../reference/command-reference/flox-install.md +[flox-build]: ../man/flox-build.md +[flox-publish]: ../man/flox-publish.md +[flox-search]: ../man/flox-search.md +[flox-show]: ../man/flox-show.md +[flox-install]: ../man/flox-install.md [organizations-concept]: ./organizations.md diff --git a/docs/explanations/services.md b/docs/explanations/services.md index f627063c..431ce03f 100644 --- a/docs/explanations/services.md +++ b/docs/explanations/services.md @@ -28,7 +28,7 @@ Services have a very simple schema consisting of a `command` to run to start the service, any `vars` you want set specifically for the service, and whether the service spawns a background process. -See [`manifest-toml(1)`](../reference/command-reference/manifest.toml.md) for +See [`manifest-toml(1)`](../man/manifest.toml.md) for more details on the exact format of the `[services]` section of the manfiest. An example service definition is shown below: diff --git a/docs/flox-5-minutes.md b/docs/flox-5-minutes.md index 66b7046d..17320a8e 100644 --- a/docs/flox-5-minutes.md +++ b/docs/flox-5-minutes.md @@ -636,19 +636,19 @@ you can activate _both_ environments to do that work. [install_flox]: ./install-flox/install.md [create_guide]: ./tutorials/creating-environments.md [share_guide]: ./tutorials/sharing-environments.md -[init]: ./reference/command-reference/flox-init.md -[search]: ./reference/command-reference/flox-search.md -[show]: ./reference/command-reference/flox-show.md +[init]: ./man/flox-init.md +[search]: ./man/flox-search.md +[show]: ./man/flox-show.md [catalog]: ./concepts/packages-and-catalog.md -[install]: ./reference/command-reference/flox-install.md -[activate]: ./reference/command-reference/flox-activate.md -[edit]: ./reference/command-reference/flox-edit.md -[push]: ./reference/command-reference/flox-push.md -[pull]: ./reference/command-reference/flox-pull.md -[delete]: ./reference/command-reference/flox-delete.md -[list]: ./reference/command-reference/flox-list.md -[manifest]: ./reference/command-reference/manifest.toml.md +[install]: ./man/flox-install.md +[activate]: ./man/flox-activate.md +[edit]: ./man/flox-edit.md +[push]: ./man/flox-push.md +[pull]: ./man/flox-pull.md +[delete]: ./man/flox-delete.md +[list]: ./man/flox-list.md +[manifest]: ./man/manifest.toml.md [rust-cookbook]: ./cookbook/languages/rust.md [multi-arch]: ./tutorials/multi-arch-environments.md -[config]: ./reference/command-reference/flox-config.md +[config]: ./man/flox-config.md [services]: ./concepts/services.md diff --git a/docs/guides/getting-started/creating-environments.md b/docs/guides/getting-started/creating-environments.md index a67a2e65..bb4db40f 100644 --- a/docs/guides/getting-started/creating-environments.md +++ b/docs/guides/getting-started/creating-environments.md @@ -228,13 +228,13 @@ flox [example-project] $ exit $ ``` -[flox_init]: ../reference/command-reference/flox-init.md -[flox_search]: ../reference/command-reference/flox-search.md -[flox_show]: ../reference/command-reference/flox-show.md -[flox_install]: ../reference/command-reference/flox-install.md +[flox_init]: ../man/flox-init.md +[flox_search]: ../man/flox-search.md +[flox_show]: ../man/flox-show.md +[flox_install]: ../man/flox-install.md [discourse]: https://discourse.floxdev.com/ -[flox_activate]: ../reference/command-reference/flox-activate.md -[flox_edit]: ../reference/command-reference/flox-edit.md +[flox_activate]: ../man/flox-activate.md +[flox_edit]: ../man/flox-edit.md [sharing_guide]: ./sharing-environments.md [layering_guide]: ./layering-multiple-environments.md [manifest_concept]: ../concepts/environments.md#manifesttoml diff --git a/docs/guides/getting-started/customizing-environments.md b/docs/guides/getting-started/customizing-environments.md index d1761382..08a165e7 100644 --- a/docs/guides/getting-started/customizing-environments.md +++ b/docs/guides/getting-started/customizing-environments.md @@ -174,10 +174,10 @@ mycli - :simple-readme:{ .flox-purple .flox-heart } [Multiple architecture environments][multi-arch-guide] [environment_concept]: ../concepts/environments.md -[flox_activate]: ../reference/command-reference/flox-activate.md +[flox_activate]: ../man/flox-activate.md [multi-arch-guide]: ./multi-arch-environments.md [rust_guide]: ../cookbook/languages/rust.md -[flox_init]: ../reference/command-reference/flox-init.md +[flox_init]: ../man/flox-init.md [activation_concept]: ../concepts/activation.md [fish_shell]: https://fishshell.com/ -[flox_install]: ../reference/command-reference/flox-install.md +[flox_install]: ../man/flox-install.md diff --git a/docs/guides/getting-started/default-environment.md b/docs/guides/getting-started/default-environment.md index 3e8285d0..de374574 100644 --- a/docs/guides/getting-started/default-environment.md +++ b/docs/guides/getting-started/default-environment.md @@ -247,6 +247,6 @@ Flox has you covered. Even better, if you want both a package manager _and_ developer environments, with Flox you only need to learn one tool. -[init]: ../reference/command-reference/flox-init.md -[push]: ../reference/command-reference/flox-push.md -[pull]: ../reference/command-reference/flox-pull.md +[init]: ../man/flox-init.md +[push]: ../man/flox-push.md +[pull]: ../man/flox-pull.md diff --git a/docs/guides/getting-started/multi-arch-environments.md b/docs/guides/getting-started/multi-arch-environments.md index 41c92525..826e240e 100644 --- a/docs/guides/getting-started/multi-arch-environments.md +++ b/docs/guides/getting-started/multi-arch-environments.md @@ -138,8 +138,8 @@ get the `systemd` package. [environment_concept]: ../concepts/environments.md [sharing_guide]: ./sharing-environments.md -[flox_search]: ../reference/command-reference/flox-search.md -[flox_show]: ../reference/command-reference/flox-show.md -[flox_edit]: ../reference/command-reference/flox-edit.md -[flox_push]: ../reference/command-reference/flox-push.md -[flox_pull]: ../reference/command-reference/flox-pull.md +[flox_search]: ../man/flox-search.md +[flox_show]: ../man/flox-show.md +[flox_edit]: ../man/flox-edit.md +[flox_push]: ../man/flox-push.md +[flox_pull]: ../man/flox-pull.md diff --git a/docs/guides/getting-started/sharing-environments.md b/docs/guides/getting-started/sharing-environments.md index b5c0a337..c4afa532 100644 --- a/docs/guides/getting-started/sharing-environments.md +++ b/docs/guides/getting-started/sharing-environments.md @@ -54,7 +54,7 @@ git clone ..example-project; flox activate ``` -[flox_init]: ../reference/command-reference/flox-init.md +[flox_init]: ../man/flox-init.md [discourse]: https://discourse.flox.dev/ [manifest_concept]: ../concepts/environments.md#manifesttoml @@ -128,9 +128,9 @@ $ flox push !!! note "Note" Right now, only environment owners can push edits to their environments. -[flox_push]: ../reference/command-reference/flox-push.md -[flox_pull]: ../reference/command-reference/flox-pull.md -[flox_activate]: ../reference/command-reference/flox-activate.md +[flox_push]: ../man/flox-push.md +[flox_pull]: ../man/flox-pull.md +[flox_activate]: ../man/flox-activate.md [floxhub_concept]: ../concepts/floxhub.md ### Pulling a remote environment without connecting to FloxHub @@ -228,4 +228,4 @@ telnet (GNU inetutils) 2.5 [environment_concept]: ../concepts/environments.md [layering_guide]: ./layering-multiple-environments.md [customizing_guide]: ./customizing-environments.md -[flox_containerize]: ../reference/command-reference/flox-containerize.md +[flox_containerize]: ../man/flox-containerize.md diff --git a/docs/guides/going-deeper/build-and-publish.md b/docs/guides/going-deeper/build-and-publish.md index 606d6556..2daa9c5b 100644 --- a/docs/guides/going-deeper/build-and-publish.md +++ b/docs/guides/going-deeper/build-and-publish.md @@ -256,15 +256,15 @@ The story doesn't end here though. In this guide we've shown you how to build and distribute programs, but you can also use it to distribute configuration files (or any other file). See the [builds][extra-builds] concept page for examples of what else you can build and publish with Flox. -[flox-manifest-build-section]: ../reference/command-reference/manifest.toml.md#build +[flox-manifest-build-section]: ../man/manifest.toml.md#build [build-concept]: ../concepts/builds.md [fhs]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard -[flox-install]: ../reference/command-reference/flox-install.md -[flox-show]: ../reference/command-reference/flox-show.md -[flox-search]: ../reference/command-reference/flox-search.md -[flox-edit]: ../reference/command-reference/flox-edit.md -[flox-build]: ../reference/command-reference/flox-build.md -[flox-publish]: ../reference/command-reference/flox-publish.md +[flox-install]: ../man/flox-install.md +[flox-show]: ../man/flox-show.md +[flox-search]: ../man/flox-search.md +[flox-edit]: ../man/flox-edit.md +[flox-build]: ../man/flox-build.md +[flox-publish]: ../man/flox-publish.md [extra-builds]: ../concepts/manifest-builds.md#example-configuration-files [publish-concept]: ../concepts/publishing.md [organizations-concept]: ../concepts/organizations.md diff --git a/docs/guides/going-deeper/ci-cd.md b/docs/guides/going-deeper/ci-cd.md index b40200c3..788c17f8 100644 --- a/docs/guides/going-deeper/ci-cd.md +++ b/docs/guides/going-deeper/ci-cd.md @@ -121,4 +121,4 @@ Here are some suggestions for things you can do with your Flox environment in CI [sharing_guide]: ./sharing-environments.md [layering_guide]: ./layering-multiple-environments.md [customizing_guide]: ./customizing-environments.md -[containerize]: ../reference/command-reference/flox-containerize.md +[containerize]: ../man/flox-containerize.md diff --git a/docs/guides/going-deeper/composition.md b/docs/guides/going-deeper/composition.md index f6280642..2da10762 100644 --- a/docs/guides/going-deeper/composition.md +++ b/docs/guides/going-deeper/composition.md @@ -297,10 +297,10 @@ This means you can spend less time getting started, and more time developing you Similarly, since you're treating environments like dependencies, if you make an improvement to a template environment while working on one project, the improvement will become available to all of your other projects that use that environment as soon as they run `flox include upgrade`. [poetry]: https://python-poetry.org/ -[flox-init]: ../reference/command-reference/flox-init.md -[flox-pull]: ../reference/command-reference/flox-pull.md -[flox-install]: ../reference/command-reference/flox-install.md -[flox-edit]: ../reference/command-reference/flox-edit.md -[flox-list]: ../reference/command-reference/flox-list.md +[flox-init]: ../man/flox-init.md +[flox-pull]: ../man/flox-pull.md +[flox-install]: ../man/flox-install.md +[flox-edit]: ../man/flox-edit.md +[flox-list]: ../man/flox-list.md [floxhub]: ../concepts/floxhub.md [hypothesis]: https://hypothesis.readthedocs.io/en/latest/ diff --git a/docs/guides/going-deeper/layering-multiple-environments.md b/docs/guides/going-deeper/layering-multiple-environments.md index 25d7377f..4b75a8f8 100644 --- a/docs/guides/going-deeper/layering-multiple-environments.md +++ b/docs/guides/going-deeper/layering-multiple-environments.md @@ -127,10 +127,10 @@ Inactive environments: - :simple-readme:{ .flox-purple .flox-heart } [Designing multiple architecture environments][multi_arch_guide] [default-env]: ./default-environment.md -[flox_init]: ../reference/command-reference/flox-init.md -[flox_install]: ../reference/command-reference/flox-install.md -[flox_activate]: ../reference/command-reference/flox-activate.md -[flox_list]: ../reference/command-reference/flox-list.md +[flox_init]: ../man/flox-init.md +[flox_install]: ../man/flox-install.md +[flox_activate]: ../man/flox-activate.md +[flox_list]: ../man/flox-list.md [sharing_guide]: ./sharing-environments.md [customizing_guide]: ./customizing-environments.md [multi_arch_guide]: ./multi-arch-environments.md diff --git a/docs/index.md b/docs/index.md index 3fc40310..e60354d5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -108,7 +108,7 @@ If you're already using Homebrew, you can easily [migrate or use Homebrew and Fl Flox lets you define what an environment _is_ in a way that can be reused across local dev, CI, and production. Leverage [pre-built integrations](https://flox.dev/docs/tutorials/ci-cd/?h=ci) for GitHub Actions, CircleCI, and GitLab to pull and activate the same environments locally, in CI and in production. -Or use Flox [containerize](https://flox.dev/docs/reference/command-reference/flox-containerize/?h=containerize) to package your environments as OCI images—fully pinned and runnable anywhere. +Or use Flox [containerize](https://flox.dev/docs/man/flox-containerize/?h=containerize) to package your environments as OCI images—fully pinned and runnable anywhere. From bare metal to VMs, from Docker Swarm to Kubernetes to AWS Lambda—the runtime context might change, but Flox environments run and behave the same everywhere. Need an example? See how [the Flox Docs team uses Flox in CI](https://flox.dev/blog/integrating-flox-with-ci-for-consistent-reproducible-dev-environments/) to build, test and deploy this docs site. @@ -131,20 +131,20 @@ The Flox product and engineering teams love to hear directly from users. Your qu [flox_5_minutes]: ./flox-5-minutes.md [create_guide]: ./tutorials/creating-environments.md [share_guide]: ./tutorials/sharing-environments.md -[init]: ./reference/command-reference/flox-init.md -[search]: ./reference/command-reference/flox-search.md -[show]: ./reference/command-reference/flox-show.md +[init]: ./man/flox-init.md +[search]: ./man/flox-search.md +[show]: ./man/flox-show.md [catalog]: ./concepts/packages-and-catalog.md -[install]: ./reference/command-reference/flox-install.md -[activate]: ./reference/command-reference/flox-activate.md -[edit]: ./reference/command-reference/flox-edit.md -[push]: ./reference/command-reference/flox-push.md -[pull]: ./reference/command-reference/flox-pull.md -[delete]: ./reference/command-reference/flox-delete.md -[list]: ./reference/command-reference/flox-list.md -[manifest]: ./reference/command-reference/manifest.toml.md +[install]: ./man/flox-install.md +[activate]: ./man/flox-activate.md +[edit]: ./man/flox-edit.md +[push]: ./man/flox-push.md +[pull]: ./man/flox-pull.md +[delete]: ./man/flox-delete.md +[list]: ./man/flox-list.md +[manifest]: ./man/manifest.toml.md [rust-cookbook]: ./cookbook/languages/rust.md [multi-arch]: ./tutorials/multi-arch-environments.md -[config]: ./reference/command-reference/flox-config.md +[config]: ./man/flox-config.md [services]: ./concepts/services.md [floxhub_packages]: https://hub.flox.dev/packages diff --git a/docs/migrations/homebrew.md b/docs/migrations/homebrew.md index eb772a58..77311e27 100644 --- a/docs/migrations/homebrew.md +++ b/docs/migrations/homebrew.md @@ -202,10 +202,10 @@ We recommend that the Flox default environment activation lines appear lowest in [default_tutorial_setup]: ../default-environment.md#initial-setup [creating_tutorial]: ../creating-environments.md [install_flox]: ../../install-flox/install.md -[search]: ../../reference/command-reference/flox-search.md -[envs]: ../../reference/command-reference/flox-envs.md -[list]: ../../reference/command-reference/flox-list.md +[search]: ../../man/flox-search.md +[envs]: ../../man/flox-envs.md +[list]: ../../man/flox-list.md [catalog]: ../../concepts/packages-and-catalog.md -[install]: ../../reference/command-reference/flox-install.md -[uninstall]: ../../reference/command-reference/flox-uninstall.md -[activate]: ../../reference/command-reference/flox-activate.md +[install]: ../../man/flox-install.md +[uninstall]: ../../man/flox-uninstall.md +[activate]: ../../man/flox-activate.md diff --git a/docs/migrations/nvm.md b/docs/migrations/nvm.md index f71b7a34..90c54514 100644 --- a/docs/migrations/nvm.md +++ b/docs/migrations/nvm.md @@ -189,5 +189,5 @@ Now that you're managing your project's Node.js version using Flox, you can `git [environment_concept]: ../../concepts/environments.md [install_flox]: ../../install-flox/install.md -[manifest]: ../../reference/command-reference/manifest.toml.md +[manifest]: ../../man/manifest.toml.md [services]: ../../concepts/services.md From 1ba019fed71f99975896645d7e3fac8e8cffd64b Mon Sep 17 00:00:00 2001 From: Zach Mitchell Date: Tue, 26 Aug 2025 13:33:01 -0600 Subject: [PATCH 4/5] fix: links to concepts/explanations --- docs/comparisons/flox-vs-containers.md | 4 ++-- docs/explanations/floxhub.md | 6 +++--- docs/flox-5-minutes.md | 4 ++-- docs/guides/getting-started/creating-environments.md | 4 ++-- docs/guides/getting-started/customizing-environments.md | 4 ++-- docs/guides/getting-started/multi-arch-environments.md | 2 +- docs/guides/getting-started/sharing-environments.md | 6 +++--- docs/guides/going-deeper/build-and-publish.md | 8 ++++---- docs/guides/going-deeper/composition.md | 2 +- docs/index.md | 6 +++--- docs/languages/c.md | 2 +- docs/languages/go.md | 6 +++--- docs/languages/jvm.md | 2 +- docs/languages/nodejs.md | 4 ++-- docs/languages/python.md | 2 +- docs/languages/ruby.md | 4 ++-- docs/languages/rust.md | 4 ++-- docs/man/flox-publish.md | 2 +- docs/migrations/homebrew.md | 4 ++-- docs/migrations/nvm.md | 4 ++-- 20 files changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/comparisons/flox-vs-containers.md b/docs/comparisons/flox-vs-containers.md index dd95c7d5..b6b06a95 100644 --- a/docs/comparisons/flox-vs-containers.md +++ b/docs/comparisons/flox-vs-containers.md @@ -446,7 +446,7 @@ you need to build a container so that it can be deployed. [containerize]: ../man/flox-containerize.md [activate]: ../man/flox-activate.md [services-start]: ../man/flox-services-start.md -[services]: ../concepts/services.md -[manifest]: ../concepts/environments.md#manifesttoml +[services]: ../explanations/services.md +[manifest]: ../explanations/environments.md#manifesttoml [early]: https://flox.dev/early/ [ci-cd]: ../tutorials/ci-cd.md diff --git a/docs/explanations/floxhub.md b/docs/explanations/floxhub.md index bfbd7162..abe2320c 100644 --- a/docs/explanations/floxhub.md +++ b/docs/explanations/floxhub.md @@ -104,6 +104,6 @@ Run the [`flox auth logout`][flox_auth] command. [flox_edit]: ../man/flox-edit.md [flox_install]: ../man/flox-install.md [flox_uninstall]: ../man/flox-uninstall.md -[generation_concept]: ../concepts/generations.md -[manifest_concept]: ../concepts/environments.md#manifesttoml -[environments_concept]: ../concepts/environments.md +[generation_concept]: ../explanations/generations.md +[manifest_concept]: ../explanations/environments.md#manifesttoml +[environments_concept]: ../explanations/environments.md diff --git a/docs/flox-5-minutes.md b/docs/flox-5-minutes.md index 17320a8e..87a4d182 100644 --- a/docs/flox-5-minutes.md +++ b/docs/flox-5-minutes.md @@ -639,7 +639,7 @@ you can activate _both_ environments to do that work. [init]: ./man/flox-init.md [search]: ./man/flox-search.md [show]: ./man/flox-show.md -[catalog]: ./concepts/packages-and-catalog.md +[catalog]: ./explanations/packages-and-catalog.md [install]: ./man/flox-install.md [activate]: ./man/flox-activate.md [edit]: ./man/flox-edit.md @@ -651,4 +651,4 @@ you can activate _both_ environments to do that work. [rust-cookbook]: ./cookbook/languages/rust.md [multi-arch]: ./tutorials/multi-arch-environments.md [config]: ./man/flox-config.md -[services]: ./concepts/services.md +[services]: ./explanations/services.md diff --git a/docs/guides/getting-started/creating-environments.md b/docs/guides/getting-started/creating-environments.md index bb4db40f..3330e7e5 100644 --- a/docs/guides/getting-started/creating-environments.md +++ b/docs/guides/getting-started/creating-environments.md @@ -237,8 +237,8 @@ $ [flox_edit]: ../man/flox-edit.md [sharing_guide]: ./sharing-environments.md [layering_guide]: ./layering-multiple-environments.md -[manifest_concept]: ../concepts/environments.md#manifesttoml -[environment_concept]: ../concepts/environments.md +[manifest_concept]: ../explanations/environments.md#manifesttoml +[environment_concept]: ../explanations/environments.md [customizing_guide]: ./customizing-environments.md ## Where to next? diff --git a/docs/guides/getting-started/customizing-environments.md b/docs/guides/getting-started/customizing-environments.md index 08a165e7..081687ea 100644 --- a/docs/guides/getting-started/customizing-environments.md +++ b/docs/guides/getting-started/customizing-environments.md @@ -173,11 +173,11 @@ mycli - :simple-readme:{ .flox-purple .flox-heart } [Multiple architecture environments][multi-arch-guide] -[environment_concept]: ../concepts/environments.md +[environment_concept]: ../explanations/environments.md [flox_activate]: ../man/flox-activate.md [multi-arch-guide]: ./multi-arch-environments.md [rust_guide]: ../cookbook/languages/rust.md [flox_init]: ../man/flox-init.md -[activation_concept]: ../concepts/activation.md +[activation_concept]: ../explanations/activation.md [fish_shell]: https://fishshell.com/ [flox_install]: ../man/flox-install.md diff --git a/docs/guides/getting-started/multi-arch-environments.md b/docs/guides/getting-started/multi-arch-environments.md index 826e240e..be1bba78 100644 --- a/docs/guides/getting-started/multi-arch-environments.md +++ b/docs/guides/getting-started/multi-arch-environments.md @@ -136,7 +136,7 @@ get the `systemd` package. - :simple-readme:{ .flox-purple .flox-heart } [Environment concept][environment_concept] -[environment_concept]: ../concepts/environments.md +[environment_concept]: ../explanations/environments.md [sharing_guide]: ./sharing-environments.md [flox_search]: ../man/flox-search.md [flox_show]: ../man/flox-show.md diff --git a/docs/guides/getting-started/sharing-environments.md b/docs/guides/getting-started/sharing-environments.md index c4afa532..ae530928 100644 --- a/docs/guides/getting-started/sharing-environments.md +++ b/docs/guides/getting-started/sharing-environments.md @@ -56,7 +56,7 @@ flox activate [flox_init]: ../man/flox-init.md [discourse]: https://discourse.flox.dev/ -[manifest_concept]: ../concepts/environments.md#manifesttoml +[manifest_concept]: ../explanations/environments.md#manifesttoml ## Sharing environments on FloxHub @@ -131,7 +131,7 @@ $ flox push [flox_push]: ../man/flox-push.md [flox_pull]: ../man/flox-pull.md [flox_activate]: ../man/flox-activate.md -[floxhub_concept]: ../concepts/floxhub.md +[floxhub_concept]: ../explanations/floxhub.md ### Pulling a remote environment without connecting to FloxHub @@ -225,7 +225,7 @@ telnet (GNU inetutils) 2.5 - :simple-readme:{ .flox-purple .flox-heart } [Designing multiple architecture environments][multi_arch_guide] [multi_arch_guide]: ./multi-arch-environments.md -[environment_concept]: ../concepts/environments.md +[environment_concept]: ../explanations/environments.md [layering_guide]: ./layering-multiple-environments.md [customizing_guide]: ./customizing-environments.md [flox_containerize]: ../man/flox-containerize.md diff --git a/docs/guides/going-deeper/build-and-publish.md b/docs/guides/going-deeper/build-and-publish.md index 2daa9c5b..e1c128fd 100644 --- a/docs/guides/going-deeper/build-and-publish.md +++ b/docs/guides/going-deeper/build-and-publish.md @@ -257,7 +257,7 @@ In this guide we've shown you how to build and distribute programs, but you can See the [builds][extra-builds] concept page for examples of what else you can build and publish with Flox. [flox-manifest-build-section]: ../man/manifest.toml.md#build -[build-concept]: ../concepts/builds.md +[build-concept]: ../explanations/builds.md [fhs]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard [flox-install]: ../man/flox-install.md [flox-show]: ../man/flox-show.md @@ -265,7 +265,7 @@ See the [builds][extra-builds] concept page for examples of what else you can bu [flox-edit]: ../man/flox-edit.md [flox-build]: ../man/flox-build.md [flox-publish]: ../man/flox-publish.md -[extra-builds]: ../concepts/manifest-builds.md#example-configuration-files -[publish-concept]: ../concepts/publishing.md -[organizations-concept]: ../concepts/organizations.md +[extra-builds]: ../explanations/manifest-builds.md#example-configuration-files +[publish-concept]: ../explanations/publishing.md +[organizations-concept]: ../explanations/organizations.md [early]: https://flox.dev/early/ diff --git a/docs/guides/going-deeper/composition.md b/docs/guides/going-deeper/composition.md index 2da10762..32877ad5 100644 --- a/docs/guides/going-deeper/composition.md +++ b/docs/guides/going-deeper/composition.md @@ -302,5 +302,5 @@ Similarly, since you're treating environments like dependencies, if you make an [flox-install]: ../man/flox-install.md [flox-edit]: ../man/flox-edit.md [flox-list]: ../man/flox-list.md -[floxhub]: ../concepts/floxhub.md +[floxhub]: ../explanations/floxhub.md [hypothesis]: https://hypothesis.readthedocs.io/en/latest/ diff --git a/docs/index.md b/docs/index.md index e60354d5..4f90ed24 100644 --- a/docs/index.md +++ b/docs/index.md @@ -85,7 +85,7 @@ Use Flox to solve three common use cases: Set up a [local developer environment](https://flox.dev/docs/tutorials/creating-environments/) that will work the same across multiple operating systems and architectures. Seamlessly switch between development environments across multiple language ecosystems using a consistent, unified workflow. -Declare all the packages, activation scripts, environment variables and [services](https://flox.dev/docs/concepts/services/) needed to reproduce the environment in a simple manifest that can be checked into [version control along with your source code](https://flox.dev/blog/flox-and-teams-managing-your-code-and-your-runtime-environment-in-just-one-place/). +Declare all the packages, activation scripts, environment variables and [services](https://flox.dev/docs/explanations/services/) needed to reproduce the environment in a simple manifest that can be checked into [version control along with your source code](https://flox.dev/blog/flox-and-teams-managing-your-code-and-your-runtime-environment-in-just-one-place/). Once your environment is configured, you can simplify the setup instructions in your README to a single command (`flox activate`), making it easy to [share environments](https://flox.dev/blog/flox-and-teams-using-shared-flox-environments/) and [onboard new developers](https://flox.dev/blog/flox-and-teams-onboarding-made-easy-with-github-and-flox/). @@ -134,7 +134,7 @@ The Flox product and engineering teams love to hear directly from users. Your qu [init]: ./man/flox-init.md [search]: ./man/flox-search.md [show]: ./man/flox-show.md -[catalog]: ./concepts/packages-and-catalog.md +[catalog]: ./explanations/packages-and-catalog.md [install]: ./man/flox-install.md [activate]: ./man/flox-activate.md [edit]: ./man/flox-edit.md @@ -146,5 +146,5 @@ The Flox product and engineering teams love to hear directly from users. Your qu [rust-cookbook]: ./cookbook/languages/rust.md [multi-arch]: ./tutorials/multi-arch-environments.md [config]: ./man/flox-config.md -[services]: ./concepts/services.md +[services]: ./explanations/services.md [floxhub_packages]: https://hub.flox.dev/packages diff --git a/docs/languages/c.md b/docs/languages/c.md index 47c8946b..01c45f1c 100644 --- a/docs/languages/c.md +++ b/docs/languages/c.md @@ -55,4 +55,4 @@ clangStdenv.mkDerivation { } ``` -[build-concept]: ../../concepts/builds.md +[build-concept]: ../../explanations/builds.md diff --git a/docs/languages/go.md b/docs/languages/go.md index a6ce8dd1..8a6869bc 100644 --- a/docs/languages/go.md +++ b/docs/languages/go.md @@ -107,6 +107,6 @@ buildGoModule { } ``` -[build-concept]: ../../concepts/builds.md -[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds -[nix-expression-hashes]: ../../concepts/nix-expression-builds.md#generating-hashes +[build-concept]: ../../explanations/builds.md +[pure-builds-section]: ../../explanations/manifest-builds.md#pure-builds +[nix-expression-hashes]: ../../explanations/nix-expression-builds.md#generating-hashes diff --git a/docs/languages/jvm.md b/docs/languages/jvm.md index ea74b6e1..93790836 100644 --- a/docs/languages/jvm.md +++ b/docs/languages/jvm.md @@ -44,4 +44,4 @@ Note that `pwd` will return the location from which the built artifact is run, n [gradle]: https://gradle.org/ [shadow]: https://gradleup.com/shadow/ -[build-concept]: ../../concepts/builds.md +[build-concept]: ../../explanations/builds.md diff --git a/docs/languages/nodejs.md b/docs/languages/nodejs.md index 54938175..dc054eaf 100644 --- a/docs/languages/nodejs.md +++ b/docs/languages/nodejs.md @@ -97,5 +97,5 @@ buildNpmPackage (final: { }); ``` -[build-concept]: ../../concepts/builds.md -[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds +[build-concept]: ../../explanations/builds.md +[pure-builds-section]: ../../explanations/manifest-builds.md#pure-builds diff --git a/docs/languages/python.md b/docs/languages/python.md index 84697324..0bba5fd4 100644 --- a/docs/languages/python.md +++ b/docs/languages/python.md @@ -355,4 +355,4 @@ runtime-packages = [ ] ``` -[build-concept]: ../../concepts/builds.md +[build-concept]: ../../explanations/builds.md diff --git a/docs/languages/ruby.md b/docs/languages/ruby.md index 6b10afde..9d1dae2f 100644 --- a/docs/languages/ruby.md +++ b/docs/languages/ruby.md @@ -82,5 +82,5 @@ command = """ sandbox = "pure" ``` -[build-concept]: ../../concepts/builds.md -[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds +[build-concept]: ../../explanations/builds.md +[pure-builds-section]: ../../explanations/manifest-builds.md#pure-builds diff --git a/docs/languages/rust.md b/docs/languages/rust.md index bbc21eb9..4ea1507f 100644 --- a/docs/languages/rust.md +++ b/docs/languages/rust.md @@ -289,5 +289,5 @@ rustPlatform.buildRustPackage { [custom-toolchains]: https://github.com/zmitchell/rust-toolchains [esp32]: https://www.espressif.com/en/products/socs/esp32 [risc-v]: https://en.wikipedia.org/wiki/RISC-V -[build-concept]: ../../concepts/builds.md -[pure-builds-section]: ../../concepts/manifest-builds.md#pure-builds +[build-concept]: ../../explanations/builds.md +[pure-builds-section]: ../../explanations/manifest-builds.md#pure-builds diff --git a/docs/man/flox-publish.md b/docs/man/flox-publish.md index 1d000534..a2a73700 100644 --- a/docs/man/flox-publish.md +++ b/docs/man/flox-publish.md @@ -86,7 +86,7 @@ Store that it was published to. a package published to an individual user’s Catalog may only be seen and installed by that user. In order to share packages with other users you must create an organization. See -https://flox.dev/docs/concepts/organizations/ for more details on +https://flox.dev/docs/explanations/organizations/ for more details on organizations and how to create them. Note that this is a paid feature available with Flox for Teams. diff --git a/docs/migrations/homebrew.md b/docs/migrations/homebrew.md index 77311e27..6a109f99 100644 --- a/docs/migrations/homebrew.md +++ b/docs/migrations/homebrew.md @@ -197,7 +197,7 @@ However, if you have the Flox default environment enabled, you should be aware o We recommend that the Flox default environment activation lines appear lowest in your dotfiles, ensuring that packages in the default environment appear in your `PATH` sooner than those from Homebrew. -[manifest_concept]: ../../concepts/environments.md#manifesttoml +[manifest_concept]: ../../explanations/environments.md#manifesttoml [default_tutorial]: ../default-environment.md [default_tutorial_setup]: ../default-environment.md#initial-setup [creating_tutorial]: ../creating-environments.md @@ -205,7 +205,7 @@ We recommend that the Flox default environment activation lines appear lowest in [search]: ../../man/flox-search.md [envs]: ../../man/flox-envs.md [list]: ../../man/flox-list.md -[catalog]: ../../concepts/packages-and-catalog.md +[catalog]: ../../explanations/packages-and-catalog.md [install]: ../../man/flox-install.md [uninstall]: ../../man/flox-uninstall.md [activate]: ../../man/flox-activate.md diff --git a/docs/migrations/nvm.md b/docs/migrations/nvm.md index 90c54514..92ed6ec1 100644 --- a/docs/migrations/nvm.md +++ b/docs/migrations/nvm.md @@ -187,7 +187,7 @@ At this point, you can replace any nvm-related instructions in your README with Now that you're managing your project's Node.js version using Flox, you can `git rm .nvmrc` and commit the result. You're free to repeat the process in other project directories before following the [instructions for uninstalling nvm as listed in the nvm README](https://github.com/nvm-sh/nvm?tab=readme-ov-file#uninstalling--removal){:target="\_blank"}. -[environment_concept]: ../../concepts/environments.md +[environment_concept]: ../../explanations/environments.md [install_flox]: ../../install-flox/install.md [manifest]: ../../man/manifest.toml.md -[services]: ../../concepts/services.md +[services]: ../../explanations/services.md From 03f9bc0358fa0240fc57b1737092ae51b21d9dd1 Mon Sep 17 00:00:00 2001 From: Zach Mitchell Date: Fri, 29 Aug 2025 09:24:01 -0600 Subject: [PATCH 5/5] wip: add todos --- docs/flox-5-minutes.md | 8 +- todo.md | 272 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 276 insertions(+), 4 deletions(-) create mode 100644 todo.md diff --git a/docs/flox-5-minutes.md b/docs/flox-5-minutes.md index 87a4d182..75af4200 100644 --- a/docs/flox-5-minutes.md +++ b/docs/flox-5-minutes.md @@ -634,8 +634,8 @@ you can activate _both_ environments to do that work. [configuring your environment][manifest]. [install_flox]: ./install-flox/install.md -[create_guide]: ./tutorials/creating-environments.md -[share_guide]: ./tutorials/sharing-environments.md +[create_guide]: ./guides/getting-started/creating-environments.md +[share_guide]: ./guides/getting-started/sharing-environments.md [init]: ./man/flox-init.md [search]: ./man/flox-search.md [show]: ./man/flox-show.md @@ -648,7 +648,7 @@ you can activate _both_ environments to do that work. [delete]: ./man/flox-delete.md [list]: ./man/flox-list.md [manifest]: ./man/manifest.toml.md -[rust-cookbook]: ./cookbook/languages/rust.md -[multi-arch]: ./tutorials/multi-arch-environments.md +[rust-cookbook]: ./languages/rust.md +[multi-arch]: ./guides/getting-started/multi-arch-environments.md [config]: ./man/flox-config.md [services]: ./explanations/services.md diff --git a/todo.md b/todo.md new file mode 100644 index 00000000..9d5bd8ff --- /dev/null +++ b/todo.md @@ -0,0 +1,272 @@ +WARNING - Doc file 'flox-5-minutes.md' contains a relative link './cookbook/languages/rust.md', but the target + 'cookbook/languages/rust.md' is not found among documentation files. +WARNING - Doc file 'flox-5-minutes.md' contains a relative link './tutorials/multi-arch-environments.md', but the target + 'tutorials/multi-arch-environments.md' is not found among documentation files. +WARNING - Doc file 'flox-5-minutes.md' contains a relative link './tutorials/creating-environments.md', but the target + 'tutorials/creating-environments.md' is not found among documentation files. +WARNING - Doc file 'flox-5-minutes.md' contains a relative link './tutorials/sharing-environments.md', but the target + 'tutorials/sharing-environments.md' is not found among documentation files. +WARNING - Doc file 'comparisons/flox-vs-containers.md' contains a relative link '../tutorials/ci-cd.md', but the target + 'tutorials/ci-cd.md' is not found among documentation files. +WARNING - Doc file 'explanations/builds.md' contains a relative link '../tutorials/ci-cd.md', but the target 'tutorials/ci-cd.md' + is not found among documentation files. +WARNING - Doc file 'explanations/environments.md' contains a relative link '../tutorials/creating-environments.md', but the target + 'tutorials/creating-environments.md' is not found among documentation files. +WARNING - Doc file 'explanations/environments.md' contains a relative link '../tutorials/sharing-environments.md', but the target + 'tutorials/sharing-environments.md' is not found among documentation files. +WARNING - Doc file 'explanations/environments.md' contains a relative link '../tutorials/customizing-environments.md', but the + target 'tutorials/customizing-environments.md' is not found among documentation files. +WARNING - Doc file 'explanations/generations.md' contains a relative link '../tutorials/sharing-environments.md', but the target + 'tutorials/sharing-environments.md' is not found among documentation files. +WARNING - Doc file 'explanations/generations.md' contains a relative link '../tutorials/creating-environments.md', but the target + 'tutorials/creating-environments.md' is not found among documentation files. +WARNING - Doc file 'explanations/generations.md' contains a relative link '../tutorials/creating-environments.md', but the target + 'tutorials/creating-environments.md' is not found among documentation files. +WARNING - Doc file 'explanations/manifest-builds.md' contains a relative link '../cookbook/languages/go.md#build-with-flox', but + the target 'cookbook/languages/go.md' is not found among documentation files. +WARNING - Doc file 'explanations/manifest-builds.md' contains a relative link '../cookbook/languages/go.md#build-with-flox', but + the target 'cookbook/languages/go.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../explanations/environments.md', + but the target 'guides/explanations/environments.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-init.md', but the target + 'guides/man/flox-init.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../explanations/environments.md', + but the target 'guides/explanations/environments.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-init.md', but the target + 'guides/man/flox-init.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-search.md', but the + target 'guides/man/flox-search.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-show.md', but the target + 'guides/man/flox-show.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-install.md', but the + target 'guides/man/flox-install.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-search.md', but the + target 'guides/man/flox-search.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-show.md', but the target + 'guides/man/flox-show.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-install.md', but the + target 'guides/man/flox-install.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-activate.md', but the + target 'guides/man/flox-activate.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link + '../explanations/environments.md#manifesttoml', but the target 'guides/explanations/environments.md' is not found among + documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-edit.md', but the target + 'guides/man/flox-edit.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-edit.md', but the target + 'guides/man/flox-edit.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link + '../explanations/environments.md#manifesttoml', but the target 'guides/explanations/environments.md' is not found among + documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-activate.md', but the + target 'guides/man/flox-activate.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../man/flox-activate.md', but the + target 'guides/man/flox-activate.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link '../explanations/environments.md', + but the target 'guides/explanations/environments.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/creating-environments.md' contains a relative link + './layering-multiple-environments.md', but the target 'guides/getting-started/layering-multiple-environments.md' is not + found among documentation files. +WARNING - Doc file 'guides/getting-started/customizing-environments.md' contains a relative link '../explanations/environments.md', + but the target 'guides/explanations/environments.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/customizing-environments.md' contains a relative link '../cookbook/languages/rust.md', + but the target 'guides/cookbook/languages/rust.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/customizing-environments.md' contains a relative link '../man/flox-init.md', but the + target 'guides/man/flox-init.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/customizing-environments.md' contains a relative link '../explanations/activation.md', + but the target 'guides/explanations/activation.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/customizing-environments.md' contains a relative link '../man/flox-install.md', but the + target 'guides/man/flox-install.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/default-environment.md' contains a relative link '../man/flox-init.md', but the target + 'guides/man/flox-init.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/default-environment.md' contains a relative link '../man/flox-push.md', but the target + 'guides/man/flox-push.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/default-environment.md' contains a relative link '../man/flox-pull.md', but the target + 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/multi-arch-environments.md' contains a relative link '../explanations/environments.md', + but the target 'guides/explanations/environments.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/multi-arch-environments.md' contains a relative link '../explanations/environments.md', + but the target 'guides/explanations/environments.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/multi-arch-environments.md' contains a relative link '../man/flox-search.md', but the + target 'guides/man/flox-search.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/multi-arch-environments.md' contains a relative link '../man/flox-show.md', but the + target 'guides/man/flox-show.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/multi-arch-environments.md' contains a relative link '../man/flox-push.md', but the + target 'guides/man/flox-push.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/multi-arch-environments.md' contains a relative link '../man/flox-pull.md', but the + target 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/multi-arch-environments.md' contains a relative link '../explanations/environments.md', + but the target 'guides/explanations/environments.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../explanations/environments.md', but + the target 'guides/explanations/environments.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-init.md', but the target + 'guides/man/flox-init.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-init.md', but the target + 'guides/man/flox-init.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link + '../explanations/environments.md#manifesttoml', but the target 'guides/explanations/environments.md' is not found among + documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-activate.md', but the + target 'guides/man/flox-activate.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-push.md', but the target + 'guides/man/flox-push.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-push.md', but the target + 'guides/man/flox-push.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../explanations/floxhub.md', but the + target 'guides/explanations/floxhub.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-push.md', but the target + 'guides/man/flox-push.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-activate.md', but the + target 'guides/man/flox-activate.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-pull.md', but the target + 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-pull.md', but the target + 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../explanations/floxhub.md', but the + target 'guides/explanations/floxhub.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-pull.md', but the target + 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-push.md', but the target + 'guides/man/flox-push.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-pull.md', but the target + 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-pull.md', but the target + 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-pull.md', but the target + 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-pull.md', but the target + 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-push.md', but the target + 'guides/man/flox-push.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-push.md', but the target + 'guides/man/flox-push.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-activate.md', but the + target 'guides/man/flox-activate.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../explanations/floxhub.md', but the + target 'guides/explanations/floxhub.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link '../man/flox-containerize.md', but the + target 'guides/man/flox-containerize.md' is not found among documentation files. +WARNING - Doc file 'guides/getting-started/sharing-environments.md' contains a relative link './layering-multiple-environments.md', + but the target 'guides/getting-started/layering-multiple-environments.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../man/manifest.toml.md#build', but the + target 'guides/man/manifest.toml.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../explanations/builds.md', but the target + 'guides/explanations/builds.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../man/flox-edit.md', but the target + 'guides/man/flox-edit.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../man/flox-build.md', but the target + 'guides/man/flox-build.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../explanations/organizations.md', but the + target 'guides/explanations/organizations.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../explanations/publishing.md', but the + target 'guides/explanations/publishing.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../man/flox-publish.md', but the target + 'guides/man/flox-publish.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../man/flox-search.md', but the target + 'guides/man/flox-search.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../man/flox-show.md', but the target + 'guides/man/flox-show.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link '../man/flox-install.md', but the target + 'guides/man/flox-install.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/build-and-publish.md' contains a relative link + '../explanations/manifest-builds.md#example-configuration-files', but the target 'guides/explanations/manifest-builds.md' + is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/ci-cd.md' contains a relative link '../man/flox-containerize.md', but the target + 'guides/man/flox-containerize.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/ci-cd.md' contains a relative link './sharing-environments.md', but the target + 'guides/going-deeper/sharing-environments.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/ci-cd.md' contains a relative link './customizing-environments.md', but the target + 'guides/going-deeper/customizing-environments.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/composition.md' contains a relative link '../man/flox-init.md', but the target + 'guides/man/flox-init.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/composition.md' contains a relative link '../man/flox-install.md', but the target + 'guides/man/flox-install.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/composition.md' contains a relative link '../explanations/floxhub.md', but the target + 'guides/explanations/floxhub.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/composition.md' contains a relative link '../man/flox-pull.md', but the target + 'guides/man/flox-pull.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/composition.md' contains a relative link '../man/flox-edit.md', but the target + 'guides/man/flox-edit.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/composition.md' contains a relative link '../man/flox-list.md', but the target + 'guides/man/flox-list.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/composition.md' contains a relative link '../man/flox-edit.md', but the target + 'guides/man/flox-edit.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link './default-environment.md', but + the target 'guides/going-deeper/default-environment.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link './default-environment.md', but + the target 'guides/going-deeper/default-environment.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link '../man/flox-install.md', but + the target 'guides/man/flox-install.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link '../man/flox-list.md', but the + target 'guides/man/flox-list.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link '../man/flox-activate.md', but + the target 'guides/man/flox-activate.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link '../man/flox-init.md', but the + target 'guides/man/flox-init.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link '../man/flox-install.md', but + the target 'guides/man/flox-install.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link './sharing-environments.md', + but the target 'guides/going-deeper/sharing-environments.md' is not found among documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link + './customizing-environments.md', but the target 'guides/going-deeper/customizing-environments.md' is not found among + documentation files. +WARNING - Doc file 'guides/going-deeper/layering-multiple-environments.md' contains a relative link './multi-arch-environments.md', + but the target 'guides/going-deeper/multi-arch-environments.md' is not found among documentation files. +WARNING - Doc file 'languages/c.md' contains a relative link '../../explanations/builds.md', but the target + '../explanations/builds.md' is not found among documentation files. Did you mean '../explanations/builds.md'? +WARNING - Doc file 'languages/go.md' contains a relative link '../../explanations/builds.md', but the target + '../explanations/builds.md' is not found among documentation files. Did you mean '../explanations/builds.md'? +WARNING - Doc file 'languages/go.md' contains a relative link '../../explanations/manifest-builds.md#pure-builds', but the target + '../explanations/manifest-builds.md' is not found among documentation files. Did you mean + '../explanations/manifest-builds.md#pure-builds'? +WARNING - Doc file 'languages/go.md' contains a relative link '../../explanations/nix-expression-builds.md#generating-hashes', but + the target '../explanations/nix-expression-builds.md' is not found among documentation files. Did you mean + '../explanations/nix-expression-builds.md#generating-hashes'? +WARNING - Doc file 'languages/jvm.md' contains a relative link '../../explanations/builds.md', but the target + '../explanations/builds.md' is not found among documentation files. Did you mean '../explanations/builds.md'? +WARNING - Doc file 'languages/nodejs.md' contains a relative link '../../explanations/builds.md', but the target + '../explanations/builds.md' is not found among documentation files. Did you mean '../explanations/builds.md'? +WARNING - Doc file 'languages/nodejs.md' contains a relative link '../../explanations/manifest-builds.md#pure-builds', but the + target '../explanations/manifest-builds.md' is not found among documentation files. Did you mean + '../explanations/manifest-builds.md#pure-builds'? +WARNING - Doc file 'languages/python.md' contains a relative link '../../explanations/builds.md', but the target + '../explanations/builds.md' is not found among documentation files. Did you mean '../explanations/builds.md'? +WARNING - Doc file 'languages/ruby.md' contains a relative link '../../explanations/builds.md', but the target + '../explanations/builds.md' is not found among documentation files. Did you mean '../explanations/builds.md'? +WARNING - Doc file 'languages/ruby.md' contains a relative link '../../explanations/manifest-builds.md#pure-builds', but the target + '../explanations/manifest-builds.md' is not found among documentation files. Did you mean + '../explanations/manifest-builds.md#pure-builds'? +WARNING - Doc file 'languages/rust.md' contains a relative link '../../explanations/builds.md', but the target + '../explanations/builds.md' is not found among documentation files. Did you mean '../explanations/builds.md'? +WARNING - Doc file 'languages/rust.md' contains a relative link '../../explanations/manifest-builds.md#pure-builds', but the target + '../explanations/manifest-builds.md' is not found among documentation files. Did you mean + '../explanations/manifest-builds.md#pure-builds'? +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../../explanations/environments.md#manifesttoml', but the + target '../explanations/environments.md' is not found among documentation files. Did you mean + '../explanations/environments.md#manifesttoml'? +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../../install-flox/install.md', but the target + '../install-flox/install.md' is not found among documentation files. Did you mean '../install-flox/install.md'? +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../../man/flox-search.md', but the target + '../man/flox-search.md' is not found among documentation files. Did you mean '../man/flox-search.md'? +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../../man/flox-install.md', but the target + '../man/flox-install.md' is not found among documentation files. Did you mean '../man/flox-install.md'? +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../../man/flox-uninstall.md', but the target + '../man/flox-uninstall.md' is not found among documentation files. Did you mean '../man/flox-uninstall.md'? +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../default-environment.md', but the target + 'default-environment.md' is not found among documentation files. +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../default-environment.md#initial-setup', but the target + 'default-environment.md' is not found among documentation files. +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../../man/flox-envs.md', but the target '../man/flox-envs.md' + is not found among documentation files. Did you mean '../man/flox-envs.md'? +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../../man/flox-list.md', but the target '../man/flox-list.md' + is not found among documentation files. Did you mean '../man/flox-list.md'? +WARNING - Doc file 'migrations/homebrew.md' contains a relative link '../creating-environments.md', but the target + 'creating-environments.md' is not found among documentation files. +WARNING - Doc file 'migrations/nvm.md' contains a relative link '../../explanations/environments.md', but the target + '../explanations/environments.md' is not found among documentation files. Did you mean '../explanations/environments.md'? +WARNING - Doc file 'migrations/nvm.md' contains a relative link '../../explanations/services.md', but the target + '../explanations/services.md' is not found among documentation files. Did you mean '../explanations/services.md'? +WARNING - Doc file 'migrations/nvm.md' contains a relative link '../../install-flox/install.md', but the target + '../install-flox/install.md' is not found among documentation files. Did you mean '../install-flox/install.md'? +WARNING - Doc file 'migrations/nvm.md' contains a relative link '../../man/manifest.toml.md', but the target + '../man/manifest.toml.md' is not found among documentation files. Did you mean '../man/manifest.toml.md'?