summaryrefslogtreecommitdiff
path: root/src/librefetch/librefetch.8.ronn
diff options
context:
space:
mode:
authorLuke Shumaker <LukeShu@sbcglobal.net>2014-06-16 22:40:57 -0400
committerLuke Shumaker <LukeShu@sbcglobal.net>2014-06-16 22:40:57 -0400
commit3d9850b56c77b51edcdb2697c74ba2d1761109dc (patch)
treee5fe03bcbf6cd4d72f7c31a3129156e6784c4325 /src/librefetch/librefetch.8.ronn
parent52cc0c3ff27d4c48d3461d9fd898367aa4a92631 (diff)
parent813bfa255a1e46f05e08dcb587b8f417b995b2d4 (diff)
Merge branch 'master' into lukeshu/xbs
Diffstat (limited to 'src/librefetch/librefetch.8.ronn')
-rw-r--r--src/librefetch/librefetch.8.ronn122
1 files changed, 81 insertions, 41 deletions
diff --git a/src/librefetch/librefetch.8.ronn b/src/librefetch/librefetch.8.ronn
index c2b8ffe..6ee3ce8 100644
--- a/src/librefetch/librefetch.8.ronn
+++ b/src/librefetch/librefetch.8.ronn
@@ -3,32 +3,41 @@ librefetch(8) -- downloads or creates a liberated source tarball
## SYNOPSIS
-`librefetch` [options] <source-url> [<output-file>]<br>
-`librefetch` -[g|V|h]
+`librefetch` [<OPTIONS>] <SOURCE-URL> [<OUTPUT-FILE>]<br>
+`librefetch` `-`[`g`|`S`|`M`|`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 to (or
+configured locations), and no file is at that URL, librefetch will
+automatically create it for you.
-There are 7 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.
- * `version`: Print `librefetch` version information.
+ * `srcbuild`: Print the effective build script.
+ * `makepkg`: Print the effective makepkg 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)
@@ -38,20 +47,43 @@ There are 7 modes:
directory, it is used instead.
* `-g` | `--geninteg`: Use `checksums` mode: Generate integrity
checks for source files.
- * `-P` | `--print`: Use `print` mode: print the effective build script.
- * `-V` | `--version`: Use `version` mode: Show version information.
+ * `-S` | `--srcbuild`: Use `srcbuild` mode: print the effective build
+ script.
+ * `-M` | `--makepkg`: Use `makepkg` mode: print the effective makepkg
+ script.
* `-h` | `--help`: Use `help` mode: Show useage information.
+Other options, if they are documented in `makepkg -h`, are passed to
+the modified copy of makepkg created during `create` mode.
+
+## 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
-a `SRCBUILD(5)`, installs source files to `$pkgdir`, and the resulting
-"package" is then used as a source tarball. The `SRCBUILD` exists in
-the same directory as the `PKGBUILD`. It can be created manually, or
-generated on-the-fly from the `PKGBUILD`. Extra steps are taken to
-ensure that as long as the same directory contents go in, an identical
-tarball will come out--the checksum of the file should not change
-based on when it is built or who builds it.
+`SRCBUILD(5)`, that installs source files to <$pkgdir>, and the
+resulting "package" is then used as a source tarball. The `SRCBUILD`
+exists in the same directory as the `PKGBUILD`. It can be created
+manually, or generated on-the-fly from the `PKGBUILD`. Extra steps
+are taken to ensure that as long as the same directory contents go in,
+an identical tarball will come out--the checksum of the file should
+not change based on when it is built or who builds it.
The `SRCBUILD` is either created, or sanitized if it already exists,
then fed to a modified version of `makepkg(8)`.
@@ -68,19 +100,19 @@ remain intact.
As explained in the `CREATE MODE` section, in `create` mode, this
program generates an `SRCBUILD` file. For debugging purposes, this
-file can be printed instead of executed with `print` mode.
+file can be printed instead of executed with `srcbuild` mode.
### PRE-EXISTING SRCBUILD
The use of `SRCBUILD` files pre-dates `librefetch`. By convention,
-they set `PKGDEST` and `PKGEXT` in `package()` in order to modify the
+they set <PKGDEST> and <PKGEXT> in `package()` in order to modify the
behavior of `makepkg`. Because a modified version of `makepkg` is
used, this interferes with the correct behavior. To compensate for
this, lines containing "`PKGDEST=`" or "`PKGEXT=`" are deleted from
the `SRCBUILD`.
The general idea is that `build()` makes any modifications to the
-source, then `package()` copies it from `$srcdir` to `$pkgdir`.
+source, then `package()` copies it from <$srcdir> to <$pkgdir>.
### SRCBUILD FROM PKGBUILD
@@ -106,31 +138,32 @@ Following is a table of the translations.
makedepends = mkdepends
Functions
prepare() { :; }
- build() { mksource; }
- check() { :; }
+ build() { mksource; }
+ check() { :; }
package() { cp -a "$srcdir"/*/ "$pkgdir/"; }
The `mksource()` function does not need to be defined. If it isn't
defined, then no transformations will be made to the source between it
-being extracted to `$srcdir` and copied to `$pkgdir`.
+being extracted to <$srcdir> and copied to <$pkgdir>.
In summary:
- * Set `mksource=()` and `mkmd5sums=(`) to act as `source=(`) and
- `md5sums=()`
+ * Set <mksource=()> and <mkmd5sums=()> to act as <source=()> and
+ <md5sums=()>, respectively.
* Declare a `mksource()` function to make modifications to the
source, if nescessary.
Other changes:
- * `pkgname` is set to `pkgbase`, or the first element of the
- `pkgname` array.
- * `options=()` is set have `makepkg` avoid making changes to
- `$pkgdir`. The exact change is:
+ * <pkgname> is set to <pkgbase>, or the first element of the
+ <pkgname> array (the effect is that split packaging is turnes
+ off).
+ * <options=()> is set have `makepkg` avoid making changes to
+ <$pkgdir>. The exact change is:
options=(!strip docs libtool staticlibs emptydirs !zipman purge !upx)
- * `PURGE_TARGETS=()` has vcs directories added to it:
+ * <PURGE_TARGETS=()> has vcs directories added to it:
PURGE_TARGETS=(.bzr/ .cvs/ .git/ .hg/ .svn/ .makepkg/)
@@ -138,20 +171,27 @@ Other changes:
The following modifications are made to makepkg:
- * Allow us to manipulate the output file (`$pkg_file`)
- * Do not include metadata in the output file (`${comp_files[@]}`)
+ * Allow us to manipulate the output file (<$pkg_file>)
+ * Do not include metadata in the output file (<${comp_files[@]}>)
* Force 'ustar' tar format, don't allow it to upgrade to 'pax' to
store extended file attributes.
* Don't symlink the resulting file into the current directory.
- * `PURGE_TARGETS` interprets an item as a directory if it ends with a
+ * <PURGE_TARGETS> interprets an item as a directory if it ends with a
slash ("/").
- * Timestamps in `$pkgdir` are reset to "1990-01-01 0:0:0 +0", so that
+ * Timestamps in <$pkgdir> are reset to "1990-01-01 0:0:0 +0", so that
the resulting tarball will be the same, regardless of when it was
created.
- * append `-libre` to `$srcdir`
- * append `-libre` to `$pkgbasedir` (which becomes `$pkgdir`)
+ * Sort the files included in the tarball; normally the order of files
+ in a tarball is essentially random (even if it tends to be the same
+ when re-created on the same machine).
+ * append `-libre` to <$srcdir>
+ * append `-libre` to <$pkgbasedir> (which becomes <$pkgdir>)
* Don't check if the package has already been built.
+For debugging purposes, this modified makepkg can be printed instead
+of executed with `makepkg` mode. Before it is run in create mode,
+`PKGEXT`, `PKGDEST`, and `pkg_file` are set as environment variables.
+
## CONFIGURATION
See `librefetch.conf(5)` for details on configuring librefetch using