From 38450796883e2920b2b31e9f79cef20859215ade Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Sat, 27 Jul 2013 20:11:06 -0600 Subject: add manpages for librefetch --- src/librefetch/librefetch.8.ronn | 154 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 src/librefetch/librefetch.8.ronn (limited to 'src/librefetch/librefetch.8.ronn') diff --git a/src/librefetch/librefetch.8.ronn b/src/librefetch/librefetch.8.ronn new file mode 100644 index 0000000..5df2e09 --- /dev/null +++ b/src/librefetch/librefetch.8.ronn @@ -0,0 +1,154 @@ +librefetch(8) -- downloads or creates a liberated source tarball +================================================================ + +## SYNOPSIS + +`librefetch` [options] []
+`librefetch` -[g|V|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. + +There are 6 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. + * `version`: Print `librefetch` version information. + * `help`: Print `librefetch` usage information. + +## OPTIONS + + * `-C`: Force `create` mode (don't download) + * `-D`: Force `download` mode (don't create) + * `-p` : Use an alternate build script for `create` mode + (instead of `PKGBUILD`). If an `SRCBUILD` file exists in the same + directory, it is used instead. + * `-g` | `--geninteg`: Use `checksums` mode: Generate integrity + checks for source files. + * `-V` | `--version`: Use `version` mode: Show version information. + * `-h` | `--help`: Use `help` mode: Show useage information. + +## 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. + +The `SRCBUILD` is either created, or sanitized if it already exists, +then fed to a modified version of `makepkg(8)`. + +The purpose of the modified `makepkg` is so that the resulting tarball +doesn't contain package metadata, doesn't end with a .pkg file +extension, and always produces an identicle tarball. + +When this documentation speaks of a file being modified, it is a +temporary copy of the file that is modified, your original file will +remain intact. + +### 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 +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`. + +### SRCBUILD FROM PKGBUILD + +Possibly more elegant than having a separate `SRCBUILD` file is having +an `mksource()` function in the main `PKGBUILD`. This results in less +boilerplate and fewer files to edit. + +Note that this only happens if a file named `SRCBUILD` doesn't already +exist; when migrating a package from a manually created `SRCBUILD` to +this method, the `SRCBUILD` must be deleted (or renamed) for this to +work. + +The dynamically created `SRCBUILD` is created by copying `PKGBUILD` to +a temorary file, then re-setting variables and re-defining functions. +Following is a table of the translations. + + Variables + source = mksource + noextract = mknoextract + *sums = mk*sums (md5, sha1, sha256, sha384, sha512) + depends = + checkdepends = + makedepends = mkdepends + Functions + prepare() { :; } + 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`. + +In summary: + + * Set `mksource=()` and `mkmd5sums=(`) to act as `source=(`) and + `md5sums=()` + * 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: + + options+=(!strip docs libtool emptydirs !zipman purge !upx) + + * `PURGE_TARGETS=()` has vcs directories added to it: + + PURGE_TARGETS+=(.bzr/ .cvs/ .git/ .hg/ .svn/) + +### MAKEPKG MODIFICATIONS + +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[@]}`) + * 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 + slash ("/"). + * 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`) + * Don't check if the package has already been built. + +## CONFIGURATION + +See `librefetch.conf(5)` for details on configuring librefetch using +the `librefetch.conf` file. + +## SEE ALSO + +librefetch.conf(5), makepkg(8), PKGBUILD(5), SRCBUILD(5) -- cgit v1.2.2