lib/filesystem.nix

   1 /**
   2   Functions for querying information about the filesystem
   3   without copying any files to the Nix store.
   4 */
   5 { lib }:
   6
   7 # Tested in lib/tests/filesystem.sh
   8 let
   9   inherit (builtins)
  10     readDir
  11     pathExists
  12     toString
  13     ;
  14
  15   inherit (lib.attrsets)
  16     mapAttrs'
  17     filterAttrs
  18     ;
  19
  20   inherit (lib.filesystem)
  21     pathType
  22     ;
  23
  24   inherit (lib.strings)
  25     hasSuffix
  26     removeSuffix
  27     ;
  28 in
  29
  30 {
  31
  32   /**
  33     The type of a path. The path needs to exist and be accessible.
  34     The result is either "directory" for a directory, "regular" for a regular file, "symlink" for a symlink, or "unknown" for anything else.
  35
  36     # Inputs
  37
  38     path
  39
  40     : The path to query
  41
  42     # Type
  43
  44     ```
  45     pathType :: Path -> String
  46     ```
  47
  48     # Examples
  49     :::{.example}
  50     ## `lib.filesystem.pathType` usage example
  51
  52     ```nix
  53     pathType /.
  54     => "directory"
  55
  56     pathType /some/file.nix
  57     => "regular"
  58     ```
  59
  60     :::
  61   */
  62   pathType =
  63     builtins.readFileType or
  64     # Nix <2.14 compatibility shim
  65     (path:
  66       if ! pathExists path
  67       # Fail irrecoverably to mimic the historic behavior of this function and
  68       # the new builtins.readFileType
  69       then abort "lib.filesystem.pathType: Path ${toString path} does not exist."
  70       # The filesystem root is the only path where `dirOf / == /` and
  71       # `baseNameOf /` is not valid. We can detect this and directly return
  72       # "directory", since we know the filesystem root can't be anything else.
  73       else if dirOf path == path
  74       then "directory"
  75       else (readDir (dirOf path)).${baseNameOf path}
  76     );
  77
  78   /**
  79     Whether a path exists and is a directory.
  80
  81
  82     # Inputs
  83
  84     `path`
  85
  86     : 1\. Function argument
  87
  88     # Type
  89
  90     ```
  91     pathIsDirectory :: Path -> Bool
  92     ```
  93
  94     # Examples
  95     :::{.example}
  96     ## `lib.filesystem.pathIsDirectory` usage example
  97
  98     ```nix
  99     pathIsDirectory /.
 100     => true
 101
 102     pathIsDirectory /this/does/not/exist
 103     => false
 104
 105     pathIsDirectory /some/file.nix
 106     => false
 107     ```
 108
 109     :::
 110   */
 111   pathIsDirectory = path:
 112     pathExists path && pathType path == "directory";
 113
 114   /**
 115     Whether a path exists and is a regular file, meaning not a symlink or any other special file type.
 116
 117
 118     # Inputs
 119
 120     `path`
 121
 122     : 1\. Function argument
 123
 124     # Type
 125
 126     ```
 127     pathIsRegularFile :: Path -> Bool
 128     ```
 129
 130     # Examples
 131     :::{.example}
 132     ## `lib.filesystem.pathIsRegularFile` usage example
 133
 134     ```nix
 135     pathIsRegularFile /.
 136     => false
 137
 138     pathIsRegularFile /this/does/not/exist
 139     => false
 140
 141     pathIsRegularFile /some/file.nix
 142     => true
 143     ```
 144
 145     :::
 146   */
 147   pathIsRegularFile = path:
 148     pathExists path && pathType path == "regular";
 149
 150   /**
 151     A map of all haskell packages defined in the given path,
 152     identified by having a cabal file with the same name as the
 153     directory itself.
 154
 155
 156     # Inputs
 157
 158     `root`
 159
 160     : The directory within to search
 161
 162     # Type
 163
 164     ```
 165     Path -> Map String Path
 166     ```
 167   */
 168   haskellPathsInDir =
 169     root:
 170     let # Files in the root
 171         root-files = builtins.attrNames (builtins.readDir root);
 172         # Files with their full paths
 173         root-files-with-paths =
 174           map (file:
 175             { name = file; value = root + "/${file}"; }
 176           ) root-files;
 177         # Subdirectories of the root with a cabal file.
 178         cabal-subdirs =
 179           builtins.filter ({ name, value }:
 180             builtins.pathExists (value + "/${name}.cabal")
 181           ) root-files-with-paths;
 182     in builtins.listToAttrs cabal-subdirs;
 183   /**
 184     Find the first directory containing a file matching 'pattern'
 185     upward from a given 'file'.
 186     Returns 'null' if no directories contain a file matching 'pattern'.
 187
 188
 189     # Inputs
 190
 191     `pattern`
 192
 193     : The pattern to search for
 194
 195     `file`
 196
 197     : The file to start searching upward from
 198
 199     # Type
 200
 201     ```
 202     RegExp -> Path -> Nullable { path : Path; matches : [ MatchResults ]; }
 203     ```
 204   */
 205   locateDominatingFile =
 206     pattern:
 207     file:
 208     let go = path:
 209           let files = builtins.attrNames (builtins.readDir path);
 210               matches = builtins.filter (match: match != null)
 211                           (map (builtins.match pattern) files);
 212           in
 213             if builtins.length matches != 0
 214               then { inherit path matches; }
 215               else if path == /.
 216                 then null
 217                 else go (dirOf path);
 218         parent = dirOf file;
 219         isDir =
 220           let base = baseNameOf file;
 221               type = (builtins.readDir parent).${base} or null;
 222           in file == /. || type == "directory";
 223     in go (if isDir then file else parent);
 224
 225
 226   /**
 227     Given a directory, return a flattened list of all files within it recursively.
 228
 229
 230     # Inputs
 231
 232     `dir`
 233
 234     : The path to recursively list
 235
 236     # Type
 237
 238     ```
 239     Path -> [ Path ]
 240     ```
 241   */
 242   listFilesRecursive =
 243     dir:
 244     lib.flatten (lib.mapAttrsToList (name: type:
 245     if type == "directory" then
 246       lib.filesystem.listFilesRecursive (dir + "/${name}")
 247     else
 248       dir + "/${name}"
 249   ) (builtins.readDir dir));
 250
 251   /**
 252     Transform a directory tree containing package files suitable for
 253     `callPackage` into a matching nested attribute set of derivations.
 254
 255     For a directory tree like this:
 256
 257     ```
 258     my-packages
 259     ├── a.nix
 260     ├── b.nix
 261     ├── c
 262     │  ├── my-extra-feature.patch
 263     │  ├── package.nix
 264     │  └── support-definitions.nix
 265     └── my-namespace
 266        ├── d.nix
 267        ├── e.nix
 268        └── f
 269           └── package.nix
 270     ```
 271
 272     `packagesFromDirectoryRecursive` will produce an attribute set like this:
 273
 274     ```nix
 275     # packagesFromDirectoryRecursive {
 276     #   callPackage = pkgs.callPackage;
 277     #   directory = ./my-packages;
 278     # }
 279     {
 280       a = pkgs.callPackage ./my-packages/a.nix { };
 281       b = pkgs.callPackage ./my-packages/b.nix { };
 282       c = pkgs.callPackage ./my-packages/c/package.nix { };
 283       my-namespace = {
 284         d = pkgs.callPackage ./my-packages/my-namespace/d.nix { };
 285         e = pkgs.callPackage ./my-packages/my-namespace/e.nix { };
 286         f = pkgs.callPackage ./my-packages/my-namespace/f/package.nix { };
 287       };
 288     }
 289     ```
 290
 291     In particular:
 292     - If the input directory contains a `package.nix` file, then
 293       `callPackage <directory>/package.nix { }` is returned.
 294     - Otherwise, the input directory's contents are listed and transformed into
 295       an attribute set.
 296       - If a file name has the `.nix` extension, it is turned into attribute
 297         where:
 298         - The attribute name is the file name without the `.nix` extension
 299         - The attribute value is `callPackage <file path> { }`
 300       - Other files are ignored.
 301       - Directories are turned into an attribute where:
 302         - The attribute name is the name of the directory
 303         - The attribute value is the result of calling
 304           `packagesFromDirectoryRecursive { ... }` on the directory.
 305
 306         As a result, directories with no `.nix` files (including empty
 307         directories) will be transformed into empty attribute sets.
 308
 309     # Inputs
 310
 311     Structured function argument
 312
 313     : Attribute set containing the following attributes.
 314       Additional attributes are ignored.
 315
 316       `callPackage`
 317
 318       : `pkgs.callPackage`
 319
 320         Type: `Path -> AttrSet -> a`
 321
 322       `directory`
 323
 324       : The directory to read package files from
 325
 326         Type: `Path`
 327
 328
 329     # Type
 330
 331     ```
 332     packagesFromDirectoryRecursive :: AttrSet -> AttrSet
 333     ```
 334
 335     # Examples
 336     :::{.example}
 337     ## `lib.filesystem.packagesFromDirectoryRecursive` usage example
 338
 339     ```nix
 340     packagesFromDirectoryRecursive {
 341       inherit (pkgs) callPackage;
 342       directory = ./my-packages;
 343     }
 344     => { ... }
 345
 346     lib.makeScope pkgs.newScope (
 347       self: packagesFromDirectoryRecursive {
 348         callPackage = self.callPackage;
 349         directory = ./my-packages;
 350       }
 351     )
 352     => { ... }
 353     ```
 354
 355     :::
 356   */
 357   packagesFromDirectoryRecursive =
 358     {
 359       callPackage,
 360       directory,
 361       ...
 362     }:
 363     let
 364       # Determine if a directory entry from `readDir` indicates a package or
 365       # directory of packages.
 366       directoryEntryIsPackage = basename: type:
 367         type == "directory" || hasSuffix ".nix" basename;
 368
 369       # List directory entries that indicate packages in the given `path`.
 370       packageDirectoryEntries = path:
 371         filterAttrs directoryEntryIsPackage (readDir path);
 372
 373       # Transform a directory entry (a `basename` and `type` pair) into a
 374       # package.
 375       directoryEntryToAttrPair = subdirectory: basename: type:
 376         let
 377           path = subdirectory + "/${basename}";
 378         in
 379         if type == "regular"
 380         then
 381         {
 382           name = removeSuffix ".nix" basename;
 383           value = callPackage path { };
 384         }
 385         else
 386         if type == "directory"
 387         then
 388         {
 389           name = basename;
 390           value = packagesFromDirectory path;
 391         }
 392         else
 393         throw
 394           ''
 395             lib.filesystem.packagesFromDirectoryRecursive: Unsupported file type ${type} at path ${toString subdirectory}
 396           '';
 397
 398       # Transform a directory into a package (if there's a `package.nix`) or
 399       # set of packages (otherwise).
 400       packagesFromDirectory = path:
 401         let
 402           defaultPackagePath = path + "/package.nix";
 403         in
 404         if pathExists defaultPackagePath
 405         then callPackage defaultPackagePath { }
 406         else mapAttrs'
 407           (directoryEntryToAttrPair path)
 408           (packageDirectoryEntries path);
 409     in
 410     packagesFromDirectory directory;
 411 }