Next: (maak container), Up: API
The archive helpers a project needs around a release: make a tarball or a zip, unpack one, and see what is inside without unpacking it. They are thin, argument-list builders over the system tools rather than a second implementation of either format, so a tarball made here is the same tarball ‘tar’ would have made by hand.
Two families are exported, and each has a command builder next to the procedure that runs it:
tar-create, tar-extract, tar-list zip-create, zip-extract, zip-list
The ‘-argv’ builders return the argument list without running anything. They are what the procedures use, and they are exported because a task that wants to log, inspect or extend a command should not have to reimplement the flag order that the format requires.
Nothing here changes maak’s working directory permanently. ‘#:directory’ names the tree the files are read from, and the archive path is still resolved against the directory the task was started in.
One trap is worth knowing about, because tar reports it badly. Writing the archive inside the tree it is packing means tar reads a file that is still growing, and GNU tar aborts with "file changed as we read it" and exit code 1. A relative output name is therefore always written in the task directory, and a task that packs "." should not hand tar an absolute output path that points back into that tree.
Return the tar flags that select COMPRESSION, as a list.
The names accepted are the ones a release actually uses: none,
gz, bz2, xz and zstd. gzip,
bzip2 and zst are accepted as aliases, so a caller can
spell the compressor rather than its extension. A name that is not one
of these raises a maak error instead of producing an archive tar would
refuse to read.
Write FILES as the tarball OUTPUT.
FILES is a list of paths relative to DIRECTORY, which defaults to the current directory. The compressor follows the output’s extension unless COMPRESSION names one, and EXCLUDE is a list of patterns to leave out.
OUTPUT is written in the directory the task started in, not in DIRECTORY, so packing the current directory does not put the growing tarball into the tree tar is reading. Passing an absolute OUTPUT that points inside the packed tree does, and tar then fails with "file changed as we read it".
(tar-create "maak-1.0.tar.gz" (list "src" "README.org" "COPYING")
#:exclude (list "*.o" "*.go"))
(tar-create "maak-1.0.tar.xz" (list ".") #:compression "xz")
Return the argv that writes FILES as the tarball OUTPUT.
FILES is a list of paths relative to DIRECTORY. With COMPRESSION
auto, the output’s extension names the compressor (see
tar-infer-compression); any other value is passed to
tar-compression-option. EXCLUDE is a list of patterns, each
passed as --exclude=PATTERN. With VERBOSE? the argv includes
-v, so tar prints every file it adds.
Unpack ARCHIVE, into DIRECTORY when one is named.
STRIP-COMPONENTS drops leading path components as the files are written; use 1 for the usual release tarball that wraps everything in one directory.
(tar-extract "maak-1.0.tar.gz" #:directory "build" #:strip-components 1)
Return the argv that unpacks ARCHIVE.
The compressor is detected from the archive itself, which is why no compression flag is needed here. DIRECTORY is where the files are written, and STRIP-COMPONENTS drops that many leading path components, which is how a release tarball with a single top-level directory is unpacked into the current one.
(tar-extract-argv "project-1.0.tar.gz" #:directory "build" #:strip-components 1)
Print the names of the files in ARCHIVE, without unpacking it.
With VERBOSE? tar prints the long listing instead of bare names.
Return the argv that prints the names of the files in ARCHIVE.
Write FILES as the zip archive OUTPUT.
FILES is a list of paths relative to DIRECTORY, which defaults to the current directory. The archive itself is written relative to the directory the task started in, so a ‘#:directory "dist"’ does not leave the zip inside dist.
(zip-create "maak-1.0.zip" (list "src" "README.org")
#:exclude (list "*.go" "*.o"))
Return the argv that writes FILES as the zip archive OUTPUT.
The archive is created in the current directory; zip-create is
the one that changes into #:directory for the duration of the
command, because Info-ZIP has no -C-style option to name a tree.
EXCLUDE is a list of patterns passed as -x, after the files,
which is where zip expects them. #:junk-paths? stores bare file
names rather than the paths they were found under.
Unpack ARCHIVE, into DIRECTORY when one is named.
With OVERWRITE? (the default) existing files are replaced without a prompt; with it #f they are kept and unzip skips them.
Return the argv that unpacks ARCHIVE.
OVERWRITE? is unzip’s -o: files already there are replaced
rather than asked about, which is what an unattended task needs.
DIRECTORY is where the files are written.
Print a listing of the files in ARCHIVE, without unpacking it.
Return the argv that lists the contents of ARCHIVE.
Next: (maak container), Up: API