summaryrefslogtreecommitdiff
path: root/src/librefetch/librefetch.8.ronn
blob: fa7aacebf87e03105ed4ad180bf815d3b8261302 (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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
librefetch(8) -- downloads or creates a liberated source tarball
================================================================

## SYNOPSIS

`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.

If a URL mentioned in the <source> array in a `PKGBUILD` 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.

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 compatibility with `PKGBUILD` files
that used a previous version of librefetch.

There are 6 modes:

 * `download`: Download the tarball from the configured mirror.
 * `create`: Create the tarball from a `PKGBUILD`/`SRCBUILD`.
 * `checksums`: Generate integrity checks for source files.
 * `srcbuild`: Print the effective build script.
 * `makepkg`: Generate and print the location of 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)
 * `-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.
 * `-S` | `--srcbuild`: Use `srcbuild` mode: print the effective build
   script.
 * `-M` | `--makepkg`: Use `makepkg` mode: generate and print the
   location of the effective makepkg script.
 * `-h` | `--help`: Use `help` mode: Show usage 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 compatibility with `PKGBUILD` files 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
`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.
If the output filename does not end with `.sig` or `.sig.part`, then
the `SRCBUILD` is fed to a modified version of `makepkg(8)`.  If the
output filename does end with `.sig` or `.sig.part`, then it uses GPG
to create a signature.  If the file it is trying to sign does not
exist yet, librefetch recurses on itself to create it.

The reason `makepkg` must be modified is that we need the resulting
tarball to be deterministic (as well as not containing package
metadata).

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 `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
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 temporary 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, sha224, sha256, sha384, sha512)
      depends      = <empty>
      checkdepends = <empty>
      makedepends  = mkdepends
      *_$CARCH     = <unset>
    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=()>, respectively.
 * Declare a `mksource()` function to make modifications to the
   source, if necessary.

Other changes:

 * <pkgname> is set to <pkgbase>, or the first element of the
   <pkgname> array (the effect is that split packaging is turned
   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=(.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 the date specified in
   <SOURCE_DATE_EPOCH>[1], or "1990-01-01 0:0:0 +0" if it's not set, so
   that the resulting tarball will be the same, regardless of when it
   was created.
 * 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
the `librefetch.conf` file.

## SEE ALSO

librefetch.conf(5), makepkg(8), PKGBUILD(5), SRCBUILD(5)

## NOTES

 1. <SOURCE_DATE_EPOCH> specification for build systems
    https://reproducible-builds.org/specs/source-date-epoch/