-
Notifications
You must be signed in to change notification settings - Fork 42
/
Copy pathchecklist.html
519 lines (480 loc) · 21.6 KB
/
checklist.html
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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="resource-type" content="document">
<meta name="description" CONTENT="How to make/update an OpenBSD port.">
<meta name="keywords" content="openbsd,ports">
<meta name="distribution" content="global">
<meta name="copyright" content="This document copyright 1998-2007 by OpenBSD.">
<title>OpenBSD Porting Checklist</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#23238E">
<a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif" border="0"></a>
<h2><font color="#e00000">OpenBSD Porting Checklist</font></h2>
This document describes how to make or upgrade a port. It is a useful
reminder of things to do. This is neither totally accurate nor perfect.
Direct comments and questions to <a href="mailto:[email protected]">
[email protected]</a>.
<hr>
<ol>
<li>
If you want to be a maintainer, subscribe to
<a href="mailto:[email protected]">[email protected].</a>
<ul><li>
This is where all ports discussions take place.
<li>
Reading this list is important since many announcements go over this list.
<li>
You will find a lot of porting-savvy people there. They can often give you
good advice or test ports for you.
</ul>
<br><li>
Being a maintainer means <strong>more</strong> than just submitting ports.
It also means trying to keep them up-to-date, and to answer questions about
them.
<br><br><li>
Check out a copy of the ports tree from cvs.
You can find instructions on how to do this at the
<a href="anoncvs.html">anonymous cvs page</a>.
<br><br><li>
Pick a place to put your port and create the basic
infrastructure there. Use the template Makefile at
<code>/usr/ports/infrastructure/templates/Makefile.template</code>.
NEED_VERSION is obsolete and should not be used in new ports.
As you are a port developer, you are supposed to update
your ports tree, including bsd.port.mk.
<ul><li>
Create the directory <code>pkg</code>.
<li>
Create the empty files <code>pkg/DESCR, pkg/PLIST</code>.
</ul>
<br><li>
Add the fetch portions of the Makefile.
<ul><li>
Fill in EXTRACT_SUFX if it's anything besides .tar.gz. Other examples are
.tar.Z, or .tgz.
<li>
Fill in DISTNAME which is the name of the file minus the extract suffix.
E.g., if you have foo-1.0.tar.gz, DISTNAME is foo-1.0.
<li>
Fill in MASTER_SITES which is a URL to the directory where the distfile
is kept. E.g., ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/.
<strong>Don't forget the trailing slash.</strong>
Try to have at least three distinct sites as well.
Place the most easily accessible first as they are traversed in order.
<li>
Keep in mind that fetch references the file as
${MASTER_SITES}${DISTNAME}${EXTRACT_SUFX}. All three are used. Don't
set DISTNAME to point to the file directly.
<li>
You can check to see if you have filled these values in correctly by typing
<b>make fetch-all</b>.
</ul>
<p>
For more complex ports, you have more options and tools available to you:
<ul><li>
You also have the variable PATCHFILES available. This is a list of vendor
(not OpenBSD) patches to the port. Common uses are things like security
or reliability fixes.
<li>
If your ports are available over large public mirrors such as GNU, SunSite, or
CPAN, we have already provided a list of sites for your use in
/usr/ports/infrastructure/templates/network.conf.template.
Set MASTER_SITES to ${MASTER_SITE_GNU}, or ${MASTER_SITE_SUNSITE}, etc.
To simplify this process, use the construct ${MASTER_SITE_FOO:=subdir/} to
append the distribution subdirectory.
<li>
Ports normally correspond to given versions of software. Once they are retrieved, files are checksummed and compared to the recorded
checksum(s) in distinfo. So, to avoid confusion, DISTFILES and PATCHFILES should have clearly visible version numbers:
don't retrieve foo-latest.tar.gz if it is a link to foo-1.0.5.tar.gz. If necessary, gently ask the original program author
to make such distinctions clear.
<li>
If a given port needs more than about 5 DISTFILES + PATCHFILES to work, use DIST_SUBDIR to avoid cluttering
/usr/ports/distfiles too much.
<li>
DIST_SUBDIR must not include version numbers. When the port is updated to a later version, some distfiles may not change, but will be
refetched if DIST_SUBDIR is changed. Even if all distfiles change, it is easier for the user to track cruft.
<li>
All DISTFILES and PATCHFILES don't necessarily come from the same set of MASTER_SITES. Supplementary sites can be
defined using the variables MASTER_SITES0 to MASTER_SITES9. Just write DISTFILES=foo-1.0.5.tar.gz:5 to
retrieve foo-1.0.5.tar.gz from MASTER_SITES5.
<li>
Some ports don't always need to retrieve all files in all circumstances. For instance, some ports may have some compilation options, and
associated files which are only required in such a case. Or they may need some files for some architectures only. In such a case, those
supplementary optional files must be mentioned in the SUPDISTFILES variable. Targets such as makesum or
mirror-distfiles will fetch those supplementary files that the casual user doesn't need.
</ul>
<br><li>
Create a checksum in <i>distinfo</i> by typing <b>make makesum</b>.
Then verify the checksum is correct by typing <b>make checksum</b>.
<ul><li>
In some rare cases, files checksums can't be verified reliably. By all means, porters should try to find sites that are reliable. Communicating
with the software author and the archive site maintainer at this stage is highly desirable. In the worst case, non-checksummable files can be
mentioned in the IGNOREFILES variable.
<li>
All files in DISTFILES are usually processed during make extract. EXTRACT_ONLY may be used to limit extraction to a
subset of files (possibly empty). The customary use of this variable is to customize extraction: for instance, if some DISTFILES need
some special treatment, they will be removed from EXTRACT_ONLY and handled manually at post-extract stage.
For historic reasons, make extract does set up the working directory first along with extracting files. Thus, providing a
pre-extract or a do-extract target is highly unusual (and fairly suspicious behavior, indicative of a high degree of obfuscation
in the port).
<li>
Patches that need specific treatment should be mentioned in DISTFILES, and removed from EXTRACT_ONLY, for historic reasons.
</ul>
<br><li>
Extract the port with <b>make extract</b>. Pay attention to where the base
of the sources are. Usually, it's <i>w-${PKGNAME}${FLAVOR_EXT}/${DISTNAME}</i>. You may need to
modify the Makefile's WRKDIST variable if it is different.
<br><br><li>
Read the installation documentation and note what you have to do to build
the port and any special options that might be needed.
<br><br><li>
Now is also a good time to figure out what kind of licensing restrictions
apply to your port. Many are freely redistributable but then again, quite
a few are not. We need four questions answered to distribute ports
properly. These are the PERMIT_* values in the Makefile.
<ul><li>
PERMIT_PACKAGE_CDROM tells us if we can put the package on the cdrom.
<li>
PERMIT_PACKAGE_FTP tells us if we can put the package on the ftp sites.
<li>
PERMIT_DISTFILES_CDROM tells us if we can mirror the distfiles on the cdrom.
<li>
PERMIT_DISTFILES_FTP tells us if we can mirror the distfiles on the ftp sites.
</ul>
<p>
Set these values to Yes if it is permitted or to a comment string stating why
it is not. Pay attention to any special conditions you may need to fulfill
later on. E.g., some ports require to install a copy of the license. We
recommend you place the license in
<code>/usr/local/share/doc/<name>/</code>.
<p>
In addition to the PERMIT_* values, put a license marker like
<code># License</code> above them as a comment, this way we know why
the PERMIT_* values are set the way they are.
<br><br><li>
Add configuration options to Makefile and/or create the configuration script.
<ul><li>
You can add a port configuration script named `configure' to a directory
named <code>scripts/</code>. This will be run before any configuration
specified by CONFIGURE_STYLE is run.
<li>
If GNU configure is used you may want to run ./configure --help
to see what options are available.
<li>
Anything that you may want to override can be changed by adding the
--option flags to the CONFIGURE_ARGS parameter in the Makefile.
<li>
Use CONFIGURE_ARGS+= to append to the variable. CONFIGURE_ARGS= will
overwrite it.
</ul>
<br><li>
Try building the port with <b>make build</b>.
<ul><li>
If you're lucky, the port will go all the way through without errors.
<li>
If it exits with an error, you will need to generate patches for your port.
Figure out what needs to be changed and make a patch for it.
<li>
Patches must be relative to ${WRKDIST}.
<li> The easiest way to reset the port and test your patches is
<b>make clean patch</b>. This will delete the work directory, re-extract,
and patch your port.
</ul>
<br><li>
Begin a cycle of <b>make build</b>, generate a patch (or use <b>make
update-patches</b>), and
<b>make clean patch</b>.
<ul><li>
Patches go in the directory <i>patches/</i> and should be named patch-* with
* being something meaningful. We recommend you name your patches
patch-FILENAME where FILENAME is the name of the file it is patching.
(<tt>make update-patches</tt> does this automatically for you.)
<li>
Applying PATCHFILES is the first half of the make patch stage. It can be
invoked separately as make distpatch, which is a convenient target for
porters. Ignore this if you haven't set it.
<li>
Only patch one source file per patchfile, please.
<li>
Use <b>make update-patches</b> to generate patches.
<li>
All patches MUST be relative to ${WRKDIST}.
<li>
Check that patches <strong>DON'T</strong> contain tags that cvs
will replace. If they do, your patches won't apply after you check
them in. You can check in your changes with -kk to avoid this.
<li>
Write a small explanation at the beginning of the patchfile about its purpose
(not mandatory).
<li>
<b>Please</b> feed your patches back to the author of that piece of software.
</ul>
<br><li>
Try setting <code>SEPARATE_BUILD</code>.
<ul><li>
If the port can build with object files outside its source tree,
this is cleaner (many programs using <code>CONFIGURE_STYLE=gnu</code> can),
and may help people who mount their ports tree on several arches.
<li>
This can also spare you some effort, as you will possibly be able to
restart the cycle at <code>configure</code> most of the time.
</ul>
<br><li>
Peruse the output (if any) and tweak any options in the Makefile.
To repeat issue the command `<b>make clean configure</b>'.
<p>
Note: make sure host-dependent files go in <i>/etc</i> or
<i>/etc/<name></i>, but <strong>NEVER REPLACE OR MODIFY</strong>
existing files in <i>/etc</i>. Best to have install place them
in <i>/usr/local/share/<name></i> and then copy to
<i>/etc</i> or <i>/etc/<name></i> only if the files do not exist.
If the files exist, display a message that says such-and-such files need
to be modified. This also guarantees that the files will be included in
the package since everything under <i>/usr/local</i> is included in the PLIST.
After a package has been installed the contents of <code>pkg/MESSAGE</code>
will be displayed if it exists.
<p>
The OpenBSD file locations are:
<pre>
user executables: /usr/local/bin
system admin executables: /usr/local/sbin
program executables: /usr/local/libexec
libraries: /usr/local/lib
architecture dependent data: /usr/local/lib/<name>
installed include files: /usr/local/include or
/usr/local/include/<name>
single-machine data: /etc or /etc/<name>
local state: /var/run
games score files: /var/games
GNU info files: /usr/local/info
man pages: /usr/local/man/...
read-only architecture-independent: /usr/local/share/<name>
misc documentation: /usr/local/share/doc/<name>
examples files: /usr/local/share/examples/<name>
</pre>
<li>
Begin a cycle of makes until the port is ready. Patch (see above)
clean, and make until the port is generated. Get rid of all warnings
if possible, especially security related warnings.
<br><br><li>
Control SEPARATE_BUILD semantics.
You have to do this only if the port builds with
SEPARATE_BUILD defined.
Ideally, the port should not modify any file in
${WRKSRC} after <b>make patch</b>.
You can check this by making sure you don't have any write access
to ${WRKSRC}. Then you can set
<code>SEPARATE_BUILD=concurrent</code> -- someone can use the same
source tree to build on distinct arches simultaneously.
Otherwise, set <code>SEPARATE_BUILD=simple</code> -- building on
distinct arches simultaneously may be met with problems, as some
source files may be regenerated at awkward moments.
<br><br><li>
Add <i>COMMENT</i> in Makefile.
COMMENT is a <strong>SHORT</strong> one-line description of the port
(max. 60 characters). Do <strong>NOT</strong> include the package
name (or version number of the software) in the comment.
Do <strong>NOT</strong> start with an uppercase letter
unless semantically significant, and
do <strong>NOT</strong> end with a period.
<strong>DON'T EVER START WITH AN INDEFINITE ARTICLE SUCH AS `a' or `an';
remove the article altogether.</strong>
<br><br><li>
Edit <i>pkg/DESCR</i>, <i>pkg/PLIST</i>.
<ul><li>
DESCR is a longer description of the port. One to a few paragraphs
concisely explaining what the port does is sufficient. It is also advised to
wrap your lines at 72 characters. This can be done by first editing the DESCR
file and then running it through 'fmt -w 72'.
<li>
PLIST is kept empty at this point.
</ul>
<br><li>
If the application needs to create a user or a group, choose the lowest free
id from <code>/usr/ports/infrastructure/db/user.list</code> for your port to
use and make sure your port gets added to this file at commit time.
<br><br><li>
Install the application with <b>make fake</b>.
Libraries should never be stripped. Executables are stripped by default;
this is governed by <code>${INSTALL_STRIP}</code>.
<code>${INSTALL_PROGRAM}</code> honors this automatically and is
preferable to unconditional stripping (e.g., by an "install-strip"
target or by running "strip" from the Makefile). You can use
<code>file</code> to determine if a binary is stripped or not.
<br><br><li>
<strong>Check port for security holes again</strong>. This is
especially important for network and setuid programs. See
<a href="porting.html#Security">our security recommendations</a>
for that. Log interesting stuff and fixes in the
<code>pkg/SECURITY</code> file. This file
should list audited potential problems, along with relevant patches,
so that another person can see at first glance what has been done.
Example:
<pre>
$OpenBSD$
${WRKDIR}/receiver.c
call to mktemp (wrapper function do_mktemp) does seem to be correct.
The server makes extensive use of strlcpy/strlcat/snprintf.
</pre>
<br><br><li>
Make sure your <code>/etc/mtree</code> directory is up-to-date.
(The next step uses the mtree lists to remove existing directories from
generated packing-lists). Remember that <code>(U)pdate</code> does not
touch <code>/etc</code>...
<br><br><li>
Create pkg/PLIST. After the install is complete use the developer's command,
<b>make plist</b> which makes the file PLIST in the <i>pkg</i> directory.
This file is a candidate packing list.
<p>
Peruse `PLIST' and verify that everything was installed and
that it was installed in the proper locations. Anything not installed
can be added to a port Makefile `post-install' rule.
<p>
Ports that install shared libraries will have another file called PFRAG.shared.
<ul><li>
PLIST describes the files being independent of whether the architecture supports shared libraries or not.
<li>
PFRAG.shared describes only the files being additionally installed on those architectures that support
shared libraries.
<li>
PFRAG.noshared describes only the files being additionally installed on architectures that do not
support shared libraries.
</ul>
<br><br><li>
Verify shared library dependencies. Run <code>make port-lib-depends-check</code>
and add every <code>LIB_DEPENDS</code> or <code>WANTLIB</code> annotation
that is needed until it runs cleanly.
You may want to read
<a href="porting/update.html">the update guidelines</a>
to understand why this is so important.
<br><br><li>
If you added to <code>LIB_DEPENDS</code>, Re-run <b>make plist</b>. It
is possible some directories do not need to be in the PLIST, as they've
been installed by a dependency.
<br><br><li>
Test the packaging.
After the port installs correctly issue the command
<code>make package</code> to create a package. To test the
package first do a <code>pkg_add</code> and then do a
<code>pkg_delete</code>
<br><br><li>
Verify dependencies. Peruse your logs to verify the port did detect what is
mentioned in DEPENDS, and nothing more. Check names for hidden dependencies
(stuff that exists elsewhere in the ports tree and might be detected if the
user installs some other ports first).
<br><br><li>
Verify shared library dependencies. Run <code>make lib-depends-check</code>
and add every <code>LIB_DEPENDS</code> or <code>WANTLIB</code> annotation
that is needed until it runs cleanly (run <code>make clean=package</code>
to remove the old package after updating the port's Makefile).
You may want to read
<a href="porting/update.html">the update guidelines</a>
to understand why this is so important.
<br><br><li>
Check for regression tests, and whether they run cleanly. Set
<code>NO_REGRESS=Yes</code> if a port has no test infrastructure.
Please note: do not set <code>NO_REGRESS</code> if a port has an empty
regression infrastructure.
<br><br><li>
Mail <a href="mailto:[email protected]">[email protected]</a> with a short
note asking for comments and testing. Make sure to attach the port/patch to
this email and send it out (mailinglist archives just contain the mails itself).
<p>
Try to get others to test it on a variety of platforms for you.
<ul><li>
The AMD64 Opteron systems are good because they are fast, and because
<code>sizeof(int) != sizeof(long)</code> on this platform.
<li>
Sun SPARC and UltraSPARC are good because they are very common and because
their byte order is the opposite of i386; if you developed on SPARC, of course,
you'd want it tested on i386.
</ul>
<br><li>
Incorporate any feedback you get. Test it again on your platform.
Get those who gave you feedback to test it again from your new port.
<br><br><li>
Finally, include it in the "ports" tree.
If you do not have CVS access, ask someone on
<a href="mailto:[email protected]">[email protected]</a> to commit it.
<br><br><li>
If you are a developer with CVS access, check it in.
Before commit, check that no users were added to
<code>/usr/ports/infrastructure/db/user.list</code>
since the port was created.
We normally use "import" for a new port,
rather than adding a zillion (or a dozen) files individually.
Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry
about that! :-) If you make changes to a specific file (edit, then
cvs commit), it will be 1.2, and that will be used.
<p>
In short, import is typically used when a port is created.
From that point on cvs add and cvs rm are typically used to add or remove
files, and the normal edit->commit cycle for changes.
You might use something like this:
<pre>
$ cd kaffe1
$ make clean # you really don't want to check in all of work!
$ cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
<i>YourName</i> <i>YourName_YYYY-MMM-DD</i>
</pre>
<ul><li>
-d cvs.openbsd.org:/cvs says where cvs lives. This can be omitted if you
have a CVSROOT environment variable defined.
<li>
-m 'kaffe port' is your login message. Change it to whatever you like
<li>
ports/lang/kaffe1 is the path relative to /cvs where the port lives
<li>
<i>YourName</i> (replaced with your login name) is the 'vendor tag'.
You imported it so you are the vendor.
<li>
<i>YourName_YYYY-MMM-DD</i> (e.g., ian_2000-Jan-01)
is the 'vendor release tag'. This is as good as any.
</ul>
<br>
As a real example, here is the output of checking in the Kaffe1 port,
which one of us did on September 8, 1998:
<pre>
$ cd kaffe1
$ make clean >/dev/null
$ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08
[email protected]'s password: (not shown, obviously)
I ports/lang/kaffe1/CVS
I ports/lang/kaffe1/files/CVS
I ports/lang/kaffe1/pkg/CVS
N ports/lang/kaffe1/Makefile
cvs server: Importing /cvs/ports/lang/kaffe1/files
N ports/lang/kaffe1/files/md5
cvs server: Importing /cvs/ports/lang/kaffe1/pkg
N ports/lang/kaffe1/pkg/COMMENT
N ports/lang/kaffe1/pkg/DESCR
N ports/lang/kaffe1/pkg/PLIST
No conflicts created by this import
$
</pre>
<li>
Last but not least, add a one-line entry for the new port
in its parent directory's Makefile, e.g., for ports/lang/kaffe1,
add it to ports/lang/Makefile.
Don't forget to commit any changes made to
<code>/usr/ports/infrastructure/db/user.list</code>.
<br><br><li>
Maintain the port! As time goes by, problems may arise, or new versions
of the software may be released. You should strive to keep your port up
to date. In other words - iterate, test, test, iterate...
<br><br><li>
When updating a port, remember to handle dependencies! You shouldn't break any
port that depends on yours. In case of problems, communicate with the
maintainers of such ports. Likewise, be alert for dependency updates, and
check that the maintainer did their job.
</ol>
Thank you for supporting the OpenBSD "ports" process!
<hr>
<a href="porting.html"><img height=24 width=24 src="back.gif"
border=0 alt="Porting"></a>
<a href="mailto:[email protected]">[email protected]</a>
<br><small>$OpenBSD: checklist.html,v 1.69 2008/11/18 22:31:12 sthen Exp $</small>
</body>
</html>