Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions concepts/manifest-builds.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion concepts/nix-expression-builds.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 6 additions & 4 deletions concepts/package-groups.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
A **catalog revision** is a snapshot of that subset of packages
at a specific `nixpkgs` commit.
</Note>
Think of package groups as a convenient way to partition the resolver's search space into discrete subproblems. They make it easier for the resolver to compute a functioning dependency graph.

Check warning on line 22 in concepts/package-groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (flox) - vale-spellcheck

concepts/package-groups.mdx#L22

Did you really mean 'resolver's'?

Package groups are also useful as an **organizational tool**. You can use them to separate runtime dependencies, dev tools, and other categories of tooling into logical groupings in the [Flox environment's manifest](/concepts/environments). This makes environments with a large number of dependencies easier to read and maintain. In Flox [manifest builds](/concepts/manifest-builds), you can use package groups to keep dev-time tools out of the build context.

Expand Down Expand Up @@ -61,12 +61,12 @@

## 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…<br/>(nixpkgs commit 2026-03-18)"]
Expand All @@ -78,7 +78,9 @@
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]
Expand Down Expand Up @@ -443,7 +445,7 @@
| --- | --- |
| 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 |
Expand Down Expand Up @@ -579,6 +581,6 @@
- **Python extensions** must link against the same `libpython`. If `numpy` and `scipy` link against different `libpython` builds, importing both in the same interpreter will crash. Putting them in the same group guarantees they share the same `libpython`.
- **C/C++ libraries** that pass data structures between each other (e.g., `libcurl` calling into `openssl`) must agree on struct layouts and ABI. Same group guarantees this.

Package groups also improve the Flox resolver's performance because it only needs to search for a compatible `nixpkgs` revision that satisfies all packages in a constrained set—i.e., the package group. Fewer packages per group means a smaller constraint-solving search space.

Check warning on line 584 in concepts/package-groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (flox) - vale-spellcheck

concepts/package-groups.mdx#L584

Did you really mean 'resolver's'?

This makes it faster and less costly to resolve a coherent dependency graph.
2 changes: 1 addition & 1 deletion languages/rust.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Loading