path: root/src/librefetch
diff options
authorLuke Shumaker <>2014-01-04 19:32:14 -0500
committerLuke Shumaker <>2014-01-04 19:39:08 -0500
commit811df5ff79f76b8128380715ac5ae127cd76be56 (patch)
tree81f6fb23b86001e5e0a3be01d3810adc49c0888f /src/librefetch
parent5f97f7885b8bdb7a6fea34d6d073428b199d66ef (diff)
librefetch: update docs
Diffstat (limited to 'src/librefetch')
3 files changed, 58 insertions, 20 deletions
diff --git a/src/librefetch/librefetch b/src/librefetch/librefetch
index a477315..819a51a 100755
--- a/src/librefetch/librefetch
+++ b/src/librefetch/librefetch
@@ -37,11 +37,12 @@ usage() {
prose "If OUTPUT_FILE isn't specified, it defaults to the non-directory
part of SOURCE_URL, in the current directory."
- prose "Unless '-C' is specified, if SOURCE_URL does not begin with the
+ prose "Unless '-C' is specified, if SOURCE_URL does not begin with a
configured mirror, create mode is inhibited."
prose "In download mode, it simply tries to download SOURCE_URL. At the
- beginning of a URL, 'libre://' expands to the configured mirror."
+ beginning of a URL, 'libre://' expands to the first configured
+ mirror."
prose "In create mode, it looks at a build script, and uses that to
create the source tarball. SOURCE_URL is ignored, except that it
@@ -56,7 +57,7 @@ usage() {
'-a -b', not '-ab'." "$cmd"
print "Example usage:"
- print ' $ %s libre://mypackage-1.0.tar.gz' "$cmd"
+ print ' $ %s' "$cmd"
print "Options:"
print " Settings:"
diff --git a/src/librefetch/librefetch.8.ronn b/src/librefetch/librefetch.8.ronn
index 16c3838..c7247d5 100644
--- a/src/librefetch/librefetch.8.ronn
+++ b/src/librefetch/librefetch.8.ronn
@@ -3,31 +3,40 @@ librefetch(8) -- downloads or creates a liberated source tarball
-`librefetch` [options] <source-url> [<output-file>]<br>
-`librefetch` -[g|P|h]
+`librefetch` [<OPTIONS>] <SOURCE-URL> [<OUTPUT-FILE>]<br>
+`librefetch` `-`[`g`|`P`|`h`]
`librefetch` is a program to streamline creation of custom source
tarballs for `PKGBUILD(5)` files.
-To automatically use `librefetch` to download or create a source
-tarball, you can add `libre://FILENAME.tar.gz` to the source array in
-your `PKGBUILD`. This works because a post-install script for the
-package adds `librefetch` as a download agent for `libre://` to
-`makepkg.conf`. Because of this, it is almost never necessary to call
-`librefetch` manually.
+If a URL mentioned in the `source` array in a `PKGUILD` is in a
+location that Parabola uploads "custom" source tarballs (or configured
+locations), and no file is at that URL, librefetch will automatically
+create it for you.
-There are 6 modes:
+This works because a post-install script for the package configures
+`librefetch` as the download agent for `https://` URLs in
+`makepkg.conf`; allowing it to jump in and create a file if need be.
+Because of this, it is almost never necessary to call `librefetch`
+The post-install script also configures `librefetch` as the download
+agent for `libre://` URLs, for compatability with PKGBUILDs that used
+a previous version of librefetch.
+There are 5 modes:
- * `download-create`: The default mode. First try `download` mode,
- then `create` mode.
* `download`: Download the tarball from the configured mirror.
* `create`: Create the tarball from a `PKGBUILD`/`SRCBUILD`.
* `checksums`: Generate integrity checks for source files.
* `print`: Print the effective build script.
* `help`: Print `librefetch` usage information.
+The normal mode of operation is `download` mode. If `download` mode
+fails, it may choose to try `create` mode.
* `-C`: Force `create` mode (don't download)
@@ -40,6 +49,24 @@ There are 6 modes:
* `-P` | `--print`: Use `print` mode: print the effective build script.
* `-h` | `--help`: Use `help` mode: Show useage information.
+If <SOURCE-URL> begins with the string `libre://`, it is replaced with
+the first value in `MIRRORS`, as configured in `librefetch.conf(5)`;
+this is for compatability with PKGBUILDs that used a previous version
+of librefetch.
+It uses `DOWNLOADER`, as configured in `librefetch.conf` to attempt to
+download the source tarball from that URL. If that fails, and
+following conditions are met, it proceeds to `create` mode:
+ * The `-D` flag has not been specified to inhibit `create` mode.
+ * The `<source-url>` begins with one of the values in `MIRRORS`.
+The latter requirement allows librefetch to be used as a generic
+HTTP(S) download agent, that can automatically create files from
+whitelisted locations.
The principle of `create` mode is that a special `PKGBUILD(5)`, called
@@ -155,6 +182,11 @@ The following modifications are made to makepkg:
See `librefetch.conf(5)` for details on configuring librefetch using
the `librefetch.conf` file.
+## BUGS
+In download mode, if the local download location contains the string
+`%u`, it will be replaced by the URL being downloaded from.
librefetch.conf(5), makepkg(8), PKGBUILD(5), SRCBUILD(5)
diff --git a/src/librefetch/librefetch.conf.5.ronn b/src/librefetch/librefetch.conf.5.ronn
index 7b25400..6158104 100644
--- a/src/librefetch/librefetch.conf.5.ronn
+++ b/src/librefetch/librefetch.conf.5.ronn
@@ -24,14 +24,19 @@ If `$XDG_CONFIG_HOME` is not set, a default value is set:
- * `MIRROR=''`:
- Files from within this tree will be attempted to be built if
- downloading them fails. Also, `libre://` expands to this
- location.
+ * `MIRRORS=( ... )`:
+ A list of locations that generated source tarballs may be located
+ at. If a URL begins with `libre://`, then `libre://` is replaced
+ with the first location listed here.
* `DOWNLOADER='/usr/bin/curl -fLC - --retry 3 --retry-delay 3 -o %o %u'`:
The HTTP client to use when downloading pre-built source tarballs
- in download mode.
+ in download mode. The format and semantics are similar to
+ `DLAGENTS` in `makepkg.conf`(5). If present, `%u` will be replaced
+ with the download URL (correctly quoted), otherwise the download
+ URL will be appended to the end of the command. If present, `%o`
+ will be replaced with the local filename that it should be
+ downloaded to.
+librefetch(8), makepkg.conf(5)