wroclaw-git-backups/nix
1
0
Fork 0
mirror of https://github.com/NixOS/nix synced 2025-07-01 12:37:59 +02:00
Code Activity

Extend internal API docs, part 2

Browse source 
Picking up from #8111.

Co-authored-by: Eelco Dolstra <edolstra@gmail.com>
This commit is contained in:
John Ericson 2023-03-26 21:12:25 -04:00
parent 8ae9d66940
commit abd5e7dec0
32 changed files with 640 additions and 359 deletions
Download patch file Download diff file Expand all files Collapse all files

107
src/libutil/archive.hh
View file

@ -7,54 +7,71 @@
namespace nix {
/* dumpPath creates a Nix archive of the specified path. The format
is as follows:
IF path points to a REGULAR FILE:
dump(path) = attrs(
[ ("type", "regular")
, ("contents", contents(path))
])
IF path points to a DIRECTORY:
dump(path) = attrs(
[ ("type", "directory")
, ("entries", concat(map(f, sort(entries(path)))))
])
where f(fn) = attrs(
[ ("name", fn)
, ("file", dump(path + "/" + fn))
])
where:
attrs(as) = concat(map(attr, as)) + encN(0)
attrs((a, b)) = encS(a) + encS(b)
encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
encN(n) = 64-bit little-endian encoding of n.
contents(path) = the contents of a regular file.
sort(strings) = lexicographic sort by 8-bit value (strcmp).
entries(path) = the entries of a directory, without `.' and
`..'.
`+' denotes string concatenation. */
/**
* dumpPath creates a Nix archive of the specified path.
*
* @param path the file system data to dump. Dumping is recursive so if
* this is a directory we dump it and all its children.
*
* @param [out] sink The serialised archive is fed into this sink.
*
* @param filter Can be used to skip certain files.
*
* The format is as follows:
*
* IF path points to a REGULAR FILE:
* dump(path) = attrs(
* [ ("type", "regular")
* , ("contents", contents(path))
* ])
*
* IF path points to a DIRECTORY:
* dump(path) = attrs(
* [ ("type", "directory")
* , ("entries", concat(map(f, sort(entries(path)))))
* ])
* where f(fn) = attrs(
* [ ("name", fn)
* , ("file", dump(path + "/" + fn))
* ])
*
* where:
*
* attrs(as) = concat(map(attr, as)) + encN(0)
* attrs((a, b)) = encS(a) + encS(b)
*
* encS(s) = encN(len(s)) + s + (padding until next 64-bit boundary)
*
* encN(n) = 64-bit little-endian encoding of n.
*
* contents(path) = the contents of a regular file.
*
* sort(strings) = lexicographic sort by 8-bit value (strcmp).
*
* entries(path) = the entries of a directory, without `.' and
* `..'.
*
* `+' denotes string concatenation.
*/
void dumpPath(const Path & path, Sink & sink,
PathFilter & filter = defaultPathFilter);
/* Same as `void dumpPath()`, but returns the last modified date of the path */
/**
* Same as dumpPath(), but returns the last modified date of the path.
*/
time_t dumpPathAndGetMtime(const Path & path, Sink & sink,
PathFilter & filter = defaultPathFilter);
/**
* Dump an archive with a single file with these contents.
*
* @param s Contents of the file.
*/
void dumpString(std::string_view s, Sink & sink);
/* FIXME: fix this API, it sucks. */
/**
* \todo Fix this API, it sucks.
*/
struct ParseSink
{
virtual void createDirectory(const Path & path) { };
@ -68,8 +85,10 @@ struct ParseSink
virtual void createSymlink(const Path & path, const std::string & target) { };
};
/* If the NAR archive contains a single file at top-level, then save
the contents of the file to `s'. Otherwise barf. */
/**
* If the NAR archive contains a single file at top-level, then save
* the contents of the file to `s'. Otherwise barf.
*/
struct RetrieveRegularNARSink : ParseSink
{
bool regular = true;
@ -97,7 +116,9 @@ void parseDump(ParseSink & sink, Source & source);
void restorePath(const Path & path, Source & source);
/* Read a NAR from 'source' and write it to 'sink'. */
/**
* Read a NAR from 'source' and write it to 'sink'.
*/
void copyNAR(Source & source, Sink & sink);
void copyPath(const Path & from, const Path & to);