From 6b938bf25faf71baaf7a5b55a84dc91ce2f14752 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Fri, 25 Sep 2026 10:24:16 -0700 Subject: [PATCH 1/2] docs(package-groups): call the default group "Default (`toplevel`)" FloxHub labels the default package group **Default**, while CLI messages and the lockfile call it `toplevel`, and a manifest only names it when `pkg-group = "toplevel"` is set explicitly. Make the docs say "Default package group (`toplevel`)" at the first mention so readers learning Flox see that the two names are the same group: - concepts/package-groups: retitle the section to "Default Group (`toplevel`)", label the diagram's subgraph "Default (toplevel)", and explain that FloxHub, the CLI, and the lockfile name the same group differently. - concepts/manifest-builds, concepts/nix-expression-builds, languages/rust: use "Default package group (`toplevel`)" at the first mention. Keep literal `toplevel` where it refers to CLI output, lockfile keys, or `flox upgrade toplevel`. Co-Authored-By: Claude Opus 5.5 --- concepts/manifest-builds.mdx | 4 ++-- concepts/nix-expression-builds.mdx | 2 +- concepts/package-groups.mdx | 8 +++++--- languages/rust.mdx | 2 +- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/concepts/manifest-builds.mdx b/concepts/manifest-builds.mdx index d6bcf1e..cbf41c3 100644 --- a/concepts/manifest-builds.mdx +++ b/concepts/manifest-builds.mdx @@ -154,8 +154,8 @@ Your package likely has dependencies, and those dependencies have their own depe We call this complete set of dependencies the "transitive closure", or simply "the closure", of your package. A large closure for your package has no direct impact on runtime performance, but it means that your package requires more disk space to install and requires more bandwidth to copy from one place to another. -By default all of the packages in the default [package group](/man/manifest.toml#package-descriptors) are included as dependencies of your packages, but these packages may only be needed by your package at _build_ time or _development_ time, not _run_ time. -As a reminder, the default package group is called `toplevel`, and all packages installed to an environment without an explicit `pkg-group` are placed into this package group. +By default all of the packages in the Default [package group](/man/manifest.toml#package-descriptors) (`toplevel`) are included as dependencies of your packages, but these packages may only be needed by your package at _build_ time or _development_ time, not _run_ time. +As a reminder, all packages installed to an environment without an explicit `pkg-group` are placed into this package group. The `runtime-packages` option allows you to trim down the packages from the `toplevel` package group that are included as runtime dependencies of your package. This option is a list of `install-id`s from the `toplevel` package group. diff --git a/concepts/nix-expression-builds.mdx b/concepts/nix-expression-builds.mdx index aa0e9c6..f8fbfd7 100644 --- a/concepts/nix-expression-builds.mdx +++ b/concepts/nix-expression-builds.mdx @@ -9,7 +9,7 @@ See the [builds concept](/concepts/builds) page for an overview of the different Nix expression builds are defined by creating files in the `.flox/pkgs/` directory of a Flox environment. These expressions are written in the Nix language, which is incredibly powerful and results in truly reproducible builds. -The environment that contains the builds doesn't need to have any packages installed because all of the build's dependencies are defined within the expression, but if there are any packages installed then Flox will attempt to produce a build that is compatible with any packages in the "toplevel" [package group](/man/manifest.toml#package-descriptors). +The environment that contains the builds doesn't need to have any packages installed because all of the build's dependencies are defined within the expression, but if there are any packages installed then Flox will attempt to produce a build that is compatible with any packages in the Default [package group](/man/manifest.toml#package-descriptors) (`toplevel`). ## Defining builds diff --git a/concepts/package-groups.mdx b/concepts/package-groups.mdx index f378ecd..f716eed 100644 --- a/concepts/package-groups.mdx +++ b/concepts/package-groups.mdx @@ -61,12 +61,12 @@ Every dependency in a package group gets pinned to the same historical `nixpkgs` ## How Package Groups Work -### Default Group: `toplevel` +### Default Group (`toplevel`) ```mermaid %%{init: {'theme':'base','themeVariables':{'primaryColor':'#e8eef6','primaryBorderColor':'#7d96b8','primaryTextColor':'#1f2937','lineColor':'#7d96b8','clusterBkg':'#f4f6fa','clusterBorder':'#7d96b8','edgeLabelBackground':'#ffffff'}}}%% flowchart LR - subgraph toplevel ["Group: toplevel"] + subgraph toplevel ["Group: Default (toplevel)"] direction TB tp["bash, curl, git, jq"] tr["Catalog rev b40629e…
(nixpkgs commit 2026-03-18)"] @@ -78,7 +78,9 @@ flowchart LR end ``` -When you install a package with `flox install`, it goes into **`toplevel`**, the default package group. `toplevel` is an **implicit** package group: any package installed without defining a `pkg-group` field gets placed into it. +When you install a package with `flox install`, it goes into the **Default package group (`toplevel`)**. This is an **implicit** package group: any package installed without defining a `pkg-group` field gets placed into it. + +FloxHub labels this group **Default**, while CLI messages and the lockfile call it `toplevel`. Both names refer to the same group. The name `toplevel` appears in your manifest only if you set `pkg-group = "toplevel"` explicitly. ```toml [install] diff --git a/languages/rust.mdx b/languages/rust.mdx index a77397e..8308cc8 100644 --- a/languages/rust.mdx +++ b/languages/rust.mdx @@ -210,7 +210,7 @@ libiconv.systems = ["aarch64-darwin", "x86_64-darwin"] On Linux, Rust executables link against `libgcc` for stack unwinding. `libgcc` is provided as part of the `gcc` package, which means that `gcc` needs to be available to your package at runtime on Linux. -This happens by default if the `gcc` package is installed in the `toplevel` (default) package group, i.e. there is no `pkg-group` set. +This happens by default if the `gcc` package is installed in the Default package group (`toplevel`), i.e. there is no `pkg-group` set. ```toml title="manifest.toml" gcc.pkg-path = "gcc" From 15c440de29b0e93164277b8446f6cecaeb23514c Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Fri, 25 Sep 2026 10:27:14 -0700 Subject: [PATCH 2/2] docs(package-groups): use "Default package group (`toplevel`)" in Nix comparison table The Appendix A comparison table still said "`toplevel` default group", which didn't match the naming used everywhere else on the page. Co-Authored-By: Claude Opus 5.5 --- concepts/package-groups.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/package-groups.mdx b/concepts/package-groups.mdx index f716eed..c20e5f2 100644 --- a/concepts/package-groups.mdx +++ b/concepts/package-groups.mdx @@ -445,7 +445,7 @@ If you're familiar with Nix flakes, Flox package groups map directly to patterns | --- | --- | | Package group (single) | Pinned nixpkgs flake input at a specific rev | | Multiple pkg-groups | Multiple nixpkgs inputs (`nixpkgs`, `nixpkgs-stable`) | -| `toplevel` default group | Primary `nixpkgs` input in a flake | +| Default package group (`toplevel`) | Primary `nixpkgs` input in a flake | | Group upgrade (`flox upgrade`) | `nix flake update nixpkgs` (per-input) | | `priority` | `meta.priority` in nixpkgs | | Lock file group entries | `flake.lock` input nodes |