forked from mirrors/nixpkgs
lib.sources: Improve docs
Change comment type so than nixdoc picks them up into Nixpkgs manual. Also improve phrasing a bit and move stuff around so that it is formatted better.
This commit is contained in:
Jan Tojnar
parent
2f012d93ed
commit
1e1396aafc
115
lib/sources.nix
115
lib/sources.nix
|
|
@ -20,17 +20,26 @@ let
|
|||
readFile
|
||||
;
|
||||
|
||||
# Returns the type of a path: regular (for file), symlink, or directory
|
||||
pathType = p: getAttr (baseNameOf p) (readDir (dirOf p));
|
||||
/*
|
||||
Returns the type of a path: regular (for file), symlink, or directory.
|
||||
*/
|
||||
pathType = path: getAttr (baseNameOf path) (readDir (dirOf path));
|
||||
|
||||
# Returns true if the path exists and is a directory, false otherwise
|
||||
pathIsDirectory = p: if pathExists p then (pathType p) == "directory" else false;
|
||||
/*
|
||||
Returns true if the path exists and is a directory, false otherwise.
|
||||
*/
|
||||
pathIsDirectory = path: if pathExists path then (pathType path) == "directory" else false;
|
||||
|
||||
# Returns true if the path exists and is a regular file, false otherwise
|
||||
pathIsRegularFile = p: if pathExists p then (pathType p) == "regular" else false;
|
||||
/*
|
||||
Returns true if the path exists and is a regular file, false otherwise.
|
||||
*/
|
||||
pathIsRegularFile = path: if pathExists path then (pathType path) == "regular" else false;
|
||||
|
||||
# Bring in a path as a source, filtering out all Subversion and CVS
|
||||
# directories, as well as backup files (*~).
|
||||
/*
|
||||
A basic filter for `cleanSourceWith` that removes
|
||||
directories of version control system, backup files (*~)
|
||||
and some generated files.
|
||||
*/
|
||||
cleanSourceFilter = name: type: let baseName = baseNameOf (toString name); in ! (
|
||||
# Filter out version control software files/directories
|
||||
(baseName == ".git" || type == "directory" && (baseName == ".svn" || baseName == "CVS" || baseName == ".hg")) ||
|
||||
|
|
@ -48,43 +57,48 @@ let
|
|||
(type == "unknown")
|
||||
);
|
||||
|
||||
# Filters a source tree removing version control files and directories using cleanSourceWith
|
||||
#
|
||||
# Example:
|
||||
# cleanSource ./.
|
||||
/*
|
||||
Filters a source tree removing version control files and directories using cleanSourceFilter.
|
||||
|
||||
Example:
|
||||
cleanSource ./.
|
||||
*/
|
||||
cleanSource = src: cleanSourceWith { filter = cleanSourceFilter; inherit src; };
|
||||
|
||||
# Like `builtins.filterSource`, except it will compose with itself,
|
||||
# allowing you to chain multiple calls together without any
|
||||
# intermediate copies being put in the nix store.
|
||||
#
|
||||
# lib.cleanSourceWith {
|
||||
# filter = f;
|
||||
# src = lib.cleanSourceWith {
|
||||
# filter = g;
|
||||
# src = ./.;
|
||||
# };
|
||||
# }
|
||||
# # Succeeds!
|
||||
#
|
||||
# builtins.filterSource f (builtins.filterSource g ./.)
|
||||
# # Fails!
|
||||
#
|
||||
# Parameters:
|
||||
#
|
||||
# src: A path or cleanSourceWith result to filter and/or rename.
|
||||
#
|
||||
# filter: A function (path -> type -> bool)
|
||||
# Optional with default value: constant true (include everything)
|
||||
# The function will be combined with the && operator such
|
||||
# that src.filter is called lazily.
|
||||
# For implementing a filter, see
|
||||
# https://nixos.org/nix/manual/#builtin-filterSource
|
||||
#
|
||||
# name: Optional name to use as part of the store path.
|
||||
# This defaults to `src.name` or otherwise `"source"`.
|
||||
#
|
||||
cleanSourceWith = { filter ? _path: _type: true, src, name ? null }:
|
||||
/*
|
||||
Like `builtins.filterSource`, except it will compose with itself,
|
||||
allowing you to chain multiple calls together without any
|
||||
intermediate copies being put in the nix store.
|
||||
|
||||
Example:
|
||||
lib.cleanSourceWith {
|
||||
filter = f;
|
||||
src = lib.cleanSourceWith {
|
||||
filter = g;
|
||||
src = ./.;
|
||||
};
|
||||
}
|
||||
# Succeeds!
|
||||
|
||||
builtins.filterSource f (builtins.filterSource g ./.)
|
||||
# Fails!
|
||||
|
||||
*/
|
||||
cleanSourceWith =
|
||||
{
|
||||
# A path or cleanSourceWith result to filter and/or rename.
|
||||
src,
|
||||
# Optional with default value: constant true (include everything)
|
||||
# The function will be combined with the && operator such
|
||||
# that src.filter is called lazily.
|
||||
# For implementing a filter, see
|
||||
# https://nixos.org/nix/manual/#builtin-filterSource
|
||||
# Type: A function (path -> type -> bool)
|
||||
filter ? _path: _type: true,
|
||||
# Optional name to use as part of the store path.
|
||||
# This defaults to `src.name` or otherwise `"source"`.
|
||||
name ? null
|
||||
}:
|
||||
let
|
||||
orig = toSourceAttributes src;
|
||||
in fromSourceAttributes {
|
||||
|
|
@ -116,9 +130,11 @@ let
|
|||
satisfiesSubpathInvariant = src ? satisfiesSubpathInvariant && src.satisfiesSubpathInvariant;
|
||||
};
|
||||
|
||||
# Filter sources by a list of regular expressions.
|
||||
#
|
||||
# E.g. `src = sourceByRegex ./my-subproject [".*\.py$" "^database.sql$"]`
|
||||
/*
|
||||
Filter sources by a list of regular expressions.
|
||||
|
||||
Example: src = sourceByRegex ./my-subproject [".*\.py$" "^database.sql$"]
|
||||
*/
|
||||
sourceByRegex = src: regexes:
|
||||
let
|
||||
isFiltered = src ? _isLibCleanSourceWith;
|
||||
|
|
@ -153,8 +169,11 @@ let
|
|||
|
||||
pathIsGitRepo = path: (tryEval (commitIdFromGitRepo path)).success;
|
||||
|
||||
# Get the commit id of a git repo
|
||||
# Example: commitIdFromGitRepo <nixpkgs/.git>
|
||||
/*
|
||||
Get the commit id of a git repo.
|
||||
|
||||
Example: commitIdFromGitRepo <nixpkgs/.git>
|
||||
*/
|
||||
commitIdFromGitRepo =
|
||||
let readCommitFromFile = file: path:
|
||||
let fileName = toString path + "/" + file;
|
||||
|
|
|
|||
Loading…
Reference in a new issue