1  .\"
  2  .\" FreeBSD pkg - a next generation package for the installation and maintenance
  3  .\" of non-core utilities.
  4  .\"
  5  .\" Redistribution and use in source and binary forms, with or without
  6  .\" modification, are permitted provided that the following conditions
  7  .\" are met:
  8  .\" 1. Redistributions of source code must retain the above copyright
  9  .\"    notice, this list of conditions and the following disclaimer.
 10  .\" 2. Redistributions in binary form must reproduce the above copyright
 11  .\"    notice, this list of conditions and the following disclaimer in the
 12  .\"    documentation and/or other materials provided with the distribution.
 13  .\"
 14  .\"
 15  .\"     @(#)pkg.8
 16  .\"
 17  .Dd March 22, 2023
 18  .Dt PKG-REGISTER 8
 19  .Os
 20  .Sh NAME
 21  .Nm "pkg register"
 22  .Nd register a package into the local package database
 23  .Sh SYNOPSIS
 24  .Nm
 25  .Op Fl dltN
 26  .Op Fl f Ar plist-file
 27  .Fl m Ar metadatadir
 28  .Fl i Ar input-path
 29  .Nm
 30  .Op Fl dltN
 31  .Fl M Ar metadatafile
 32  .Pp
 33  .Nm
 34  .Op Cm --{debug,test,no-registration}
 35  .Op Cm --relocate Ar location
 36  .Op Cm --plist Ar plist-file
 37  .Cm --metadata Ar metadatadir
 38  .Cm --root Ar input-path
 39  .Nm
 40  .Op Cm --{debug,test,no-registration}
 41  .Op Cm --relocate Ar location
 42  .Cm --manifest Ar metadatafile
 43  .Sh DESCRIPTION
 44  .Nm
 45  is used for registering a package into the local package database.
 46  .Pp
 47  .Nm
 48  assembles a full set of package metadata from various possible inputs,
 49  and writes the metadata into the package registry database.
 50  This is one of the final steps when installing software from ports:
 51  the package files are installed into the filesystem, and then
 52  .Nm
 53  is called to record what was installed into the package database.
 54  .Pp
 55  .Nm
 56  can derive package metadata from a number of different sources:
 57  .Bl -bullet
 58  .It
 59  The package manifest
 60  .It
 61  The metadata directory
 62  .It
 63  Direct analysis of files installed by the package
 64  .El
 65  .Pp
 66  The package manifest is a
 67  .Cm UCL
 68  format listing of package metadata.
 69  It can contain all of the necessary metadata needed by the package,
 70  but the more usual approach is to provide selected items via the
 71  manifest, and fill in the rest, either from legacy files such as
 72  .Fa pkg-plist ,
 73  .Fa +DESC ,
 74  .Fa +DISPLAY
 75  or
 76  .Fa +MESSAGE
 77  which are optional and mostly located in the
 78  .Ar metadatadir
 79  given as the argument to the
 80  .Fl m
 81  option.
 82  .Pp
 83  Other information about shared library requirements and the packages
 84  necessary to provide them may be obtained by direct analysis of the
 85  files installed by the package.
 86  File checksums may be left blank in the input metadata:
 87  all checksums will be recalculated from the installed or staged files
 88  overwriting the input.
 89  This is the mechanism currently used when installing software directly
 90  from the ports tree, as it provides reasonable backwards compatibility
 91  with the old style
 92  .Xr pkg_add 1
 93  command.
 94  .Pp
 95  Reading in a complete and comprehensive manifest from one file is a
 96  simpler alternative, but requires all the metadata to have been
 97  assembled beforehand.
 98  .Pp
 99  Direct analysis of the installed files can be suppressed by use of
