1.\"	$OpenBSD: register-plist.1,v 1.7 2023/10/06 12:45:45 espie Exp $
2.\"
3.\" Copyright (c) 2010 Marc Espie <espie@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: October 6 2023 $
18.Dt REGISTER-PLIST 1
19.Os
20.Sh NAME
21.Nm register-plist
22.Nd smart diff and registration of packing-lists
23.Sh SYNOPSIS
24.Nm register-plist
25.Op Fl n
26.Op Fl s Ar snapdir
27.Ar dir
28.Op Ar pkgname ...
29.Nm
30.Fl p
31.Ar dir
32.Nm
33.Fl t
34.Ar p1
35.Ar p2
36.Sh DESCRIPTION
37.Nm
38is used to check that a packing-list for a given package name doesn't change.
39By default, it is invoked at the end of
40.Li make package ,
41and compares a temporary package with the
42.Pa ${PLIST_REPOSITORY}
43before moving it to
44.Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/all
45.Po
46see
47.Ev PACKAGE_REPOSITORY
48and
49.Ev PLIST_REPOSITORY
50in
51.Xr bsd.port.mk 5
52.Pc .
53Package names (package stem plus version) are used to uniquely identify
54packages.
55When something in the package changes, the package name should change,
56usually by increasing
57.Ev REVISION .
58.Pp
59.Nm
60checks for a lot of details, including DESCR contents.
61Thus changes in MAINTAINER, hard and symlinks existence and values,
62comments, and other things, will trigger
63.Ev REVISION
64bumps).
65.Pp
66Dependencies receive special treatment.
67Addition or deletion of dependencies should warrant a bump, but
68.Nm
69will also verify that dependencies go
70.Sq forward :
71namely it's okay for a
72.Cm @wantlib
73to go from
74.Pa liba.so.2.0
75to
76.Pa liba.so.3.0
77but not the other way around.
78.Pp
79Starting with
80.Ox 6.6 ,
81.Cm @version
82bumps allow system-wide change to affect plists without triggering an
83error.
84.Pp
85.Nm
86records a packing-list for each
87.Ar pkgname
88into the given directory
89.Ar dir .
90If no previous packing-list for the given pkgname exists, the packing-list
91is recorded.
92If a previous packing-list exists,
93.Nm
94compares both packing-list for discrepancies.
95Whenever something significant changes,
96.Nm
97will display a diff of the differences, and exit with an error.
98.Pp
99Some items in the packing-list may change without actual problems.
100For instance, dependencies are allowed to go forward.
101On the other hand, some items like the package DESCR can't change at all.
102Since this is a generated file, porters often overlook that items such as
103the HOMEPAGE or the MAINTAINER's email address are embedded into that file,
104and thus that changing these requires a REVISION bump.
105.Pp
106If option
107.Fl n
108is specified,
109.Nm
110will do the exact same checks, but will not write any new packing-list.
111.Pp
112If option
113.Fl s Ar snapdir
114is specified,
115.Nm
116will write the packing-list into a separate
117.Ar snapdir
118directory if there have been no errors
119(snapshot directory, to record all packing-lists from the current snapshot).
120.Pp
121.Nm
122can also be invoked with
123.Fl p
124and a
125.Ar dir .
126This will read the packing-list from standard input and check
127that it would register correctly into
128.Ar dir ,
129as used by
130target
131.Cm check-register
132in
133.Xr bsd.port.mk 5 .
134.Pp
135.Nm
136can also be invoked with
137.Fl t
138and two packing-lists
139.Ar p1
140.Ar p2
141to directly compare those packing-lists.
142.Sh SEE ALSO
143.Xr bsd.port.mk 5
144