Official preference when multiple aliases are available?

Development Documentation
1

I have been looking for guidance on best practice regarding the usage of aliased library functions, such as builtins.concatStringsSep, lib.concatStringsSep and lib.strings.concatStringsSep, but was unable to find any so far.

Quickly searching through the current (4e64dfc2) Nixpkgs repo yields the following results on usage statistics:

nixpkgs ❯ rg 'builtins\.concatStringsSep' | wc -l 301 nixpkgs ❯ rg 'lib\.concatStringsSep' | wc -l 1184 nixpkgs ❯ rg 'lib\.strings\.concatStringsSep' | wc -l 53

There are times, where I would prefer builtin, as it doesn’t require importing lib, which can make evaluating quick expressions in the shell easier. At other times I feel like using everything from lib would be more consistent and I wouldn’t have to worry about where something comes from, thus less things to remember and keep track of. On the other hand using the full lib.module.function form makes it feel a bit more organized.

Are there reasons that I haven’t thought of or official recommendations that I haven’t managed to find, or is it really just up to personal preference?

Thanks in advance!

ps.: Sorry if I have selected the wrong category for this topic. I felt like it would fit in here, but feel free to move it elsewhere if I was wrong!

2 Likes
2

The existence of it in lib is merely for convenience, in your own projects you can use whatever you find convenient.

3

That, and being able to improve the implementations. builtins are much harder to change, even subtly (e.g. list ordering), because nix has to uphold backwards compatibility for reproducibility’s sake. Functions in lib can change by NixOS release.

The advice I’ve seen is to prefer lib - assuming you’re developing in a context where using nixpkgs isn’t an unreasonable overhead - since those functions can sometimes be more efficient and let you benefit from improvements over time. This also matters especially in nixpkgs since changes to builtins can be taped over using lib. This only matters rarely, though, I only recall seeing one case where there is a meaningful difference.

3 Likes
4

I tend to use lib, as for some functions I forget whether they are in builtins or not :slight_smile:

1 Like