summaryrefslogtreecommitdiff
path: root/src/librefetch/librefetch.8.ronn
blob: c2b8ffe3df9ca9b1c7cb8ff6ec524173e574aa80 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
librefetch(8) -- downloads or creates a liberated source tarball
================================================================

## SYNOPSIS

`librefetch` [options] <source-url> [<output-file>]<br>
`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 7 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.
 * `help`: Print `librefetch` usage information.

## OPTIONS

 * `-C`: Force `create` mode (don't download)
 * `-D`: Force `download` mode (don't create)
 * `-p` <file>: 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.
 * `-P` | `--print`: Use `print` mode: print the effective build script.
 * `-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.

## SRCBUILD GENERATION

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.

### 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      = <empty>
      checkdepends = <empty>
      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 staticlibs emptydirs !zipman purge !upx)

 * `PURGE_TARGETS=()` has vcs directories added to it:

      PURGE_TARGETS=(.bzr/ .cvs/ .git/ .hg/ .svn/ .makepkg/)

### 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)