1.\" $NetBSD: pkg_create.1,v 1.2 2015/10/10 10:08:12 mbalmer Exp $ 2.\" 3.\" FreeBSD install - a package for the installation and maintenance 4.\" of non-core utilities. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" Jordan K. Hubbard 16.\" 17.\" 18.\" @(#)pkg_create.1 19.\" from FreeBSD Id: pkg_create.1,v 1.19 1997/05/02 22:00:05 max Exp 20.\" 21.\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords, 22.\" added dependency tracking, etc. 23.\" 24.\" [jkh] Took John's changes back and made some additional extensions for 25.\" better integration with FreeBSD's new ports collection. 26.\" 27.Dd October 10, 2015 28.Dt PKG_CREATE 1 29.Os 30.Sh NAME 31.Nm pkg_create 32.Nd a utility for creating software package distributions 33.Sh SYNOPSIS 34.Nm 35.Op Fl ElOUVv 36.Bk -words 37.Op Fl B Ar build-info-file 38.Ek 39.Bk -words 40.Op Fl b Ar build-version-file 41.Ek 42.Bk -words 43.Op Fl C Ar cpkgs 44.Ek 45.Bk -words 46.Op Fl D Ar displayfile 47.Ek 48.Bk -words 49.Op Fl F Ar compression 50.Ek 51.Bk -words 52.Op Fl g Ar group 53.Ek 54.Bk -words 55.Op Fl I Ar realprefix 56.Ek 57.Bk -words 58.Op Fl i Ar iscript 59.Ek 60.Bk -words 61.Op Fl K Ar pkg_dbdir 62.Ek 63.Bk -words 64.Op Fl k Ar dscript 65.Ek 66.Bk -words 67.Op Fl n Ar preserve-file 68.Ek 69.Bk -words 70.Op Fl P Ar dpkgs 71.Ek 72.Bk -words 73.Op Fl T Ar buildpkgs 74.Ek 75.Bk -words 76.Op Fl p Ar prefix 77.Ek 78.Bk -words 79.Op Fl S Ar size-all-file 80.Ek 81.Bk -words 82.Op Fl s Ar size-pkg-file 83.Ek 84.Bk -words 85.Op Fl t Ar template 86.Ek 87.Bk -words 88.Op Fl u Ar owner 89.Ek 90.Bk -words 91.Fl c Ar comment 92.Ek 93.Bk -words 94.Fl d Ar description 95.Ek 96.Bk -words 97.Fl f Ar packlist 98.Ek 99.Ar pkg-name 100.Sh DESCRIPTION 101The 102.Nm 103command is used to create packages that will subsequently be fed to 104one of the package extraction/info utilities. 105The input description and command line arguments for the creation of a 106package are not really meant to be human-generated, though it is easy 107enough to do so. 108It is more expected that you will use a front-end tool for 109the job rather than muddling through it yourself. 110Nonetheless, a short description of the input syntax is included in this 111document. 112.Sh OPTIONS 113The following command line options are supported: 114.Bl -tag -width indent 115.It Fl B Ar build-info-file 116Install the file 117.Ar build-info-file 118so that users of binary packages can see what 119.Xr make 1 120definitions 121were used to control the build when creating the 122binary package. 123This allows various build definitions to be retained in a binary package 124and viewed wherever it is installed, using 125.Xr pkg_info 1 . 126.It Fl b Ar build-version-file 127Install the file 128.Ar build-version-file 129so that users of binary packages can see what versions of 130the files used to control the build were used when creating the 131binary package. 132This allows some fine-grained version control information to be retained 133in a binary package and viewed wherever it is installed, using 134.Xr pkg_info 1 . 135.It Fl C Ar cpkgs 136Set the initial package conflict list to 137.Ar cpkgs . 138This is assumed to be a whitespace separated list of package names 139and is meant as a convenient shorthand for specifying multiple 140.Cm @pkgcfl 141directives in the packing list (see PACKING LIST DETAILS section below). 142.It Fl c Ar [-]desc 143Fetch package 144.Pq one line description 145from file 146.Ar desc 147or, if preceded by 148.Cm - , 149the argument itself. 150This string should also give some idea of which version of the product 151(if any) the package represents. 152.It Fl D Ar displayfile 153Display the file after installing the package. 154Useful for things like legal notices on almost-free software, etc. 155.It Fl d Ar [-]desc 156Fetch long description for package from file 157.Ar desc 158or, if preceded by 159.Cm - , 160the argument itself. 161.It Fl E 162Add an empty views file to the package. 163.It Fl F Ar compression 164Use 165.Ar compression 166as compression algorithm. 167This overrides the heuristic to guess the compression type from the 168output name. 169Currently supported values are bzip2, gzip, none and xz. 170.It Fl f Ar packlist 171Fetch 172.Pq packing list 173for package from the file 174.Ar packlist 175or 176.Cm stdin 177if 178.Ar packlist 179is a 180.Cm - 181(dash). 182.It Fl g Ar group 183Make 184.Ar group 185the default group ownership instead of extracting it from the file system. 186.It Fl I Ar realprefix 187Provide the real prefix, as opposed to the staging prefix, for use in 188staged installations of packages. 189.It Fl i Ar iscript 190Set 191.Ar iscript 192to be the install procedure for the package. 193This can be any executable program (or shell script). 194It will be invoked automatically when the package is later installed. 195.It Fl K Ar pkg_dbdir 196Override the value of the 197.Dv PKG_DBDIR 198configuration option with the value 199.Ar pkg_dbdir . 200.It Fl k Ar dscript 201Set 202.Ar dscript 203to be the de-install procedure for the package. 204This can be any executable program (or shell script). 205It will be invoked automatically 206when the package is later (if ever) de-installed. 207.It Fl l 208Check that any symbolic links which are to be placed in the package are 209relative to the current prefix. 210This means using 211.Xr unlink 2 212and 213.Xr symlink 2 214to remove and re-link 215any symbolic links which are targeted at full path names. 216.It Fl n Ar preserve-file 217The file is used to denote that the package should not be deleted. 218This is intended for use where the deletion of packages may present 219a bootstrap problem. 220.It Fl O 221Go into a 222.Pq packing list only 223mode. 224This is used to do 225.Pq fake pkg_add 226operations when a package is installed. 227In such cases, it is necessary to know what the final, adjusted packing 228list will look like. 229.It Fl P Ar dpkgs 230Set the initial package dependency list to 231.Ar dpkgs . 232This is assumed to be a whitespace separated list of package names 233and is meant as a convenient shorthand for specifying multiple 234.Cm @pkgdep 235directives in the packing list (see PACKING LIST DETAILS section below). 236In addition, the exact versions of the packages referred to in the 237.Ar dpkgs 238list will be added to the packing list in the form of 239.Cm @blddep 240directives. 241.It Fl T Ar buildpkgs 242The exact versions of the packages referred to in the 243.Ar buildpkgs 244list will be added to the packing list in the form of 245.Cm @blddep 246directives. 247This directives are stored after those created by the 248.Fl P 249option. 250.Ar buildpkgs 251is assumed to be a whitespace separated list of package names. 252.It Fl p Ar prefix 253Set 254.Ar prefix 255as the initial directory 256.Pq base 257to start from in selecting files for 258the package. 259.It Fl S Ar size-all-file 260Store the given file for later querying with the 261.Xr pkg_info 1 262.Fl S 263flag. 264The file is expected to contain the size (in bytes) of all files of 265this package plus any required packages added up and stored as a 266ASCII string, terminated by a newline. 267.It Fl s Ar size-pkg-file 268Store the given file for later querying with the 269.Xr pkg_info 1 270.Fl s 271flag. 272The file is expected to contain the size (in bytes) of all files of 273this package added up and stored as a ASCII string, terminated by a newline. 274.It Fl t Ar template 275Use 276.Ar template 277as the input to 278.Xr mktemp 3 . 279By default, this is the string 280.Pa /tmp/instmp.XXXXXX , 281but it may be necessary to override it in the situation where 282space in your 283.Pa /tmp 284directory is limited. 285Be sure to leave some number of 286.Sq X 287characters for 288.Xr mktemp 3 289to fill in with a unique ID. 290.It Fl U 291Do not update the package file database with any file information. 292.It Fl u Ar owner 293Make 294.Ar owner 295the default owner instead of extracting it from the file system. 296.It Fl V 297Print version number and exit. 298.It Fl v 299Turn on verbose output. 300.El 301.Sh PACKING LIST DETAILS 302The 303.Pq packing list 304format (see 305.Fl f ) 306is fairly simple, being 307nothing more than a single column of filenames to include in the 308package. 309However, since absolute pathnames are generally a bad idea 310for a package that could be installed potentially anywhere, there is 311another method of specifying where things are supposed to go 312and, optionally, what ownership and mode information they should be 313installed with. 314This is done by embedding specialized command sequences 315in the packing list. 316Briefly described, these sequences are: 317.Bl -tag -width indent -compact 318.It Cm @cwd Ar directory 319Set the internal directory pointer to point to 320.Ar directory . 321All subsequent filenames will be assumed relative to this directory. 322Note: 323.Cm @cd 324is also an alias for this command. 325.It Cm @src Ar directory 326This command is supported for compatibility only. 327It was formerly used to override 328.Cm @cwd 329during package creation. 330.It Cm @exec Ar command 331Execute 332.Ar command 333as part of the unpacking process. 334If 335.Ar command 336contains any of the following sequences somewhere in it, they will 337be expanded inline. 338For the following examples, assume that 339.Cm @cwd 340is set to 341.Pa /usr/local 342and the last extracted file was 343.Pa bin/emacs . 344.Bl -tag -width indent -compact 345.It Cm "\&%F" 346Expands to the last filename extracted (as specified), in the example case 347.Pa bin/emacs 348.It Cm "\&%D" 349Expand to the current directory prefix, as set with 350.Cm @cwd , 351in the example case 352.Pa /usr/local . 353.It Cm "\&%B" 354Expand to the 355.Pq basename 356of the fully qualified filename, that 357is the current directory prefix, plus the last filespec, minus 358the trailing filename. 359In the example case, that would be 360.Pa /usr/local/bin . 361.It Cm "\&%f" 362Expand to the 363.Pq filename 364part of the fully qualified name, or 365the converse of 366.Cm \&%B , 367being in the example case, 368.Pa emacs . 369.El 370.It Cm @unexec Ar command 371Execute 372.Ar command 373as part of the deinstallation process. 374Expansion of special 375.Cm \&% 376sequences is the same as for 377.Cm @exec . 378This command is not executed during the package add, as 379.Cm @exec 380is, but rather when the package is deleted. 381This is useful for deleting links and other ancillary files that were created 382as a result of adding the package, but not directly known to the package's 383table of contents (and hence not automatically removable). 384The advantage of using 385.Cm @unexec 386over a deinstallation script is that you can use the 387.Pq special sequence expansion 388to get at files regardless of where they've 389been potentially redirected (see 390.Fl p ) . 391.It Cm @mode Ar mode 392Set default permission for all subsequently extracted files to 393.Ar mode . 394Format is the same as that used by the 395.Cm chmod 396command (well, considering that it's later handed off to it, that's 397no surprise). 398Use without an arg to set back to default (extraction) permissions. 399.It Cm @option Ar option 400Set internal package options, the only currently supported one 401being 402.Ar preserve , 403which tells pkg_add to move any existing files out of the way, 404preserving the previous contents (which are also resurrected on 405pkg_delete, so caveat emptor). 406.It Cm @owner Ar user 407Set default ownership for all subsequently extracted files to 408.Ar user . 409Use without an arg to set back to default (extraction) 410ownership. 411.It Cm @group Ar group 412Set default group ownership for all subsequently extracted files to 413.Ar group . 414Use without an arg to set back to default (extraction) 415group ownership. 416.It Cm @comment Ar string 417Embed a comment in the packing list. 418Useful in trying to document some particularly hairy sequence that 419may trip someone up later. 420.It Cm @ignore 421Used internally to tell extraction to ignore the next file (don't 422copy it anywhere), as it's used for some special purpose. 423.It Cm @name Ar name 424Set the name of the package. 425This is mandatory and is usually put at the top. 426This name is potentially different than the name of the file it came in, 427and is used when keeping track of the package for later deinstallation. 428Note that 429.Nm 430will derive this field from the 431.Ar pkg-name 432and add it automatically if none is given. 433.It Cm @pkgdir Ar name 434Declare directory 435.Pa name 436as managed. 437If it does not exist at installation time, it is created. 438If this directory is no longer referenced by packages and the last 439file or directory in it is deleted, the directory is removed as well. 440.It Cm @dirrm Ar name 441This command is supported for compatibility only. 442If directory 443.Pa name 444exists, it will be deleted at deinstall time. 445.It Cm @display Ar name 446Declare 447.Pa name 448as the file to be displayed at install time (see 449.Fl D 450above). 451.It Cm @pkgdep Ar pkgname 452Declare a dependency on the 453.Ar pkgname 454package. 455The 456.Ar pkgname 457package must be installed before this package may be 458installed, and this package must be deinstalled before the 459.Ar pkgname 460package is deinstalled. 461Multiple 462.Cm @pkgdep 463directives may be used if the package depends on multiple other packages. 464.It Cm @blddep Ar pkgname 465Declare that this package was built with the exact version 466of 467.Ar pkgname 468(since the 469.Cm @pkgdep 470directive may contain wildcards or relational 471package version information). 472.It Cm @pkgcfl Ar pkgcflname 473Declare a conflict with the 474.Ar pkgcflname 475package, as the two packages contain references to the same files, 476and so cannot co-exist on the same system. 477.El 478.Sh ENVIRONMENT 479See 480.Xr pkg_install.conf 5 481for options, that can also be specified using the environment. 482.Sh SEE ALSO 483.Xr pkg_add 1 , 484.Xr pkg_admin 1 , 485.Xr pkg_delete 1 , 486.Xr pkg_info 1 , 487.Xr pkg_install.conf 5 488.Xr pkgsrc 7 489.Sh HISTORY 490The 491.Nm 492command first appeared in 493.Fx . 494.Sh AUTHORS 495.Bl -tag -width indent -compact 496.It Jordan Hubbard 497did most of the work. 498.It John Kohl 499refined it for 500.Nx . 501.It Hubert Feyrer 502added 503.Nx 504wildcard dependency processing, pkgdb, pkg size recording etc. 505.El 506