diff options
Diffstat (limited to 'src/librefetch/librefetch.8.ronn')
| -rw-r--r-- | src/librefetch/librefetch.8.ronn | 54 |
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 ## SYNOPSIS -`librefetch` [options] <source-url> [<output-file>]<br> -`librefetch` -[g|P|h] +`librefetch` [<OPTIONS>] <SOURCE-URL> [<OUTPUT-FILE>]<br> +`librefetch` `-`[`g`|`P`|`h`] ## DESCRIPTION `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` +manually. + +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. + ## OPTIONS * `-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. +## DOWNLOAD MODE + +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. + ## CREATE MODE 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. + ## SEE ALSO librefetch.conf(5), makepkg(8), PKGBUILD(5), SRCBUILD(5) |