Represent Packages with pkglite.txt
The output file of
pkglite::pack() uses a standard file
format to allow the storage, exchange, and parsing of the packaged
assets. The specification for this file is detailed below.
Filename and extension
Unless specified, the output file is automatically named.
- A single R package named
pkg1 is packed into
- Multiple R packages named
are packed into
The file extension is
.txt so that one can recognize,
open, and inspect it directly using regular text editors.
The overall goal here is to make the file format unambiguous,
human-friendly, and machine-readable. For
follow the DCF
(Debian Control File) format, used by Debian, R, and RStudio IDE.
The minimalist, time-tested format allows us to save key-value data in
plain text that humans can easily read and write. The format is also
extendable to include more information about the assets being
pkglite.txt is structured following these rules:
- One file contains multiple DCF format blocks.
- Each block includes the metadata and the content of one file in an R
- Each block is separated by a blank line. The last block has a
trailing blank line.
Field names and values
Each block has at least four key-value pairs called
fields. For example:
#' @keywords internal
The keys and values in these fields are separated by a colon and a
whitespace except for
Content, whose value part starts in a
R package name. Since one
pkglite.txt might contain
files from multiple packages, this field is used to declare the package
the file is under explicitly.
This design implies that each
pkglite.txt can only store
multiple R packages with unique names.
The relative path (to the package root) of the file.
File format category. It can be
binary. This determines how the file content will be read
The file content. The text format files are stored as-is, while the
binary files are stored in the hexadecimal format, following the RTF
format convention. In both cases, two whitespaces are added before each
line of the value part.