Add 'nix nar' manpages

This commit is contained in:
Eelco Dolstra 2020-12-09 19:21:48 +01:00
parent a407d14339
commit 2cc02bbe76
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
8 changed files with 98 additions and 15 deletions

View file

@ -62,6 +62,13 @@ struct CmdCatNar : StoreCommand, MixCat
return "print the contents of a file inside a NAR file on stdout";
}
std::string doc() override
{
return
#include "nar-cat.md"
;
}
void run(ref<Store> store) override
{
cat(makeNarAccessor(make_ref<std::string>(readFile(narPath))));

View file

@ -49,14 +49,11 @@ struct CmdDumpPath2 : Command
return "serialise a path to stdout in NAR format";
}
Examples examples() override
std::string doc() override
{
return {
Example{
"To serialise directory 'foo' as a NAR:",
"nix nar dump-path ./foo"
},
};
return
#include "nar-dump-path.md"
;
}
void run() override

View file

@ -75,6 +75,8 @@ struct MixLs : virtual Args, MixJSON
if (json) {
JSONPlaceholder jsonRoot(std::cout);
if (showDirectory)
throw UsageError("'--directory' is useless with '--json'");
listNar(jsonRoot, accessor, path, recursive);
} else
listText(accessor);
@ -127,14 +129,11 @@ struct CmdLsNar : Command, MixLs
expectArg("path", &path);
}
Examples examples() override
std::string doc() override
{
return {
Example{
"To list a specific file in a NAR:",
"nix nar ls -l hello.nar /bin/hello"
},
};
return
#include "nar-ls.md"
;
}
std::string description() override

19
src/nix/nar-cat.md Normal file
View file

@ -0,0 +1,19 @@
R""(
# Examples
* List a file in a NAR and pipe it through `gunzip`:
```console
# nix nar cat ./hello.nar /share/man/man1/hello.1.gz | gunzip
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.4.
.TH HELLO "1" "November 2014" "hello 2.10" "User Commands"
```
# Description
This command prints on standard output the contents of the regular
file *path* inside the NAR file *nar*.
)""

17
src/nix/nar-dump-path.md Normal file
View file

@ -0,0 +1,17 @@
R""(
# Examples
* To serialise directory `foo` as a NAR:
```console
# nix nar dump-path ./foo > foo.nar
```
# Description
This command generates a NAR file containing the serialisation of
*path*, which must contain only regular files, directories and
symbolic links. The NAR is written to standard output.
)""

24
src/nix/nar-ls.md Normal file
View file

@ -0,0 +1,24 @@
R""(
# Examples
* To list a specific file in a NAR:
```console
# nix nar ls -l ./hello.nar /bin/hello
-r-xr-xr-x 38184 hello
```
* To recursively list the contents of a directory inside a NAR, in JSON
format:
```console
# nix nar ls --json -R ./hello.nar /bin
{"type":"directory","entries":{"hello":{"type":"regular","size":38184,"executable":true,"narOffset":400}}}
```
# Description
This command shows information about a *path* inside NAR file *nar*.
)""

View file

@ -9,7 +9,14 @@ struct CmdNar : NixMultiCommand
std::string description() override
{
return "query the contents of NAR files";
return "create or inspect NAR files";
}
std::string doc() override
{
return
#include "nar.md"
;
}
Category category() override { return catUtility; }

13
src/nix/nar.md Normal file
View file

@ -0,0 +1,13 @@
R""(
# Description
`nix nar` provides several subcommands for creating and inspecting
*Nix Archives* (NARs).
# File format
For the definition of the NAR file format, see Figure 5.2 in
https://edolstra.github.io/pubs/phd-thesis.pdf.
)""