path: root/src/librefetch/librefetch.8.ronn
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/librefetch.8.ronn
parent5f97f7885b8bdb7a6fea34d6d073428b199d66ef (diff)
librefetch: update docs
Diffstat (limited to 'src/librefetch/librefetch.8.ronn')
1 files changed, 43 insertions, 11 deletions
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)