100  the
101  .Fl t
102  option.
103  This is intended for testing the functionality of
104  .Xr pkg 8
105  itself, and should not be routinely used.
106  .Sh OPTIONS
107  The following options are supported by
108  .Nm :
109  .Bl -tag -width metadata
110  .It Fl A , Cm --automatic
111  Mark the package to be automatically removed if no other packages
112  depend on it.
113  For more information please refer to
114  .Xr pkg-autoremove 8 .
115  .It Fl d , Cm --debug
116  Enable debugging output.
117  .It Fl N , Cm --no-registration
118  Disable registration in the package database, the files will be installed,
119  the scripts will be executed.
120  .It Fl f Ar plist-file , Cm --plist Ar plist-file
121  Specifies a
122  .Fa pkg-plist
123  style packing list file.
124  .It Fl i Ar input-path , Cm --root Ar input-path
125  Specifies the package input path or staging directory.
126  .It  Fl M Ar manifest , Cm --manifest Ar manifest
127  Specifies the package manifest file.
128  Use of this option means that the only file which will be used as a
129  source of package metadata is the named
130  .Ar manifest
131  file.
132  The
133  .Fl M
134  option is mutually exclusive with
135  .Fl m .
136  .It  Fl m Ar metadatadir , Cm --metadata Ar metadatadir
137  Specifies the metadata directory to use when registering the package.
138  This directory will hold the package manifest, and optionally may contain
139  a number of other old-style metadata input files.
140  The
141  .Fl m
142  option is mutually exclusive with
143  .Fl M .
144  .It  Fl t , Cm --test
145  Enable testing mode.
146  This allows
147  .Nm
148  to update the package database without performing any of the usual
149  analyses of files installed by the package.
150  This option should only be used with caution, and preferably only
151  for the intended purpose of performing regression tests on
152  .Xr pkg 8
153  itself.
154  .It Cm --relocate Ar location
155  Annotates the package as having been relocated to
156  .Pa location ,
157  which is an alternate system root.
158  This is an experimental feature and intended for cross-architecture
159  package management.
160  There is no corresponding single letter option.
161  .Pq DEPRECATED
162  .El
163  .Sh ENVIRONMENT
164  The following environment variables affect the execution of
165  .Nm .
166  See
167  .Xr pkg.conf 5
168  for further description.
169  .Bl -tag -width ".Ev NO_DESCRIPTIONS"
170  .It Ev PKG_DBDIR
171  .El
172  .Sh FILES
173  See
174  .Xr pkg.conf 5 .
175  .Sh SEE ALSO
176  .Xr pkg_create 3 ,
177  .Xr pkg_printf 3 ,
178  .Xr pkg_repo_create 3 ,
179  .Xr pkg_repos 3 ,
180  .Xr pkg-keywords 5 ,
181  .Xr pkg-lua-script 5 ,
182  .Xr pkg-repository 5 ,
183  .Xr pkg-script 5 ,
184  .Xr pkg-triggers 5 ,
185  .Xr pkg.conf 5 ,
186  .Xr pkg 8 ,
187  .Xr pkg-add 8 ,
188  .Xr pkg-alias 8 ,
189  .Xr pkg-annotate 8 ,
190  .Xr pkg-audit 8 ,
191  .Xr pkg-autoremove 8 ,
192  .Xr pkg-check 8 ,
193  .Xr pkg-clean 8 ,
194  .Xr pkg-config 8 ,
195  .Xr pkg-create 8 ,
196  .Xr pkg-delete 8 ,
197  .Xr pkg-fetch 8 ,
198  .Xr pkg-help 8 ,
199  .Xr pkg-info 8 ,
200  .Xr pkg-install 8 ,
201  .Xr pkg-key 8 ,
202  .Xr pkg-lock 8 ,
203  .Xr pkg-plugins 8 ,
204  .Xr pkg-query 8 ,
205  .Xr pkg-repo 8 ,
206  .Xr pkg-repositories 8 ,
207  .Xr pkg-rquery 8 ,
208  .Xr pkg-search 8 ,
209  .Xr pkg-set 8 ,
210  .Xr pkg-shell 8 ,
211  .Xr pkg-shlib 8 ,
212  .Xr pkg-ssh 8 ,
213  .Xr pkg-stats 8 ,
214  .Xr pkg-triggers 8 ,
215  .Xr pkg-unregister 8 ,
216  .Xr pkg-update 8 ,
217  .Xr pkg-updating 8 ,
218  .Xr pkg-upgrade 8 ,
219  .Xr pkg-version 8 ,
220  .Xr pkg-which 8