doc/pkgsrc.html

   1 <html xmlns="http://www.w3.org/1999/xhtml">
   2 <head>
   3   <meta name="generator" content=
   4   "HTML Tidy for NetBSD (vers 1st August 2004), see www.w3.org" />
   5   <meta http-equiv="Content-Type" content=
   6   "text/html; charset=us-ascii" />
   7
   8   <title>The pkgsrc guide</title>
   9   <link rel="stylesheet" href="/NetBSD.css" type="text/css" />
  10   <meta name="generator" content=
  11   "DocBook XSL Stylesheets VX.X.X" />
  12   <meta name="description" content=
  13   "Information about using the NetBSD package system (pkgsrc) from both a user view for installing packages as well as from a pkgsrc developers' view for creating new packages." />
  14   </head>
  15
  16 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
  17 alink="#0000FF">
  18   <div class="book" lang="en" xml:lang="en">
  19     <div class="titlepage">
  20       <div>
  21         <div>
  22           <h1 class="title"><a name="the-pkgsrc-guide" id=
  23           "the-pkgsrc-guide"></a>The pkgsrc guide</h1>
  24         </div>
  25
  26         <div>
  27           <h2 class="subtitle">Documentation on the NetBSD packages
  28           system</h2>
  29         </div>
  30
  31         <div>
  32           <div class="authorgroup">
  33             <div class="author">
  34               <h3 class="author"><span class=
  35               "firstname">Alistair</span> <span class=
  36               "surname">Crooks</span></h3>
  37
  38               <div class="affiliation">
  39                 <div class="address">
  40                   <p><code class="email">&lt;<a href=
  41                   "mailto:agc@NetBSD.org">agc@NetBSD.org</a>&gt;</code></p>
  42                 </div>
  43               </div>
  44             </div>
  45
  46             <div class="author">
  47               <h3 class="author"><span class=
  48               "firstname">Hubert</span> <span class=
  49               "surname">Feyrer</span></h3>
  50
  51               <div class="affiliation">
  52                 <div class="address">
  53                   <p><code class="email">&lt;<a href=
  54                   "mailto:hubertf@NetBSD.org">hubertf@NetBSD.org</a>&gt;</code></p>
  55                 </div>
  56               </div>
  57             </div>
  58
  59             <h3 class="corpauthor">The pkgsrc Developers</h3>
  60           </div>
  61         </div>
  62
  63         <div>
  64           <p class="copyright">Copyright &#169; 1994-2005 The
  65           NetBSD Foundation, Inc</p>
  66         </div>
  67
  68         <div xmlns="http://www.w3.org/TR/xhtml1/transitional">
  69           <p xmlns="" class="pubdate">$NetBSD: pkgsrc.xml,v 1.10
  70           2005/10/05 13:59:56 dillo Exp $</p>
  71         </div>
  72
  73         <div>
  74           <div class="abstract">
  75             <p class="title"><b>Abstract</b></p>
  76
  77             <p>Information about using the NetBSD package system
  78             (pkgsrc) from both a user view for installing packages
  79             as well as from a pkgsrc developers' view for creating
  80             new packages.</p>
  81           </div>
  82         </div>
  83       </div>
  84       <hr />
  85     </div>
  86
  87     <div class="toc">
  88       <p><b>Table of Contents</b></p>
  89
  90       <dl>
  91         <dt><span class="chapter"><a href="#introduction">1. What
  92         is pkgsrc?</a></span></dt>
  93
  94         <dd>
  95           <dl>
  96             <dt><span class="sect1"><a href=
  97             "#introduction-section">1.1.
  98             Introduction</a></span></dt>
  99
 100             <dt><span class="sect1"><a href="#overview">1.2.
 101             Overview</a></span></dt>
 102
 103             <dt><span class="sect1"><a href="#terminology">1.3.
 104             Terminology</a></span></dt>
 105
 106             <dt><span class="sect1"><a href="#typography">1.4.
 107             Typography</a></span></dt>
 108           </dl>
 109         </dd>
 110
 111         <dt><span class="part"><a href="#users-guide">I. The pkgsrc
 112         user's guide</a></span></dt>
 113
 114         <dd>
 115           <dl>
 116             <dt><span class="chapter"><a href="#getting">2. Where
 117             to get pkgsrc</a></span></dt>
 118
 119             <dd>
 120               <dl>
 121                 <dt><span class="sect1"><a href="#as-tar-file">2.1.
 122                 As tar file</a></span></dt>
 123
 124                 <dt><span class="sect1"><a href="#via-sup">2.2. Via
 125                 SUP</a></span></dt>
 126
 127                 <dt><span class="sect1"><a href="#via-cvs">2.3. Via
 128                 CVS</a></span></dt>
 129               </dl>
 130             </dd>
 131
 132             <dt><span class="chapter"><a href="#platforms">3. Using
 133             pkgsrc on systems other than NetBSD</a></span></dt>
 134
 135             <dd>
 136               <dl>
 137                 <dt><span class="sect1"><a href=
 138                 "#bootstrapping-pkgsrc">3.1. Bootstrapping
 139                 pkgsrc</a></span></dt>
 140
 141                 <dt><span class="sect1"><a href=
 142                 "#platform-specific-notes">3.2. Platform-specific
 143                 notes</a></span></dt>
 144
 145                 <dd>
 146                   <dl>
 147                     <dt><span class="sect2"><a href=
 148                     "#darwin">3.2.1. Darwin (Mac OS
 149                     X)</a></span></dt>
 150
 151                     <dt><span class="sect2"><a href=
 152                     "#freebsd">3.2.2. FreeBSD</a></span></dt>
 153
 154                     <dt><span class="sect2"><a href=
 155                     "#interix">3.2.3. Interix</a></span></dt>
 156
 157                     <dt><span class="sect2"><a href="#irix">3.2.4.
 158                     IRIX</a></span></dt>
 159
 160                     <dt><span class="sect2"><a href="#linux">3.2.5.
 161                     Linux</a></span></dt>
 162
 163                     <dt><span class="sect2"><a href=
 164                     "#openbsd">3.2.6. OpenBSD</a></span></dt>
 165
 166                     <dt><span class="sect2"><a href=
 167                     "#solaris">3.2.7. Solaris</a></span></dt>
 168                   </dl>
 169                 </dd>
 170               </dl>
 171             </dd>
 172
 173             <dt><span class="chapter"><a href="#using">4. Using
 174             pkgsrc</a></span></dt>
 175
 176             <dd>
 177               <dl>
 178                 <dt><span class="sect1"><a href=
 179                 "#getting-started">4.1. Working with binary
 180                 packages</a></span></dt>
 181
 182                 <dd>
 183                   <dl>
 184                     <dt><span class="sect2"><a href=
 185                     "#where-to-get-binary-packages">4.1.1. Where to
 186                     get binary packages</a></span></dt>
 187
 188                     <dt><span class="sect2"><a href=
 189                     "#how-to-use-binary-packages">4.1.2. How to use
 190                     binary packages</a></span></dt>
 191
 192                     <dt><span class="sect2"><a href=
 193                     "#a-word-of-warning">4.1.3. A word of
 194                     warning</a></span></dt>
 195                   </dl>
 196                 </dd>
 197
 198                 <dt><span class="sect1"><a href=
 199                 "#building-packages-from-source">4.2. Building
 200                 packages from source</a></span></dt>
 201
 202                 <dd>
 203                   <dl>
 204                     <dt><span class="sect2"><a href=
 205                     "#requirements">4.2.1.
 206                     Requirements</a></span></dt>
 207
 208                     <dt><span class="sect2"><a href=
 209                     "#fetching-distfiles">4.2.2. Fetching
 210                     distfiles</a></span></dt>
 211
 212                     <dt><span class="sect2"><a href=
 213                     "#how-to-build-and-install">4.2.3. How to build
 214                     and install</a></span></dt>
 215
 216                     <dt><span class="sect2"><a href=
 217                     "#selecting-the-compiler">4.2.4. Selecting the
 218                     compiler</a></span></dt>
 219                   </dl>
 220                 </dd>
 221               </dl>
 222             </dd>
 223
 224             <dt><span class="chapter"><a href="#configuring">5.
 225             Configuring pkgsrc</a></span></dt>
 226
 227             <dd>
 228               <dl>
 229                 <dt><span class="sect1"><a href=
 230                 "#general-configuration">5.1. General
 231                 configuration</a></span></dt>
 232
 233                 <dt><span class="sect1"><a href=
 234                 "#variables-affecting-build">5.2. Variables
 235                 affecting the build process</a></span></dt>
 236
 237                 <dt><span class="sect1"><a href=
 238                 "#developer-advanced-settings">5.3.
 239                 Developer/advanced settings</a></span></dt>
 240
 241                 <dt><span class="sect1"><a href=
 242                 "#selecting-build-options">5.4. Selecting Build
 243                 Options</a></span></dt>
 244               </dl>
 245             </dd>
 246
 247             <dt><span class="chapter"><a href="#binary">6. Creating
 248             binary packages</a></span></dt>
 249
 250             <dd>
 251               <dl>
 252                 <dt><span class="sect1"><a href=
 253                 "#building-a-single-binary-package">6.1. Building a
 254                 single binary package</a></span></dt>
 255
 256                 <dt><span class="sect1"><a href=
 257                 "#settings-for-creationg-of-binary-packages">6.2.
 258                 Settings for creation of binary
 259                 packages</a></span></dt>
 260
 261                 <dt><span class="sect1"><a href="#bulkbuild">6.3.
 262                 Doing a bulk build of all packages</a></span></dt>
 263
 264                 <dd>
 265                   <dl>
 266                     <dt><span class="sect2"><a href=
 267                     "#binary.configuration">6.3.1.
 268                     Configuration</a></span></dt>
 269
 270                     <dt><span class="sect2"><a href=
 271                     "#other-environmental-considerations">6.3.2.
 272                     Other environmental
 273                     considerations</a></span></dt>
 274
 275                     <dt><span class="sect2"><a href=
 276                     "#operation">6.3.3. Operation</a></span></dt>
 277
 278                     <dt><span class="sect2"><a href=
 279                     "#what-it-does">6.3.4. What it
 280                     does</a></span></dt>
 281
 282                     <dt><span class="sect2"><a href=
 283                     "#disk-space-requirements">6.3.5. Disk space
 284                     requirements</a></span></dt>
 285
 286                     <dt><span class="sect2"><a href=
 287                     "#setting-up-a-sandbox">6.3.6. Setting up a
 288                     sandbox for chrooted builds</a></span></dt>
 289
 290                     <dt><span class="sect2"><a href=
 291                     "#building-a-partial-set">6.3.7. Building a
 292                     partial set of packages</a></span></dt>
 293
 294                     <dt><span class="sect2"><a href=
 295                     "#bulk-upload">6.3.8. Uploading results of a
 296                     bulk build</a></span></dt>
 297                   </dl>
 298                 </dd>
 299
 300                 <dt><span class="sect1"><a href=
 301                 "#creating-cdroms">6.4. Creating a multiple CD-ROM
 302                 packages collection</a></span></dt>
 303
 304                 <dd>
 305                   <dl>
 306                     <dt><span class="sect2"><a href=
 307                     "#cdpack-example">6.4.1. Example of
 308                     cdpack</a></span></dt>
 309                   </dl>
 310                 </dd>
 311               </dl>
 312             </dd>
 313
 314             <dt><span class="chapter"><a href="#faq">7. Frequently
 315             Asked Questions</a></span></dt>
 316
 317             <dd>
 318               <dl>
 319                 <dt><span class="sect1"><a href=
 320                 "#mailing-list-pointers">7.1. Are there any mailing
 321                 lists for pkg-related discussion?</a></span></dt>
 322
 323                 <dt><span class="sect1"><a href=
 324                 "#pkgviews-docs">7.2. Where's the pkgviews
 325                 documentation?</a></span></dt>
 326
 327                 <dt><span class="sect1"><a href=
 328                 "#faq-pkgtools">7.3. Utilities for package
 329                 management (pkgtools)</a></span></dt>
 330
 331                 <dt><span class="sect1"><a href=
 332                 "#non-root-pkgsrc">7.4. How to use pkgsrc as
 333                 non-root</a></span></dt>
 334
 335                 <dt><span class="sect1"><a href=
 336                 "#resume-transfers">7.5. How to resume transfers
 337                 when fetching distfiles?</a></span></dt>
 338
 339                 <dt><span class="sect1"><a href=
 340                 "#XFree86-from-pkgsrc">7.6. How can I install/use
 341                 XFree86 from pkgsrc?</a></span></dt>
 342
 343                 <dt><span class="sect1"><a href=
 344                 "#x.org-from-pkgsrc">7.7. How can I install/use
 345                 X.org from pkgsrc?</a></span></dt>
 346
 347                 <dt><span class="sect1"><a href=
 348                 "#fetch-behind-firewall">7.8. How to fetch files
 349                 from behind a firewall</a></span></dt>
 350
 351                 <dt><span class="sect1"><a href="#passive-ftp">7.9.
 352                 How do I tell <span><strong class="command">make
 353                 fetch</strong></span> to do passive
 354                 FTP?</a></span></dt>
 355
 356                 <dt><span class="sect1"><a href=
 357                 "#fetching-all-distfiles">7.10. How to fetch all
 358                 distfiles at once</a></span></dt>
 359
 360                 <dt><span class="sect1"><a href=
 361                 "#tmac.andoc-missing">7.11. What does
 362                 &#8220;<span class="quote">Don't know how to make
 363                 /usr/share/tmac/tmac.andoc</span>&#8221;
 364                 mean?</a></span></dt>
 365
 366                 <dt><span class="sect1"><a href=
 367                 "#bsd.own.mk-missing">7.12. What does
 368                 &#8220;<span class="quote">Could not find
 369                 bsd.own.mk</span>&#8221; mean?</a></span></dt>
 370
 371                 <dt><span class="sect1"><a href=
 372                 "#using-sudo-with-pkgsrc">7.13. Using 'sudo' with
 373                 pkgsrc</a></span></dt>
 374
 375                 <dt><span class="sect1"><a href="#faq.conf">7.14.
 376                 How do I change the location of configuration
 377                 files?</a></span></dt>
 378
 379                 <dt><span class="sect1"><a href=
 380                 "#audit-packages">7.15. Automated security
 381                 checks</a></span></dt>
 382               </dl>
 383             </dd>
 384           </dl>
 385         </dd>
 386
 387         <dt><span class="part"><a href="#developers-guide">II. The
 388         pkgsrc developer's guide</a></span></dt>
 389
 390         <dd>
 391           <dl>
 392             <dt><span class="chapter"><a href="#components">8.
 393             Package components - files, directories and
 394             contents</a></span></dt>
 395
 396             <dd>
 397               <dl>
 398                 <dt><span class="sect1"><a href=
 399                 "#components.Makefile">8.1. <code xmlns=
 400                 "http://www.w3.org/TR/xhtml1/transitional" class=
 401                 "filename">Makefile</code></a></span></dt>
 402
 403                 <dt><span class="sect1"><a href=
 404                 "#components.distinfo">8.2. <code xmlns=
 405                 "http://www.w3.org/TR/xhtml1/transitional" class=
 406                 "filename">distinfo</code></a></span></dt>
 407
 408                 <dt><span class="sect1"><a href=
 409                 "#components.patches">8.3.
 410                 patches/*</a></span></dt>
 411
 412                 <dt><span class="sect1"><a href=
 413                 "#other-mandatory-files">8.4. Other mandatory
 414                 files</a></span></dt>
 415
 416                 <dt><span class="sect1"><a href=
 417                 "#components.optional">8.5. Optional
 418                 files</a></span></dt>
 419
 420                 <dt><span class="sect1"><a href="#work-dir">8.6.
 421                 <code xmlns=
 422                 "http://www.w3.org/TR/xhtml1/transitional" class=
 423                 "filename">work*</code></a></span></dt>
 424
 425                 <dt><span class="sect1"><a href="#files-dir">8.7.
 426                 <code xmlns=
 427                 "http://www.w3.org/TR/xhtml1/transitional" class=
 428                 "filename">files/*</code></a></span></dt>
 429               </dl>
 430             </dd>
 431
 432             <dt><span class="chapter"><a href="#makefile">9.
 433             Programming in <code xmlns=
 434             "http://www.w3.org/TR/xhtml1/transitional" class=
 435             "filename">Makefile</code>s</a></span></dt>
 436
 437             <dd>
 438               <dl>
 439                 <dt><span class="sect1"><a href=
 440                 "#makefile.variables">9.1. <code xmlns=
 441                 "http://www.w3.org/TR/xhtml1/transitional" class=
 442                 "filename">Makefile</code>
 443                 variables</a></span></dt>
 444
 445                 <dd>
 446                   <dl>
 447                     <dt><span class="sect2"><a href=
 448                     "#makefile.variables.names">9.1.1. Naming
 449                     conventions</a></span></dt>
 450                   </dl>
 451                 </dd>
 452
 453                 <dt><span class="sect1"><a href=
 454                 "#makefile.code">9.2. Code snippets</a></span></dt>
 455
 456                 <dd>
 457                   <dl>
 458                     <dt><span class="sect2"><a href=
 459                     "#adding-to-list">9.2.1. Adding things to a
 460                     list</a></span></dt>
 461
 462                     <dt><span class="sect2"><a href=
 463                     "#converting-internal-to-external">9.2.2.
 464                     Converting an internal list into an external
 465                     list</a></span></dt>
 466
 467                     <dt><span class="sect2"><a href=
 468                     "#passing-variable-to-shell">9.2.3. Passing
 469                     variables to a shell command</a></span></dt>
 470
 471                     <dt><span class="sect2"><a href=
 472                     "#quoting-guideline">9.2.4. Quoting
 473                     guideline</a></span></dt>
 474
 475                     <dt><span class="sect2"><a href=
 476                     "#bsd-make-bug-workaround">9.2.5. Workaround
 477                     for a bug in BSD Make</a></span></dt>
 478                   </dl>
 479                 </dd>
 480               </dl>
 481             </dd>
 482
 483             <dt><span class="chapter"><a href="#plist">10. PLIST
 484             issues</a></span></dt>
 485
 486             <dd>
 487               <dl>
 488                 <dt><span class="sect1"><a href="#rcs-id">10.1. RCS
 489                 ID</a></span></dt>
 490
 491                 <dt><span class="sect1"><a href=
 492                 "#automatic-plist-generation">10.2. Semi-automatic
 493                 <code xmlns=
 494                 "http://www.w3.org/TR/xhtml1/transitional" class=
 495                 "filename">PLIST</code> generation</a></span></dt>
 496
 497                 <dt><span class="sect1"><a href=
 498                 "#print-PLIST">10.3. Tweaking output of
 499                 <span><strong class="command">make
 500                 print-PLIST</strong></span></a></span></dt>
 501
 502                 <dt><span class="sect1"><a href="#plist.misc">10.4.
 503                 Variable substitution in PLIST</a></span></dt>
 504
 505                 <dt><span class="sect1"><a href=
 506                 "#manpage-compression">10.5. Man page
 507                 compression</a></span></dt>
 508
 509                 <dt><span class="sect1"><a href=
 510                 "#using-PLIST_SRC">10.6. Changing PLIST source with
 511                 <code class=
 512                 "varname">PLIST_SRC</code></a></span></dt>
 513
 514                 <dt><span class="sect1"><a href=
 515                 "#platform-specific-plist">10.7. Platform-specific
 516                 and differing PLISTs</a></span></dt>
 517
 518                 <dt><span class="sect1"><a href=
 519                 "#faq.common-dirs">10.8. Sharing directories
 520                 between packages</a></span></dt>
 521               </dl>
 522             </dd>
 523
 524             <dt><span class="chapter"><a href="#buildlink">11.
 525             Buildlink methodology</a></span></dt>
 526
 527             <dd>
 528               <dl>
 529                 <dt><span class="sect1"><a href=
 530                 "#converting-to-buildlink3">11.1. Converting
 531                 packages to use buildlink3</a></span></dt>
 532
 533                 <dt><span class="sect1"><a href=
 534                 "#creating-buildlink3.mk">11.2. Writing
 535                 <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
 536                 class="filename">buildlink3.mk</code>
 537                 files</a></span></dt>
 538
 539                 <dd>
 540                   <dl>
 541                     <dt><span class="sect2"><a href=
 542                     "#anatomy-of-bl3">11.2.1. Anatomy of a
 543                     buildlink3.mk file</a></span></dt>
 544
 545                     <dt><span class="sect2"><a href=
 546                     "#updating-buildlink-depends">11.2.2. Updating
 547                     <code class=
 548                     "varname">BUILDLINK_DEPENDS.<em class=
 549                     "replaceable"><code>pkg</code></em></code> in
 550                     <code xmlns=
 551                     "http://www.w3.org/TR/xhtml1/transitional"
 552                     class="filename">buildlink3.mk</code>
 553                     files</a></span></dt>
 554                   </dl>
 555                 </dd>
 556
 557                 <dt><span class="sect1"><a href=
 558                 "#writing-builtin.mk">11.3. Writing <code xmlns=
 559                 "http://www.w3.org/TR/xhtml1/transitional" class=
 560                 "filename">builtin.mk</code> files</a></span></dt>
 561
 562                 <dd>
 563                   <dl>
 564                     <dt><span class="sect2"><a href=
 565                     "#anatomy-of-builtin.mk">11.3.1. Anatomy of a
 566                     <code xmlns=
 567                     "http://www.w3.org/TR/xhtml1/transitional"
 568                     class="filename">builtin.mk</code>
 569                     file</a></span></dt>
 570
 571                     <dt><span class="sect2"><a href=
 572                     "#native-or-pkgsrc-preference">11.3.2. Global
 573                     preferences for native or pkgsrc
 574                     software</a></span></dt>
 575                   </dl>
 576                 </dd>
 577               </dl>
 578             </dd>
 579
 580             <dt><span class="chapter"><a href="#pkginstall">12. The
 581             pkginstall framework</a></span></dt>
 582
 583             <dd>
 584               <dl>
 585                 <dt><span class="sect1"><a href=
 586                 "#files-and-dirs-outside-prefix">12.1. Files and
 587                 directories outside the installation
 588                 prefix</a></span></dt>
 589
 590                 <dd>
 591                   <dl>
 592                     <dt><span class="sect2"><a href=
 593                     "#dirs-outside-prefix">12.1.1. Directory
 594                     manipulation</a></span></dt>
 595
 596                     <dt><span class="sect2"><a href=
 597                     "#files-outside-prefix">12.1.2. File
 598                     manipulation</a></span></dt>
 599                   </dl>
 600                 </dd>
 601
 602                 <dt><span class="sect1"><a href="#conf-files">12.2.
 603                 Configuration files</a></span></dt>
 604
 605                 <dd>
 606                   <dl>
 607                     <dt><span class="sect2"><a href=
 608                     "#conf-files-sysconfdir">12.2.1. How
 609                     <code class="varname">PKG_SYSCONFDIR</code> is
 610                     set</a></span></dt>
 611
 612                     <dt><span class="sect2"><a href=
 613                     "#conf-files-configure">12.2.2. Telling the
 614                     software where configuration files
 615                     are</a></span></dt>
 616
 617                     <dt><span class="sect2"><a href=
 618                     "#conf-files-patching">12.2.3. Patching
 619                     installations</a></span></dt>
 620
 621                     <dt><span class="sect2"><a href=
 622                     "#conf-files-disable">12.2.4. Disabling
 623                     handling of configuration files</a></span></dt>
 624                   </dl>
 625                 </dd>
 626
 627                 <dt><span class="sect1"><a href=
 628                 "#rcd-scripts">12.3. System startup
 629                 scripts</a></span></dt>
 630
 631                 <dd>
 632                   <dl>
 633                     <dt><span class="sect2"><a href=
 634                     "#rcd-scripts-disable">12.3.1. Disabling
 635                     handling of system startup
 636                     scripts</a></span></dt>
 637                   </dl>
 638                 </dd>
 639
 640                 <dt><span class="sect1"><a href=
 641                 "#users-and-groups">12.4. System users and
 642                 groups</a></span></dt>
 643
 644                 <dt><span class="sect1"><a href="#shells">12.5.
 645                 System shells</a></span></dt>
 646
 647                 <dd>
 648                   <dl>
 649                     <dt><span class="sect2"><a href=
 650                     "#shells-disable">12.5.1. Disabling handling of
 651                     configuration files</a></span></dt>
 652                   </dl>
 653                 </dd>
 654               </dl>
 655             </dd>
 656
 657             <dt><span class="chapter"><a href="#options">13.
 658             Options handling</a></span></dt>
 659
 660             <dd>
 661               <dl>
 662                 <dt><span class="sect1"><a href=
 663                 "#global-default-options">13.1. Global default
 664                 options</a></span></dt>
 665
 666                 <dt><span class="sect1"><a href=
 667                 "#converting-to-options">13.2. Converting packages
 668                 to use <code xmlns=
 669                 "http://www.w3.org/TR/xhtml1/transitional" class=
 670                 "filename">bsd.options.mk</code></a></span></dt>
 671
 672                 <dt><span class="sect1"><a href=
 673                 "#option-names">13.3. Option Names</a></span></dt>
 674               </dl>
 675             </dd>
 676
 677             <dt><span class="chapter"><a href="#build">14. The
 678             build process</a></span></dt>
 679
 680             <dd>
 681               <dl>
 682                 <dt><span class="sect1"><a href=
 683                 "#build.prefix">14.1. Program
 684                 location</a></span></dt>
 685
 686                 <dt><span class="sect1"><a href=
 687                 "#main-targets">14.2. Main targets</a></span></dt>
 688
 689                 <dt><span class="sect1"><a href=
 690                 "#build.helpful-targets">14.3. Other helpful
 691                 targets</a></span></dt>
 692               </dl>
 693             </dd>
 694
 695             <dt><span class="chapter"><a href="#fixes">15. Notes on
 696             fixes for packages</a></span></dt>
 697
 698             <dd>
 699               <dl>
 700                 <dt><span class="sect1"><a href=
 701                 "#general-operation">15.1. General
 702                 operation</a></span></dt>
 703
 704                 <dd>
 705                   <dl>
 706                     <dt><span class="sect2"><a href=
 707                     "#pulling-vars-from-etc-mk.conf">15.1.1. How to
 708                     pull in variables from
 709                     /etc/mk.conf</a></span></dt>
 710
 711                     <dt><span class="sect2"><a href=
 712                     "#where-to-install-documentation">15.1.2. Where
 713                     to install documentation</a></span></dt>
 714
 715                     <dt><span class="sect2"><a href=
 716                     "#restricted-packages">15.1.3. Restricted
 717                     packages</a></span></dt>
 718
 719                     <dt><span class="sect2"><a href=
 720                     "#dependencies">15.1.4. Handling
 721                     dependencies</a></span></dt>
 722
 723                     <dt><span class="sect2"><a href=
 724                     "#conflicts">15.1.5. Handling conflicts with
 725                     other packages</a></span></dt>
 726
 727                     <dt><span class="sect2"><a href=
 728                     "#not-building-packages">15.1.6. Packages that
 729                     cannot or should not be built</a></span></dt>
 730
 731                     <dt><span class="sect2"><a href=
 732                     "#undeletable-packages">15.1.7. Packages which
 733                     should not be deleted, once
 734                     installed</a></span></dt>
 735
 736                     <dt><span class="sect2"><a href=
 737                     "#security-handling">15.1.8. Handling packages
 738                     with security problems</a></span></dt>
 739
 740                     <dt><span class="sect2"><a href=
 741                     "#compiler-bugs">15.1.9. How to handle compiler
 742                     bugs</a></span></dt>
 743
 744                     <dt><span class="sect2"><a href=
 745                     "#bumping-pkgrevision">15.1.10. How to handle
 746                     incrementing versions when fixing an existing
 747                     package</a></span></dt>
 748
 749                     <dt><span class="sect2"><a href=
 750                     "#portability-of-packages">15.1.11. Portability
 751                     of packages</a></span></dt>
 752                   </dl>
 753                 </dd>
 754
 755                 <dt><span class="sect1"><a href=
 756                 "#downloading-issues">15.2. Possible downloading
 757                 issues</a></span></dt>
 758
 759                 <dd>
 760                   <dl>
 761                     <dt><span class="sect2"><a href=
 762                     "#no-plain-download">15.2.1. Packages whose
 763                     distfiles aren't available for plain
 764                     downloading</a></span></dt>
 765
 766                     <dt><span class="sect2"><a href=
 767                     "#modified-distfiles-same-name">15.2.2. How to
 768                     handle modified distfiles with the 'old'
 769                     name</a></span></dt>
 770                   </dl>
 771                 </dd>
 772
 773                 <dt><span class="sect1"><a href=
 774                 "#configuration-gotchas">15.3. Configuration
 775                 gotchas</a></span></dt>
 776
 777                 <dd>
 778                   <dl>
 779                     <dt><span class="sect2"><a href=
 780                     "#fixes.libtool">15.3.1. Shared libraries -
 781                     libtool</a></span></dt>
 782
 783                     <dt><span class="sect2"><a href=
 784                     "#using-libtool">15.3.2. Using libtool on GNU
 785                     packages that already support
 786                     libtool</a></span></dt>
 787
 788                     <dt><span class="sect2"><a href=
 789                     "#autoconf-automake">15.3.3. GNU
 790                     Autoconf/Automake</a></span></dt>
 791                   </dl>
 792                 </dd>
 793
 794                 <dt><span class="sect1"><a href=
 795                 "#building-considerations">15.4. Building
 796                 considerations</a></span></dt>
 797
 798                 <dd>
 799                   <dl>
 800                     <dt><span class="sect2"><a href=
 801                     "#cpp-defines">15.4.1. CPP
 802                     defines</a></span></dt>
 803
 804                     <dt><span class="sect2"><a href=
 805                     "#cpp-list">15.4.2. Getting a list of CPP
 806                     defines</a></span></dt>
 807                   </dl>
 808                 </dd>
 809
 810                 <dt><span class="sect1"><a href=
 811                 "#package-specific-actions">15.5. Package specific
 812                 actions</a></span></dt>
 813
 814                 <dd>
 815                   <dl>
 816                     <dt><span class="sect2"><a href=
 817                     "#user-interaction">15.5.1. User
 818                     interaction</a></span></dt>
 819
 820                     <dt><span class="sect2"><a href=
 821                     "#handling-licenses">15.5.2. Handling
 822                     licenses</a></span></dt>
 823
 824                     <dt><span class="sect2"><a href=
 825                     "#installing-score-files">15.5.3. Installing
 826                     score files</a></span></dt>
 827
 828                     <dt><span class="sect2"><a href=
 829                     "#perl-scripts">15.5.4. Packages containing
 830                     perl scripts</a></span></dt>
 831
 832                     <dt><span class="sect2"><a href=
 833                     "#hardcoded-paths">15.5.5. Packages with
 834                     hardcoded paths to other
 835                     interpreters</a></span></dt>
 836
 837                     <dt><span class="sect2"><a href=
 838                     "#perl-modules">15.5.6. Packages installing
 839                     perl modules</a></span></dt>
 840
 841                     <dt><span class="sect2"><a href=
 842                     "#faq.info-files">15.5.7. Packages installing
 843                     info files</a></span></dt>
 844
 845                     <dt><span class="sect2"><a href=
 846                     "#gconf2-data-files">15.5.8. Packages
 847                     installing GConf2 data files</a></span></dt>
 848
 849                     <dt><span class="sect2"><a href=
 850                     "#scrollkeeper-data-files">15.5.9. Packages
 851                     installing scrollkeeper data
 852                     files</a></span></dt>
 853
 854                     <dt><span class="sect2"><a href=
 855                     "#x11-fonts">15.5.10. Packages installing X11
 856                     fonts</a></span></dt>
 857
 858                     <dt><span class="sect2"><a href=
 859                     "#gtk2-modules">15.5.11. Packages installing
 860                     GTK2 modules</a></span></dt>
 861
 862                     <dt><span class="sect2"><a href=
 863                     "#sgml-xml-data">15.5.12. Packages installing
 864                     SGML or XML data</a></span></dt>
 865
 866                     <dt><span class="sect2"><a href=
 867                     "#mime-database">15.5.13. Packages installing
 868                     extensions to the MIME database</a></span></dt>
 869
 870                     <dt><span class="sect2"><a href=
 871                     "#intltool">15.5.14. Packages using
 872                     intltool</a></span></dt>
 873
 874                     <dt><span class="sect2"><a href=
 875                     "#startup-scripts">15.5.15. Packages installing
 876                     startup scripts</a></span></dt>
 877                   </dl>
 878                 </dd>
 879
 880                 <dt><span class="sect1"><a href=
 881                 "#feedback-to-author">15.6. Feedback to the
 882                 author</a></span></dt>
 883               </dl>
 884             </dd>
 885
 886             <dt><span class="chapter"><a href="#debug">16.
 887             Debugging</a></span></dt>
 888
 889             <dt><span class="chapter"><a href="#submit">17.
 890             Submitting and Committing</a></span></dt>
 891
 892             <dd>
 893               <dl>
 894                 <dt><span class="sect1"><a href=
 895                 "#submitting-your-package">17.1. Submitting your
 896                 packages</a></span></dt>
 897
 898                 <dt><span class="sect1"><a href=
 899                 "#general-notes-for-changes">17.2. General notes
 900                 when adding, updating, or removing
 901                 packages</a></span></dt>
 902
 903                 <dt><span class="sect1"><a href=
 904                 "#committing-importing">17.3. Committing: Importing
 905                 a package into CVS</a></span></dt>
 906
 907                 <dt><span class="sect1"><a href=
 908                 "#updating-package">17.4. Updating a package to a
 909                 newer version</a></span></dt>
 910
 911                 <dt><span class="sect1"><a href=
 912                 "#moving-package">17.5. Moving a package in
 913                 pkgsrc</a></span></dt>
 914               </dl>
 915             </dd>
 916           </dl>
 917         </dd>
 918
 919         <dt><span class="appendix"><a href="#examples">A. A simple
 920         example package: bison</a></span></dt>
 921
 922         <dd>
 923           <dl>
 924             <dt><span class="sect1"><a href="#example-files">A.1.
 925             files</a></span></dt>
 926
 927             <dd>
 928               <dl>
 929                 <dt><span class="sect2"><a href=
 930                 "#example-Makefile">A.1.1. Makefile</a></span></dt>
 931
 932                 <dt><span class="sect2"><a href=
 933                 "#example-descr">A.1.2. DESCR</a></span></dt>
 934
 935                 <dt><span class="sect2"><a href=
 936                 "#example-plist">A.1.3. PLIST</a></span></dt>
 937
 938                 <dt><span class="sect2"><a href=
 939                 "#checking-package-with-pkglint">A.1.4. Checking a
 940                 package with <span><strong class=
 941                 "command">pkglint</strong></span></a></span></dt>
 942               </dl>
 943             </dd>
 944
 945             <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2.
 946             Steps for building, installing,
 947             packaging</a></span></dt>
 948           </dl>
 949         </dd>
 950
 951         <dt><span class="appendix"><a href="#logs">B. Build
 952         logs</a></span></dt>
 953
 954         <dd>
 955           <dl>
 956             <dt><span class="sect1"><a href="#logs.building">B.1.
 957             Building figlet</a></span></dt>
 958
 959             <dt><span class="sect1"><a href="#logs.package">B.2.
 960             Packaging figlet</a></span></dt>
 961           </dl>
 962         </dd>
 963
 964         <dt><span class="appendix"><a href="#ftp-layout">C. Layout
 965         of the FTP server's package archive</a></span></dt>
 966
 967         <dt><span class="appendix"><a href="#editing">D. Editing
 968         guidelines for the pkgsrc guide</a></span></dt>
 969
 970         <dd>
 971           <dl>
 972             <dt><span class="sect1"><a href="#targets">D.1.
 973             Targets</a></span></dt>
 974
 975             <dt><span class="sect1"><a href="#procedure">D.2.
 976             Procedure</a></span></dt>
 977           </dl>
 978         </dd>
 979       </dl>
 980     </div>
 981
 982     <div class="chapter" lang="en" xml:lang="en">
 983       <div class="titlepage">
 984         <div>
 985           <div>
 986             <h2 class="title"><a name="introduction" id=
 987             "introduction"></a>Chapter&nbsp;1.&nbsp;What is
 988             pkgsrc?</h2>
 989           </div>
 990         </div>
 991       </div>
 992
 993       <div class="toc">
 994         <p><b>Table of Contents</b></p>
 995
 996         <dl>
 997           <dt><span class="sect1"><a href=
 998           "#introduction-section">1.1. Introduction</a></span></dt>
 999
1000           <dt><span class="sect1"><a href="#overview">1.2.
1001           Overview</a></span></dt>
1002
1003           <dt><span class="sect1"><a href="#terminology">1.3.
1004           Terminology</a></span></dt>
1005
1006           <dt><span class="sect1"><a href="#typography">1.4.
1007           Typography</a></span></dt>
1008         </dl>
1009       </div>
1010
1011       <div class="sect1" lang="en" xml:lang="en">
1012         <div class="titlepage">
1013           <div>
1014             <div>
1015               <h2 class="title" style="clear: both"><a name=
1016               "introduction-section" id=
1017               "introduction-section"></a>1.1.&nbsp;Introduction</h2>
1018             </div>
1019           </div>
1020         </div>
1021
1022         <p>There is a lot of software freely available for
1023         Unix-based systems, which usually runs on NetBSD and other
1024         Unix-flavoured systems, too, sometimes with some
1025         modifications. The NetBSD Packages Collection (pkgsrc)
1026         incorporates any such changes necessary to make that
1027         software run, and makes the installation (and
1028         de-installation) of the software package easy by means of a
1029         single command.</p>
1030
1031         <p>Once the software has been built, it is manipulated with
1032         the <span><strong class="command">pkg_*</strong></span>
1033         tools so that installation and de-installation, printing of
1034         an inventory of all installed packages and retrieval of
1035         one-line comments or more verbose descriptions are all
1036         simple.</p>
1037
1038         <p>pkgsrc currently contains several thousand packages,
1039         including:</p>
1040
1041         <div class="itemizedlist">
1042           <ul type="disc">
1043             <li>
1044               <p><a xmlns=
1045               "http://www.w3.org/TR/xhtml1/transitional" href=
1046               "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/apache/README.html"
1047               target="_top"><code xmlns="" class=
1048               "filename">www/apache</code></a> - The Apache web
1049               server</p>
1050             </li>
1051
1052             <li>
1053               <p><a xmlns=
1054               "http://www.w3.org/TR/xhtml1/transitional" href=
1055               "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/mozilla/README.html"
1056               target="_top"><code xmlns="" class=
1057               "filename">www/mozilla</code></a> - The Mozilla web
1058               browser</p>
1059             </li>
1060
1061             <li>
1062               <p><a xmlns=
1063               "http://www.w3.org/TR/xhtml1/transitional" href=
1064               "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/meta-pkgs/gnome/README.html"
1065               target="_top"><code xmlns="" class=
1066               "filename">meta-pkgs/gnome</code></a> - The GNOME
1067               Desktop Environment</p>
1068             </li>
1069
1070             <li>
1071               <p><a xmlns=
1072               "http://www.w3.org/TR/xhtml1/transitional" href=
1073               "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/meta-pkgs/kde3/README.html"
1074               target="_top"><code xmlns="" class=
1075               "filename">meta-pkgs/kde3</code></a> - The K Desktop
1076               Environment</p>
1077             </li>
1078           </ul>
1079         </div>
1080
1081         <p>...just to name a few.</p>
1082
1083         <p>pkgsrc has built-in support for handling varying
1084         dependencies, such as pthreads and X11, and extended
1085         features such as IPv6 support on a range of platforms.</p>
1086
1087         <p>pkgsrc was derived from FreeBSD's ports system, and
1088         initially developed for NetBSD only. Since then, pkgsrc has
1089         grown a lot, and now supports the following platforms:</p>
1090
1091         <div class="itemizedlist">
1092           <ul type="disc">
1093             <li>
1094               <p><a href="http://developer.apple.com/darwin/"
1095               target="_top">Darwin</a> (<a href=
1096               "http://www.apple.com/macosx/" target="_top">Mac OS
1097               X</a>)</p>
1098             </li>
1099
1100             <li>
1101               <p><a href="http://www.DragonFlyBSD.org/" target=
1102               "_top">DragonFlyBSD</a></p>
1103             </li>
1104
1105             <li>
1106               <p><a href="http://www.FreeBSD.org/" target=
1107               "_top">FreeBSD</a></p>
1108             </li>
1109
1110             <li>
1111               <p>Microsoft Windows, via <a href=
1112               "http://www.microsoft.com/windows/sfu/" target=
1113               "_top">Interix</a></p>
1114             </li>
1115
1116             <li>
1117               <p><a href="http://www.sgi.com/software/irix6.5/"
1118               target="_top">IRIX</a></p>
1119             </li>
1120
1121             <li>
1122               <p><a href="http://www.linux.org/" target=
1123               "_top">Linux</a></p>
1124             </li>
1125
1126             <li>
1127               <p><a href="http://www.NetBSD.org/" target=
1128               "_top">NetBSD</a> (of course)</p>
1129             </li>
1130
1131             <li>
1132               <p><a href="http://h30097.www3.hp.com/" target=
1133               "_top">Tru64</a> (Digital UNIX, OSF1)</p>
1134             </li>
1135
1136             <li>
1137               <p><a href="http://www.openbsd.org/" target=
1138               "_top">OpenBSD</a></p>
1139             </li>
1140
1141             <li>
1142               <p><a href="http://www.sun.com/solaris/" target=
1143               "_top">Solaris</a></p>
1144             </li>
1145           </ul>
1146         </div>
1147       </div>
1148
1149       <div class="sect1" lang="en" xml:lang="en">
1150         <div class="titlepage">
1151           <div>
1152             <div>
1153               <h2 class="title" style="clear: both"><a name=
1154               "overview" id="overview"></a>1.2.&nbsp;Overview</h2>
1155             </div>
1156           </div>
1157         </div>
1158
1159         <p>This document is divided into two parts. The first,
1160         <a href="#users-guide" title=
1161         "Part&nbsp;I.&nbsp;The pkgsrc user's guide">The pkgsrc
1162         user's guide</a>, describes how one can use one of the
1163         packages in the Package Collection, either by installing a
1164         precompiled binary package, or by building one's own copy
1165         using the NetBSD package system. The second part, <a href=
1166         "#developers-guide" title=
1167         "Part&nbsp;II.&nbsp;The pkgsrc developer's guide">The
1168         pkgsrc developer's guide</a>, explains how to prepare a
1169         package so it can be easily built by other NetBSD users
1170         without knowing about the package's building details.</p>
1171
1172         <p>This document is available in various formats:</p>
1173
1174         <div class="itemizedlist">
1175           <ul type="disc">
1176             <li>
1177               <p><a href="index.html" target="_top">HTML</a></p>
1178             </li>
1179
1180             <li>
1181               <p><a href="pkgsrc.pdf" target="_top">PDF</a></p>
1182             </li>
1183
1184             <li>
1185               <p><a href="pkgsrc.ps" target="_top">PS</a></p>
1186             </li>
1187
1188             <li>
1189               <p><a href="pkgsrc.txt" target="_top">TXT</a></p>
1190             </li>
1191           </ul>
1192         </div>
1193       </div>
1194
1195       <div class="sect1" lang="en" xml:lang="en">
1196         <div class="titlepage">
1197           <div>
1198             <div>
1199               <h2 class="title" style="clear: both"><a name=
1200               "terminology" id=
1201               "terminology"></a>1.3.&nbsp;Terminology</h2>
1202             </div>
1203           </div>
1204         </div>
1205
1206         <p>There has been a lot of talk about &#8220;<span class=
1207         "quote">ports</span>&#8221;, &#8220;<span class=
1208         "quote">packages</span>&#8221;, etc. so far. Here is a
1209         description of all the terminology used within this
1210         document.</p>
1211
1212         <div class="variablelist">
1213           <dl>
1214             <dt><span class="term">Package</span></dt>
1215
1216             <dd>
1217               <p>A set of files and building instructions that
1218               describe what's necessary to build a certain piece of
1219               software using pkgsrc. Packages are traditionally
1220               stored under <code xmlns=
1221               "http://www.w3.org/TR/xhtml1/transitional" class=
1222               "filename">/usr/pkgsrc</code>.</p>
1223             </dd>
1224
1225             <dt><span class="term">The NetBSD package
1226             system</span></dt>
1227
1228             <dd>
1229               <p>This is the former name of &#8220;<span class=
1230               "quote">pkgsrc</span>&#8221;. It is part of the
1231               NetBSD operating system and can be bootstrapped to
1232               run on non-NetBSD operating systems as well. It
1233               handles building (compiling), installing, and
1234               removing of packages.</p>
1235             </dd>
1236
1237             <dt><span class="term">Distfile</span></dt>
1238
1239             <dd>
1240               <p>This term describes the file or files that are
1241               provided by the author of the piece of software to
1242               distribute his work. All the changes necessary to
1243               build on NetBSD are reflected in the corresponding
1244               package. Usually the distfile is in the form of a
1245               compressed tar-archive, but other types are possible,
1246               too. Distfiles are usually stored below <code xmlns=
1247               "http://www.w3.org/TR/xhtml1/transitional" class=
1248               "filename">/usr/pkgsrc/distfiles</code>.</p>
1249             </dd>
1250
1251             <dt><span class="term">Port</span></dt>
1252
1253             <dd>
1254               <p>This is the term used by FreeBSD and OpenBSD
1255               people for what we call a package. In NetBSD
1256               terminology, &#8220;<span class=
1257               "quote">port</span>&#8221; refers to a different
1258               architecture.</p>
1259             </dd>
1260
1261             <dt><span class="term">Precompiled/binary
1262             package</span></dt>
1263
1264             <dd>
1265               <p>A set of binaries built with pkgsrc from a
1266               distfile and stuffed together in a single
1267               <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
1268               class="filename">.tgz</code> file so it can be
1269               installed on machines of the same machine
1270               architecture without the need to recompile. Packages
1271               are usually generated in <code xmlns=
1272               "http://www.w3.org/TR/xhtml1/transitional" class=
1273               "filename">/usr/pkgsrc/packages</code>; there is also
1274               an archive on <a href=
1275               "ftp://ftp.NetBSD.org/pub/NetBSD/packages/" target=
1276               "_top">ftp.NetBSD.org</a>.</p>
1277
1278               <p>Sometimes, this is referred to by the term
1279               &#8220;<span class="quote">package</span>&#8221; too,
1280               especially in the context of precompiled
1281               packages.</p>
1282             </dd>
1283
1284             <dt><span class="term">Program</span></dt>
1285
1286             <dd>
1287               <p>The piece of software to be installed which will
1288               be constructed from all the files in the distfile by
1289               the actions defined in the corresponding package.</p>
1290             </dd>
1291           </dl>
1292         </div>
1293       </div>
1294
1295       <div class="sect1" lang="en" xml:lang="en">
1296         <div class="titlepage">
1297           <div>
1298             <div>
1299               <h2 class="title" style="clear: both"><a name=
1300               "typography" id=
1301               "typography"></a>1.4.&nbsp;Typography</h2>
1302             </div>
1303           </div>
1304         </div>
1305
1306         <p>When giving examples for commands, shell prompts are
1307         used to show if the command should/can be issued as root,
1308         or if &#8220;<span class="quote">normal</span>&#8221; user
1309         privileges are sufficient. We use a <code class=
1310         "prompt">#</code> for root's shell prompt, and a
1311         <code class="prompt">%</code> for users' shell prompt,
1312         assuming they use the C-shell or tcsh.</p>
1313       </div>
1314     </div>
1315
1316     <div class="part" lang="en" xml:lang="en">
1317       <div class="titlepage">
1318         <div>
1319           <div>
1320             <h1 class="title"><a name="users-guide" id=
1321             "users-guide"></a>Part&nbsp;I.&nbsp;The pkgsrc user's
1322             guide</h1>
1323           </div>
1324         </div>
1325       </div>
1326
1327       <div class="toc">
1328         <p><b>Table of Contents</b></p>
1329
1330         <dl>
1331           <dt><span class="chapter"><a href="#getting">2. Where to
1332           get pkgsrc</a></span></dt>
1333
1334           <dd>
1335             <dl>
1336               <dt><span class="sect1"><a href="#as-tar-file">2.1.
1337               As tar file</a></span></dt>
1338
1339               <dt><span class="sect1"><a href="#via-sup">2.2. Via
1340               SUP</a></span></dt>
1341
1342               <dt><span class="sect1"><a href="#via-cvs">2.3. Via
1343               CVS</a></span></dt>
1344             </dl>
1345           </dd>
1346
1347           <dt><span class="chapter"><a href="#platforms">3. Using
1348           pkgsrc on systems other than NetBSD</a></span></dt>
1349
1350           <dd>
1351             <dl>
1352               <dt><span class="sect1"><a href=
1353               "#bootstrapping-pkgsrc">3.1. Bootstrapping
1354               pkgsrc</a></span></dt>
1355
1356               <dt><span class="sect1"><a href=
1357               "#platform-specific-notes">3.2. Platform-specific
1358               notes</a></span></dt>
1359
1360               <dd>
1361                 <dl>
1362                   <dt><span class="sect2"><a href="#darwin">3.2.1.
1363                   Darwin (Mac OS X)</a></span></dt>
1364
1365                   <dt><span class="sect2"><a href="#freebsd">3.2.2.
1366                   FreeBSD</a></span></dt>
1367
1368                   <dt><span class="sect2"><a href="#interix">3.2.3.
1369                   Interix</a></span></dt>
1370
1371                   <dt><span class="sect2"><a href="#irix">3.2.4.
1372                   IRIX</a></span></dt>
1373
1374                   <dt><span class="sect2"><a href="#linux">3.2.5.
1375                   Linux</a></span></dt>
1376
1377                   <dt><span class="sect2"><a href="#openbsd">3.2.6.
1378                   OpenBSD</a></span></dt>
1379
1380                   <dt><span class="sect2"><a href="#solaris">3.2.7.
1381                   Solaris</a></span></dt>
1382                 </dl>
1383               </dd>
1384             </dl>
1385           </dd>
1386
1387           <dt><span class="chapter"><a href="#using">4. Using
1388           pkgsrc</a></span></dt>
1389
1390           <dd>
1391             <dl>
1392               <dt><span class="sect1"><a href=
1393               "#getting-started">4.1. Working with binary
1394               packages</a></span></dt>
1395
1396               <dd>
1397                 <dl>
1398                   <dt><span class="sect2"><a href=
1399                   "#where-to-get-binary-packages">4.1.1. Where to
1400                   get binary packages</a></span></dt>
1401
1402                   <dt><span class="sect2"><a href=
1403                   "#how-to-use-binary-packages">4.1.2. How to use
1404                   binary packages</a></span></dt>
1405
1406                   <dt><span class="sect2"><a href=
1407                   "#a-word-of-warning">4.1.3. A word of
1408                   warning</a></span></dt>
1409                 </dl>
1410               </dd>
1411
1412               <dt><span class="sect1"><a href=
1413               "#building-packages-from-source">4.2. Building
1414               packages from source</a></span></dt>
1415
1416               <dd>
1417                 <dl>
1418                   <dt><span class="sect2"><a href=
1419                   "#requirements">4.2.1.
1420                   Requirements</a></span></dt>
1421
1422                   <dt><span class="sect2"><a href=
1423                   "#fetching-distfiles">4.2.2. Fetching
1424                   distfiles</a></span></dt>
1425
1426                   <dt><span class="sect2"><a href=
1427                   "#how-to-build-and-install">4.2.3. How to build
1428                   and install</a></span></dt>
1429
1430                   <dt><span class="sect2"><a href=
1431                   "#selecting-the-compiler">4.2.4. Selecting the
1432                   compiler</a></span></dt>
1433                 </dl>
1434               </dd>
1435             </dl>
1436           </dd>
1437
1438           <dt><span class="chapter"><a href="#configuring">5.
1439           Configuring pkgsrc</a></span></dt>
1440
1441           <dd>
1442             <dl>
1443               <dt><span class="sect1"><a href=
1444               "#general-configuration">5.1. General
1445               configuration</a></span></dt>
1446
1447               <dt><span class="sect1"><a href=
1448               "#variables-affecting-build">5.2. Variables affecting
1449               the build process</a></span></dt>
1450
1451               <dt><span class="sect1"><a href=
1452               "#developer-advanced-settings">5.3.
1453               Developer/advanced settings</a></span></dt>
1454
1455               <dt><span class="sect1"><a href=
1456               "#selecting-build-options">5.4. Selecting Build
1457               Options</a></span></dt>
1458             </dl>
1459           </dd>
1460
1461           <dt><span class="chapter"><a href="#binary">6. Creating
1462           binary packages</a></span></dt>
1463
1464           <dd>
1465             <dl>
1466               <dt><span class="sect1"><a href=
1467               "#building-a-single-binary-package">6.1. Building a
1468               single binary package</a></span></dt>
1469
1470               <dt><span class="sect1"><a href=
1471               "#settings-for-creationg-of-binary-packages">6.2.
1472               Settings for creation of binary
1473               packages</a></span></dt>
1474
1475               <dt><span class="sect1"><a href="#bulkbuild">6.3.
1476               Doing a bulk build of all packages</a></span></dt>
1477
1478               <dd>
1479                 <dl>
1480                   <dt><span class="sect2"><a href=
1481                   "#binary.configuration">6.3.1.
1482                   Configuration</a></span></dt>
1483
1484                   <dt><span class="sect2"><a href=
1485                   "#other-environmental-considerations">6.3.2.
1486                   Other environmental
1487                   considerations</a></span></dt>
1488
1489                   <dt><span class="sect2"><a href=
1490                   "#operation">6.3.3. Operation</a></span></dt>
1491
1492                   <dt><span class="sect2"><a href=
1493                   "#what-it-does">6.3.4. What it
1494                   does</a></span></dt>
1495
1496                   <dt><span class="sect2"><a href=
1497                   "#disk-space-requirements">6.3.5. Disk space
1498                   requirements</a></span></dt>
1499
1500                   <dt><span class="sect2"><a href=
1501                   "#setting-up-a-sandbox">6.3.6. Setting up a
1502                   sandbox for chrooted builds</a></span></dt>
1503
1504                   <dt><span class="sect2"><a href=
1505                   "#building-a-partial-set">6.3.7. Building a
1506                   partial set of packages</a></span></dt>
1507
1508                   <dt><span class="sect2"><a href=
1509                   "#bulk-upload">6.3.8. Uploading results of a bulk
1510                   build</a></span></dt>
1511                 </dl>
1512               </dd>
1513
1514               <dt><span class="sect1"><a href=
1515               "#creating-cdroms">6.4. Creating a multiple CD-ROM
1516               packages collection</a></span></dt>
1517
1518               <dd>
1519                 <dl>
1520                   <dt><span class="sect2"><a href=
1521                   "#cdpack-example">6.4.1. Example of
1522                   cdpack</a></span></dt>
1523                 </dl>
1524               </dd>
1525             </dl>
1526           </dd>
1527
1528           <dt><span class="chapter"><a href="#faq">7. Frequently
1529           Asked Questions</a></span></dt>
1530
1531           <dd>
1532             <dl>
1533               <dt><span class="sect1"><a href=
1534               "#mailing-list-pointers">7.1. Are there any mailing
1535               lists for pkg-related discussion?</a></span></dt>
1536
1537               <dt><span class="sect1"><a href="#pkgviews-docs">7.2.
1538               Where's the pkgviews documentation?</a></span></dt>
1539
1540               <dt><span class="sect1"><a href="#faq-pkgtools">7.3.
1541               Utilities for package management
1542               (pkgtools)</a></span></dt>
1543
1544               <dt><span class="sect1"><a href=
1545               "#non-root-pkgsrc">7.4. How to use pkgsrc as
1546               non-root</a></span></dt>
1547
1548               <dt><span class="sect1"><a href=
1549               "#resume-transfers">7.5. How to resume transfers when
1550               fetching distfiles?</a></span></dt>
1551
1552               <dt><span class="sect1"><a href=
1553               "#XFree86-from-pkgsrc">7.6. How can I install/use
1554               XFree86 from pkgsrc?</a></span></dt>
1555
1556               <dt><span class="sect1"><a href=
1557               "#x.org-from-pkgsrc">7.7. How can I install/use X.org
1558               from pkgsrc?</a></span></dt>
1559
1560               <dt><span class="sect1"><a href=
1561               "#fetch-behind-firewall">7.8. How to fetch files from
1562               behind a firewall</a></span></dt>
1563
1564               <dt><span class="sect1"><a href="#passive-ftp">7.9.
1565               How do I tell <span><strong class="command">make
1566               fetch</strong></span> to do passive
1567               FTP?</a></span></dt>
1568
1569               <dt><span class="sect1"><a href=
1570               "#fetching-all-distfiles">7.10. How to fetch all
1571               distfiles at once</a></span></dt>
1572
1573               <dt><span class="sect1"><a href=
1574               "#tmac.andoc-missing">7.11. What does
1575               &#8220;<span class="quote">Don't know how to make
1576               /usr/share/tmac/tmac.andoc</span>&#8221;
1577               mean?</a></span></dt>
1578
1579               <dt><span class="sect1"><a href=
1580               "#bsd.own.mk-missing">7.12. What does
1581               &#8220;<span class="quote">Could not find
1582               bsd.own.mk</span>&#8221; mean?</a></span></dt>
1583
1584               <dt><span class="sect1"><a href=
1585               "#using-sudo-with-pkgsrc">7.13. Using 'sudo' with
1586               pkgsrc</a></span></dt>
1587
1588               <dt><span class="sect1"><a href="#faq.conf">7.14. How
1589               do I change the location of configuration
1590               files?</a></span></dt>
1591
1592               <dt><span class="sect1"><a href=
1593               "#audit-packages">7.15. Automated security
1594               checks</a></span></dt>
1595             </dl>
1596           </dd>
1597         </dl>
1598       </div>
1599
1600       <div class="chapter" lang="en" xml:lang="en">
1601         <div class="titlepage">
1602           <div>
1603             <div>
1604               <h2 class="title"><a name="getting" id=
1605               "getting"></a>Chapter&nbsp;2.&nbsp;Where to get
1606               pkgsrc</h2>
1607             </div>
1608           </div>
1609         </div>
1610
1611         <div class="toc">
1612           <p><b>Table of Contents</b></p>
1613
1614           <dl>
1615             <dt><span class="sect1"><a href="#as-tar-file">2.1. As
1616             tar file</a></span></dt>
1617
1618             <dt><span class="sect1"><a href="#via-sup">2.2. Via
1619             SUP</a></span></dt>
1620
1621             <dt><span class="sect1"><a href="#via-cvs">2.3. Via
1622             CVS</a></span></dt>
1623           </dl>
1624         </div>
1625
1626         <p>There are three ways to get pkgsrc. Either as a tar
1627         file, via SUP, or via CVS. All three ways are described
1628         here.</p>
1629
1630         <div class="sect1" lang="en" xml:lang="en">
1631           <div class="titlepage">
1632             <div>
1633               <div>
1634                 <h2 class="title" style="clear: both"><a name=
1635                 "as-tar-file" id="as-tar-file"></a>2.1.&nbsp;As tar
1636                 file</h2>
1637               </div>
1638             </div>
1639           </div>
1640
1641           <p>To get pkgsrc going, you need to get the pkgsrc.tar.gz
1642           file from <a href=
1643           "ftp://ftp.NetBSD.org/pub/NetBSD/NetBSD-current/tar_files/pkgsrc.tar.gz"
1644           target="_top">ftp.NetBSD.org</a> and unpack it into
1645           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
1646           class="filename">/usr/pkgsrc</code>.</p>
1647         </div>
1648
1649         <div class="sect1" lang="en" xml:lang="en">
1650           <div class="titlepage">
1651             <div>
1652               <div>
1653                 <h2 class="title" style="clear: both"><a name=
1654                 "via-sup" id="via-sup"></a>2.2.&nbsp;Via SUP</h2>
1655               </div>
1656             </div>
1657           </div>
1658
1659           <p>As an alternative to the tar file, you can get pkgsrc
1660           via the Software Update Protocol, SUP. To do so, make
1661           sure your supfile has a line</p>
1662           <pre class="programlisting">
1663     release=pkgsrc
1664 </pre>
1665
1666           <p>in it, see the examples in <code xmlns=
1667           "http://www.w3.org/TR/xhtml1/transitional" class=
1668           "filename">/usr/share/examples/supfiles</code>, and that
1669           the <code xmlns=
1670           "http://www.w3.org/TR/xhtml1/transitional" class=
1671           "filename">/usr/pkgsrc</code> directory exists. Then,
1672           simply run <span><strong class="command">sup -v
1673           <em class="replaceable"><code>/path/to/your/supfile</code></em></strong></span>.</p>
1674         </div>
1675
1676         <div class="sect1" lang="en" xml:lang="en">
1677           <div class="titlepage">
1678             <div>
1679               <div>
1680                 <h2 class="title" style="clear: both"><a name=
1681                 "via-cvs" id="via-cvs"></a>2.3.&nbsp;Via CVS</h2>
1682               </div>
1683             </div>
1684           </div>
1685
1686           <p>To get pkgsrc via CVS, make sure you have
1687           &#8220;<span class="quote">cvs</span>&#8221; installed.
1688           To do an initial (full) checkout of pkgsrc, do the
1689           following steps:</p>
1690           <pre class="screen">
1691 <code class="prompt">%</code> <strong class=
1692 "userinput"><code>setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot</code></strong>
1693 <code class="prompt">%</code> <strong class=
1694 "userinput"><code>setenv CVS_RSH ssh</code></strong>
1695 <code class="prompt">%</code> <strong class=
1696 "userinput"><code>cd /usr</code></strong>
1697 <code class="prompt">%</code> <strong class=
1698 "userinput"><code>cvs checkout -P pkgsrc</code></strong>
1699 </pre>
1700
1701           <p>This will create the <code xmlns=
1702           "http://www.w3.org/TR/xhtml1/transitional" class=
1703           "filename">pkgsrc</code> directory in your <code xmlns=
1704           "http://www.w3.org/TR/xhtml1/transitional" class=
1705           "filename">/usr</code>, and all the package source will
1706           be stored under <code xmlns=
1707           "http://www.w3.org/TR/xhtml1/transitional" class=
1708           "filename">/usr/pkgsrc</code>. To update pkgsrc after the
1709           initial checkout, make sure you have <code class=
1710           "varname">CVS_RSH</code> set as above, then do:</p>
1711           <pre class="screen">
1712 <code class="prompt">%</code> <strong class=
1713 "userinput"><code>cd /usr/pkgsrc</code></strong>
1714 <code class="prompt">%</code> <strong class=
1715 "userinput"><code>cvs -q update -dP</code></strong>
1716 </pre>
1717
1718           <p>Please also note that it is possible to have multiple
1719           copies of the pkgsrc hierarchy in use at any one time -
1720           all work is done relatively within the pkgsrc tree.</p>
1721         </div>
1722       </div>
1723
1724       <div class="chapter" lang="en" xml:lang="en">
1725         <div class="titlepage">
1726           <div>
1727             <div>
1728               <h2 class="title"><a name="platforms" id=
1729               "platforms"></a>Chapter&nbsp;3.&nbsp;Using pkgsrc on
1730               systems other than NetBSD</h2>
1731             </div>
1732           </div>
1733         </div>
1734
1735         <div class="toc">
1736           <p><b>Table of Contents</b></p>
1737
1738           <dl>
1739             <dt><span class="sect1"><a href=
1740             "#bootstrapping-pkgsrc">3.1. Bootstrapping
1741             pkgsrc</a></span></dt>
1742
1743             <dt><span class="sect1"><a href=
1744             "#platform-specific-notes">3.2. Platform-specific
1745             notes</a></span></dt>
1746
1747             <dd>
1748               <dl>
1749                 <dt><span class="sect2"><a href="#darwin">3.2.1.
1750                 Darwin (Mac OS X)</a></span></dt>
1751
1752                 <dt><span class="sect2"><a href="#freebsd">3.2.2.
1753                 FreeBSD</a></span></dt>
1754
1755                 <dt><span class="sect2"><a href="#interix">3.2.3.
1756                 Interix</a></span></dt>
1757
1758                 <dt><span class="sect2"><a href="#irix">3.2.4.
1759                 IRIX</a></span></dt>
1760
1761                 <dt><span class="sect2"><a href="#linux">3.2.5.
1762                 Linux</a></span></dt>
1763
1764                 <dt><span class="sect2"><a href="#openbsd">3.2.6.
1765                 OpenBSD</a></span></dt>
1766
1767                 <dt><span class="sect2"><a href="#solaris">3.2.7.
1768                 Solaris</a></span></dt>
1769               </dl>
1770             </dd>
1771           </dl>
1772         </div>
1773
1774         <div class="sect1" lang="en" xml:lang="en">
1775           <div class="titlepage">
1776             <div>
1777               <div>
1778                 <h2 class="title" style="clear: both"><a name=
1779                 "bootstrapping-pkgsrc" id=
1780                 "bootstrapping-pkgsrc"></a>3.1.&nbsp;Bootstrapping
1781                 pkgsrc</h2>
1782               </div>
1783             </div>
1784           </div>
1785
1786           <p>For operating systems other than NetBSD, we provide a
1787           bootstrap kit to build the required tools to use pkgsrc
1788           on your platform. Besides support for native NetBSD,
1789           pkgsrc and the bootstrap kit have support for the
1790           following operating systems:</p>
1791
1792           <div class="itemizedlist">
1793             <ul type="disc">
1794               <li>
1795                 <p>Darwin (Mac OS X)</p>
1796               </li>
1797
1798               <li>
1799                 <p>DragonFlyBSD</p>
1800               </li>
1801
1802               <li>
1803                 <p>FreeBSD</p>
1804               </li>
1805
1806               <li>
1807                 <p>Interix (Windows 2000, XP, 2003)</p>
1808               </li>
1809
1810               <li>
1811                 <p>IRIX</p>
1812               </li>
1813
1814               <li>
1815                 <p>Linux</p>
1816               </li>
1817
1818               <li>
1819                 <p>OpenBSD</p>
1820               </li>
1821
1822               <li>
1823                 <p>Solaris</p>
1824               </li>
1825
1826               <li>
1827                 <p>Tru64 (Digital UNIX/OSF1)</p>
1828               </li>
1829             </ul>
1830           </div>
1831
1832           <p>Support for other platforms is under development.</p>
1833
1834           <p>Installing the bootstrap kit should be as simple
1835           as:</p>
1836           <pre class="screen">
1837 <code class="prompt">#</code> <strong class=
1838 "userinput"><code>env CVS_RSH=ssh cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout pkgsrc</code></strong>
1839 <code class="prompt">#</code> <strong class=
1840 "userinput"><code>cd pkgsrc/bootstrap</code></strong>
1841 <code class="prompt">#</code> <strong class=
1842 "userinput"><code>./bootstrap</code></strong>
1843 </pre>
1844
1845           <p>See <a href="#getting" title=
1846           "Chapter&nbsp;2.&nbsp;Where to get pkgsrc">Chapter 2,
1847           <i>Where to get pkgsrc</i></a> for other ways to get
1848           pkgsrc before bootstrapping. The given
1849           <span><strong class="command">bootstrap</strong></span>
1850           command will use the defaults of <code xmlns=
1851           "http://www.w3.org/TR/xhtml1/transitional" class=
1852           "filename">/usr/pkg</code> for the <span class=
1853           "emphasis"><em>prefix</em></span> where programs will be
1854           installed in, and <code xmlns=
1855           "http://www.w3.org/TR/xhtml1/transitional" class=
1856           "filename">/var/db/pkg</code> for the package database
1857           directory where pkgsrc will do its internal bookkeeping.
1858           However, these can also be set using command-line
1859           arguments.</p>
1860
1861           <p>Binary packages for the pkgsrc tools and an initial
1862           set of packages is available for supported platforms. An
1863           up-to-date list of these can be found on <a href=
1864           "http://www.pkgsrc.org/" target=
1865           "_top">www.pkgsrc.org</a>.</p>
1866
1867           <div class="note" style=
1868           "margin-left: 0.5in; margin-right: 0.5in;">
1869             <h3 class="title">Note</h3>
1870
1871             <p>The bootstrap installs a <span><strong class=
1872             "command">bmake</strong></span> tool. Use this
1873             <span><strong class="command">bmake</strong></span>
1874             when building via pkgsrc. For examples in this guide,
1875             use <span><strong class="command">bmake</strong></span>
1876             instead of &#8220;<span class=
1877             "quote">make</span>&#8221;.</p>
1878           </div>
1879         </div>
1880
1881         <div class="sect1" lang="en" xml:lang="en">
1882           <div class="titlepage">
1883             <div>
1884               <div>
1885                 <h2 class="title" style="clear: both"><a name=
1886                 "platform-specific-notes" id=
1887                 "platform-specific-notes"></a>3.2.&nbsp;Platform-specific
1888                 notes</h2>
1889               </div>
1890             </div>
1891           </div>
1892
1893           <p>Here are some platform-specific notes you should be
1894           aware of.</p>
1895
1896           <div class="sect2" lang="en" xml:lang="en">
1897             <div class="titlepage">
1898               <div>
1899                 <div>
1900                   <h3 class="title"><a name="darwin" id=
1901                   "darwin"></a>3.2.1.&nbsp;Darwin (Mac OS X)</h3>
1902                 </div>
1903               </div>
1904             </div>
1905
1906             <p>Darwin 5.x and 6.x are supported. There are two
1907             methods of using pkgsrc on Mac OS X, by using a
1908             <a href="#platform.osx-image" title=
1909             "3.2.1.1.&nbsp;Using a disk image">disk image</a>, or a
1910             <a href="#platform.osx-ufs" title=
1911             "3.2.1.2.&nbsp;Using a UFS partition">UFS
1912             partition</a>.</p>
1913
1914             <p>Before you start, you will need to download and
1915             install the Mac OS X Developer Tools from Apple's
1916             Developer Connection. See <a href=
1917             "http://developer.apple.com/macosx/" target=
1918             "_top">http://developer.apple.com/macosx/</a> for
1919             details. Also, make sure you install X11 for Mac OS X
1920             and the X11 SDK from <a href=
1921             "http://www.apple.com/macosx/x11/download/" target=
1922             "_top">http://www.apple.com/macosx/x11/download/</a> if
1923             you intend to build packages that use the X11 Window
1924             System.</p>
1925
1926             <p>If you already have a UFS partition, or have a spare
1927             partition that you can format as UFS, it is recommended
1928             to use that instead of the disk image. It'll be
1929             somewhat faster and will mount automatically at boot
1930             time, where you must manually mount a disk image.</p>
1931
1932             <div class="note" style=
1933             "margin-left: 0.5in; margin-right: 0.5in;">
1934               <h3 class="title">Note</h3>
1935
1936               <p>You cannot use a HFS+ file system for pkgsrc,
1937               because pkgsrc currently requires the file system to
1938               be case-sensitive, and HFS+ is not.</p>
1939             </div>
1940
1941             <div class="sect3" lang="en" xml:lang="en">
1942               <div class="titlepage">
1943                 <div>
1944                   <div>
1945                     <h4 class="title"><a name="platform.osx-image"
1946                     id="platform.osx-image"></a>3.2.1.1.&nbsp;Using
1947                     a disk image</h4>
1948                   </div>
1949                 </div>
1950               </div>
1951
1952               <p>Create the disk image:</p>
1953               <pre class="screen">
1954 <code class="prompt">#</code> <strong class=
1955 "userinput"><code>cd pkgsrc/bootstrap</code></strong>
1956 <code class="prompt">#</code> <strong class=
1957 "userinput"><code>./ufsdiskimage create ~/Documents/NetBSD 512</code></strong> # megabytes - season to taste
1958 <code class="prompt">#</code> <strong class=
1959 "userinput"><code>./ufsdiskimage mount ~/Documents/NetBSD</code></strong>
1960 <code class="prompt">#</code> <strong class=
1961 "userinput"><code>sudo chown `id -u`:`id -g` /Volumes/NetBSD</code></strong>
1962 </pre>
1963
1964               <p>That's it!</p>
1965             </div>
1966
1967             <div class="sect3" lang="en" xml:lang="en">
1968               <div class="titlepage">
1969                 <div>
1970                   <div>
1971                     <h4 class="title"><a name="platform.osx-ufs"
1972                     id="platform.osx-ufs"></a>3.2.1.2.&nbsp;Using a
1973                     UFS partition</h4>
1974                   </div>
1975                 </div>
1976               </div>
1977
1978               <p>By default, <code xmlns=
1979               "http://www.w3.org/TR/xhtml1/transitional" class=
1980               "filename">/usr</code> will be on your root file
1981               system, normally HFS+. It is possible to use the
1982               default <span class="emphasis"><em>prefix</em></span>
1983               of <code xmlns=
1984               "http://www.w3.org/TR/xhtml1/transitional" class=
1985               "filename">/usr/pkg</code> by symlinking <code xmlns=
1986               "http://www.w3.org/TR/xhtml1/transitional" class=
1987               "filename">/usr/pkg</code> to a directory on a UFS
1988               file system. Obviously, another symlink is required
1989               if you want to place the package database directory
1990               outside the <span class=
1991               "emphasis"><em>prefix</em></span>. e.g.</p>
1992               <pre class="screen">
1993 <code class="prompt">#</code> <strong class=
1994 "userinput"><code>./bootstrap --pkgdbdir /usr/pkg/pkgdb --pkgsrcdir /Volumes/ufs/pkgsrc</code></strong>
1995 </pre>
1996
1997               <p>If you created your partitions at the time of
1998               installing Mac OS X and formatted the target
1999               partition as UFS, it should automatically mount on
2000               <code xmlns=
2001               "http://www.w3.org/TR/xhtml1/transitional" class=
2002               "filename">/Volumes/&lt;volume name&gt;</code> when
2003               the machine boots. If you are (re)formatting a
2004               partition as UFS, you need to ensure that the
2005               partition map correctly reflects &#8220;<span class=
2006               "quote">Apple_UFS</span>&#8221; and not
2007               &#8220;<span class=
2008               "quote">Apple_HFS</span>&#8221;.</p>
2009
2010               <p>The problem is that none of the disk tools will
2011               let you touch a disk that is booted from. You can
2012               unmount the partition, but even if you newfs it, the
2013               partition type will be incorrect and the automounter
2014               won't mount it. It can be mounted manually, but it
2015               won't appear in Finder.</p>
2016
2017               <p>You'll need to boot off of the OS X Installation
2018               (User) CD. When the Installation program starts, go
2019               up to the menu and select Disk Utility. Now, you will
2020               be able to select the partition you want to be UFS,
2021               and Format it Apple UFS. Quit the Disk Utility, quit
2022               the installer which will reboot your machine. The new
2023               UFS file system will appear in Finder.</p>
2024
2025               <p>Be aware that the permissions on the new file
2026               system will be writable by root only.</p>
2027
2028               <p>This note is as of 10.2 (Jaguar) and applies to
2029               earlier versions. Hopefully Apple will fix Disk
2030               Utility in 10.3 (Panther).</p>
2031             </div>
2032           </div>
2033
2034           <div class="sect2" lang="en" xml:lang="en">
2035             <div class="titlepage">
2036               <div>
2037                 <div>
2038                   <h3 class="title"><a name="freebsd" id=
2039                   "freebsd"></a>3.2.2.&nbsp;FreeBSD</h3>
2040                 </div>
2041               </div>
2042             </div>
2043
2044             <p>FreeBSD 4.7 and 5.0 have been tested and are
2045             supported, other versions may work.</p>
2046
2047             <p>Care should be taken so that the tools that this kit
2048             installs do not conflict with the FreeBSD userland
2049             tools. There are several steps:</p>
2050
2051             <div class="orderedlist">
2052               <ol type="1">
2053                 <li>
2054                   <p>FreeBSD stores its ports pkg database in
2055                   <code xmlns=
2056                   "http://www.w3.org/TR/xhtml1/transitional" class=
2057                   "filename">/var/db/pkg</code>. It is therefore
2058                   recommended that you choose a different location
2059                   (e.g. <code xmlns=
2060                   "http://www.w3.org/TR/xhtml1/transitional" class=
2061                   "filename">/usr/pkgdb</code>) by using the
2062                   --pkgdbdir option to the bootstrap script.</p>
2063                 </li>
2064
2065                 <li>
2066                   <p>If you do not intend to use the FreeBSD ports
2067                   tools, it's probably a good idea to move them out
2068                   of the way to avoid confusion, e.g.</p>
2069                   <pre class="screen">
2070 <code class="prompt">#</code> <strong class=
2071 "userinput"><code>cd /usr/sbin</code></strong>
2072 <code class="prompt">#</code> <strong class=
2073 "userinput"><code>mv pkg_add pkg_add.orig</code></strong>
2074 <code class="prompt">#</code> <strong class=
2075 "userinput"><code>mv pkg_create pkg_create.orig</code></strong>
2076 <code class="prompt">#</code> <strong class=
2077 "userinput"><code>mv pkg_delete pkg_delete.orig</code></strong>
2078 <code class="prompt">#</code> <strong class=
2079 "userinput"><code>mv pkg_info pkg_info.orig</code></strong>
2080 </pre>
2081                 </li>
2082
2083                 <li>
2084                   <p>An example <code xmlns=
2085                   "http://www.w3.org/TR/xhtml1/transitional" class=
2086                   "filename">/etc/mk.conf</code> file will be
2087                   placed in <code xmlns=
2088                   "http://www.w3.org/TR/xhtml1/transitional" class=
2089                   "filename">/etc/mk.conf.example</code> file when
2090                   you use the bootstrap script.</p>
2091                 </li>
2092               </ol>
2093             </div>
2094           </div>
2095
2096           <div class="sect2" lang="en" xml:lang="en">
2097             <div class="titlepage">
2098               <div>
2099                 <div>
2100                   <h3 class="title"><a name="interix" id=
2101                   "interix"></a>3.2.3.&nbsp;Interix</h3>
2102                 </div>
2103               </div>
2104             </div>
2105
2106             <p>Interix is a POSIX-compatible subsystem for the
2107             Windows NT kernel, providing a Unix-like environment
2108             with a tighter kernel integration than available with
2109             Cygwin. It is part of the Windows Services for Unix
2110             package, available for free for any licensed copy of
2111             Windows 2000, XP (not including XP Home), or 2003. SFU
2112             can be downloaded from <a href=
2113             "http://www.microsoft.com/windows/sfu/" target=
2114             "_top">http://www.microsoft.com/windows/sfu/</a>.</p>
2115
2116             <p>Services for Unix 3.5, current as of this writing,
2117             has been tested. 3.0 or 3.1 may work, but are not
2118             officially supported. (The main difference in 3.0/3.1
2119             is lack of pthreads.)</p>
2120
2121             <div class="sect3" lang="en" xml:lang="en">
2122               <div class="titlepage">
2123                 <div>
2124                   <div>
2125                     <h4 class="title"><a name=
2126                     "platform.interix-sfu-install" id=
2127                     "platform.interix-sfu-install"></a>3.2.3.1.&nbsp;When
2128                     installing Interix/SFU</h4>
2129                   </div>
2130                 </div>
2131               </div>
2132
2133               <p>At an absolute minimum, the following packages
2134               must be installed from the Windows Services for Unix
2135               3.5 distribution in order to use pkgsrc:</p>
2136
2137               <div class="itemizedlist">
2138                 <ul type="disc">
2139                   <li>
2140                     <p>Utilities -&gt; Base Utilities</p>
2141                   </li>
2142
2143                   <li>
2144                     <p>Interix GNU Components -&gt; (all)</p>
2145                   </li>
2146
2147                   <li>
2148                     <p>Remote Connectivity</p>
2149                   </li>
2150
2151                   <li>
2152                     <p>Interix SDK</p>
2153                   </li>
2154                 </ul>
2155               </div>
2156
2157               <p>When using pkgsrc on Interix, DO NOT install the
2158               Utilities subcomponent "UNIX Perl". That is Perl 5.6
2159               without shared module support, installed to
2160               /usr/local, and will only cause confusion. Instead,
2161               install Perl 5.8 from pkgsrc (or from a binary
2162               package).</p>
2163
2164               <p>The Remote Connectivity subcomponent "Windows
2165               Remote Shell Service" does not need to be installed,
2166               but Remote Connectivity itself should be installed in
2167               order to have a working inetd.</p>
2168
2169               <p>Finally, during installation you may be asked
2170               whether to enable setuid behavior for Interix
2171               programs, and whether to make pathnames default to
2172               case-sensitive. Setuid should be enabled, and
2173               case-sensitivity MUST be enabled. (Without
2174               case-sensitivity, a large number of packages
2175               including perl will not build.)</p>
2176             </div>
2177
2178             <div class="sect3" lang="en" xml:lang="en">
2179               <div class="titlepage">
2180                 <div>
2181                   <div>
2182                     <h4 class="title"><a name=
2183                     "platform.interix-sfu-postinstall" id=
2184                     "platform.interix-sfu-postinstall"></a>3.2.3.2.&nbsp;What
2185                     to do if Interix/SFU is already installed</h4>
2186                   </div>
2187                 </div>
2188               </div>
2189
2190               <p>If SFU is already installed and you wish to alter
2191               these settings to work with pkgsrc, note the
2192               following things.</p>
2193
2194               <div class="itemizedlist">
2195                 <ul type="disc">
2196                   <li>
2197                     <p>To uninstall UNIX Perl, use Add/Remove
2198                     Programs, select Microsoft Windows Services for
2199                     UNIX, then click Change. In the installer,
2200                     choose Add or Remove, then uncheck
2201                     Utilities-&gt;UNIX Perl.</p>
2202                   </li>
2203
2204                   <li>
2205                     <p>To enable case-sensitivity for the file
2206                     system, run REGEDIT.EXE, and change the
2207                     following registry key:</p>
2208
2209                     <p>
2210                     HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session
2211                     Manager\kernel</p>
2212
2213                     <p>Set the DWORD value "obcaseinsensitive" to
2214                     0; then reboot.</p>
2215                   </li>
2216
2217                   <li>
2218                     <p>To enable setuid binaries (optional), run
2219                     REGEDIT.EXE, and change the following registry
2220                     key:</p>
2221
2222                     <p>
2223                     HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Services
2224                     for UNIX</p>
2225
2226                     <p>Set the DWORD value "EnableSetuidBinaries"
2227                     to 1; then reboot.</p>
2228                   </li>
2229                 </ul>
2230               </div>
2231             </div>
2232
2233             <div class="sect3" lang="en" xml:lang="en">
2234               <div class="titlepage">
2235                 <div>
2236                   <div>
2237                     <h4 class="title"><a name=
2238                     "platform.interix-notes" id=
2239                     "platform.interix-notes"></a>3.2.3.3.&nbsp;Important
2240                     notes for using pkgsrc</h4>
2241                   </div>
2242                 </div>
2243               </div>
2244
2245               <p>The package imanager (either the pkgsrc "su" user,
2246               or the user running "pkg_add") must be a member of
2247               the local Administrators group. Such a user must also
2248               be used to run the bootstrap. This is slightly
2249               relaxed from the normal pkgsrc requirement of
2250               "root".</p>
2251
2252               <p>The package manager should use a umask of 002.
2253               "make install" will automatically complain if this is
2254               not the case. This ensures that directories written
2255               in /var/db/pkg are Administrators-group
2256               writeable.</p>
2257
2258               <p>The popular Interix binary packages from
2259               http://www.interopsystems.com/ use an older version
2260               of pkgsrc's pkg_* tools. Ideally, these should NOT be
2261               used in conjunction with pkgsrc. If you choose to use
2262               them at the same time as the pkgsrc packages, ensure
2263               that you use the proper pkg_* tools for each type of
2264               binary package.</p>
2265
2266               <p>The TERM setting used for DOS-type console windows
2267               (including those invoked by the csh and ksh startup
2268               shortcuts) is "interix". Most systems don't have a
2269               termcap/terminfo entry for it, but the following
2270               .termcap entry provides adequate emulation in most
2271               cases:</p>
2272               <pre class="programlisting">
2273     interix:kP=\E[S:kN=\E[T:kH=\E[U:dc@:DC@:tc=pcansi:
2274 </pre>
2275             </div>
2276           </div>
2277
2278           <div class="sect2" lang="en" xml:lang="en">
2279             <div class="titlepage">
2280               <div>
2281                 <div>
2282                   <h3 class="title"><a name="irix" id=
2283                   "irix"></a>3.2.4.&nbsp;IRIX</h3>
2284                 </div>
2285               </div>
2286             </div>
2287
2288             <p>You will need a working C compiler, either gcc or
2289             SGI's MIPS and MIPSpro compiler (cc/c89). Please set
2290             the <code class="varname">CC</code> environment
2291             variable according to your preference. If you do not
2292             have a license for the MIPSpro compiler suite, you can
2293             download a gcc tardist file from <a href=
2294             "http://freeware.sgi.com/" target=
2295             "_top">http://freeware.sgi.com/</a>.</p>
2296
2297             <p>Please note that you will need IRIX 6.5.17 or
2298             higher, as this is the earliest version of IRIX
2299             providing support for <a href=
2300             "http://netbsd.gw.com/cgi-bin/man-cgi?if_indextoname+3+NetBSD-current">
2301             <span class="citerefentry"><span class=
2302             "refentrytitle">if_indextoname</span>(3)</span></a>,
2303             <a href=
2304             "http://netbsd.gw.com/cgi-bin/man-cgi?if_nametoindex+3+NetBSD-current">
2305             <span class="citerefentry"><span class=
2306             "refentrytitle">if_nametoindex</span>(3)</span></a>,
2307             etc.</p>
2308
2309             <p>At this point in time, pkgsrc only supports one ABI
2310             at a time. That is, you can not switch between the old
2311             32-bit ABI, the new 32-bit ABI and the 64-bit ABI. If
2312             you start out using "abi=n32", that's what all your
2313             packages will be built with.</p>
2314
2315             <p>Therefore, please make sure that you have no
2316             conflicting <code class="varname">CFLAGS</code> in your
2317             environment or the <code xmlns=
2318             "http://www.w3.org/TR/xhtml1/transitional" class=
2319             "filename">/etc/mk.conf</code>. Particularly, make sure
2320             that you do not try to link n32 object files with lib64
2321             or vice versa. Check your <code xmlns=
2322             "http://www.w3.org/TR/xhtml1/transitional" class=
2323             "filename">/etc/compiler.defaults</code>!</p>
2324
2325             <p>If you have the actual pkgsrc tree mounted via NFS
2326             from a different host, please make sure to set
2327             <code class="varname">WRKOBJDIR</code> to a local
2328             directory, as it appears that IRIX linker occasionally
2329             runs into issues when trying to link over a
2330             network-mounted file system.</p>
2331
2332             <p>The bootstrapping process should set all the right
2333             options for programs such as imake(1), but you may want
2334             to set some options depending on your local setup.
2335             Please see <code xmlns=
2336             "http://www.w3.org/TR/xhtml1/transitional" class=
2337             "filename">pkgsrc/mk/defaults/mk.conf</code> and, of
2338             course, your compiler's man pages for details.</p>
2339
2340             <p>If you are using SGI's MIPSPro compiler, please
2341             set</p>
2342             <pre class="programlisting">
2343     PKGSRC_COMPILER=        mipspro
2344 </pre>
2345
2346             <p>in <code xmlns=
2347             "http://www.w3.org/TR/xhtml1/transitional" class=
2348             "filename">/etc/mk.conf</code>. Otherwise, pkgsrc will
2349             assume you are using gcc and may end up passing invalid
2350             flags to the compiler. Note that bootstrap should
2351             create an appropriate <code xmlns=
2352             "http://www.w3.org/TR/xhtml1/transitional" class=
2353             "filename">mk.conf.example</code> by default.</p>
2354
2355             <p>If you have both the MIPSPro compiler chain
2356             installed as well as gcc, but want to make sure that
2357             MIPRPro is used, please set your <code class=
2358             "varname">PATH</code> to <span class=
2359             "emphasis"><em>not</em></span> include the location of
2360             gcc (often <code xmlns=
2361             "http://www.w3.org/TR/xhtml1/transitional" class=
2362             "filename">/usr/freeware/bin</code>), and (important)
2363             pass the '--preserve-path' flag.</p>
2364           </div>
2365
2366           <div class="sect2" lang="en" xml:lang="en">
2367             <div class="titlepage">
2368               <div>
2369                 <div>
2370                   <h3 class="title"><a name="linux" id=
2371                   "linux"></a>3.2.5.&nbsp;Linux</h3>
2372                 </div>
2373               </div>
2374             </div>
2375
2376             <p>Some versions of Linux (for example Debian
2377             GNU/Linux) need either libtermcap or libcurses
2378             (libncurses). Installing the distributions
2379             libncurses-dev package (or equivalent) should fix the
2380             problem.</p>
2381
2382             <p>pkgsrc supports both gcc (GNU Compiler Collection)
2383             and icc (Intel C++ Compiler). gcc is the default. icc
2384             8.0 and 8.1 on i386 have been tested.</p>
2385
2386             <p>To bootstrap using icc, assuming the default icc
2387             installation directory:</p>
2388             <pre class="programlisting">
2389     env CC=/opt/intel_cc_80/bin/icc LDFLAGS=-static-libcxa \
2390             ac_cv___attribute__=yes ./bootstrap
2391 </pre>
2392
2393             <div class="note" style=
2394             "margin-left: 0.5in; margin-right: 0.5in;">
2395               <h3 class="title">Note</h3>
2396
2397               <p>icc 8.1 needs the `-i-static' argument instead of
2398               -static-libcxa.</p>
2399             </div>
2400
2401             <p>icc supports __attribute__, but the GNU configure
2402             test uses a nested function, which icc does not
2403             support. #undef'ing __attribute__ has the unfortunate
2404             side-effect of breaking many of the Linux header files,
2405             which cannot be compiled properly without
2406             __attribute__. The test must be overridden so that
2407             __attribute__ is assumed supported by the compiler.</p>
2408
2409             <p>After bootstrapping, you should set <code class=
2410             "varname">PKGSRC_COMPILER</code> in <code xmlns=
2411             "http://www.w3.org/TR/xhtml1/transitional" class=
2412             "filename">/etc/mk.conf</code>:</p>
2413             <pre class="programlisting">
2414     PKGSRC_COMPILER=        icc
2415 </pre>
2416
2417             <p>The default installation directory for icc is
2418             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
2419             class="filename">/opt/intel_cc_80</code>, which is also
2420             the pkgsrc default. If you have installed it into a
2421             different directory, set <code class=
2422             "varname">ICCBASE</code> in <code xmlns=
2423             "http://www.w3.org/TR/xhtml1/transitional" class=
2424             "filename">/etc/mk.conf</code>:</p>
2425             <pre class="programlisting">
2426     ICCBASE=                /opt/icc
2427 </pre>
2428
2429             <p>pkgsrc uses the static linking method of the runtime
2430             libraries provided by icc, so binaries can be run on
2431             other systems which do not have the shared libraries
2432             installed.</p>
2433
2434             <p>Libtool, however, extracts a list of libraries from
2435             the <a href=
2436             "http://netbsd.gw.com/cgi-bin/man-cgi?ld+1+NetBSD-current">
2437             <span class="citerefentry"><span class=
2438             "refentrytitle">ld</span>(1)</span></a> command run
2439             when linking a C++ shared library and records it,
2440             throwing away the -Bstatic and -Bdynamic options
2441             interspersed between the libraries. This means that
2442             libtool-linked C++ shared libraries will have a runtime
2443             dependency on the icc libraries until this is fixed in
2444             libtool.</p>
2445           </div>
2446
2447           <div class="sect2" lang="en" xml:lang="en">
2448             <div class="titlepage">
2449               <div>
2450                 <div>
2451                   <h3 class="title"><a name="openbsd" id=
2452                   "openbsd"></a>3.2.6.&nbsp;OpenBSD</h3>
2453                 </div>
2454               </div>
2455             </div>
2456
2457             <p>OpenBSD 3.0 and 3.2 are tested and supported.</p>
2458
2459             <p>Care should be taken so that the tools that this kit
2460             installs do not conflict with the OpenBSD userland
2461             tools. There are several steps:</p>
2462
2463             <div class="orderedlist">
2464               <ol type="1">
2465                 <li>
2466                   <p>OpenBSD stores its ports pkg database in
2467                   <code xmlns=
2468                   "http://www.w3.org/TR/xhtml1/transitional" class=
2469                   "filename">/var/db/pkg</code>. It is therefore
2470                   recommended that you choose a different location
2471                   (e.g. <code xmlns=
2472                   "http://www.w3.org/TR/xhtml1/transitional" class=
2473                   "filename">/usr/pkgdb</code>) by using the
2474                   --pkgdbdir option to the bootstrap script.</p>
2475                 </li>
2476
2477                 <li>
2478                   <p>If you do not intend to use the OpenBSD ports
2479                   tools, it's probably a good idea to move them out
2480                   of the way to avoid confusion, e.g.</p>
2481                   <pre class="screen">
2482 <code class="prompt">#</code> <strong class=
2483 "userinput"><code>cd /usr/sbin</code></strong>
2484 <code class="prompt">#</code> <strong class=
2485 "userinput"><code>mv pkg_add pkg_add.orig</code></strong>
2486 <code class="prompt">#</code> <strong class=
2487 "userinput"><code>mv pkg_create pkg_create.orig</code></strong>
2488 <code class="prompt">#</code> <strong class=
2489 "userinput"><code>mv pkg_delete pkg_delete.orig</code></strong>
2490 <code class="prompt">#</code> <strong class=
2491 "userinput"><code>mv pkg_info pkg_info.orig</code></strong>
2492 </pre>
2493                 </li>
2494
2495                 <li>
2496                   <p>An example <code xmlns=
2497                   "http://www.w3.org/TR/xhtml1/transitional" class=
2498                   "filename">/etc/mk.conf</code> file will be
2499                   placed in <code xmlns=
2500                   "http://www.w3.org/TR/xhtml1/transitional" class=
2501                   "filename">/etc/mk.conf.example</code> file when
2502                   you use the bootstrap script. OpenBSD's make
2503                   program uses <code xmlns=
2504                   "http://www.w3.org/TR/xhtml1/transitional" class=
2505                   "filename">/etc/mk.conf</code> as well. You can
2506                   work around this by enclosing all the
2507                   pkgsrc-specific parts of the file with:</p>
2508                   <pre class="programlisting">
2509     .ifdef BSD_PKG_MK
2510     # pkgsrc stuff, e.g. insert defaults/mk.conf or similar here
2511     .else
2512     # OpenBSD stuff
2513     .endif
2514 </pre>
2515                 </li>
2516               </ol>
2517             </div>
2518           </div>
2519
2520           <div class="sect2" lang="en" xml:lang="en">
2521             <div class="titlepage">
2522               <div>
2523                 <div>
2524                   <h3 class="title"><a name="solaris" id=
2525                   "solaris"></a>3.2.7.&nbsp;Solaris</h3>
2526                 </div>
2527               </div>
2528             </div>
2529
2530             <p>Solaris 2.6 through 9 are supported on both x86 and
2531             sparc. You will need a working C compiler. Both gcc
2532             2.95.3 and Sun WorkShop 5 have been tested.</p>
2533
2534             <p>The following packages are required on Solaris 8 for
2535             the bootstrap process and to build packages.</p>
2536
2537             <div class="itemizedlist">
2538               <ul type="disc">
2539                 <li>
2540                   <p>SUNWsprot</p>
2541                 </li>
2542
2543                 <li>
2544                   <p>SUNWarc</p>
2545                 </li>
2546
2547                 <li>
2548                   <p>SUNWbtool</p>
2549                 </li>
2550
2551                 <li>
2552                   <p>SUNWtoo</p>
2553                 </li>
2554
2555                 <li>
2556                   <p>SUNWlibm</p>
2557                 </li>
2558               </ul>
2559             </div>
2560
2561             <p>Please note the use of GNU binutils on Solaris is
2562             <span class="emphasis"><em>not</em></span>
2563             supported.</p>
2564
2565             <div class="sect3" lang="en" xml:lang="en">
2566               <div class="titlepage">
2567                 <div>
2568                   <div>
2569                     <h4 class="title"><a name="solaris-gcc-note"
2570                     id="solaris-gcc-note"></a>3.2.7.1.&nbsp;If you
2571                     are using gcc</h4>
2572                   </div>
2573                 </div>
2574               </div>
2575
2576               <p>It makes life much simpler if you only use the
2577               same gcc consistently for building all packages.</p>
2578
2579               <p>It is recommended that an external gcc be used
2580               only for bootstrapping, then either build gcc from
2581               <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
2582               href=
2583               "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/lang/gcc/README.html"
2584               target="_top"><code xmlns="" class=
2585               "filename">lang/gcc</code></a> or install a binary
2586               gcc package, then remove gcc used during
2587               bootstrapping.</p>
2588
2589               <p>Binary packages of gcc can be found through
2590               <a href=
2591               "http://www.sun.com/bigadmin/common/freewareSearch.html"
2592               target=
2593               "_top">http://www.sun.com/bigadmin/common/freewareSearch.html</a>.</p>
2594             </div>
2595
2596             <div class="sect3" lang="en" xml:lang="en">
2597               <div class="titlepage">
2598                 <div>
2599                   <div>
2600                     <h4 class="title"><a name=
2601                     "solaris-sun-workshop-note" id=
2602                     "solaris-sun-workshop-note"></a>3.2.7.2.&nbsp;If
2603                     you are using Sun WorkShop</h4>
2604                   </div>
2605                 </div>
2606               </div>
2607
2608               <p>You will need at least the following packages
2609               installed (from WorkShop 5.0)</p>
2610
2611               <div class="itemizedlist">
2612                 <ul type="disc">
2613                   <li>
2614                     <p>SPROcc - Sun WorkShop Compiler C 5.0</p>
2615                   </li>
2616
2617                   <li>
2618                     <p>SPROcpl - Sun WorkShop Compiler C++ 5.0</p>
2619                   </li>
2620
2621                   <li>
2622                     <p>SPROild - Sun WorkShop Incremental
2623                     Linker</p>
2624                   </li>
2625
2626                   <li>
2627                     <p>SPROlang - Sun WorkShop Compilers common
2628                     components</p>
2629                   </li>
2630                 </ul>
2631               </div>
2632
2633               <p>You should set <code class="varname">CC</code>,
2634               <code class="varname">CXX</code> and optionally,
2635               <code class="varname">CPP</code> in <code xmlns=
2636               "http://www.w3.org/TR/xhtml1/transitional" class=
2637               "filename">/etc/mk.conf</code>, e.g.:</p>
2638               <pre class="programlisting">
2639     CC=     cc
2640     CXX=    CC
2641     CPP=    /usr/ccs/lib/cpp
2642 </pre>
2643
2644               <p>You may also want to build 64-bit binaries,
2645               e.g.:</p>
2646               <pre class="programlisting">
2647     CFLAGS= -xtarget=ultra -xarch=v9
2648 </pre>
2649
2650               <p>Whichever compiler you use, please ensure the
2651               compiler tools and your $prefix are in your
2652               <code class="varname">PATH</code>. This includes
2653               <code xmlns=
2654               "http://www.w3.org/TR/xhtml1/transitional" class=
2655               "filename">/usr/ccs/{bin,lib}</code> and e.g.
2656               <code xmlns=
2657               "http://www.w3.org/TR/xhtml1/transitional" class=
2658               "filename">/usr/pkg/{bin,sbin}</code>.</p>
2659             </div>
2660           </div>
2661         </div>
2662       </div>
2663
2664       <div class="chapter" lang="en" xml:lang="en">
2665         <div class="titlepage">
2666           <div>
2667             <div>
2668               <h2 class="title"><a name="using" id=
2669               "using"></a>Chapter&nbsp;4.&nbsp;Using pkgsrc</h2>
2670             </div>
2671           </div>
2672         </div>
2673
2674         <div class="toc">
2675           <p><b>Table of Contents</b></p>
2676
2677           <dl>
2678             <dt><span class="sect1"><a href="#getting-started">4.1.
2679             Working with binary packages</a></span></dt>
2680
2681             <dd>
2682               <dl>
2683                 <dt><span class="sect2"><a href=
2684                 "#where-to-get-binary-packages">4.1.1. Where to get
2685                 binary packages</a></span></dt>
2686
2687                 <dt><span class="sect2"><a href=
2688                 "#how-to-use-binary-packages">4.1.2. How to use
2689                 binary packages</a></span></dt>
2690
2691                 <dt><span class="sect2"><a href=
2692                 "#a-word-of-warning">4.1.3. A word of
2693                 warning</a></span></dt>
2694               </dl>
2695             </dd>
2696
2697             <dt><span class="sect1"><a href=
2698             "#building-packages-from-source">4.2. Building packages
2699             from source</a></span></dt>
2700
2701             <dd>
2702               <dl>
2703                 <dt><span class="sect2"><a href=
2704                 "#requirements">4.2.1. Requirements</a></span></dt>
2705
2706                 <dt><span class="sect2"><a href=
2707                 "#fetching-distfiles">4.2.2. Fetching
2708                 distfiles</a></span></dt>
2709
2710                 <dt><span class="sect2"><a href=
2711                 "#how-to-build-and-install">4.2.3. How to build and
2712                 install</a></span></dt>
2713
2714                 <dt><span class="sect2"><a href=
2715                 "#selecting-the-compiler">4.2.4. Selecting the
2716                 compiler</a></span></dt>
2717               </dl>
2718             </dd>
2719           </dl>
2720         </div>
2721
2722         <div class="sect1" lang="en" xml:lang="en">
2723           <div class="titlepage">
2724             <div>
2725               <div>
2726                 <h2 class="title" style="clear: both"><a name=
2727                 "getting-started" id=
2728                 "getting-started"></a>4.1.&nbsp;Working with binary
2729                 packages</h2>
2730               </div>
2731             </div>
2732           </div>
2733
2734           <p>This section describes how to find, retrieve and
2735           install a precompiled binary package that someone else
2736           already prepared for your type of machine.</p>
2737
2738           <div class="sect2" lang="en" xml:lang="en">
2739             <div class="titlepage">
2740               <div>
2741                 <div>
2742                   <h3 class="title"><a name=
2743                   "where-to-get-binary-packages" id=
2744                   "where-to-get-binary-packages"></a>4.1.1.&nbsp;Where
2745                   to get binary packages</h3>
2746                 </div>
2747               </div>
2748             </div>
2749
2750             <p>Precompiled packages are stored on ftp.NetBSD.org
2751             and its mirrors in the directory <code xmlns=
2752             "http://www.w3.org/TR/xhtml1/transitional" class=
2753             "filename">/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/</code>
2754             for anonymous FTP access. <code class=
2755             "varname">OSVERSION</code> is the NetBSD version
2756             (<span><strong class="command">uname
2757             -r</strong></span>), <code class="varname">ARCH</code>
2758             is the architecture (<span><strong class=
2759             "command">uname -p</strong></span>). In that directory,
2760             there is a subdirectory for each category plus a
2761             subdirectory <code xmlns=
2762             "http://www.w3.org/TR/xhtml1/transitional" class=
2763             "filename">All</code> which includes the actual
2764             binaries in <code xmlns=
2765             "http://www.w3.org/TR/xhtml1/transitional" class=
2766             "filename">.tgz</code> files. The category
2767             subdirectories use symbolic links to those files (this
2768             is the same directory layout as in <code xmlns=
2769             "http://www.w3.org/TR/xhtml1/transitional" class=
2770             "filename">/usr/pkgsrc/packages</code>).</p>
2771
2772             <p>This same directory layout applies for CD-ROM
2773             distributions, only that the directory may be rooted
2774             somewhere else, probably somewhere below <code xmlns=
2775             "http://www.w3.org/TR/xhtml1/transitional" class=
2776             "filename">/cdrom</code>. Please consult your CD-ROMs
2777             documentation for the exact location.</p>
2778           </div>
2779
2780           <div class="sect2" lang="en" xml:lang="en">
2781             <div class="titlepage">
2782               <div>
2783                 <div>
2784                   <h3 class="title"><a name=
2785                   "how-to-use-binary-packages" id=
2786                   "how-to-use-binary-packages"></a>4.1.2.&nbsp;How
2787                   to use binary packages</h3>
2788                 </div>
2789               </div>
2790             </div>
2791
2792             <p>If you have the files on a CD-ROM or downloaded them
2793             to your hard disk, you can install them with the
2794             following command (be sure to <span><strong class=
2795             "command">su</strong></span> to root first):</p>
2796             <pre class="screen">
2797 <code class="prompt">#</code> <strong class=
2798 "userinput"><code>pkg_add /path/to/package.tgz</code></strong>
2799 </pre>
2800
2801             <p>If you have FTP access and you don't want to
2802             download the packages via FTP prior to installation,
2803             you can do this automatically by giving
2804             <span><strong class="command">pkg_add</strong></span>
2805             an FTP URL:</p>
2806             <pre class="screen">
2807 <code class="prompt">#</code> <strong class=
2808 "userinput"><code>pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All/package.tgz</code></strong>
2809 </pre>
2810
2811             <p>Note that any prerequisite packages needed to run
2812             the package in question will be installed, too,
2813             assuming they are present where you install from.</p>
2814
2815             <p>To save some typing, you can set the <code class=
2816             "varname">PKG_PATH</code> environment variable to a
2817             semicolon-separated list of paths (including remote
2818             URLs); trailing slashes are not allowed.</p>
2819
2820             <p>Additionally to the <code xmlns=
2821             "http://www.w3.org/TR/xhtml1/transitional" class=
2822             "filename">All</code> directory there exists a
2823             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
2824             class="filename">vulnerable</code> directory to which
2825             binary packages with known vulnerabilities are moved,
2826             since removing them could cause missing dependencies.
2827             To use these packages, add the <code xmlns=
2828             "http://www.w3.org/TR/xhtml1/transitional" class=
2829             "filename">vulnerable</code> directory to your
2830             <code class="varname">PKG_PATH</code>. However, you
2831             should run <a xmlns=
2832             "http://www.w3.org/TR/xhtml1/transitional" href=
2833             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"
2834             target="_top"><code xmlns="" class=
2835             "filename">security/audit-packages</code></a>
2836             regularly, especially after installing new packages,
2837             and verify that the vulnerabilities are acceptable for
2838             your configuration. An example <code class=
2839             "varname">PKG_PATH</code> would be: <code xmlns=
2840             "http://www.w3.org/TR/xhtml1/transitional" class=
2841             "filename">ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All;ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/vulnerable</code>
2842             Please note that semicolon (';') is a shell
2843             meta-character, so you'll probably have to quote
2844             it.</p>
2845
2846             <p>After you've installed packages, be sure to have
2847             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
2848             class="filename">/usr/pkg/bin</code> and <code xmlns=
2849             "http://www.w3.org/TR/xhtml1/transitional" class=
2850             "filename">/usr/pkg/sbin</code> in your <code class=
2851             "varname">PATH</code> so you can actually start the
2852             just installed program.</p>
2853           </div>
2854
2855           <div class="sect2" lang="en" xml:lang="en">
2856             <div class="titlepage">
2857               <div>
2858                 <div>
2859                   <h3 class="title"><a name="a-word-of-warning" id=
2860                   "a-word-of-warning"></a>4.1.3.&nbsp;A word of
2861                   warning</h3>
2862                 </div>
2863               </div>
2864             </div>
2865
2866             <p>Please pay very careful attention to the warnings
2867             expressed in the <a href=
2868             "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
2869             <span class="citerefentry"><span class=
2870             "refentrytitle">pkg_add</span>(1)</span></a> manual
2871             page about the inherent dangers of installing binary
2872             packages which you did not create yourself, and the
2873             security holes that can be introduced onto your system
2874             by indiscriminate adding of such files.</p>
2875           </div>
2876         </div>
2877
2878         <div class="sect1" lang="en" xml:lang="en">
2879           <div class="titlepage">
2880             <div>
2881               <div>
2882                 <h2 class="title" style="clear: both"><a name=
2883                 "building-packages-from-source" id=
2884                 "building-packages-from-source"></a>4.2.&nbsp;Building
2885                 packages from source</h2>
2886               </div>
2887             </div>
2888           </div>
2889
2890           <p>This assumes that the package is already in pkgsrc. If
2891           it is not, see <a href="#developers-guide" title=
2892           "Part&nbsp;II.&nbsp;The pkgsrc developer's guide">Part&nbsp;II,
2893           &#8220;The pkgsrc developer's guide&#8221;</a> for
2894           instructions how to create your own packages.</p>
2895
2896           <div class="sect2" lang="en" xml:lang="en">
2897             <div class="titlepage">
2898               <div>
2899                 <div>
2900                   <h3 class="title"><a name="requirements" id=
2901                   "requirements"></a>4.2.1.&nbsp;Requirements</h3>
2902                 </div>
2903               </div>
2904             </div>
2905
2906             <p>To build packages from source on a NetBSD system the
2907             &#8220;<span class="quote">comp</span>&#8221; and the
2908             &#8220;<span class="quote">text</span>&#8221;
2909             distribution sets must be installed. If you want to
2910             build X11-related packages the &#8220;<span class=
2911             "quote">xbase</span>&#8221; and &#8220;<span class=
2912             "quote">xcomp</span>&#8221; distribution sets are
2913             required, too.</p>
2914           </div>
2915
2916           <div class="sect2" lang="en" xml:lang="en">
2917             <div class="titlepage">
2918               <div>
2919                 <div>
2920                   <h3 class="title"><a name="fetching-distfiles"
2921                   id="fetching-distfiles"></a>4.2.2.&nbsp;Fetching
2922                   distfiles</h3>
2923                 </div>
2924               </div>
2925             </div>
2926
2927             <p>The first step for building a package is downloading
2928             the distfiles (i.e. the unmodified source). If they
2929             have not yet been downloaded, pkgsrc will fetch them
2930             automatically.</p>
2931
2932             <p>You can overwrite some of the major distribution
2933             sites to fit to sites that are close to your own. Have
2934             a look at <code xmlns=
2935             "http://www.w3.org/TR/xhtml1/transitional" class=
2936             "filename">pkgsrc/mk/defaults/mk.conf</code> to find
2937             some examples &#8212; in particular, look for the
2938             <code class="varname">MASTER_SORT</code>, <code class=
2939             "varname">MASTER_SORT_REGEX</code> and <code class=
2940             "varname">INET_COUNTRY</code> definitions. This may
2941             save some of your bandwidth and time.</p>
2942
2943             <p>You can change these settings either in your shell's
2944             environment, or, if you want to keep the settings, by
2945             editing the <code xmlns=
2946             "http://www.w3.org/TR/xhtml1/transitional" class=
2947             "filename">/etc/mk.conf</code> file, and adding the
2948             definitions there.</p>
2949
2950             <p>If you don't have a permanent Internet connection
2951             and you want to know which files to download,
2952             <span><strong class="command">make
2953             fetch-list</strong></span> will tell you what you'll
2954             need. Put these distfiles into <code xmlns=
2955             "http://www.w3.org/TR/xhtml1/transitional" class=
2956             "filename">/usr/pkgsrc/distfiles</code>.</p>
2957           </div>
2958
2959           <div class="sect2" lang="en" xml:lang="en">
2960             <div class="titlepage">
2961               <div>
2962                 <div>
2963                   <h3 class="title"><a name=
2964                   "how-to-build-and-install" id=
2965                   "how-to-build-and-install"></a>4.2.3.&nbsp;How to
2966                   build and install</h3>
2967                 </div>
2968               </div>
2969             </div>
2970
2971             <p>Assuming that the distfile has been fetched (see
2972             previous section), become root and change into the
2973             relevant directory and run <span><strong class=
2974             "command">make</strong></span>.</p>
2975
2976             <div class="note" style=
2977             "margin-left: 0.5in; margin-right: 0.5in;">
2978               <h3 class="title">Note</h3>
2979
2980               <p>If using bootstrap or pkgsrc on a non-NetBSD
2981               system, use the pkgsrc <span><strong class=
2982               "command">bmake</strong></span> command instead of
2983               &#8220;<span class="quote">make</span>&#8221; in the
2984               examples in this guide.</p>
2985             </div>
2986
2987             <p>For example, type</p>
2988             <pre class="screen">
2989 <code class="prompt">%</code> <strong class=
2990 "userinput"><code>cd misc/figlet</code></strong>
2991 <code class="prompt">%</code> <strong class=
2992 "userinput"><code>make</code></strong>
2993 </pre>
2994
2995             <p>at the shell prompt to build the various components
2996             of the package, and</p>
2997             <pre class="screen">
2998 <code class="prompt">#</code> <strong class=
2999 "userinput"><code>make install</code></strong>
3000 </pre>
3001
3002             <p>to install the various components into the correct
3003             places on your system. Installing the package on your
3004             system requires you to be root. However, pkgsrc has a
3005             <span class="emphasis"><em>just-in-time-su</em></span>
3006             feature, which allows you to only become root for the
3007             actual installation step</p>
3008
3009             <p>Taking the figlet utility as an example, we can
3010             install it on our system by building as shown in
3011             <a href="#logs" title=
3012             "Appendix&nbsp;B.&nbsp;Build logs">Appendix B, <i>Build
3013             logs</i></a>.</p>
3014
3015             <p>The program is installed under the default root of
3016             the packages tree - <code xmlns=
3017             "http://www.w3.org/TR/xhtml1/transitional" class=
3018             "filename">/usr/pkg</code>. Should this not conform to
3019             your tastes, set the <code class=
3020             "varname">LOCALBASE</code> variable in your
3021             environment, and it will use that value as the root of
3022             your packages tree. So, to use <code xmlns=
3023             "http://www.w3.org/TR/xhtml1/transitional" class=
3024             "filename">/usr/local</code>, set <code class=
3025             "varname">LOCALBASE=/usr/local</code> in your
3026             environment. Please note that you should use a
3027             directory which is dedicated to packages and not shared
3028             with other programs (i.e., do not try and use
3029             <code class="varname">LOCALBASE=/usr</code>). Also, you
3030             should not try to add any of your own files or
3031             directories (such as <code xmlns=
3032             "http://www.w3.org/TR/xhtml1/transitional" class=
3033             "filename">src/</code>, <code xmlns=
3034             "http://www.w3.org/TR/xhtml1/transitional" class=
3035             "filename">obj/</code>, or <code xmlns=
3036             "http://www.w3.org/TR/xhtml1/transitional" class=
3037             "filename">pkgsrc/</code>) below the <code class=
3038             "varname">LOCALBASE</code> tree. This is to prevent
3039             possible conflicts between programs and other files
3040             installed by the package system and whatever else may
3041             have been installed there.</p>
3042
3043             <p>Some packages look in <code xmlns=
3044             "http://www.w3.org/TR/xhtml1/transitional" class=
3045             "filename">/etc/mk.conf</code> to alter some
3046             configuration options at build time. Have a look at
3047             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3048             class="filename">pkgsrc/mk/defaults/mk.conf</code> to
3049             get an overview of what will be set there by default.
3050             Environment variables such as <code class=
3051             "varname">LOCALBASE</code> can be set in <code xmlns=
3052             "http://www.w3.org/TR/xhtml1/transitional" class=
3053             "filename">/etc/mk.conf</code> to save having to
3054             remember to set them each time you want to use
3055             pkgsrc.</p>
3056
3057             <p>Occasionally, people want to &#8220;<span class=
3058             "quote">look under the covers</span>&#8221; to see what
3059             is going on when a package is building or being
3060             installed. This may be for debugging purposes, or out
3061             of simple curiosity. A number of utility values have
3062             been added to help with this.</p>
3063
3064             <div class="orderedlist">
3065               <ol type="1">
3066                 <li>
3067                   <p>If you invoke the <a href=
3068                   "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
3069                   <span class="citerefentry"><span class=
3070                   "refentrytitle">make</span>(1)</span></a> command
3071                   with <code class=
3072                   "varname">PKG_DEBUG_LEVEL=2</code>, then a huge
3073                   amount of information will be displayed. For
3074                   example,</p>
3075                   <pre class="screen">
3076 <strong class=
3077 "userinput"><code>make patch PKG_DEBUG_LEVEL=2</code></strong>
3078 </pre>
3079
3080                   <p>will show all the commands that are invoked,
3081                   up to and including the &#8220;<span class=
3082                   "quote">patch</span>&#8221; stage.</p>
3083                 </li>
3084
3085                 <li>
3086                   <p>If you want to know the value of a certain
3087                   <a href=
3088                   "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
3089                   <span class="citerefentry"><span class=
3090                   "refentrytitle">make</span>(1)</span></a>
3091                   definition, then the <code class=
3092                   "varname">VARNAME</code> definition should be
3093                   used, in conjunction with the show-var target.
3094                   e.g. to show the expansion of the <a href=
3095                   "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
3096                   <span class="citerefentry"><span class=
3097                   "refentrytitle">make</span>(1)</span></a>
3098                   variable <code class=
3099                   "varname">LOCALBASE</code>:</p>
3100                   <pre class="screen">
3101 <code class="prompt">%</code> <strong class=
3102 "userinput"><code>make show-var VARNAME=LOCALBASE</code></strong>
3103 /usr/pkg
3104 <code class="prompt">%</code>
3105
3106 </pre>
3107                 </li>
3108               </ol>
3109             </div>
3110
3111             <p>If you want to install a binary package that you've
3112             either created yourself (see next section), that you
3113             put into pkgsrc/packages manually or that is located on
3114             a remote FTP server, you can use the "bin-install"
3115             target. This target will install a binary package - if
3116             available - via <a href=
3117             "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
3118             <span class="citerefentry"><span class=
3119             "refentrytitle">pkg_add</span>(1)</span></a>, else do a
3120             <span><strong class="command">make
3121             package</strong></span>. The list of remote FTP sites
3122             searched is kept in the variable <code class=
3123             "varname">BINPKG_SITES</code>, which defaults to
3124             ftp.NetBSD.org. Any flags that should be added to
3125             <a href=
3126             "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
3127             <span class="citerefentry"><span class=
3128             "refentrytitle">pkg_add</span>(1)</span></a> can be put
3129             into <code class="varname">BIN_INSTALL_FLAGS</code>.
3130             See <code xmlns=
3131             "http://www.w3.org/TR/xhtml1/transitional" class=
3132             "filename">pkgsrc/mk/defaults/mk.conf</code> for more
3133             details.</p>
3134
3135             <p>A final word of warning: If you set up a system that
3136             has a non-standard setting for <code class=
3137             "varname">LOCALBASE</code>, be sure to set that before
3138             any packages are installed, as you can not use several
3139             directories for the same purpose. Doing so will result
3140             in pkgsrc not being able to properly detect your
3141             installed packages, and fail miserably. Note also that
3142             precompiled binary packages are usually built with the
3143             default <code class="varname">LOCALBASE</code> of
3144             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3145             class="filename">/usr/pkg</code>, and that you should
3146             <span class="emphasis"><em>not</em></span> install any
3147             if you use a non-standard <code class=
3148             "varname">LOCALBASE</code>.</p>
3149           </div>
3150
3151           <div class="sect2" lang="en" xml:lang="en">
3152             <div class="titlepage">
3153               <div>
3154                 <div>
3155                   <h3 class="title"><a name=
3156                   "selecting-the-compiler" id=
3157                   "selecting-the-compiler"></a>4.2.4.&nbsp;Selecting
3158                   the compiler</h3>
3159                 </div>
3160               </div>
3161             </div>
3162
3163             <p>By default, pkgsrc will use GCC to build packages.
3164             This may be overridden by setting the following
3165             variables in /etc/mk.conf:</p>
3166
3167             <div class="variablelist">
3168               <dl>
3169                 <dt><span class="term"><code class=
3170                 "varname">PKGSRC_COMPILER</code>:</span></dt>
3171
3172                 <dd>
3173                   <p>This is a list of values specifying the chain
3174                   of compilers to invoke when building packages.
3175                   Valid values are:</p>
3176
3177                   <div class="itemizedlist">
3178                     <ul type="disc">
3179                       <li>
3180                         <p><code class="varname">distcc</code>:
3181                         distributed C/C++ (chainable)</p>
3182                       </li>
3183
3184                       <li>
3185                         <p><code class="varname">ccache</code>:
3186                         compiler cache (chainable)</p>
3187                       </li>
3188
3189                       <li>
3190                         <p><code class="varname">gcc</code>: GNU
3191                         C/C++ Compiler</p>
3192                       </li>
3193
3194                       <li>
3195                         <p><code class="varname">mipspro</code>:
3196                         Silicon Graphics, Inc. MIPSpro
3197                         (n32/n64)</p>
3198                       </li>
3199
3200                       <li>
3201                         <p><code class="varname">mipspro</code>:
3202                         Silicon Graphics, Inc. MIPSpro (o32)</p>
3203                       </li>
3204
3205                       <li>
3206                         <p><code class="varname">sunpro</code>:
3207                         Microsystems, Inc. WorkShip/Forte/Sun ONE
3208                         Studio</p>
3209                       </li>
3210                     </ul>
3211                   </div>
3212
3213                   <p>The default is &#8220;<span class=
3214                   "quote"><code class=
3215                   "varname">gcc</code></span>&#8221;. You can use
3216                   <code class="varname">ccache</code> and/or
3217                   <code class="varname">distcc</code> with an
3218                   appropriate <code class=
3219                   "varname">PKGSRC_COMPILER</code> setting, e.g.
3220                   &#8220;<span class="quote"><code class=
3221                   "varname">ccache gcc</code></span>&#8221;. This
3222                   variable should always be terminated with a value
3223                   for a real compiler.</p>
3224                 </dd>
3225
3226                 <dt><span class="term"><code class=
3227                 "varname">GCC_REQD</code>:</span></dt>
3228
3229                 <dd>
3230                   <p>This specifies the minimum version of GCC to
3231                   use when building packages. If the system GCC
3232                   doesn't satisfy this requirement, then pkgsrc
3233                   will build and install one of the GCC packages to
3234                   use instead.</p>
3235                 </dd>
3236               </dl>
3237             </div>
3238           </div>
3239         </div>
3240       </div>
3241
3242       <div class="chapter" lang="en" xml:lang="en">
3243         <div class="titlepage">
3244           <div>
3245             <div>
3246               <h2 class="title"><a name="configuring" id=
3247               "configuring"></a>Chapter&nbsp;5.&nbsp;Configuring
3248               pkgsrc</h2>
3249             </div>
3250           </div>
3251         </div>
3252
3253         <div class="toc">
3254           <p><b>Table of Contents</b></p>
3255
3256           <dl>
3257             <dt><span class="sect1"><a href=
3258             "#general-configuration">5.1. General
3259             configuration</a></span></dt>
3260
3261             <dt><span class="sect1"><a href=
3262             "#variables-affecting-build">5.2. Variables affecting
3263             the build process</a></span></dt>
3264
3265             <dt><span class="sect1"><a href=
3266             "#developer-advanced-settings">5.3. Developer/advanced
3267             settings</a></span></dt>
3268
3269             <dt><span class="sect1"><a href=
3270             "#selecting-build-options">5.4. Selecting Build
3271             Options</a></span></dt>
3272           </dl>
3273         </div>
3274
3275         <div class="sect1" lang="en" xml:lang="en">
3276           <div class="titlepage">
3277             <div>
3278               <div>
3279                 <h2 class="title" style="clear: both"><a name=
3280                 "general-configuration" id=
3281                 "general-configuration"></a>5.1.&nbsp;General
3282                 configuration</h2>
3283               </div>
3284             </div>
3285           </div>
3286
3287           <p>In this section, you can find some variables that
3288           apply to all pkgsrc packages. The preferred method of
3289           setting these variables is by setting them in
3290           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3291           class="filename">/etc/mk.conf</code>.</p>
3292
3293           <div class="itemizedlist">
3294             <ul type="disc">
3295               <li>
3296                 <p><code class="varname">LOCALBASE</code>: Where
3297                 packages will be installed. The default is
3298                 <code xmlns=
3299                 "http://www.w3.org/TR/xhtml1/transitional" class=
3300                 "filename">/usr/pkg</code>. Do not mix binary
3301                 packages with different <code class=
3302                 "varname">LOCALBASE</code>s!</p>
3303               </li>
3304
3305               <li>
3306                 <p><code class="varname">CROSSBASE</code>: Where
3307                 &#8220;<span class="quote">cross</span>&#8221;
3308                 category packages will be installed. The default is
3309                 <code xmlns=
3310                 "http://www.w3.org/TR/xhtml1/transitional" class=
3311                 "filename">${LOCALBASE}/cross</code>.</p>
3312               </li>
3313
3314               <li>
3315                 <p><code class="varname">X11BASE</code>: Where X11
3316                 is installed on the system. The default is
3317                 <code xmlns=
3318                 "http://www.w3.org/TR/xhtml1/transitional" class=
3319                 "filename">/usr/X11R6</code>.</p>
3320               </li>
3321
3322               <li>
3323                 <p><code class="varname">DISTDIR</code>: Where to
3324                 store the downloaded copies of the original source
3325                 distributions used for building pkgsrc packages.
3326                 The default is <code xmlns=
3327                 "http://www.w3.org/TR/xhtml1/transitional" class=
3328                 "filename">${PKGSRCDIR}/distfiles</code>.</p>
3329               </li>
3330
3331               <li>
3332                 <p><code class=
3333                 "varname">MASTER_SITE_OVERRIDE</code>: If set,
3334                 override the packages' <code class=
3335                 "varname">MASTER_SITES</code> with this value.</p>
3336               </li>
3337
3338               <li>
3339                 <p><code class="varname">MASTER_SITE_BACKUP</code>:
3340                 Backup location(s) for distribution files and patch
3341                 files if not found locally or in <code xmlns=
3342                 "http://www.w3.org/TR/xhtml1/transitional" class=
3343                 "filename">${MASTER_SITES}</code> or <code xmlns=
3344                 "http://www.w3.org/TR/xhtml1/transitional" class=
3345                 "filename">${PATCH_SITES}</code> respectively. The
3346                 defaults are <code xmlns=
3347                 "http://www.w3.org/TR/xhtml1/transitional" class=
3348                 "filename">ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}/</code>
3349                 and <code xmlns=
3350                 "http://www.w3.org/TR/xhtml1/transitional" class=
3351                 "filename">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/</code>.</p>
3352               </li>
3353
3354               <li>
3355                 <p><code class="varname">BINPKG_SITES</code>: List
3356                 of sites carrying binary pkgs.</p>
3357               </li>
3358             </ul>
3359           </div>
3360         </div>
3361
3362         <div class="sect1" lang="en" xml:lang="en">
3363           <div class="titlepage">
3364             <div>
3365               <div>
3366                 <h2 class="title" style="clear: both"><a name=
3367                 "variables-affecting-build" id=
3368                 "variables-affecting-build"></a>5.2.&nbsp;Variables
3369                 affecting the build process</h2>
3370               </div>
3371             </div>
3372           </div>
3373
3374           <p>XXX</p>
3375
3376           <div class="itemizedlist">
3377             <ul type="disc">
3378               <li>
3379                 <p><code class="varname">PACKAGES</code>: The top
3380                 level directory for the binary packages. The
3381                 default is <code xmlns=
3382                 "http://www.w3.org/TR/xhtml1/transitional" class=
3383                 "filename">${PKGSRCDIR}/packages</code>.</p>
3384               </li>
3385
3386               <li>
3387                 <p><code class="varname">WRKOBJDIR</code>: The top
3388                 level directory where, if defined, the separate
3389                 working directories will get created, and
3390                 symbolically linked to from <code xmlns=
3391                 "http://www.w3.org/TR/xhtml1/transitional" class=
3392                 "filename">${WRKDIR}</code> (see below). This is
3393                 useful for building packages on several
3394                 architectures, then <code xmlns=
3395                 "http://www.w3.org/TR/xhtml1/transitional" class=
3396                 "filename">${PKGSRCDIR}</code> can be NFS-mounted
3397                 while <code xmlns=
3398                 "http://www.w3.org/TR/xhtml1/transitional" class=
3399                 "filename">${WRKOBJDIR}</code> is local to every
3400                 architecture. (It should be noted that <code class=
3401                 "varname">PKGSRCDIR</code> should not be set by the
3402                 user &#8212; it is an internal definition which
3403                 refers to the root of the pkgsrc tree. It is
3404                 possible to have many pkgsrc tree instances.)</p>
3405               </li>
3406
3407               <li>
3408                 <p><code class="varname">LOCALPATCHES</code>:
3409                 Directory for local patches that aren't part of
3410                 pkgsrc. See <a href="#components.patches" title=
3411                 "8.3.&nbsp;patches/*">Section&nbsp;8.3,
3412                 &#8220;patches/*&#8221;</a> for more information.
3413                 <em class="replaceable"><code>rel</code></em> and
3414                 <em class="replaceable"><code>arch</code></em> are
3415                 replaced with OS release (&#8220;<span class=
3416                 "quote">2.0</span>&#8221;, etc.) and architecture
3417                 (&#8220;<span class="quote">mipsel</span>&#8221;,
3418                 etc.).</p>
3419               </li>
3420
3421               <li>
3422                 <p><code class="varname">PKGMAKECONF</code>:
3423                 Location of the <code xmlns=
3424                 "http://www.w3.org/TR/xhtml1/transitional" class=
3425                 "filename">mk.conf</code> file used by a package's
3426                 BSD-style Makefile. If this is not set,
3427                 <code class="varname">MAKECONF</code> is set to
3428                 <code xmlns=
3429                 "http://www.w3.org/TR/xhtml1/transitional" class=
3430                 "filename">/dev/null</code> to avoid picking up
3431                 settings used by builds in <code xmlns=
3432                 "http://www.w3.org/TR/xhtml1/transitional" class=
3433                 "filename">/usr/src</code>.</p>
3434               </li>
3435             </ul>
3436           </div>
3437         </div>
3438
3439         <div class="sect1" lang="en" xml:lang="en">
3440           <div class="titlepage">
3441             <div>
3442               <div>
3443                 <h2 class="title" style="clear: both"><a name=
3444                 "developer-advanced-settings" id=
3445                 "developer-advanced-settings"></a>5.3.&nbsp;Developer/advanced
3446                 settings</h2>
3447               </div>
3448             </div>
3449           </div>
3450
3451           <p>XXX</p>
3452
3453           <div class="itemizedlist">
3454             <ul type="disc">
3455               <li>
3456                 <p><code class="varname">PKG_DEVELOPER</code>: Run
3457                 some sanity checks that package developers
3458                 want:</p>
3459
3460                 <div class="itemizedlist">
3461                   <ul type="circle">
3462                     <li>
3463                       <p>make sure patches apply with zero fuzz</p>
3464                     </li>
3465
3466                     <li>
3467                       <p>run check-shlibs to see that all binaries
3468                       will find their shared libs.</p>
3469                     </li>
3470                   </ul>
3471                 </div>
3472               </li>
3473
3474               <li>
3475                 <p><code class="varname">PKG_DEBUG_LEVEL</code>:
3476                 The level of debugging output which is displayed
3477                 whilst making and installing the package. The
3478                 default value for this is 0, which will not display
3479                 the commands as they are executed (normal, default,
3480                 quiet operation); the value 1 will display all
3481                 shell commands before their invocation, and the
3482                 value 2 will display both the shell commands before
3483                 their invocation, and their actual execution
3484                 progress with <span><strong class="command">set
3485                 -x</strong></span> will be displayed.</p>
3486               </li>
3487             </ul>
3488           </div>
3489         </div>
3490
3491         <div class="sect1" lang="en" xml:lang="en">
3492           <div class="titlepage">
3493             <div>
3494               <div>
3495                 <h2 class="title" style="clear: both"><a name=
3496                 "selecting-build-options" id=
3497                 "selecting-build-options"></a>5.4.&nbsp;Selecting
3498                 Build Options</h2>
3499               </div>
3500             </div>
3501           </div>
3502
3503           <p>Some packages have build time options, usually to
3504           select between different dependencies, enable optional
3505           support for big dependencies or enable experimental
3506           features.</p>
3507
3508           <p>To see which options, if any, a package supports, and
3509           which options are mutually exclusive, run
3510           <span><strong class="command">make
3511           show-options</strong></span>, for example:</p>
3512           <pre class="programlisting">
3513     The following options are supported by this package:
3514     ssl      Enable SSL support.
3515     Exactly one of the following gecko options is required:
3516     firefox  Use firefox as gecko rendering engine.
3517     mozilla  Use mozilla as gecko rendering engine.
3518     At most one of the following database options may be selected:
3519     mysql    Enable support for MySQL database.
3520     pgsql    Enable support for PostgreSQL database.
3521
3522     These options are enabled by default: firefox
3523     These options are currently enabled: mozilla ssl
3524 </pre>
3525
3526           <p>The following variables can be defined in <code xmlns=
3527           "http://www.w3.org/TR/xhtml1/transitional" class=
3528           "filename">/etc/mk.conf</code> to select which options to
3529           enable for a package: <code class=
3530           "varname">PKG_DEFAULT_OPTIONS</code>, which can be used
3531           to select or disable options for all packages that
3532           support them, and <code class=
3533           "varname">PKG_OPTIONS.<em class=
3534           "replaceable"><code>pkgbase</code></em></code>, which can
3535           be used to select or disable options specifically for
3536           package <em class=
3537           "replaceable"><code>pkgbase</code></em>. Options listed
3538           in these variables are selected, options preceded by
3539           &#8220;<span class="quote">-</span>&#8221; are
3540           disabled.</p>
3541
3542           <p>The following settings are consulted in the order
3543           given, and the last setting that selects or disables an
3544           option is used:</p>
3545
3546           <div class="orderedlist">
3547             <ol type="1">
3548               <li>
3549                 <p>the default options as suggested by the package
3550                 maintainer</p>
3551               </li>
3552
3553               <li>
3554                 <p>the options implied by the settings of legacy
3555                 variables (see below)</p>
3556               </li>
3557
3558               <li>
3559                 <p><code class=
3560                 "varname">PKG_DEFAULT_OPTIONS</code></p>
3561               </li>
3562
3563               <li>
3564                 <p><code class="varname">PKG_OPTIONS.<em class=
3565                 "replaceable"><code>pkgbase</code></em></code></p>
3566               </li>
3567             </ol>
3568           </div>
3569
3570           <p>For groups of mutually exclusive options, the last
3571           option selected is used, all others are automatically
3572           disabled. If an option of the group is explicitly
3573           disabled, the previously selected option, if any, is
3574           used. It is an error if no option from a required group
3575           of options is selected, and building the package will
3576           fail.</p>
3577
3578           <p>Before the options framework was introduced, build
3579           options were selected by setting a variable in
3580           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3581           class="filename">/etc/mk.conf</code> for each option. To
3582           ease transition to the options framework for the user,
3583           these legacy variables are converted to the appropriate
3584           options setting automatically. A warning is issued to
3585           prompt the user to update <code xmlns=
3586           "http://www.w3.org/TR/xhtml1/transitional" class=
3587           "filename">/etc/mk.conf</code> to use the options
3588           framework directly. Support for these legacy variables
3589           will be removed eventually.</p>
3590         </div>
3591       </div>
3592
3593       <div class="chapter" lang="en" xml:lang="en">
3594         <div class="titlepage">
3595           <div>
3596             <div>
3597               <h2 class="title"><a name="binary" id=
3598               "binary"></a>Chapter&nbsp;6.&nbsp;Creating binary
3599               packages</h2>
3600             </div>
3601           </div>
3602         </div>
3603
3604         <div class="toc">
3605           <p><b>Table of Contents</b></p>
3606
3607           <dl>
3608             <dt><span class="sect1"><a href=
3609             "#building-a-single-binary-package">6.1. Building a
3610             single binary package</a></span></dt>
3611
3612             <dt><span class="sect1"><a href=
3613             "#settings-for-creationg-of-binary-packages">6.2.
3614             Settings for creation of binary
3615             packages</a></span></dt>
3616
3617             <dt><span class="sect1"><a href="#bulkbuild">6.3. Doing
3618             a bulk build of all packages</a></span></dt>
3619
3620             <dd>
3621               <dl>
3622                 <dt><span class="sect2"><a href=
3623                 "#binary.configuration">6.3.1.
3624                 Configuration</a></span></dt>
3625
3626                 <dt><span class="sect2"><a href=
3627                 "#other-environmental-considerations">6.3.2. Other
3628                 environmental considerations</a></span></dt>
3629
3630                 <dt><span class="sect2"><a href="#operation">6.3.3.
3631                 Operation</a></span></dt>
3632
3633                 <dt><span class="sect2"><a href=
3634                 "#what-it-does">6.3.4. What it does</a></span></dt>
3635
3636                 <dt><span class="sect2"><a href=
3637                 "#disk-space-requirements">6.3.5. Disk space
3638                 requirements</a></span></dt>
3639
3640                 <dt><span class="sect2"><a href=
3641                 "#setting-up-a-sandbox">6.3.6. Setting up a sandbox
3642                 for chrooted builds</a></span></dt>
3643
3644                 <dt><span class="sect2"><a href=
3645                 "#building-a-partial-set">6.3.7. Building a partial
3646                 set of packages</a></span></dt>
3647
3648                 <dt><span class="sect2"><a href=
3649                 "#bulk-upload">6.3.8. Uploading results of a bulk
3650                 build</a></span></dt>
3651               </dl>
3652             </dd>
3653
3654             <dt><span class="sect1"><a href="#creating-cdroms">6.4.
3655             Creating a multiple CD-ROM packages
3656             collection</a></span></dt>
3657
3658             <dd>
3659               <dl>
3660                 <dt><span class="sect2"><a href=
3661                 "#cdpack-example">6.4.1. Example of
3662                 cdpack</a></span></dt>
3663               </dl>
3664             </dd>
3665           </dl>
3666         </div>
3667
3668         <div class="sect1" lang="en" xml:lang="en">
3669           <div class="titlepage">
3670             <div>
3671               <div>
3672                 <h2 class="title" style="clear: both"><a name=
3673                 "building-a-single-binary-package" id=
3674                 "building-a-single-binary-package"></a>6.1.&nbsp;Building
3675                 a single binary package</h2>
3676               </div>
3677             </div>
3678           </div>
3679
3680           <p>Once you have built and installed a package, you can
3681           create a <span class="emphasis"><em>binary
3682           package</em></span> which can be installed on another
3683           system with <a href=
3684           "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
3685           <span class="citerefentry"><span class=
3686           "refentrytitle">pkg_add</span>(1)</span></a>. This saves
3687           having to build the same package on a group of hosts and
3688           wasting CPU time. It also provides a simple means for
3689           others to install your package, should you distribute
3690           it.</p>
3691
3692           <p>To create a binary package, change into the
3693           appropriate directory in pkgsrc, and run
3694           <span><strong class="command">make
3695           package</strong></span>:</p>
3696           <pre class="screen">
3697 <code class="prompt">#</code> <strong class=
3698 "userinput"><code>cd misc/figlet</code></strong>
3699 <code class="prompt">#</code> <strong class=
3700 "userinput"><code>make package</code></strong>
3701 </pre>
3702
3703           <p>This will build and install your package (if not
3704           already done), and then build a binary package from what
3705           was installed. You can then use the <span><strong class=
3706           "command">pkg_*</strong></span> tools to manipulate it.
3707           Binary packages are created by default in <code xmlns=
3708           "http://www.w3.org/TR/xhtml1/transitional" class=
3709           "filename">/usr/pkgsrc/packages</code>, in the form of a
3710           gzipped tar file. See <a href="#logs.package" title=
3711           "B.2.&nbsp;Packaging figlet">Section B.2,
3712           &#8220;Packaging figlet&#8221;</a> for a continuation of
3713           the above <a xmlns=
3714           "http://www.w3.org/TR/xhtml1/transitional" href=
3715           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/misc/figlet/README.html"
3716           target="_top"><code xmlns="" class=
3717           "filename">misc/figlet</code></a> example.</p>
3718
3719           <p>See <a href="#submit" title=
3720           "Chapter&nbsp;17.&nbsp;Submitting and Committing">Chapter
3721           17, <i>Submitting and Committing</i></a> for information
3722           on how to submit such a binary package.</p>
3723         </div>
3724
3725         <div class="sect1" lang="en" xml:lang="en">
3726           <div class="titlepage">
3727             <div>
3728               <div>
3729                 <h2 class="title" style="clear: both"><a name=
3730                 "settings-for-creationg-of-binary-packages" id=
3731                 "settings-for-creationg-of-binary-packages"></a>6.2.&nbsp;Settings
3732                 for creation of binary packages</h2>
3733               </div>
3734             </div>
3735           </div>
3736
3737           <p>See <a href="#build.helpful-targets" title=
3738           "14.3.&nbsp;Other helpful targets">Section&nbsp;14.3,
3739           &#8220;Other helpful targets&#8221;</a>.</p>
3740         </div>
3741
3742         <div class="sect1" lang="en" xml:lang="en">
3743           <div class="titlepage">
3744             <div>
3745               <div>
3746                 <h2 class="title" style="clear: both"><a name=
3747                 "bulkbuild" id="bulkbuild"></a>6.3.&nbsp;Doing a
3748                 bulk build of all packages</h2>
3749               </div>
3750             </div>
3751           </div>
3752
3753           <p>If you want to get a full set of precompiled binary
3754           packages, this section describes how to get them. Beware
3755           that the bulk build will remove all currently installed
3756           packages from your system! Having an FTP server
3757           configured either on the machine doing the bulk builds or
3758           on a nearby NFS server can help to make the packages
3759           available to everyone. See <a href=
3760           "http://netbsd.gw.com/cgi-bin/man-cgi?ftpd+8+NetBSD-current">
3761           <span class="citerefentry"><span class=
3762           "refentrytitle">ftpd</span>(8)</span></a> for more
3763           information. If you use a remote NFS server's storage, be
3764           sure to not actually compile on NFS storage, as this
3765           slows things down a lot.</p>
3766
3767           <div class="sect2" lang="en" xml:lang="en">
3768             <div class="titlepage">
3769               <div>
3770                 <div>
3771                   <h3 class="title"><a name="binary.configuration"
3772                   id=
3773                   "binary.configuration"></a>6.3.1.&nbsp;Configuration</h3>
3774                 </div>
3775               </div>
3776             </div>
3777
3778             <div class="sect3" lang="en" xml:lang="en">
3779               <div class="titlepage">
3780                 <div>
3781                   <div>
3782                     <h4 class="title"><a name="binary.mk.conf" id=
3783                     "binary.mk.conf"></a>6.3.1.1.&nbsp;/etc/mk.conf</h4>
3784                   </div>
3785                 </div>
3786               </div>
3787
3788               <p>You may want to set variables in <code xmlns=
3789               "http://www.w3.org/TR/xhtml1/transitional" class=
3790               "filename">/etc/mk.conf</code>. Look at <code xmlns=
3791               "http://www.w3.org/TR/xhtml1/transitional" class=
3792               "filename">pkgsrc/mk/defaults/mk.conf</code> for
3793               details of the default settings. You will want to
3794               ensure that <code class=
3795               "varname">ACCEPTABLE_LICENSES</code> meet your local
3796               policy. As used in this example, <code class=
3797               "varname">_ACCEPTABLE=yes</code> accepts <span class=
3798               "emphasis"><em>all</em></span> licenses.</p>
3799               <pre class="programlisting">
3800     PACKAGES?=      ${_PKGSRCDIR}/packages/${MACHINE_ARCH}
3801     WRKOBJDIR?=     /usr/tmp/pkgsrc   # build here instead of in pkgsrc
3802     BSDSRCDIR=      /usr/src
3803     BSDXSRCDIR=     /usr/xsrc         # for x11/xservers
3804     OBJHOSTNAME?=   yes               # use work.`hostname`
3805     FAILOVER_FETCH= yes               # insist on the correct checksum
3806     PKG_DEVELOPER?= yes
3807     _ACCEPTABLE=    yes
3808 </pre>
3809             </div>
3810
3811             <div class="sect3" lang="en" xml:lang="en">
3812               <div class="titlepage">
3813                 <div>
3814                   <div>
3815                     <h4 class="title"><a name="build.conf" id=
3816                     "build.conf"></a>6.3.1.2.&nbsp;<code xmlns=
3817                     "http://www.w3.org/TR/xhtml1/transitional"
3818                     class="filename">build.conf</code></h4>
3819                   </div>
3820                 </div>
3821               </div>
3822
3823               <p>In <code xmlns=
3824               "http://www.w3.org/TR/xhtml1/transitional" class=
3825               "filename">pkgsrc/mk/bulk</code>, copy <code xmlns=
3826               "http://www.w3.org/TR/xhtml1/transitional" class=
3827               "filename">build.conf-example</code> to <code xmlns=
3828               "http://www.w3.org/TR/xhtml1/transitional" class=
3829               "filename">build.conf</code> and edit it, following
3830               the comments in that file. This is the config file
3831               that determines where log files are generated after
3832               the build, where to mail the build report to, where
3833               your pkgsrc tree is located and the user to which
3834               user to <a href=
3835               "http://netbsd.gw.com/cgi-bin/man-cgi?su+8+NetBSD-current">
3836               <span class="citerefentry"><span class=
3837               "refentrytitle">su</span>(8)</span></a> to do a
3838               <span><strong class="command">cvs
3839               update</strong></span>.</p>
3840             </div>
3841
3842             <div class="sect3" lang="en" xml:lang="en">
3843               <div class="titlepage">
3844                 <div>
3845                   <div>
3846                     <h4 class="title"><a name="pre-build.local" id=
3847                     "pre-build.local"></a>6.3.1.3.&nbsp;<code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3848                     class="filename">pre-build.local</code></h4>
3849                   </div>
3850                 </div>
3851               </div>
3852
3853               <p>It is possible to configure the bulk build to
3854               perform certain site-specific tasks at the end of the
3855               pre-build stage. If the file <code xmlns=
3856               "http://www.w3.org/TR/xhtml1/transitional" class=
3857               "filename">pre-build.local</code> exists in
3858               <code xmlns=
3859               "http://www.w3.org/TR/xhtml1/transitional" class=
3860               "filename">/usr/pkgsrc/mk/bulk</code>, it will be
3861               executed (as a <a href=
3862               "http://netbsd.gw.com/cgi-bin/man-cgi?sh+1+NetBSD-current">
3863               <span class="citerefentry"><span class=
3864               "refentrytitle">sh</span>(1)</span></a> script) at
3865               the end of the usual pre-build stage. An example use
3866               of <code xmlns=
3867               "http://www.w3.org/TR/xhtml1/transitional" class=
3868               "filename">pre-build.local</code> is to have the
3869               line:</p>
3870               <pre class="screen">
3871 <code class="prompt">#</code> <strong class=
3872 "userinput"><code>echo "I do not have enough disk space to build this pig." \
3873     &gt; pkgsrc/misc/openoffice/$BROKENF</code></strong>
3874 </pre>
3875
3876               <p>to prevent the system from trying to build a
3877               particular package which requires nearly 3 GB of disk
3878               space.</p>
3879             </div>
3880           </div>
3881
3882           <div class="sect2" lang="en" xml:lang="en">
3883             <div class="titlepage">
3884               <div>
3885                 <div>
3886                   <h3 class="title"><a name=
3887                   "other-environmental-considerations" id=
3888                   "other-environmental-considerations"></a>6.3.2.&nbsp;Other
3889                   environmental considerations</h3>
3890                 </div>
3891               </div>
3892             </div>
3893
3894             <p>As <code xmlns=
3895             "http://www.w3.org/TR/xhtml1/transitional" class=
3896             "filename">/usr/pkg</code> will be completely deleted
3897             at the start of bulk builds, make sure your login shell
3898             is placed somewhere else. Either drop it into
3899             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3900             class="filename">/usr/local/bin</code> (and adjust your
3901             login shell in the passwd file), or (re-)install it via
3902             <a href=
3903             "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
3904             <span class="citerefentry"><span class=
3905             "refentrytitle">pkg_add</span>(1)</span></a> from
3906             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3907             class="filename">/etc/rc.local</code>, so you can login
3908             after a reboot (remember that your current process
3909             won't die if the package is removed, you just can't
3910             start any new instances of the shell any more). Also,
3911             if you use NetBSD earlier than 1.5, or you still want
3912             to use the pkgsrc version of ssh for some reason, be
3913             sure to install ssh before starting it from
3914             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3915             class="filename">rc.local</code>:</p>
3916             <pre class="programlisting">
3917     ( cd /usr/pkgsrc/security/ssh ; make bulk-install )
3918     if [ -f /usr/pkg/etc/rc.d/sshd ]; then
3919         /usr/pkg/etc/rc.d/sshd
3920     fi
3921 </pre>
3922
3923             <p>Not doing so will result in you being not able to
3924             log in via ssh after the bulk build is finished or if
3925             the machine gets rebooted or crashes. You have been
3926             warned! :)</p>
3927           </div>
3928
3929           <div class="sect2" lang="en" xml:lang="en">
3930             <div class="titlepage">
3931               <div>
3932                 <div>
3933                   <h3 class="title"><a name="operation" id=
3934                   "operation"></a>6.3.3.&nbsp;Operation</h3>
3935                 </div>
3936               </div>
3937             </div>
3938
3939             <p>Make sure you don't need any of the packages still
3940             installed.</p>
3941
3942             <div class="warning" style=
3943             "margin-left: 0.5in; margin-right: 0.5in;">
3944               <h3 class="title">Warning</h3>
3945
3946               <p>During the bulk build, <span class=
3947               "emphasis"><em>all packages will be
3948               removed!</em></span></p>
3949             </div>
3950
3951             <p>Be sure to remove all other things that might
3952             interfere with builds, like some libs installed in
3953             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3954             class="filename">/usr/local</code>, etc. then become
3955             root and type:</p>
3956             <pre class="screen">
3957 <code class="prompt">#</code> <strong class=
3958 "userinput"><code>cd /usr/pkgsrc</code></strong>
3959 <code class="prompt">#</code> <strong class=
3960 "userinput"><code>sh mk/bulk/build</code></strong>
3961 </pre>
3962
3963             <p>If for some reason your last build didn't complete
3964             (power failure, system panic, ...), you can continue it
3965             by running:</p>
3966             <pre class="screen">
3967 <code class="prompt">#</code> <strong class=
3968 "userinput"><code>sh mk/bulk/build restart</code></strong>
3969 </pre>
3970
3971             <p>At the end of the bulk build, you will get a summary
3972             via mail, and find build logs in the directory
3973             specified by <code class="varname">FTP</code> in the
3974             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
3975             class="filename">build.conf</code> file.</p>
3976           </div>
3977
3978           <div class="sect2" lang="en" xml:lang="en">
3979             <div class="titlepage">
3980               <div>
3981                 <div>
3982                   <h3 class="title"><a name="what-it-does" id=
3983                   "what-it-does"></a>6.3.4.&nbsp;What it does</h3>
3984                 </div>
3985               </div>
3986             </div>
3987
3988             <p>The bulk builds consist of three steps:</p>
3989
3990             <div class="variablelist">
3991               <dl>
3992                 <dt><span class="term">1. pre-build</span></dt>
3993
3994                 <dd>
3995                   <p>The script updates your pkgsrc tree via
3996                   (anon)cvs, then cleans out any broken distfiles,
3997                   and removes all packages installed.</p>
3998                 </dd>
3999
4000                 <dt><span class="term">2. the bulk
4001                 build</span></dt>
4002
4003                 <dd>
4004                   <p>This is basically &#8220;<span class=
4005                   "quote">make bulk-package</span>&#8221; with an
4006                   optimised order in which packages will be built.
4007                   Packages that don't require other packages will
4008                   be built first, and packages with many
4009                   dependencies will be built later.</p>
4010                 </dd>
4011
4012                 <dt><span class="term">3. post-build</span></dt>
4013
4014                 <dd>
4015                   <p>Generates a report that's placed in the
4016                   directory specified in the <code xmlns=
4017                   "http://www.w3.org/TR/xhtml1/transitional" class=
4018                   "filename">build.conf</code> file named
4019                   <code xmlns=
4020                   "http://www.w3.org/TR/xhtml1/transitional" class=
4021                   "filename">broken.html</code>, a short version of
4022                   that report will also be mailed to the build's
4023                   admin.</p>
4024                 </dd>
4025               </dl>
4026             </div>
4027
4028             <p>During the build, a list of broken packages will be
4029             compiled in <code xmlns=
4030             "http://www.w3.org/TR/xhtml1/transitional" class=
4031             "filename">/usr/pkgsrc/.broken</code> (or <code xmlns=
4032             "http://www.w3.org/TR/xhtml1/transitional" class=
4033             "filename">.../.broken.${MACHINE}</code> if
4034             <code class="varname">OBJMACHINE</code> is set),
4035             individual build logs of broken builds can be found in
4036             the package's directory. These files are used by the
4037             bulk-targets to mark broken builds to not waste time
4038             trying to rebuild them, and they can be used to debug
4039             these broken package builds later.</p>
4040           </div>
4041
4042           <div class="sect2" lang="en" xml:lang="en">
4043             <div class="titlepage">
4044               <div>
4045                 <div>
4046                   <h3 class="title"><a name=
4047                   "disk-space-requirements" id=
4048                   "disk-space-requirements"></a>6.3.5.&nbsp;Disk
4049                   space requirements</h3>
4050                 </div>
4051               </div>
4052             </div>
4053
4054             <p>Currently, roughly the following requirements are
4055             valid for NetBSD 2.0/i386:</p>
4056
4057             <div class="itemizedlist">
4058               <ul type="disc">
4059                 <li>
4060                   <p>10 GB - distfiles (NFS ok)</p>
4061                 </li>
4062
4063                 <li>
4064                   <p>8 GB - full set of all binaries (NFS ok)</p>
4065                 </li>
4066
4067                 <li>
4068                   <p>5 GB - temp space for compiling (local disk
4069                   recommended)</p>
4070                 </li>
4071               </ul>
4072             </div>
4073
4074             <p>Note that all pkgs will be de-installed as soon as
4075             they are turned into a binary package, and that sources
4076             are removed, so there is no excessively huge demand to
4077             disk space. Afterwards, if the package is needed again,
4078             it will be installed via <a href=
4079             "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
4080             <span class="citerefentry"><span class=
4081             "refentrytitle">pkg_add</span>(1)</span></a> instead of
4082             building again, so there are no cycles wasted by
4083             recompiling.</p>
4084           </div>
4085
4086           <div class="sect2" lang="en" xml:lang="en">
4087             <div class="titlepage">
4088               <div>
4089                 <div>
4090                   <h3 class="title"><a name="setting-up-a-sandbox"
4091                   id="setting-up-a-sandbox"></a>6.3.6.&nbsp;Setting
4092                   up a sandbox for chrooted builds</h3>
4093                 </div>
4094               </div>
4095             </div>
4096
4097             <p>If you don't want all the packages nuked from a
4098             machine (rendering it useless for anything but pkg
4099             compiling), there is the possibility of doing the
4100             package bulk build inside a chroot environment.</p>
4101
4102             <p>The first step is to set up a chroot sandbox, e.g.
4103             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
4104             class="filename">/usr/sandbox</code>. This can be done
4105             by using null mounts, or manually.</p>
4106
4107             <p>There is a shell script called <code xmlns=
4108             "http://www.w3.org/TR/xhtml1/transitional" class=
4109             "filename">pkgsrc/mk/bulk/mksandbox</code> which will
4110             set up the sandbox environment using null mounts. It
4111             will also create a script called <code xmlns=
4112             "http://www.w3.org/TR/xhtml1/transitional" class=
4113             "filename">sandbox</code> in the root of the sandbox
4114             environment, which will allow the null mounts to be
4115             activated using the <span><strong class=
4116             "command">sandbox mount</strong></span> command and
4117             deactivated using the <span><strong class=
4118             "command">sandbox umount</strong></span> command.</p>
4119
4120             <p>To set up a sandbox environment by hand, after
4121             extracting all the sets from a NetBSD installation or
4122             doing a <span><strong class="command">make distribution
4123             DESTDIR=/usr/sandbox</strong></span> in <code xmlns=
4124             "http://www.w3.org/TR/xhtml1/transitional" class=
4125             "filename">/usr/src/etc</code>, be sure the following
4126             items are present and properly configured:</p>
4127
4128             <div class="procedure">
4129               <ol type="1">
4130                 <li>
4131                   <p>Kernel</p>
4132                   <pre class="screen">
4133 <code class="prompt">#</code> <strong class=
4134 "userinput"><code>cp /netbsd /usr/sandbox</code></strong>
4135 </pre>
4136                 </li>
4137
4138                 <li>
4139                   <p><code xmlns=
4140                   "http://www.w3.org/TR/xhtml1/transitional" class=
4141                   "filename">/dev/*</code></p>
4142                   <pre class="screen">
4143 <code class="prompt">#</code> <strong class=
4144 "userinput"><code>cd /usr/sandbox/dev ; sh MAKEDEV all</code></strong>
4145 </pre>
4146                 </li>
4147
4148                 <li>
4149                   <p><code xmlns=
4150                   "http://www.w3.org/TR/xhtml1/transitional" class=
4151                   "filename">/etc/resolv.conf</code> (for <a xmlns=
4152                   "http://www.w3.org/TR/xhtml1/transitional" href=
4153                   "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/smtpd/README.html"
4154                   target="_top"><code xmlns="" class=
4155                   "filename">security/smtpd</code></a> and
4156                   mail):</p>
4157                   <pre class="screen">
4158 <code class="prompt">#</code> <strong class=
4159 "userinput"><code>cp /etc/resolv.conf /usr/sandbox/etc</code></strong>
4160 </pre>
4161                 </li>
4162
4163                 <li>
4164                   <p>Working(!) mail config (hostname,
4165                   sendmail.cf):</p>
4166                   <pre class="screen">
4167 <code class="prompt">#</code> <strong class=
4168 "userinput"><code>cp /etc/mail/sendmail.cf /usr/sandbox/etc/mail</code></strong>
4169 </pre>
4170                 </li>
4171
4172                 <li>
4173                   <p><code xmlns=
4174                   "http://www.w3.org/TR/xhtml1/transitional" class=
4175                   "filename">/etc/localtime</code> (for <a xmlns=
4176                   "http://www.w3.org/TR/xhtml1/transitional" href=
4177                   "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/smtpd/README.html"
4178                   target="_top"><code xmlns="" class=
4179                   "filename">security/smtpd</code></a>):</p>
4180                   <pre class="screen">
4181 <code class="prompt">#</code> <strong class=
4182 "userinput"><code>ln -sf /usr/share/zoneinfo/UTC /usr/sandbox/etc/localtime</code></strong>
4183 </pre>
4184                 </li>
4185
4186                 <li>
4187                   <p><code xmlns=
4188                   "http://www.w3.org/TR/xhtml1/transitional" class=
4189                   "filename">/usr/src</code> (system sources, for
4190                   <a xmlns=
4191                   "http://www.w3.org/TR/xhtml1/transitional" href=
4192                   "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/aperture/README.html"
4193                   target="_top"><code xmlns="" class=
4194                   "filename">sysutils/aperture</code></a>,
4195                   <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
4196                   href=
4197                   "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/net/ppp-mppe/README.html"
4198                   target="_top"><code xmlns="" class=
4199                   "filename">net/ppp-mppe</code></a>):</p>
4200                   <pre class="screen">
4201 <code class="prompt">#</code> <strong class=
4202 "userinput"><code>ln -s ../disk1/cvs .</code></strong>
4203 <code class="prompt">#</code> <strong class=
4204 "userinput"><code>ln -s cvs/src-2.0 src</code></strong>
4205 </pre>
4206                 </li>
4207
4208                 <li>
4209                   <p>Create <code xmlns=
4210                   "http://www.w3.org/TR/xhtml1/transitional" class=
4211                   "filename">/var/db/pkg</code> (not part of
4212                   default install):</p>
4213                   <pre class="screen">
4214 <code class="prompt">#</code> <strong class=
4215 "userinput"><code>mkdir /usr/sandbox/var/db/pkg</code></strong>
4216 </pre>
4217                 </li>
4218
4219                 <li>
4220                   <p>Create <code xmlns=
4221                   "http://www.w3.org/TR/xhtml1/transitional" class=
4222                   "filename">/usr/pkg</code> (not part of default
4223                   install):</p>
4224                   <pre class="screen">
4225 <code class="prompt">#</code> <strong class=
4226 "userinput"><code>mkdir /usr/sandbox/usr/pkg</code></strong>
4227 </pre>
4228                 </li>
4229
4230                 <li>
4231                   <p>Checkout pkgsrc via cvs into <code xmlns=
4232                   "http://www.w3.org/TR/xhtml1/transitional" class=
4233                   "filename">/usr/sandbox/usr/pkgsrc</code>:</p>
4234                   <pre class="screen">
4235 <code class="prompt">#</code> <strong class=
4236 "userinput"><code>cd /usr/sandbox/usr</code></strong>
4237 <code class="prompt">#</code> <strong class=
4238 "userinput"><code>cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout -d -P pkgsrc</code></strong>
4239 </pre>
4240
4241                   <p>Do not mount/link this to the copy of your
4242                   pkgsrc tree you do development in, as this will
4243                   likely cause problems!</p>
4244                 </li>
4245
4246                 <li>
4247                   <p>Make <code xmlns=
4248                   "http://www.w3.org/TR/xhtml1/transitional" class=
4249                   "filename">/usr/sandbox/usr/pkgsrc/packages</code>
4250                   and <code xmlns=
4251                   "http://www.w3.org/TR/xhtml1/transitional" class=
4252                   "filename">.../distfiles</code> point somewhere
4253                   appropriate. NFS- and/or nullfs-mounts may come
4254                   in handy!</p>
4255                 </li>
4256
4257                 <li>
4258                   <p>Edit <code xmlns=
4259                   "http://www.w3.org/TR/xhtml1/transitional" class=
4260                   "filename">/etc/mk.conf</code>, see <a href=
4261                   "#binary.mk.conf" title=
4262                   "6.3.1.1.&nbsp;/etc/mk.conf">Section&nbsp;6.3.1.1,
4263                   &#8220;/etc/mk.conf&#8221;</a>.</p>
4264                 </li>
4265
4266                 <li>
4267                   <p>Adjust <code xmlns=
4268                   "http://www.w3.org/TR/xhtml1/transitional" class=
4269                   "filename">mk/bulk/build.conf</code> to suit your
4270                   needs.</p>
4271                 </li>
4272
4273                 <li>
4274                   <p>If you have set <code class=
4275                   "varname">CVS_USER</code> in <code xmlns=
4276                   "http://www.w3.org/TR/xhtml1/transitional" class=
4277                   "filename">build.conf</code>, make sure that
4278                   account exists and can do a <span><strong class=
4279                   "command">cvs ${CVS_FLAGS} update</strong></span>
4280                   properly!</p>
4281                 </li>
4282               </ol>
4283             </div>
4284
4285             <p>When the chroot sandbox is set up, you can start the
4286             build with the following steps:</p>
4287             <pre class="screen">
4288 <code class="prompt">#</code> <strong class=
4289 "userinput"><code>cd /usr/sandbox/usr/pkgsrc</code></strong>
4290 <code class="prompt">#</code> <strong class=
4291 "userinput"><code>sh mk/bulk/do-sandbox-build</code></strong>
4292 </pre>
4293
4294             <p>This will just jump inside the sandbox and start
4295             building. At the end of the build, mail will be sent
4296             with the results of the build. Created binary pkgs will
4297             be in <code xmlns=
4298             "http://www.w3.org/TR/xhtml1/transitional" class=
4299             "filename">/usr/sandbox/usr/pkgsrc/packages</code>
4300             (wherever that points/mounts to/from).</p>
4301           </div>
4302
4303           <div class="sect2" lang="en" xml:lang="en">
4304             <div class="titlepage">
4305               <div>
4306                 <div>
4307                   <h3 class="title"><a name=
4308                   "building-a-partial-set" id=
4309                   "building-a-partial-set"></a>6.3.7.&nbsp;Building
4310                   a partial set of packages</h3>
4311                 </div>
4312               </div>
4313             </div>
4314
4315             <p>In addition to building a complete set of all
4316             packages in pkgsrc, the <code xmlns=
4317             "http://www.w3.org/TR/xhtml1/transitional" class=
4318             "filename">pkgsrc/mk/bulk/build</code> script may be
4319             used to build a subset of the packages contained in
4320             pkgsrc. By setting <code class=
4321             "varname">SPECIFIC_PKGS</code> in <code xmlns=
4322             "http://www.w3.org/TR/xhtml1/transitional" class=
4323             "filename">/etc/mk.conf</code>, the variables</p>
4324
4325             <div class="itemizedlist">
4326               <ul type="disc">
4327                 <li>
4328                   <p>SITE_SPECIFIC_PKGS</p>
4329                 </li>
4330
4331                 <li>
4332                   <p>HOST_SPECIFIC_PKGS</p>
4333                 </li>
4334
4335                 <li>
4336                   <p>GROUP_SPECIFIC_PKGS</p>
4337                 </li>
4338
4339                 <li>
4340                   <p>USER_SPECIFIC_PKGS</p>
4341                 </li>
4342               </ul>
4343             </div>
4344
4345             <p>will define the set of packages which should be
4346             built. The bulk build code will also include any
4347             packages which are needed as dependencies for the
4348             explicitly listed packages.</p>
4349
4350             <p>One use of this is to do a bulk build with
4351             <code class="varname">SPECIFIC_PKGS</code> in a chroot
4352             sandbox periodically to have a complete set of the
4353             binary packages needed for your site available without
4354             the overhead of building extra packages that are not
4355             needed.</p>
4356           </div>
4357
4358           <div class="sect2" lang="en" xml:lang="en">
4359             <div class="titlepage">
4360               <div>
4361                 <div>
4362                   <h3 class="title"><a name="bulk-upload" id=
4363                   "bulk-upload"></a>6.3.8.&nbsp;Uploading results
4364                   of a bulk build</h3>
4365                 </div>
4366               </div>
4367             </div>
4368
4369             <p>This section describes how pkgsrc developers can
4370             upload binary pkgs built by bulk builds to
4371             ftp.NetBSD.org.</p>
4372
4373             <p>If you would like to automatically create checksum
4374             files for the binary packages you intend to upload,
4375             remember to set <code class="varname">MKSUMS=yes</code>
4376             in your <code xmlns=
4377             "http://www.w3.org/TR/xhtml1/transitional" class=
4378             "filename">mk/bulk/build.conf</code>.</p>
4379
4380             <p>If you would like to PGP sign the checksum files
4381             (highly recommended!), remember to set <code class=
4382             "varname">SIGN_AS=username@NetBSD.org</code> in your
4383             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
4384             class="filename">mk/bulk/build.conf</code>. This will
4385             prompt you for your GPG password to sign the files
4386             before uploading everything.</p>
4387
4388             <p>Then, make sure that you have <code class=
4389             "varname">RSYNC_DST</code> set properly in your
4390             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
4391             class="filename">mk/bulk/build.conf</code> file, i.e.
4392             adjust it to something like one of the following:</p>
4393             <pre class="screen">
4394 RSYNC_DST=$CVS_USER@ftp.NetBSD.org:/pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload
4395 </pre>
4396
4397             <p>Please use appropriate values for "pkgsrc-200xQy",
4398             "NetBSD-a.b.c" and "arch" here. If your login on
4399             ftp.NetBSD.org is different from <code class=
4400             "varname">CVS_USER</code>, write your login directly
4401             into the variable, e.g. my local account is "feyrer",
4402             but for my login "hubertf", I use:</p>
4403             <pre class="screen">
4404 RSYNC_DST=hubertf@ftp.NetBSD.org:/pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload
4405 </pre>
4406
4407             <p>A separate <code xmlns=
4408             "http://www.w3.org/TR/xhtml1/transitional" class=
4409             "filename">upload</code> directory is used here to
4410             allow "closing" the directory during upload. To do so,
4411             run the following command on ftp.NetBSD.org next:</p>
4412             <pre class="screen">
4413 nbftp% <strong class=
4414 "userinput"><code>mkdir -p -m 750 /pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload</code></strong>
4415 </pre>
4416
4417             <p>Please note that <code xmlns=
4418             "http://www.w3.org/TR/xhtml1/transitional" class=
4419             "filename">/pub/NetBSD/packages</code> is only
4420             appropriate for packages for the NetBSD operating
4421             system. Binary packages for other operating systems
4422             should go into <code xmlns=
4423             "http://www.w3.org/TR/xhtml1/transitional" class=
4424             "filename">/pub/pkgsrc</code>.</p>
4425
4426             <p>Before uploading the binary pkgs, ssh authentication
4427             needs to be set up. This example shows how to set up
4428             temporary keys for the root account <span class=
4429             "emphasis"><em>inside the sandbox</em></span> (assuming
4430             that no keys should be present there usually):</p>
4431             <pre class="screen">
4432 <code class="prompt">#</code> <strong class=
4433 "userinput"><code>chroot /usr/sandbox</code></strong>
4434 chroot-<code class="prompt">#</code> <strong class=
4435 "userinput"><code>rm $HOME/.ssh/id-dsa*</code></strong>
4436 chroot-<code class="prompt">#</code> <strong class=
4437 "userinput"><code>ssh-keygen -t dsa</code></strong>
4438 chroot-<code class="prompt">#</code> <strong class=
4439 "userinput"><code>cat $HOME/.ssh/id-dsa.pub</code></strong>
4440 </pre>
4441
4442             <p>Now take the output of <code xmlns=
4443             "http://www.w3.org/TR/xhtml1/transitional" class=
4444             "filename">id-dsa.pub</code> and append it to your
4445             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
4446             class="filename">~/.ssh/authorized_keys</code> file on
4447             ftp.NetBSD.org. You can remove the key after the upload
4448             is done!</p>
4449
4450             <p>Next, test if your ssh connection really works:</p>
4451             <pre class="screen">
4452 chroot-<code class="prompt">#</code> <strong class=
4453 "userinput"><code>ssh ftp.NetBSD.org date</code></strong>
4454 </pre>
4455
4456             <p>Use "-l yourNetBSDlogin" here as appropriate!</p>
4457
4458             <p>Now after all this works, you can exit the sandbox
4459             and start the upload:</p>
4460             <pre class="screen">
4461 chroot-<code class="prompt">#</code> <strong class=
4462 "userinput"><code>exit</code></strong>
4463 <code class="prompt">#</code> <strong class=
4464 "userinput"><code>cd /usr/sandbox/usr/pkgsrc</code></strong>
4465 <code class="prompt">#</code> <strong class=
4466 "userinput"><code>sh mk/bulk/do-sandbox-upload</code></strong>
4467 </pre>
4468
4469             <p>The upload process may take quite some time. Use
4470             <a href=
4471             "http://netbsd.gw.com/cgi-bin/man-cgi?ls+1+NetBSD-current">
4472             <span class="citerefentry"><span class=
4473             "refentrytitle">ls</span>(1)</span></a> or <a href=
4474             "http://netbsd.gw.com/cgi-bin/man-cgi?du+1+NetBSD-current">
4475             <span class="citerefentry"><span class=
4476             "refentrytitle">du</span>(1)</span></a> on the FTP
4477             server to monitor progress of the upload. The upload
4478             script will take care of not uploading restricted
4479             packages and putting vulnerable packages into the
4480             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
4481             class="filename">vulnerable</code> subdirectory.</p>
4482
4483             <p>After the upload has ended, first thing is to revoke
4484             ssh access:</p>
4485             <pre class="screen">
4486 nbftp% <strong class=
4487 "userinput"><code>vi ~/.ssh/authorized_keys</code></strong>
4488 Gdd:x!
4489 </pre>
4490
4491             <p>Use whatever is needed to remove the key you've
4492             entered before! Last, move the uploaded packages out of
4493             the <code xmlns=
4494             "http://www.w3.org/TR/xhtml1/transitional" class=
4495             "filename">upload</code> directory to have them
4496             accessible to everyone:</p>
4497             <pre class="screen">
4498 nbftp% <strong class=
4499 "userinput"><code>cd /pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch</code></strong>
4500 nbftp% <strong class=
4501 "userinput"><code>mv upload/* .</code></strong>
4502 nbftp% <strong class="userinput"><code>rmdir upload</code></strong>
4503 nbftp% <strong class="userinput"><code>chmod 755 .</code></strong>
4504 </pre>
4505           </div>
4506         </div>
4507
4508         <div class="sect1" lang="en" xml:lang="en">
4509           <div class="titlepage">
4510             <div>
4511               <div>
4512                 <h2 class="title" style="clear: both"><a name=
4513                 "creating-cdroms" id=
4514                 "creating-cdroms"></a>6.4.&nbsp;Creating a multiple
4515                 CD-ROM packages collection</h2>
4516               </div>
4517             </div>
4518           </div>
4519
4520           <p>After your pkgsrc bulk-build has completed, you may
4521           wish to create a CD-ROM set of the resulting binary
4522           packages to assist in installing packages on other
4523           machines. The <a xmlns=
4524           "http://www.w3.org/TR/xhtml1/transitional" href=
4525           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/cdpack/README.html"
4526           target="_top"><code xmlns="" class=
4527           "filename">pkgtools/cdpack</code></a> package provides a
4528           simple tool for creating the ISO 9660 images.
4529           <span><strong class="command">cdpack</strong></span>
4530           arranges the packages on the CD-ROMs in a way that keeps
4531           all the dependencies for a given package on the same CD
4532           as that package.</p>
4533
4534           <div class="sect2" lang="en" xml:lang="en">
4535             <div class="titlepage">
4536               <div>
4537                 <div>
4538                   <h3 class="title"><a name="cdpack-example" id=
4539                   "cdpack-example"></a>6.4.1.&nbsp;Example of
4540                   cdpack</h3>
4541                 </div>
4542               </div>
4543             </div>
4544
4545             <p>Complete documentation for cdpack is found in the
4546             cdpack(1) man page. The following short example assumes
4547             that the binary packages are left in <code xmlns=
4548             "http://www.w3.org/TR/xhtml1/transitional" class=
4549             "filename">/usr/pkgsrc/packages/All</code> and that
4550             sufficient disk space exists in <code xmlns=
4551             "http://www.w3.org/TR/xhtml1/transitional" class=
4552             "filename">/u2</code> to hold the ISO 9660 images.</p>
4553             <pre class="screen">
4554 <code class="prompt">#</code> <strong class=
4555 "userinput"><code>mkdir /u2/images</code></strong>
4556 <code class="prompt">#</code> <strong class=
4557 "userinput"><code>pkg_add /usr/pkgsrc/packages/All/cdpack</code></strong>
4558 <code class="prompt">#</code> <strong class=
4559 "userinput"><code>cdpack /usr/pkgsrc/packages/All /u2/images</code></strong>
4560 </pre>
4561
4562             <p>If you wish to include a common set of files
4563             (<code xmlns="http://www.w3.org/TR/xhtml1/transitional"
4564             class="filename">COPYRIGHT</code>, <code xmlns=
4565             "http://www.w3.org/TR/xhtml1/transitional" class=
4566             "filename">README</code>, etc.) on each CD in the
4567             collection, then you need to create a directory which
4568             contains these files. e.g.</p>
4569             <pre class="screen">
4570 <code class="prompt">#</code> <strong class=
4571 "userinput"><code>mkdir /tmp/common</code></strong>
4572 <code class="prompt">#</code> <strong class=
4573 "userinput"><code>echo "This is a README" &gt; /tmp/common/README</code></strong>
4574 <code class="prompt">#</code> <strong class=
4575 "userinput"><code>echo "Another file" &gt; /tmp/common/COPYING</code></strong>
4576 <code class="prompt">#</code> <strong class=
4577 "userinput"><code>mkdir /tmp/common/bin</code></strong>
4578 <code class="prompt">#</code> <strong class=
4579 "userinput"><code>echo "#!/bin/sh" &gt; /tmp/common/bin/myscript</code></strong>
4580 <code class="prompt">#</code> <strong class=
4581 "userinput"><code>echo "echo Hello world" &gt;&gt; /tmp/common/bin/myscript</code></strong>
4582 <code class="prompt">#</code> <strong class=
4583 "userinput"><code>chmod 755 /tmp/common/bin/myscript</code></strong>
4584 </pre>
4585
4586             <p>Now create the images:</p>
4587             <pre class="screen">
4588 <code class="prompt">#</code> <strong class=
4589 "userinput"><code>cdpack -x /tmp/common /usr/pkgsrc/packages/All /u2/images</code></strong>
4590 </pre>
4591
4592             <p>Each image will contain <code xmlns=
4593             "http://www.w3.org/TR/xhtml1/transitional" class=
4594             "filename">README</code>, <code xmlns=
4595             "http://www.w3.org/TR/xhtml1/transitional" class=
4596             "filename">COPYING</code>, and <code xmlns=
4597             "http://www.w3.org/TR/xhtml1/transitional" class=
4598             "filename">bin/myscript</code> in their root
4599             directories.</p>
4600           </div>
4601         </div>
4602       </div>
4603
4604       <div class="chapter" lang="en" xml:lang="en">
4605         <div class="titlepage">
4606           <div>
4607             <div>
4608               <h2 class="title"><a name="faq" id=
4609               "faq"></a>Chapter&nbsp;7.&nbsp;Frequently Asked
4610               Questions</h2>
4611             </div>
4612           </div>
4613         </div>
4614
4615         <div class="toc">
4616           <p><b>Table of Contents</b></p>
4617
4618           <dl>
4619             <dt><span class="sect1"><a href=
4620             "#mailing-list-pointers">7.1. Are there any mailing
4621             lists for pkg-related discussion?</a></span></dt>
4622
4623             <dt><span class="sect1"><a href="#pkgviews-docs">7.2.
4624             Where's the pkgviews documentation?</a></span></dt>
4625
4626             <dt><span class="sect1"><a href="#faq-pkgtools">7.3.
4627             Utilities for package management
4628             (pkgtools)</a></span></dt>
4629
4630             <dt><span class="sect1"><a href="#non-root-pkgsrc">7.4.
4631             How to use pkgsrc as non-root</a></span></dt>
4632
4633             <dt><span class="sect1"><a href=
4634             "#resume-transfers">7.5. How to resume transfers when
4635             fetching distfiles?</a></span></dt>
4636
4637             <dt><span class="sect1"><a href=
4638             "#XFree86-from-pkgsrc">7.6. How can I install/use
4639             XFree86 from pkgsrc?</a></span></dt>
4640
4641             <dt><span class="sect1"><a href=
4642             "#x.org-from-pkgsrc">7.7. How can I install/use X.org
4643             from pkgsrc?</a></span></dt>
4644
4645             <dt><span class="sect1"><a href=
4646             "#fetch-behind-firewall">7.8. How to fetch files from
4647             behind a firewall</a></span></dt>
4648
4649             <dt><span class="sect1"><a href="#passive-ftp">7.9. How
4650             do I tell <span><strong class="command">make
4651             fetch</strong></span> to do passive
4652             FTP?</a></span></dt>
4653
4654             <dt><span class="sect1"><a href=
4655             "#fetching-all-distfiles">7.10. How to fetch all
4656             distfiles at once</a></span></dt>
4657
4658             <dt><span class="sect1"><a href=
4659             "#tmac.andoc-missing">7.11. What does
4660             &#8220;<span class="quote">Don't know how to make
4661             /usr/share/tmac/tmac.andoc</span>&#8221;
4662             mean?</a></span></dt>
4663
4664             <dt><span class="sect1"><a href=
4665             "#bsd.own.mk-missing">7.12. What does
4666             &#8220;<span class="quote">Could not find
4667             bsd.own.mk</span>&#8221; mean?</a></span></dt>
4668
4669             <dt><span class="sect1"><a href=
4670             "#using-sudo-with-pkgsrc">7.13. Using 'sudo' with
4671             pkgsrc</a></span></dt>
4672
4673             <dt><span class="sect1"><a href="#faq.conf">7.14. How
4674             do I change the location of configuration
4675             files?</a></span></dt>
4676
4677             <dt><span class="sect1"><a href="#audit-packages">7.15.
4678             Automated security checks</a></span></dt>
4679           </dl>
4680         </div>
4681
4682         <p>This section contains hints, tips &amp; tricks on
4683         special things in pkgsrc that we didn't find a better place
4684         for in the previous chapters, and it contains items for
4685         both pkgsrc users and developers.</p>
4686
4687         <div class="sect1" lang="en" xml:lang="en">
4688           <div class="titlepage">
4689             <div>
4690               <div>
4691                 <h2 class="title" style="clear: both"><a name=
4692                 "mailing-list-pointers" id=
4693                 "mailing-list-pointers"></a>7.1.&nbsp;Are there any
4694                 mailing lists for pkg-related discussion?</h2>
4695               </div>
4696             </div>
4697           </div>
4698
4699           <p>The following mailing lists may be of interest to
4700           pkgsrc users:</p>
4701
4702           <div class="itemizedlist">
4703             <ul type="disc">
4704               <li>
4705                 <p><a href=
4706                 "http://www.NetBSD.org/MailingLists/index.html#pkgsrc-bugs"
4707                 target="_top">pkgsrc-bugs</a>: A list where problem
4708                 reports related to pkgsrc are sent and
4709                 discussed.</p>
4710               </li>
4711
4712               <li>
4713                 <p><a href=
4714                 "http://www.NetBSD.org/MailingLists/index.html#pkgsrc-bulk"
4715                 target="_top">pkgsrc-bulk</a>: A list where the
4716                 results of pkgsrc bulk builds are sent and
4717                 discussed.</p>
4718               </li>
4719
4720               <li>
4721                 <p><a href=
4722                 "http://www.NetBSD.org/MailingLists/index.html#pkgsrc-changes"
4723                 target="_top">pkgsrc-changes</a>: A list where all
4724                 commit messages to pkgsrc are sent.</p>
4725               </li>
4726
4727               <li>
4728                 <p><a href=
4729                 "http://www.NetBSD.org/MailingLists/index.html#tech-pkg"
4730                 target="_top">tech-pkg</a>: A general discussion
4731                 list for all things related to pkgsrc.</p>
4732               </li>
4733             </ul>
4734           </div>
4735
4736           <p>To subscribe, do:</p>
4737           <pre class="programlisting">
4738     <code class="prompt">%</code> echo subscribe <em class=
4739 "replaceable"><code>listname</code></em> | mail majordomo@NetBSD.org
4740 </pre>
4741
4742           <p>Archives for all these mailing lists are available
4743           from <a href="http://mail-index.NetBSD.org/" target=
4744           "_top">http://mail-index.NetBSD.org/</a>.</p>
4745         </div>
4746
4747         <div class="sect1" lang="en" xml:lang="en">
4748           <div class="titlepage">
4749             <div>
4750               <div>
4751                 <h2 class="title" style="clear: both"><a name=
4752                 "pkgviews-docs" id=
4753                 "pkgviews-docs"></a>7.2.&nbsp;Where's the pkgviews
4754                 documentation?</h2>
4755               </div>
4756             </div>
4757           </div>
4758
4759           <p>Pkgviews is tightly integrated with buildlink. You can
4760           find a pkgviews User's guide in <code xmlns=
4761           "http://www.w3.org/TR/xhtml1/transitional" class=
4762           "filename">pkgsrc/mk/buildlink3/PKGVIEWS_UG</code>.</p>
4763         </div>
4764
4765         <div class="sect1" lang="en" xml:lang="en">
4766           <div class="titlepage">
4767             <div>
4768               <div>
4769                 <h2 class="title" style="clear: both"><a name=
4770                 "faq-pkgtools" id=
4771                 "faq-pkgtools"></a>7.3.&nbsp;Utilities for package
4772                 management (pkgtools)</h2>
4773               </div>
4774             </div>
4775           </div>
4776
4777           <p>The <code xmlns=
4778           "http://www.w3.org/TR/xhtml1/transitional" class=
4779           "filename">pkgsrc/pkgtools</code> directory pkgtools
4780           contains a number of useful utilities for both users and
4781           developers of pkgsrc. This section attempts only to make
4782           the reader aware of the utilities and when they might be
4783           useful, and not to duplicate the documentation that comes
4784           with each package.</p>
4785
4786           <p>Utilities used by pkgsrc (automatically installed when
4787           needed):</p>
4788
4789           <div class="itemizedlist">
4790             <ul type="disc">
4791               <li>
4792                 <p><a xmlns=
4793                 "http://www.w3.org/TR/xhtml1/transitional" href=
4794                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/x11-links/README.html"
4795                 target="_top"><code xmlns="" class=
4796                 "filename">pkgtools/x11-links</code></a>: Symlinks
4797                 for use by buildlink.</p>
4798               </li>
4799             </ul>
4800           </div>
4801
4802           <p>OS tool augmentation (automatically installed when
4803           needed):</p>
4804
4805           <div class="itemizedlist">
4806             <ul type="disc">
4807               <li>
4808                 <p><a xmlns=
4809                 "http://www.w3.org/TR/xhtml1/transitional" href=
4810                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/digest/README.html"
4811                 target="_top"><code xmlns="" class=
4812                 "filename">pkgtools/digest</code></a>: Calculates
4813                 various kinds of checksums (including SHA1).</p>
4814               </li>
4815
4816               <li>
4817                 <p><a xmlns=
4818                 "http://www.w3.org/TR/xhtml1/transitional" href=
4819                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/libnbcompat/README.html"
4820                 target="_top"><code xmlns="" class=
4821                 "filename">pkgtools/libnbcompat</code></a>:
4822                 Compatibility library for pkgsrc tools.</p>
4823               </li>
4824
4825               <li>
4826                 <p><a xmlns=
4827                 "http://www.w3.org/TR/xhtml1/transitional" href=
4828                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/mtree/README.html"
4829                 target="_top"><code xmlns="" class=
4830                 "filename">pkgtools/mtree</code></a>: Installed on
4831                 non-BSD systems due to lack of native mtree.</p>
4832               </li>
4833
4834               <li>
4835                 <p><a xmlns=
4836                 "http://www.w3.org/TR/xhtml1/transitional" href=
4837                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_install/README.html"
4838                 target="_top"><code xmlns="" class=
4839                 "filename">pkgtools/pkg_install</code></a>:
4840                 Up-to-date replacement for <code xmlns=
4841                 "http://www.w3.org/TR/xhtml1/transitional" class=
4842                 "filename">/usr/sbin/pkg_install</code>, or for use
4843                 on operating systems where pkg_install is not
4844                 present.</p>
4845               </li>
4846             </ul>
4847           </div>
4848
4849           <p>Utilities used by pkgsrc (not automatically
4850           installed):</p>
4851
4852           <div class="itemizedlist">
4853             <ul type="disc">
4854               <li>
4855                 <p><a xmlns=
4856                 "http://www.w3.org/TR/xhtml1/transitional" href=
4857                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_tarup/README.html"
4858                 target="_top"><code xmlns="" class=
4859                 "filename">pkgtools/pkg_tarup</code></a>: Create a
4860                 binary package from an already-installed package.
4861                 Used by <span><strong class="command">make
4862                 replace</strong></span> to save the old
4863                 package.</p>
4864               </li>
4865
4866               <li>
4867                 <p><a xmlns=
4868                 "http://www.w3.org/TR/xhtml1/transitional" href=
4869                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/dfdisk/README.html"
4870                 target="_top"><code xmlns="" class=
4871                 "filename">pkgtools/dfdisk</code></a>: Adds extra
4872                 functionality to pkgsrc, allowing it to fetch
4873                 distfiles from multiple locations. It currently
4874                 supports the following methods: multiple CD-ROMs
4875                 and network FTP/HTTP connections.</p>
4876               </li>
4877
4878               <li>
4879                 <p><a xmlns=
4880                 "http://www.w3.org/TR/xhtml1/transitional" href=
4881                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/xpkgwedge/README.html"
4882                 target="_top"><code xmlns="" class=
4883                 "filename">pkgtools/xpkgwedge</code></a>: Put X11
4884                 packages someplace else (enabled by default).</p>
4885               </li>
4886
4887               <li>
4888                 <p><a xmlns=
4889                 "http://www.w3.org/TR/xhtml1/transitional" href=
4890                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/cpuflags/README.html"
4891                 target="_top"><code xmlns="" class=
4892                 "filename">devel/cpuflags</code></a>: Determine the
4893                 best compiler flags to optimise code for your
4894                 current CPU and compiler.</p>
4895               </li>
4896             </ul>
4897           </div>
4898
4899           <p>Utilities for keeping track of installed packages,
4900           being up to date, etc:</p>
4901
4902           <div class="itemizedlist">
4903             <ul type="disc">
4904               <li>
4905                 <p><a xmlns=
4906                 "http://www.w3.org/TR/xhtml1/transitional" href=
4907                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_chk/README.html"
4908                 target="_top"><code xmlns="" class=
4909                 "filename">pkgtools/pkg_chk</code></a>: Reports on
4910                 packages whose installed versions do not match the
4911                 latest pkgsrc entries.</p>
4912               </li>
4913
4914               <li>
4915                 <p><a xmlns=
4916                 "http://www.w3.org/TR/xhtml1/transitional" href=
4917                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdep/README.html"
4918                 target="_top"><code xmlns="" class=
4919                 "filename">pkgtools/pkgdep</code></a>: Makes
4920                 dependency graphs of packages, to aid in choosing a
4921                 strategy for updating.</p>
4922               </li>
4923
4924               <li>
4925                 <p><a xmlns=
4926                 "http://www.w3.org/TR/xhtml1/transitional" href=
4927                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdepgraph/README.html"
4928                 target="_top"><code xmlns="" class=
4929                 "filename">pkgtools/pkgdepgraph</code></a>: Makes
4930                 graphs from the output of <a xmlns=
4931                 "http://www.w3.org/TR/xhtml1/transitional" href=
4932                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdep/README.html"
4933                 target="_top"><code xmlns="" class=
4934                 "filename">pkgtools/pkgdep</code></a> (uses
4935                 graphviz).</p>
4936               </li>
4937
4938               <li>
4939                 <p><a xmlns=
4940                 "http://www.w3.org/TR/xhtml1/transitional" href=
4941                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html"
4942                 target="_top"><code xmlns="" class=
4943                 "filename">pkgtools/pkglint</code></a>: The
4944                 pkglint(1) program checks a pkgsrc entry for
4945                 errors, lintpkgsrc(1) does various checks on the
4946                 complete pkgsrc system.</p>
4947               </li>
4948
4949               <li>
4950                 <p><a xmlns=
4951                 "http://www.w3.org/TR/xhtml1/transitional" href=
4952                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgsurvey/README.html"
4953                 target="_top"><code xmlns="" class=
4954                 "filename">pkgtools/pkgsurvey</code></a>: Report
4955                 what packages you have installed.</p>
4956               </li>
4957             </ul>
4958           </div>
4959
4960           <p>Utilities for people maintaining or creating
4961           individual packages:</p>
4962
4963           <div class="itemizedlist">
4964             <ul type="disc">
4965               <li>
4966                 <p><a xmlns=
4967                 "http://www.w3.org/TR/xhtml1/transitional" href=
4968                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdiff/README.html"
4969                 target="_top"><code xmlns="" class=
4970                 "filename">pkgtools/pkgdiff</code></a>: Automate
4971                 making and maintaining patches for a package
4972                 (includes pkgdiff, pkgvi, mkpatches, etc.).</p>
4973               </li>
4974
4975               <li>
4976                 <p><a xmlns=
4977                 "http://www.w3.org/TR/xhtml1/transitional" href=
4978                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/rpm2pkg/README.html"
4979                 target="_top"><code xmlns="" class=
4980                 "filename">pkgtools/rpm2pkg</code></a>, <a xmlns=
4981                 "http://www.w3.org/TR/xhtml1/transitional" href=
4982                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/url2pkg/README.html"
4983                 target="_top"><code xmlns="" class=
4984                 "filename">pkgtools/url2pkg</code></a>: Aids in
4985                 converting to pkgsrc.</p>
4986               </li>
4987
4988               <li>
4989                 <p><a xmlns=
4990                 "http://www.w3.org/TR/xhtml1/transitional" href=
4991                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/gensolpkg/README.html"
4992                 target="_top"><code xmlns="" class=
4993                 "filename">pkgtools/gensolpkg</code></a>: Convert
4994                 pkgsrc to a Solaris package.</p>
4995               </li>
4996             </ul>
4997           </div>
4998
4999           <p>Utilities for people maintaining pkgsrc (or: more
5000           obscure pkg utilities)</p>
5001
5002           <div class="itemizedlist">
5003             <ul type="disc">
5004               <li>
5005                 <p><a xmlns=
5006                 "http://www.w3.org/TR/xhtml1/transitional" href=
5007                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_comp/README.html"
5008                 target="_top"><code xmlns="" class=
5009                 "filename">pkgtools/pkg_comp</code></a>: Build
5010                 packages in a chrooted area.</p>
5011               </li>
5012
5013               <li>
5014                 <p><a xmlns=
5015                 "http://www.w3.org/TR/xhtml1/transitional" href=
5016                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/libkver/README.html"
5017                 target="_top"><code xmlns="" class=
5018                 "filename">pkgtools/libkver</code></a>: Spoof
5019                 kernel version for chrooted cross builds.</p>
5020               </li>
5021             </ul>
5022           </div>
5023         </div>
5024
5025         <div class="sect1" lang="en" xml:lang="en">
5026           <div class="titlepage">
5027             <div>
5028               <div>
5029                 <h2 class="title" style="clear: both"><a name=
5030                 "non-root-pkgsrc" id=
5031                 "non-root-pkgsrc"></a>7.4.&nbsp;How to use pkgsrc
5032                 as non-root</h2>
5033               </div>
5034             </div>
5035           </div>
5036
5037           <p>If you want to use pkgsrc as non-root user, you can
5038           set some variables to make pkgsrc work under these
5039           conditions. At the very least, you need to set
5040           <code class="varname">UNPRIVILEGED</code> to
5041           &#8220;<span class="quote">yes</span>&#8221;; this will
5042           turn on unprivileged mode and set multiple related
5043           variables to allow installation of packages as
5044           non-root.</p>
5045
5046           <p>In case the defaults are not enough, you may want to
5047           tune some other variables used. For example, if the
5048           automatic user/group detection leads to incorrect values
5049           (or not the ones you would like to use), you can change
5050           them by setting <code class=
5051           "varname">UNPRIVILEGED_USER</code> and <code class=
5052           "varname">UNPRIVILEGED_GROUP</code> respectively.</p>
5053
5054           <p>As regards bootstrapping, please note that the
5055           <span><strong class="command">bootstrap</strong></span>
5056           script will ease non-root configuration when given the
5057           &#8220;<span class=
5058           "quote">--ignore-user-check</span>&#8221; flag, as it
5059           will choose and use multiple default directories under
5060           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
5061           class="filename">~/pkg</code> as the installation
5062           targets. These directories can be overriden by the
5063           &#8220;<span class="quote">--prefix</span>&#8221; flag
5064           provided by the script, as well as some others that allow
5065           finer tuning of the tree layout.</p>
5066         </div>
5067
5068         <div class="sect1" lang="en" xml:lang="en">
5069           <div class="titlepage">
5070             <div>
5071               <div>
5072                 <h2 class="title" style="clear: both"><a name=
5073                 "resume-transfers" id=
5074                 "resume-transfers"></a>7.5.&nbsp;How to resume
5075                 transfers when fetching distfiles?</h2>
5076               </div>
5077             </div>
5078           </div>
5079
5080           <p>By default, resuming transfers in pkgsrc is disabled,
5081           but you can enable this feature by adding the option
5082           <code class="varname">PKG_RESUME_TRANSFERS=YES</code>
5083           into <code xmlns=
5084           "http://www.w3.org/TR/xhtml1/transitional" class=
5085           "filename">/etc/mk.conf</code>. If, during a fetch step,
5086           an incomplete distfile is found, pkgsrc will try to
5087           resume it.</p>
5088
5089           <p>You can also use a different program than the default
5090           <a href=
5091           "http://netbsd.gw.com/cgi-bin/man-cgi?ftp+1+NetBSD-current">
5092           <span class="citerefentry"><span class=
5093           "refentrytitle">ftp</span>(1)</span></a> by changing the
5094           <code class="varname">FETCH_CMD</code> variable. Don't
5095           forget to set <code class=
5096           "varname">FETCH_RESUME_ARGS</code> and <code class=
5097           "varname">FETCH_OUTPUT_ARGS</code> if you are not using
5098           default values.</p>
5099
5100           <p>For example, if you want to use <code xmlns=
5101           "http://www.w3.org/TR/xhtml1/transitional" class=
5102           "filename">wget</code> to resume downloads, you'll have
5103           to use something like:</p>
5104           <pre class="programlisting">
5105     FETCH_CMD=             wget
5106     FETCH_BEFORE_ARGS=     --passive-ftp
5107     FETCH_RESUME_ARGS=     -c
5108     FETCH_OUTPUT_ARGS=     -O
5109 </pre>
5110         </div>
5111
5112         <div class="sect1" lang="en" xml:lang="en">
5113           <div class="titlepage">
5114             <div>
5115               <div>
5116                 <h2 class="title" style="clear: both"><a name=
5117                 "XFree86-from-pkgsrc" id=
5118                 "XFree86-from-pkgsrc"></a>7.6.&nbsp;How can I
5119                 install/use XFree86 from pkgsrc?</h2>
5120               </div>
5121             </div>
5122           </div>
5123
5124           <p>If you want to use XFree86 from pkgsrc instead of your
5125           system's own X11 (<code xmlns=
5126           "http://www.w3.org/TR/xhtml1/transitional" class=
5127           "filename">/usr/X11R6</code>, <code xmlns=
5128           "http://www.w3.org/TR/xhtml1/transitional" class=
5129           "filename">/usr/openwin</code>, ...), you will have to
5130           add the following line into <code xmlns=
5131           "http://www.w3.org/TR/xhtml1/transitional" class=
5132           "filename">/etc/mk.conf</code>:</p>
5133           <pre class="programlisting">
5134     X11_TYPE=XFree86
5135 </pre>
5136         </div>
5137
5138         <div class="sect1" lang="en" xml:lang="en">
5139           <div class="titlepage">
5140             <div>
5141               <div>
5142                 <h2 class="title" style="clear: both"><a name=
5143                 "x.org-from-pkgsrc" id=
5144                 "x.org-from-pkgsrc"></a>7.7.&nbsp;How can I
5145                 install/use X.org from pkgsrc?</h2>
5146               </div>
5147             </div>
5148           </div>
5149
5150           <p>If you want to use X.org from pkgsrc instead of your
5151           system's own X11 (<code xmlns=
5152           "http://www.w3.org/TR/xhtml1/transitional" class=
5153           "filename">/usr/X11R6</code>, <code xmlns=
5154           "http://www.w3.org/TR/xhtml1/transitional" class=
5155           "filename">/usr/openwin</code>, ...) you will have to add
5156           the following line into <code xmlns=
5157           "http://www.w3.org/TR/xhtml1/transitional" class=
5158           "filename">/etc/mk.conf</code>:</p>
5159           <pre class="programlisting">
5160     X11_TYPE=xorg
5161 </pre>
5162         </div>
5163
5164         <div class="sect1" lang="en" xml:lang="en">
5165           <div class="titlepage">
5166             <div>
5167               <div>
5168                 <h2 class="title" style="clear: both"><a name=
5169                 "fetch-behind-firewall" id=
5170                 "fetch-behind-firewall"></a>7.8.&nbsp;How to fetch
5171                 files from behind a firewall</h2>
5172               </div>
5173             </div>
5174           </div>
5175
5176           <p>If you are sitting behind a firewall which does not
5177           allow direct connections to Internet hosts (i.e.
5178           non-NAT), you may specify the relevant proxy hosts. This
5179           is done using an environment variable in the form of a
5180           URL, e.g. in Amdahl, the machine &#8220;<span class=
5181           "quote">orpheus.amdahl.com</span>&#8221; is one of the
5182           firewalls, and it uses port 80 as the proxy port number.
5183           So the proxy environment variables are:</p>
5184           <pre class="programlisting">
5185     ftp_proxy=ftp://orpheus.amdahl.com:80/
5186     http_proxy=http://orpheus.amdahl.com:80/
5187 </pre>
5188         </div>
5189
5190         <div class="sect1" lang="en" xml:lang="en">
5191           <div class="titlepage">
5192             <div>
5193               <div>
5194                 <h2 class="title" style="clear: both"><a name=
5195                 "passive-ftp" id="passive-ftp"></a>7.9.&nbsp;How do
5196                 I tell <span><strong class="command">make
5197                 fetch</strong></span> to do passive FTP?</h2>
5198               </div>
5199             </div>
5200           </div>
5201
5202           <p>This depends on which utility is used to retrieve
5203           distfiles. From <code xmlns=
5204           "http://www.w3.org/TR/xhtml1/transitional" class=
5205           "filename">bsd.pkg.mk</code>, <code class=
5206           "varname">FETCH_CMD</code> is assigned the first
5207           available command from the following list:</p>
5208
5209           <div class="itemizedlist">
5210             <ul type="disc">
5211               <li>
5212                 <p><code xmlns=
5213                 "http://www.w3.org/TR/xhtml1/transitional" class=
5214                 "filename">${LOCALBASE}/bin/ftp</code></p>
5215               </li>
5216
5217               <li>
5218                 <p><code xmlns=
5219                 "http://www.w3.org/TR/xhtml1/transitional" class=
5220                 "filename">/usr/bin/ftp</code></p>
5221               </li>
5222             </ul>
5223           </div>
5224
5225           <p>On a default NetBSD installation, this will be
5226           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
5227           class="filename">/usr/bin/ftp</code>, which automatically
5228           tries passive connections first, and falls back to active
5229           connections if the server refuses to do passive. For the
5230           other tools, add the following to your <code xmlns=
5231           "http://www.w3.org/TR/xhtml1/transitional" class=
5232           "filename">/etc/mk.conf</code> file: <code class=
5233           "varname">PASSIVE_FETCH=1</code>.</p>
5234
5235           <p>Having that option present will prevent <code xmlns=
5236           "http://www.w3.org/TR/xhtml1/transitional" class=
5237           "filename">/usr/bin/ftp</code> from falling back to
5238           active transfers.</p>
5239         </div>
5240
5241         <div class="sect1" lang="en" xml:lang="en">
5242           <div class="titlepage">
5243             <div>
5244               <div>
5245                 <h2 class="title" style="clear: both"><a name=
5246                 "fetching-all-distfiles" id=
5247                 "fetching-all-distfiles"></a>7.10.&nbsp;How to
5248                 fetch all distfiles at once</h2>
5249               </div>
5250             </div>
5251           </div>
5252
5253           <p>You would like to download all the distfiles in a
5254           single batch from work or university, where you can't run
5255           a <span><strong class="command">make
5256           fetch</strong></span>. There is an archive of distfiles
5257           on <a href=
5258           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/"
5259           target="_top">ftp.NetBSD.org</a>, but downloading the
5260           entire directory may not be appropriate.</p>
5261
5262           <p>The answer here is to do a <span><strong class=
5263           "command">make fetch-list</strong></span> in <code xmlns=
5264           "http://www.w3.org/TR/xhtml1/transitional" class=
5265           "filename">/usr/pkgsrc</code> or one of its
5266           subdirectories, carry the resulting list to your machine
5267           at work/school and use it there. If you don't have a
5268           NetBSD-compatible <a href=
5269           "http://netbsd.gw.com/cgi-bin/man-cgi?ftp+1+NetBSD-current">
5270           <span class="citerefentry"><span class=
5271           "refentrytitle">ftp</span>(1)</span></a> (like lukemftp)
5272           at work, don't forget to set <code class=
5273           "varname">FETCH_CMD</code> to something that fetches a
5274           URL:</p>
5275
5276           <p>At home:</p>
5277           <pre class="screen">
5278 <code class="prompt">%</code> <strong class=
5279 "userinput"><code>cd /usr/pkgsrc</code></strong>
5280 <code class="prompt">%</code> <strong class=
5281 "userinput"><code>make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles &gt;/tmp/fetch.sh</code></strong>
5282 <code class="prompt">%</code> <strong class=
5283 "userinput"><code>scp /tmp/fetch.sh work:/tmp</code></strong>
5284 </pre>
5285
5286           <p>At work:</p>
5287           <pre class="screen">
5288 <code class="prompt">%</code> <strong class=
5289 "userinput"><code>sh /tmp/fetch.sh</code></strong>
5290 </pre>
5291
5292           <p>then tar up <code xmlns=
5293           "http://www.w3.org/TR/xhtml1/transitional" class=
5294           "filename">/tmp/distfiles</code> and take it home.</p>
5295
5296           <p>If you have a machine running NetBSD, and you want to
5297           get <span class="emphasis"><em>all</em></span> distfiles
5298           (even ones that aren't for your machine architecture),
5299           you can do so by using the above-mentioned
5300           <span><strong class="command">make
5301           fetch-list</strong></span> approach, or fetch the
5302           distfiles directly by running:</p>
5303           <pre class="screen">
5304 <code class="prompt">%</code> <strong class=
5305 "userinput"><code>make mirror-distfiles</code></strong>
5306 </pre>
5307
5308           <p>If you even decide to ignore <code class=
5309           "varname">NO_{SRC,BIN}_ON_{FTP,CDROM}</code>, then you
5310           can get everything by running:</p>
5311           <pre class="screen">
5312 <code class="prompt">%</code> <strong class=
5313 "userinput"><code>make fetch NO_SKIP=yes</code></strong>
5314 </pre>
5315         </div>
5316
5317         <div class="sect1" lang="en" xml:lang="en">
5318           <div class="titlepage">
5319             <div>
5320               <div>
5321                 <h2 class="title" style="clear: both"><a name=
5322                 "tmac.andoc-missing" id=
5323                 "tmac.andoc-missing"></a>7.11.&nbsp;What does
5324                 &#8220;<span class="quote">Don't know how to make
5325                 /usr/share/tmac/tmac.andoc</span>&#8221; mean?</h2>
5326               </div>
5327             </div>
5328           </div>
5329
5330           <p>When compiling the <a xmlns=
5331           "http://www.w3.org/TR/xhtml1/transitional" href=
5332           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_install/README.html"
5333           target="_top"><code xmlns="" class=
5334           "filename">pkgtools/pkg_install</code></a> package, you
5335           get the error from make that it doesn't know how to make
5336           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
5337           class="filename">/usr/share/tmac/tmac.andoc</code>? This
5338           indicates that you don't have installed the
5339           &#8220;<span class="quote">text</span>&#8221; set (nroff,
5340           ...) from the NetBSD base distribution on your machine.
5341           It is recommended to do that to format man pages.</p>
5342
5343           <p>In the case of the <a xmlns=
5344           "http://www.w3.org/TR/xhtml1/transitional" href=
5345           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_install/README.html"
5346           target="_top"><code xmlns="" class=
5347           "filename">pkgtools/pkg_install</code></a> package, you
5348           can get away with setting <code class=
5349           "varname">NOMAN=YES</code> either in the environment or
5350           in <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
5351           class="filename">/etc/mk.conf</code>.</p>
5352         </div>
5353
5354         <div class="sect1" lang="en" xml:lang="en">
5355           <div class="titlepage">
5356             <div>
5357               <div>
5358                 <h2 class="title" style="clear: both"><a name=
5359                 "bsd.own.mk-missing" id=
5360                 "bsd.own.mk-missing"></a>7.12.&nbsp;What does
5361                 &#8220;<span class="quote">Could not find
5362                 bsd.own.mk</span>&#8221; mean?</h2>
5363               </div>
5364             </div>
5365           </div>
5366
5367           <p>You didn't install the compiler set, <code xmlns=
5368           "http://www.w3.org/TR/xhtml1/transitional" class=
5369           "filename">comp.tgz</code>, when you installed your
5370           NetBSD machine. Please get and install it, by extracting
5371           it in <code xmlns=
5372           "http://www.w3.org/TR/xhtml1/transitional" class=
5373           "filename">/</code>:</p>
5374           <pre class="screen">
5375 <code class="prompt">#</code> <strong class=
5376 "userinput"><code>cd /</code></strong>
5377 <code class="prompt">#</code> <strong class=
5378 "userinput"><code>tar --unlink -zxvpf .../comp.tgz</code></strong>
5379 </pre>
5380
5381           <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional"
5382           class="filename">comp.tgz</code> is part of every NetBSD
5383           release. Get the one that corresponds to your release
5384           (determine via <span><strong class="command">uname
5385           -r</strong></span>).</p>
5386         </div>
5387
5388         <div class="sect1" lang="en" xml:lang="en">
5389           <div class="titlepage">
5390             <div>
5391               <div>
5392                 <h2 class="title" style="clear: both"><a name=
5393                 "using-sudo-with-pkgsrc" id=
5394                 "using-sudo-with-pkgsrc"></a>7.13.&nbsp;Using
5395                 'sudo' with pkgsrc</h2>
5396               </div>
5397             </div>
5398           </div>
5399
5400           <p>When installing packages as non-root user and using
5401           the just-in-time <a href=
5402           "http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-current">
5403           <span class="citerefentry"><span class=
5404           "refentrytitle">su</span>(1)</span></a> feature of
5405           pkgsrc, it can become annoying to type in the root
5406           password for each required package installed. To avoid
5407           this, the sudo package can be used, which does password
5408           caching over a limited time. To use it, install sudo
5409           (either as binary package or from <a xmlns=
5410           "http://www.w3.org/TR/xhtml1/transitional" href=
5411           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/sudo/README.html"
5412           target="_top"><code xmlns="" class=
5413           "filename">security/sudo</code></a>) and then put the
5414           following into your <code xmlns=
5415           "http://www.w3.org/TR/xhtml1/transitional" class=
5416           "filename">/etc/mk.conf</code>:</p>
5417           <pre class="programlisting">
5418     .if exists(${LOCALBASE}/bin/sudo)
5419     SU_CMD=        ${LOCALBASE}/bin/sudo /bin/sh -c
5420     .endif
5421 </pre>
5422         </div>
5423
5424         <div class="sect1" lang="en" xml:lang="en">
5425           <div class="titlepage">
5426             <div>
5427               <div>
5428                 <h2 class="title" style="clear: both"><a name=
5429                 "faq.conf" id="faq.conf"></a>7.14.&nbsp;How do I
5430                 change the location of configuration files?</h2>
5431               </div>
5432             </div>
5433           </div>
5434
5435           <p>As the system administrator, you can choose where
5436           configuration files are installed. The default settings
5437           make all these files go into <code xmlns=
5438           "http://www.w3.org/TR/xhtml1/transitional" class=
5439           "filename">${PREFIX}/etc</code> or some of its
5440           subdirectories; this may be suboptimal depending on your
5441           expectations (e.g., a read-only, NFS-exported
5442           <code class="varname">PREFIX</code> with a need of
5443           per-machine configuration of the provided packages).</p>
5444
5445           <p>In order to change the defaults, you can modify the
5446           <code class="varname">PKG_SYSCONFBASE</code> variable (in
5447           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
5448           class="filename">/etc/mk.conf</code>) to point to your
5449           preferred configuration directory; some common examples
5450           include <code xmlns=
5451           "http://www.w3.org/TR/xhtml1/transitional" class=
5452           "filename">/etc</code> or <code xmlns=
5453           "http://www.w3.org/TR/xhtml1/transitional" class=
5454           "filename">/etc/pkg</code>.</p>
5455
5456           <p>Furthermore, you can change this value on a
5457           per-package basis by setting the <code class=
5458           "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>
5459           variable. <code class="varname">PKG_SYSCONFVAR</code>'s
5460           value usually matches the name of the package you would
5461           like to modify, that is, the contents of <code class=
5462           "varname">PKGBASE</code>.</p>
5463
5464           <p>Note that after changing these settings, you must
5465           rebuild and reinstall any affected packages.</p>
5466         </div>
5467
5468         <div class="sect1" lang="en" xml:lang="en">
5469           <div class="titlepage">
5470             <div>
5471               <div>
5472                 <h2 class="title" style="clear: both"><a name=
5473                 "audit-packages" id=
5474                 "audit-packages"></a>7.15.&nbsp;Automated security
5475                 checks</h2>
5476               </div>
5477             </div>
5478           </div>
5479
5480           <p>Please be aware that there can often be bugs in
5481           third-party software, and some of these bugs can leave a
5482           machine vulnerable to exploitation by attackers. In an
5483           effort to lessen the exposure, the NetBSD packages team
5484           maintains a database of known-exploits to packages which
5485           have at one time been included in pkgsrc. The database
5486           can be downloaded automatically, and a security audit of
5487           all packages installed on a system can take place. To do
5488           this, install the <a xmlns=
5489           "http://www.w3.org/TR/xhtml1/transitional" href=
5490           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"
5491           target="_top"><code xmlns="" class=
5492           "filename">security/audit-packages</code></a> package. It
5493           has two components:</p>
5494
5495           <div class="orderedlist">
5496             <ol type="1">
5497               <li>
5498                 <p><span><strong class=
5499                 "command">download-vulnerability-list</strong></span>,
5500                 an easy way to download a list of the security
5501                 vulnerabilities information. This list is kept up
5502                 to date by the NetBSD security officer and the
5503                 NetBSD packages team, and is distributed from the
5504                 NetBSD ftp server:</p>
5505
5506                 <p><a href=
5507                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities"
5508                 target=
5509                 "_top">ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities</a></p>
5510               </li>
5511
5512               <li>
5513                 <p><span><strong class=
5514                 "command">audit-packages</strong></span>, an easy
5515                 way to audit the current machine, checking each
5516                 vulnerability which is known. If a vulnerable
5517                 package is installed, it will be shown by output to
5518                 stdout, including a description of the type of
5519                 vulnerability, and a URL containing more
5520                 information.</p>
5521               </li>
5522             </ol>
5523           </div>
5524
5525           <p>Use of the <a xmlns=
5526           "http://www.w3.org/TR/xhtml1/transitional" href=
5527           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"
5528           target="_top"><code xmlns="" class=
5529           "filename">security/audit-packages</code></a> package is
5530           strongly recommended! After &#8220;<span class=
5531           "quote">audit-packages</span>&#8221; is installed, please
5532           read the package's message, which you can get by running
5533           <strong class="userinput"><code>pkg_info -D
5534           audit-package</code></strong>.</p>
5535         </div>
5536       </div>
5537     </div>
5538
5539     <div class="part" lang="en" xml:lang="en">
5540       <div class="titlepage">
5541         <div>
5542           <div>
5543             <h1 class="title"><a name="developers-guide" id=
5544             "developers-guide"></a>Part&nbsp;II.&nbsp;The pkgsrc
5545             developer's guide</h1>
5546           </div>
5547         </div>
5548       </div>
5549
5550       <div class="toc">
5551         <p><b>Table of Contents</b></p>
5552
5553         <dl>
5554           <dt><span class="chapter"><a href="#components">8.
5555           Package components - files, directories and
5556           contents</a></span></dt>
5557
5558           <dd>
5559             <dl>
5560               <dt><span class="sect1"><a href=
5561               "#components.Makefile">8.1. <code xmlns=
5562               "http://www.w3.org/TR/xhtml1/transitional" class=
5563               "filename">Makefile</code></a></span></dt>
5564
5565               <dt><span class="sect1"><a href=
5566               "#components.distinfo">8.2. <code xmlns=
5567               "http://www.w3.org/TR/xhtml1/transitional" class=
5568               "filename">distinfo</code></a></span></dt>
5569
5570               <dt><span class="sect1"><a href=
5571               "#components.patches">8.3. patches/*</a></span></dt>
5572
5573               <dt><span class="sect1"><a href=
5574               "#other-mandatory-files">8.4. Other mandatory
5575               files</a></span></dt>
5576
5577               <dt><span class="sect1"><a href=
5578               "#components.optional">8.5. Optional
5579               files</a></span></dt>
5580
5581               <dt><span class="sect1"><a href="#work-dir">8.6.
5582               <code xmlns=
5583               "http://www.w3.org/TR/xhtml1/transitional" class=
5584               "filename">work*</code></a></span></dt>
5585
5586               <dt><span class="sect1"><a href="#files-dir">8.7.
5587               <code xmlns=
5588               "http://www.w3.org/TR/xhtml1/transitional" class=
5589               "filename">files/*</code></a></span></dt>
5590             </dl>
5591           </dd>
5592
5593           <dt><span class="chapter"><a href="#makefile">9.
5594           Programming in <code xmlns=
5595           "http://www.w3.org/TR/xhtml1/transitional" class=
5596           "filename">Makefile</code>s</a></span></dt>
5597
5598           <dd>
5599             <dl>
5600               <dt><span class="sect1"><a href=
5601               "#makefile.variables">9.1. <code xmlns=
5602               "http://www.w3.org/TR/xhtml1/transitional" class=
5603               "filename">Makefile</code> variables</a></span></dt>
5604
5605               <dd>
5606                 <dl>
5607                   <dt><span class="sect2"><a href=
5608                   "#makefile.variables.names">9.1.1. Naming
5609                   conventions</a></span></dt>
5610                 </dl>
5611               </dd>
5612
5613               <dt><span class="sect1"><a href="#makefile.code">9.2.
5614               Code snippets</a></span></dt>
5615
5616               <dd>
5617                 <dl>
5618                   <dt><span class="sect2"><a href=
5619                   "#adding-to-list">9.2.1. Adding things to a
5620                   list</a></span></dt>
5621
5622                   <dt><span class="sect2"><a href=
5623                   "#converting-internal-to-external">9.2.2.
5624                   Converting an internal list into an external
5625                   list</a></span></dt>
5626
5627                   <dt><span class="sect2"><a href=
5628                   "#passing-variable-to-shell">9.2.3. Passing
5629                   variables to a shell command</a></span></dt>
5630
5631                   <dt><span class="sect2"><a href=
5632                   "#quoting-guideline">9.2.4. Quoting
5633                   guideline</a></span></dt>
5634
5635                   <dt><span class="sect2"><a href=
5636                   "#bsd-make-bug-workaround">9.2.5. Workaround for
5637                   a bug in BSD Make</a></span></dt>
5638                 </dl>
5639               </dd>
5640             </dl>
5641           </dd>
5642
5643           <dt><span class="chapter"><a href="#plist">10. PLIST
5644           issues</a></span></dt>
5645
5646           <dd>
5647             <dl>
5648               <dt><span class="sect1"><a href="#rcs-id">10.1. RCS
5649               ID</a></span></dt>
5650
5651               <dt><span class="sect1"><a href=
5652               "#automatic-plist-generation">10.2. Semi-automatic
5653               <code xmlns=
5654               "http://www.w3.org/TR/xhtml1/transitional" class=
5655               "filename">PLIST</code> generation</a></span></dt>
5656
5657               <dt><span class="sect1"><a href="#print-PLIST">10.3.
5658               Tweaking output of <span><strong class="command">make
5659               print-PLIST</strong></span></a></span></dt>
5660
5661               <dt><span class="sect1"><a href="#plist.misc">10.4.
5662               Variable substitution in PLIST</a></span></dt>
5663
5664               <dt><span class="sect1"><a href=
5665               "#manpage-compression">10.5. Man page
5666               compression</a></span></dt>
5667
5668               <dt><span class="sect1"><a href=
5669               "#using-PLIST_SRC">10.6. Changing PLIST source with
5670               <code class=
5671               "varname">PLIST_SRC</code></a></span></dt>
5672
5673               <dt><span class="sect1"><a href=
5674               "#platform-specific-plist">10.7. Platform-specific
5675               and differing PLISTs</a></span></dt>
5676
5677               <dt><span class="sect1"><a href=
5678               "#faq.common-dirs">10.8. Sharing directories between
5679               packages</a></span></dt>
5680             </dl>
5681           </dd>
5682
5683           <dt><span class="chapter"><a href="#buildlink">11.
5684           Buildlink methodology</a></span></dt>
5685
5686           <dd>
5687             <dl>
5688               <dt><span class="sect1"><a href=
5689               "#converting-to-buildlink3">11.1. Converting packages
5690               to use buildlink3</a></span></dt>
5691
5692               <dt><span class="sect1"><a href=
5693               "#creating-buildlink3.mk">11.2. Writing <code xmlns=
5694               "http://www.w3.org/TR/xhtml1/transitional" class=
5695               "filename">buildlink3.mk</code> files</a></span></dt>
5696
5697               <dd>
5698                 <dl>
5699                   <dt><span class="sect2"><a href=
5700                   "#anatomy-of-bl3">11.2.1. Anatomy of a
5701                   buildlink3.mk file</a></span></dt>
5702
5703                   <dt><span class="sect2"><a href=
5704                   "#updating-buildlink-depends">11.2.2. Updating
5705                   <code class=
5706                   "varname">BUILDLINK_DEPENDS.<em class="replaceable">
5707                   <code>pkg</code></em></code> in <code xmlns=
5708                   "http://www.w3.org/TR/xhtml1/transitional" class=
5709                   "filename">buildlink3.mk</code>
5710                   files</a></span></dt>
5711                 </dl>
5712               </dd>
5713
5714               <dt><span class="sect1"><a href=
5715               "#writing-builtin.mk">11.3. Writing <code xmlns=
5716               "http://www.w3.org/TR/xhtml1/transitional" class=
5717               "filename">builtin.mk</code> files</a></span></dt>
5718
5719               <dd>
5720                 <dl>
5721                   <dt><span class="sect2"><a href=
5722                   "#anatomy-of-builtin.mk">11.3.1. Anatomy of a
5723                   <code xmlns=
5724                   "http://www.w3.org/TR/xhtml1/transitional" class=
5725                   "filename">builtin.mk</code> file</a></span></dt>
5726
5727                   <dt><span class="sect2"><a href=
5728                   "#native-or-pkgsrc-preference">11.3.2. Global
5729                   preferences for native or pkgsrc
5730                   software</a></span></dt>
5731                 </dl>
5732               </dd>
5733             </dl>
5734           </dd>
5735
5736           <dt><span class="chapter"><a href="#pkginstall">12. The
5737           pkginstall framework</a></span></dt>
5738
5739           <dd>
5740             <dl>
5741               <dt><span class="sect1"><a href=
5742               "#files-and-dirs-outside-prefix">12.1. Files and
5743               directories outside the installation
5744               prefix</a></span></dt>
5745
5746               <dd>
5747                 <dl>
5748                   <dt><span class="sect2"><a href=
5749                   "#dirs-outside-prefix">12.1.1. Directory
5750                   manipulation</a></span></dt>
5751
5752                   <dt><span class="sect2"><a href=
5753                   "#files-outside-prefix">12.1.2. File
5754                   manipulation</a></span></dt>
5755                 </dl>
5756               </dd>
5757
5758               <dt><span class="sect1"><a href="#conf-files">12.2.
5759               Configuration files</a></span></dt>
5760
5761               <dd>
5762                 <dl>
5763                   <dt><span class="sect2"><a href=
5764                   "#conf-files-sysconfdir">12.2.1. How <code class=
5765                   "varname">PKG_SYSCONFDIR</code> is
5766                   set</a></span></dt>
5767
5768                   <dt><span class="sect2"><a href=
5769                   "#conf-files-configure">12.2.2. Telling the
5770                   software where configuration files
5771                   are</a></span></dt>
5772
5773                   <dt><span class="sect2"><a href=
5774                   "#conf-files-patching">12.2.3. Patching
5775                   installations</a></span></dt>
5776
5777                   <dt><span class="sect2"><a href=
5778                   "#conf-files-disable">12.2.4. Disabling handling
5779                   of configuration files</a></span></dt>
5780                 </dl>
5781               </dd>
5782
5783               <dt><span class="sect1"><a href="#rcd-scripts">12.3.
5784               System startup scripts</a></span></dt>
5785
5786               <dd>
5787                 <dl>
5788                   <dt><span class="sect2"><a href=
5789                   "#rcd-scripts-disable">12.3.1. Disabling handling
5790                   of system startup scripts</a></span></dt>
5791                 </dl>
5792               </dd>
5793
5794               <dt><span class="sect1"><a href=
5795               "#users-and-groups">12.4. System users and
5796               groups</a></span></dt>
5797
5798               <dt><span class="sect1"><a href="#shells">12.5.
5799               System shells</a></span></dt>
5800
5801               <dd>
5802                 <dl>
5803                   <dt><span class="sect2"><a href=
5804                   "#shells-disable">12.5.1. Disabling handling of
5805                   configuration files</a></span></dt>
5806                 </dl>
5807               </dd>
5808             </dl>
5809           </dd>
5810
5811           <dt><span class="chapter"><a href="#options">13. Options
5812           handling</a></span></dt>
5813
5814           <dd>
5815             <dl>
5816               <dt><span class="sect1"><a href=
5817               "#global-default-options">13.1. Global default
5818               options</a></span></dt>
5819
5820               <dt><span class="sect1"><a href=
5821               "#converting-to-options">13.2. Converting packages to
5822               use <code xmlns=
5823               "http://www.w3.org/TR/xhtml1/transitional" class=
5824               "filename">bsd.options.mk</code></a></span></dt>
5825
5826               <dt><span class="sect1"><a href="#option-names">13.3.
5827               Option Names</a></span></dt>
5828             </dl>
5829           </dd>
5830
5831           <dt><span class="chapter"><a href="#build">14. The build
5832           process</a></span></dt>
5833
5834           <dd>
5835             <dl>
5836               <dt><span class="sect1"><a href="#build.prefix">14.1.
5837               Program location</a></span></dt>
5838
5839               <dt><span class="sect1"><a href="#main-targets">14.2.
5840               Main targets</a></span></dt>
5841
5842               <dt><span class="sect1"><a href=
5843               "#build.helpful-targets">14.3. Other helpful
5844               targets</a></span></dt>
5845             </dl>
5846           </dd>
5847
5848           <dt><span class="chapter"><a href="#fixes">15. Notes on
5849           fixes for packages</a></span></dt>
5850
5851           <dd>
5852             <dl>
5853               <dt><span class="sect1"><a href=
5854               "#general-operation">15.1. General
5855               operation</a></span></dt>
5856
5857               <dd>
5858                 <dl>
5859                   <dt><span class="sect2"><a href=
5860                   "#pulling-vars-from-etc-mk.conf">15.1.1. How to
5861                   pull in variables from
5862                   /etc/mk.conf</a></span></dt>
5863
5864                   <dt><span class="sect2"><a href=
5865                   "#where-to-install-documentation">15.1.2. Where
5866                   to install documentation</a></span></dt>
5867
5868                   <dt><span class="sect2"><a href=
5869                   "#restricted-packages">15.1.3. Restricted
5870                   packages</a></span></dt>
5871
5872                   <dt><span class="sect2"><a href=
5873                   "#dependencies">15.1.4. Handling
5874                   dependencies</a></span></dt>
5875
5876                   <dt><span class="sect2"><a href=
5877                   "#conflicts">15.1.5. Handling conflicts with
5878                   other packages</a></span></dt>
5879
5880                   <dt><span class="sect2"><a href=
5881                   "#not-building-packages">15.1.6. Packages that
5882                   cannot or should not be built</a></span></dt>
5883
5884                   <dt><span class="sect2"><a href=
5885                   "#undeletable-packages">15.1.7. Packages which
5886                   should not be deleted, once
5887                   installed</a></span></dt>
5888
5889                   <dt><span class="sect2"><a href=
5890                   "#security-handling">15.1.8. Handling packages
5891                   with security problems</a></span></dt>
5892
5893                   <dt><span class="sect2"><a href=
5894                   "#compiler-bugs">15.1.9. How to handle compiler
5895                   bugs</a></span></dt>
5896
5897                   <dt><span class="sect2"><a href=
5898                   "#bumping-pkgrevision">15.1.10. How to handle
5899                   incrementing versions when fixing an existing
5900                   package</a></span></dt>
5901
5902                   <dt><span class="sect2"><a href=
5903                   "#portability-of-packages">15.1.11. Portability
5904                   of packages</a></span></dt>
5905                 </dl>
5906               </dd>
5907
5908               <dt><span class="sect1"><a href=
5909               "#downloading-issues">15.2. Possible downloading
5910               issues</a></span></dt>
5911
5912               <dd>
5913                 <dl>
5914                   <dt><span class="sect2"><a href=
5915                   "#no-plain-download">15.2.1. Packages whose
5916                   distfiles aren't available for plain
5917                   downloading</a></span></dt>
5918
5919                   <dt><span class="sect2"><a href=
5920                   "#modified-distfiles-same-name">15.2.2. How to
5921                   handle modified distfiles with the 'old'
5922                   name</a></span></dt>
5923                 </dl>
5924               </dd>
5925
5926               <dt><span class="sect1"><a href=
5927               "#configuration-gotchas">15.3. Configuration
5928               gotchas</a></span></dt>
5929
5930               <dd>
5931                 <dl>
5932                   <dt><span class="sect2"><a href=
5933                   "#fixes.libtool">15.3.1. Shared libraries -
5934                   libtool</a></span></dt>
5935
5936                   <dt><span class="sect2"><a href=
5937                   "#using-libtool">15.3.2. Using libtool on GNU
5938                   packages that already support
5939                   libtool</a></span></dt>
5940
5941                   <dt><span class="sect2"><a href=
5942                   "#autoconf-automake">15.3.3. GNU
5943                   Autoconf/Automake</a></span></dt>
5944                 </dl>
5945               </dd>
5946
5947               <dt><span class="sect1"><a href=
5948               "#building-considerations">15.4. Building
5949               considerations</a></span></dt>
5950
5951               <dd>
5952                 <dl>
5953                   <dt><span class="sect2"><a href=
5954                   "#cpp-defines">15.4.1. CPP
5955                   defines</a></span></dt>
5956
5957                   <dt><span class="sect2"><a href=
5958                   "#cpp-list">15.4.2. Getting a list of CPP
5959                   defines</a></span></dt>
5960                 </dl>
5961               </dd>
5962
5963               <dt><span class="sect1"><a href=
5964               "#package-specific-actions">15.5. Package specific
5965               actions</a></span></dt>
5966
5967               <dd>
5968                 <dl>
5969                   <dt><span class="sect2"><a href=
5970                   "#user-interaction">15.5.1. User
5971                   interaction</a></span></dt>
5972
5973                   <dt><span class="sect2"><a href=
5974                   "#handling-licenses">15.5.2. Handling
5975                   licenses</a></span></dt>
5976
5977                   <dt><span class="sect2"><a href=
5978                   "#installing-score-files">15.5.3. Installing
5979                   score files</a></span></dt>
5980
5981                   <dt><span class="sect2"><a href=
5982                   "#perl-scripts">15.5.4. Packages containing perl
5983                   scripts</a></span></dt>
5984
5985                   <dt><span class="sect2"><a href=
5986                   "#hardcoded-paths">15.5.5. Packages with
5987                   hardcoded paths to other
5988                   interpreters</a></span></dt>
5989
5990                   <dt><span class="sect2"><a href=
5991                   "#perl-modules">15.5.6. Packages installing perl
5992                   modules</a></span></dt>
5993
5994                   <dt><span class="sect2"><a href=
5995                   "#faq.info-files">15.5.7. Packages installing
5996                   info files</a></span></dt>
5997
5998                   <dt><span class="sect2"><a href=
5999                   "#gconf2-data-files">15.5.8. Packages installing
6000                   GConf2 data files</a></span></dt>
6001
6002                   <dt><span class="sect2"><a href=
6003                   "#scrollkeeper-data-files">15.5.9. Packages
6004                   installing scrollkeeper data
6005                   files</a></span></dt>
6006
6007                   <dt><span class="sect2"><a href=
6008                   "#x11-fonts">15.5.10. Packages installing X11
6009                   fonts</a></span></dt>
6010
6011                   <dt><span class="sect2"><a href=
6012                   "#gtk2-modules">15.5.11. Packages installing GTK2
6013                   modules</a></span></dt>
6014
6015                   <dt><span class="sect2"><a href=
6016                   "#sgml-xml-data">15.5.12. Packages installing
6017                   SGML or XML data</a></span></dt>
6018
6019                   <dt><span class="sect2"><a href=
6020                   "#mime-database">15.5.13. Packages installing
6021                   extensions to the MIME database</a></span></dt>
6022
6023                   <dt><span class="sect2"><a href=
6024                   "#intltool">15.5.14. Packages using
6025                   intltool</a></span></dt>
6026
6027                   <dt><span class="sect2"><a href=
6028                   "#startup-scripts">15.5.15. Packages installing
6029                   startup scripts</a></span></dt>
6030                 </dl>
6031               </dd>
6032
6033               <dt><span class="sect1"><a href=
6034               "#feedback-to-author">15.6. Feedback to the
6035               author</a></span></dt>
6036             </dl>
6037           </dd>
6038
6039           <dt><span class="chapter"><a href="#debug">16.
6040           Debugging</a></span></dt>
6041
6042           <dt><span class="chapter"><a href="#submit">17.
6043           Submitting and Committing</a></span></dt>
6044
6045           <dd>
6046             <dl>
6047               <dt><span class="sect1"><a href=
6048               "#submitting-your-package">17.1. Submitting your
6049               packages</a></span></dt>
6050
6051               <dt><span class="sect1"><a href=
6052               "#general-notes-for-changes">17.2. General notes when
6053               adding, updating, or removing
6054               packages</a></span></dt>
6055
6056               <dt><span class="sect1"><a href=
6057               "#committing-importing">17.3. Committing: Importing a
6058               package into CVS</a></span></dt>
6059
6060               <dt><span class="sect1"><a href=
6061               "#updating-package">17.4. Updating a package to a
6062               newer version</a></span></dt>
6063
6064               <dt><span class="sect1"><a href=
6065               "#moving-package">17.5. Moving a package in
6066               pkgsrc</a></span></dt>
6067             </dl>
6068           </dd>
6069         </dl>
6070       </div>
6071
6072       <div class="chapter" lang="en" xml:lang="en">
6073         <div class="titlepage">
6074           <div>
6075             <div>
6076               <h2 class="title"><a name="components" id=
6077               "components"></a>Chapter&nbsp;8.&nbsp;Package
6078               components - files, directories and contents</h2>
6079             </div>
6080           </div>
6081         </div>
6082
6083         <div class="toc">
6084           <p><b>Table of Contents</b></p>
6085
6086           <dl>
6087             <dt><span class="sect1"><a href=
6088             "#components.Makefile">8.1. <code xmlns=
6089             "http://www.w3.org/TR/xhtml1/transitional" class=
6090             "filename">Makefile</code></a></span></dt>
6091
6092             <dt><span class="sect1"><a href=
6093             "#components.distinfo">8.2. <code xmlns=
6094             "http://www.w3.org/TR/xhtml1/transitional" class=
6095             "filename">distinfo</code></a></span></dt>
6096
6097             <dt><span class="sect1"><a href=
6098             "#components.patches">8.3. patches/*</a></span></dt>
6099
6100             <dt><span class="sect1"><a href=
6101             "#other-mandatory-files">8.4. Other mandatory
6102             files</a></span></dt>
6103
6104             <dt><span class="sect1"><a href=
6105             "#components.optional">8.5. Optional
6106             files</a></span></dt>
6107
6108             <dt><span class="sect1"><a href="#work-dir">8.6.
6109             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
6110             class="filename">work*</code></a></span></dt>
6111
6112             <dt><span class="sect1"><a href="#files-dir">8.7.
6113             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
6114             class="filename">files/*</code></a></span></dt>
6115           </dl>
6116         </div>
6117
6118         <p>Whenever you're preparing a package, there are a number
6119         of files involved which are described in the following
6120         sections.</p>
6121
6122         <div class="sect1" lang="en" xml:lang="en">
6123           <div class="titlepage">
6124             <div>
6125               <div>
6126                 <h2 class="title" style="clear: both"><a name=
6127                 "components.Makefile" id=
6128                 "components.Makefile"></a>8.1.&nbsp;<code xmlns=
6129                 "http://www.w3.org/TR/xhtml1/transitional" class=
6130                 "filename">Makefile</code></h2>
6131               </div>
6132             </div>
6133           </div>
6134
6135           <p>Building, installation and creation of a binary
6136           package are all controlled by the package's <code xmlns=
6137           "http://www.w3.org/TR/xhtml1/transitional" class=
6138           "filename">Makefile</code>. The <code xmlns=
6139           "http://www.w3.org/TR/xhtml1/transitional" class=
6140           "filename">Makefile</code> describes various things about
6141           a package, for example from where to get it, how to
6142           configure, build, and install it.</p>
6143
6144           <p>A package <code xmlns=
6145           "http://www.w3.org/TR/xhtml1/transitional" class=
6146           "filename">Makefile</code> contains several sections that
6147           describe the package.</p>
6148
6149           <p>In the first section there are the following
6150           variables, which should appear exactly in the order given
6151           here.</p>
6152
6153           <div class="itemizedlist">
6154             <ul type="disc">
6155               <li>
6156                 <p><code class="varname">DISTNAME</code> is the
6157                 basename of the distribution file to be downloaded
6158                 from the package's website.</p>
6159               </li>
6160
6161               <li>
6162                 <p><code class="varname">PKGNAME</code> is the name
6163                 of the package, as used by pkgsrc. You only need to
6164                 provide it if it differs from <code class=
6165                 "varname">DISTNAME</code>. Usually it is the
6166                 directory name together with the version number. It
6167                 must match the regular expression <code class=
6168                 "varname">^[A-Za-z0-9][A-Za-z0-9-_.+]*$</code>,
6169                 that is, it starts with a letter or digit, and
6170                 contains only letters, digits, dashes, underscores,
6171                 dots and plus signs.</p>
6172               </li>
6173
6174               <li>
6175                 <p><code class="varname">CATEGORIES</code> is a
6176                 list of categories which the package fits in. You
6177                 can choose any of the top-level directories of
6178                 pkgsrc for it.</p>
6179
6180                 <p>Currently the following values are available for
6181                 <code class="varname">CATEGORIES</code>. If more
6182                 than one is used, they need to be separated by
6183                 spaces:</p>
6184                 <pre class="programlisting">
6185     archivers     cross         geography     meta-pkgs     security
6186     audio         databases     graphics      misc          shells
6187     benchmarks    devel         ham           multimedia    sysutils
6188     biology       editors       inputmethod   net           textproc
6189     cad           emulators     lang          news          time
6190     chat          finance       mail          parallel      wm
6191     comms         fonts         math          pkgtools      www
6192     converters    games         mbone         print         x11
6193 </pre>
6194               </li>
6195
6196               <li>
6197                 <p><code class="varname">MASTER_SITES</code> is a
6198                 list of URLs where the distribution files can be
6199                 downloaded. Each URL must end with a slash.</p>
6200
6201                 <p>The <code class="varname">MASTER_SITES</code>
6202                 may make use of the following predefined sites:</p>
6203                 <pre class="programlisting">
6204     ${MASTER_SITE_APACHE}
6205     ${MASTER_SITE_BACKUP}
6206     ${MASTER_SITE_CYGWIN}
6207     ${MASTER_SITE_DEBIAN}
6208     ${MASTER_SITE_FREEBSD}
6209     ${MASTER_SITE_FREEBSD_LOCAL}
6210     ${MASTER_SITE_GNOME}
6211     ${MASTER_SITE_GNU}
6212     ${MASTER_SITE_GNUSTEP}
6213     ${MASTER_SITE_IFARCHIVE}
6214     ${MASTER_SITE_MOZILLA}
6215     ${MASTER_SITE_OPENOFFICE}
6216     ${MASTER_SITE_PERL_CPAN}
6217     ${MASTER_SITE_R_CRAN}
6218     ${MASTER_SITE_SOURCEFORGE}
6219     ${MASTER_SITE_SUNSITE}
6220     ${MASTER_SITE_SUSE}
6221     ${MASTER_SITE_TEX_CTAN}
6222     ${MASTER_SITE_XCONTRIB}
6223     ${MASTER_SITE_XEMACS}
6224 </pre>
6225
6226                 <p>If one of these predefined sites is chosen, you
6227                 may want to specify a subdirectory of that site.
6228                 Since these macros may expand to more than one
6229                 actual site, you <span class=
6230                 "emphasis"><em>must</em></span> use the following
6231                 construct to specify a subdirectory:</p>
6232                 <pre class="programlisting">
6233     ${MASTER_SITE_GNU:=subdirectory/name/}
6234     ${MASTER_SITE_SOURCEFORGE:=project_name/}
6235 </pre>
6236
6237                 <p>Note the trailing slash after the subdirectory
6238                 name.</p>
6239
6240                 <p>If the package has multiple <code class=
6241                 "varname">DISTFILES</code> or multiple <code class=
6242                 "varname">PATCHFILES</code> from different sites,
6243                 set <code class="varname">SITES_foo</code> to a
6244                 list of URIs where file &#8220;<span class=
6245                 "quote">foo</span>&#8221; may be found.
6246                 &#8220;<span class="quote">foo</span>&#8221;
6247                 includes the suffix, e.g.:</p>
6248                 <pre class="programlisting">
6249     DISTFILES=      ${DISTNAME}${EXTRACT_SUFX}
6250     DISTFILES+=     foo-file.tar.gz
6251     SITES_foo-file.tar.gz=http://www.somewhere.com/somehow/ \
6252             http://www.somewhereelse.com/mirror/somehow/
6253 </pre>
6254               </li>
6255
6256               <li>
6257                 <p><code class="varname">DISTFILES</code>: Name(s)
6258                 of archive file(s) containing distribution. The
6259                 default is <code xmlns=
6260                 "http://www.w3.org/TR/xhtml1/transitional" class=
6261                 "filename">${DISTNAME}${EXTRACT_SUFX}</code>.
6262                 Should only be set if you have more than one
6263                 distfile.</p>
6264
6265                 <p>Note that the normal default setting of
6266                 <code class="varname">DISTFILES</code> must be made
6267                 explicit if you want to add to it (rather than
6268                 replace it), as you usually would.</p>
6269               </li>
6270
6271               <li>
6272                 <p><code class="varname">EXTRACT_SUFX</code>:
6273                 Suffix of the distribution file, will be appended
6274                 to <code class="varname">DISTNAME</code>. Defaults
6275                 to <code xmlns=
6276                 "http://www.w3.org/TR/xhtml1/transitional" class=
6277                 "filename">.tar.gz</code>.</p>
6278               </li>
6279             </ul>
6280           </div>
6281
6282           <p>The second section contains information about
6283           separately downloaded patches, if any.</p>
6284
6285           <div class="itemizedlist">
6286             <ul type="disc">
6287               <li>
6288                 <p><code class="varname">PATCHFILES:</code> Name(s)
6289                 of additional files that contain distribution
6290                 patches. There is no default. pkgsrc will look for
6291                 them at <code class="varname">PATCH_SITES</code>.
6292                 They will automatically be uncompressed before
6293                 patching if the names end with <code xmlns=
6294                 "http://www.w3.org/TR/xhtml1/transitional" class=
6295                 "filename">.gz</code> or <code xmlns=
6296                 "http://www.w3.org/TR/xhtml1/transitional" class=
6297                 "filename">.Z</code>.</p>
6298               </li>
6299
6300               <li>
6301                 <p><code class="varname">PATCH_SITES</code>:
6302                 Primary location(s) for distribution patch files
6303                 (see <code class="varname">PATCHFILES</code> below)
6304                 if not found locally.</p>
6305               </li>
6306             </ul>
6307           </div>
6308
6309           <p>The third section contains the following
6310           variables.</p>
6311
6312           <div class="itemizedlist">
6313             <ul type="disc">
6314               <li>
6315                 <p><code class="varname">MAINTAINER</code> is the
6316                 email address of the person who feels responsible
6317                 for this package, and who is most likely to look at
6318                 problems or questions regarding this package which
6319                 have been reported with <a href=
6320                 "http://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1+NetBSD-current">
6321                 <span class="citerefentry"><span class=
6322                 "refentrytitle">send-pr</span>(1)</span></a>. Other
6323                 developers should contact the <code class=
6324                 "varname">MAINTAINER</code> before making major
6325                 changes to the package. When packaging a new
6326                 program, set <code class=
6327                 "varname">MAINTAINER</code> to yourself. If you
6328                 really can't maintain the package for future
6329                 updates, set it to <code class="email">&lt;<a href=
6330                 "mailto:tech-pkg@NetBSD.org">tech-pkg@NetBSD.org</a>&gt;</code>.</p>
6331               </li>
6332
6333               <li>
6334                 <p><code class="varname">HOMEPAGE</code> is a URL
6335                 where users can find more information about the
6336                 package.</p>
6337               </li>
6338
6339               <li>
6340                 <p><code class="varname">COMMENT</code> is a
6341                 one-line description of the package (should not
6342                 include the package name).</p>
6343               </li>
6344             </ul>
6345           </div>
6346
6347           <p>Other variables that affect the build:</p>
6348
6349           <div class="itemizedlist">
6350             <ul type="disc">
6351               <li>
6352                 <p><code class="varname">WRKSRC</code>: The
6353                 directory where the interesting distribution files
6354                 of the package are found. The default is
6355                 <code xmlns=
6356                 "http://www.w3.org/TR/xhtml1/transitional" class=
6357                 "filename">${WRKDIR}/${DISTNAME}</code>, which
6358                 works for most packages.</p>
6359
6360                 <p>If a package doesn't create a subdirectory for
6361                 itself (most GNU software does, for instance), but
6362                 extracts itself in the current directory, you
6363                 should set <code class="varname">WRKSRC=
6364                 ${WRKDIR}</code>.</p>
6365
6366                 <p>If a package doesn't create a subdirectory with
6367                 the name of <code class="varname">DISTNAME</code>
6368                 but some different name, set <code class=
6369                 "varname">WRKSRC</code> to point to the proper name
6370                 in <code xmlns=
6371                 "http://www.w3.org/TR/xhtml1/transitional" class=
6372                 "filename">${WRKDIR}</code>, for example
6373                 <code class="varname">WRKSRC=
6374                 ${WRKDIR}/${DISTNAME}/unix</code>. See <a xmlns=
6375                 "http://www.w3.org/TR/xhtml1/transitional" href=
6376                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/lang/tcl/README.html"
6377                 target="_top"><code xmlns="" class=
6378                 "filename">lang/tcl</code></a> and <a xmlns=
6379                 "http://www.w3.org/TR/xhtml1/transitional" href=
6380                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/tk/README.html"
6381                 target="_top"><code xmlns="" class=
6382                 "filename">x11/tk</code></a> for other
6383                 examples.</p>
6384
6385                 <p>The name of the working directory created by
6386                 pkgsrc is taken from the <code class=
6387                 "varname">WRKDIR_BASENAME</code> variable. By
6388                 default, its value is <code xmlns=
6389                 "http://www.w3.org/TR/xhtml1/transitional" class=
6390                 "filename">work</code>. If you want to use the same
6391                 pkgsrc tree for building different kinds of binary
6392                 packages, you can change the variable according to
6393                 your needs. Two other variables handle common cases
6394                 of setting <code class=
6395                 "varname">WRKDIR_BASENAME</code> individually. If
6396                 <code class="varname">OBJHOSTNAME</code> is defined
6397                 in <code xmlns=
6398                 "http://www.w3.org/TR/xhtml1/transitional" class=
6399                 "filename">/etc/mk.conf</code>, the first component
6400                 of the host's name is attached to the directory
6401                 name. If <code class="varname">OBJMACHINE</code> is
6402                 defined, the platform name is attached, which might
6403                 look like <code xmlns=
6404                 "http://www.w3.org/TR/xhtml1/transitional" class=
6405                 "filename">work.i386</code> or <code xmlns=
6406                 "http://www.w3.org/TR/xhtml1/transitional" class=
6407                 "filename">work.sparc</code>.</p>
6408               </li>
6409             </ul>
6410           </div>
6411
6412           <p>Please pay attention to the following gotchas:</p>
6413
6414           <div class="itemizedlist">
6415             <ul type="disc">
6416               <li>
6417                 <p>Add <code class="varname">MANCOMPRESSED</code>
6418                 if man pages are installed in compressed form by
6419                 the package; see comment in <code xmlns=
6420                 "http://www.w3.org/TR/xhtml1/transitional" class=
6421                 "filename">bsd.pkg.mk</code>.</p>
6422               </li>
6423
6424               <li>
6425                 <p>Replace <code xmlns=
6426                 "http://www.w3.org/TR/xhtml1/transitional" class=
6427                 "filename">/usr/local</code> with
6428                 &#8220;<span class="quote">${PREFIX}</span>&#8221;
6429                 in all files (see patches, below).</p>
6430               </li>
6431
6432               <li>
6433                 <p>If the package installs any info files, see
6434                 <a href="#faq.info-files" title=
6435                 "15.5.7.&nbsp;Packages installing info files">Section&nbsp;15.5.7,
6436                 &#8220;Packages installing info
6437                 files&#8221;</a>.</p>
6438               </li>
6439             </ul>
6440           </div>
6441         </div>
6442
6443         <div class="sect1" lang="en" xml:lang="en">
6444           <div class="titlepage">
6445             <div>
6446               <div>
6447                 <h2 class="title" style="clear: both"><a name=
6448                 "components.distinfo" id=
6449                 "components.distinfo"></a>8.2.&nbsp;<code xmlns=
6450                 "http://www.w3.org/TR/xhtml1/transitional" class=
6451                 "filename">distinfo</code></h2>
6452               </div>
6453             </div>
6454           </div>
6455
6456           <p>The <code xmlns=
6457           "http://www.w3.org/TR/xhtml1/transitional" class=
6458           "filename">distinfo</code> file contains the message
6459           digest, or checksum, of each distfile needed for the
6460           package. This ensures that the distfiles retrieved from
6461           the Internet have not been corrupted during transfer or
6462           altered by a malign force to introduce a security hole.
6463           Due to recent rumor about weaknesses of digest
6464           algorithms, all distfiles are protected using both SHA1
6465           and RMD160 message digests, as well as the file size.</p>
6466
6467           <p>The <code xmlns=
6468           "http://www.w3.org/TR/xhtml1/transitional" class=
6469           "filename">distinfo</code> file also contains the
6470           checksums for all the patches found in the <code xmlns=
6471           "http://www.w3.org/TR/xhtml1/transitional" class=
6472           "filename">patches</code> directory (see <a href=
6473           "#components.patches" title=
6474           "8.3.&nbsp;patches/*">Section&nbsp;8.3,
6475           &#8220;patches/*&#8221;</a>).</p>
6476
6477           <p>To regenerate the <code xmlns=
6478           "http://www.w3.org/TR/xhtml1/transitional" class=
6479           "filename">distinfo</code> file, use the
6480           <span><strong class="command">make
6481           makedistinfo</strong></span> or <span><strong class=
6482           "command">make mdi</strong></span> command.</p>
6483
6484           <p>Some packages have different sets of distfiles
6485           depending on the platform, for example <a xmlns=
6486           "http://www.w3.org/TR/xhtml1/transitional" href=
6487           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/navigator/README.html"
6488           target="_top"><code xmlns="" class=
6489           "filename">www/navigator</code></a>). These are kept in
6490           the same <code xmlns=
6491           "http://www.w3.org/TR/xhtml1/transitional" class=
6492           "filename">distinfo</code> file and care should be taken
6493           when upgrading such a package to ensure distfile
6494           information is not lost.</p>
6495         </div>
6496
6497         <div class="sect1" lang="en" xml:lang="en">
6498           <div class="titlepage">
6499             <div>
6500               <div>
6501                 <h2 class="title" style="clear: both"><a name=
6502                 "components.patches" id=
6503                 "components.patches"></a>8.3.&nbsp;patches/*</h2>
6504               </div>
6505             </div>
6506           </div>
6507
6508           <p>This directory contains files that are used by the
6509           <a href=
6510           "http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current">
6511           <span class="citerefentry"><span class=
6512           "refentrytitle">patch</span>(1)</span></a> command to
6513           modify the sources as distributed in the distribution
6514           file into a form that will compile and run perfectly on
6515           NetBSD. The files are applied successively in alphabetic
6516           order (as returned by a shell &#8220;<span class=
6517           "quote">patches/patch-*</span>&#8221; glob expansion), so
6518           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
6519           class="filename">patch-aa</code> is applied before
6520           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
6521           class="filename">patch-ab</code>, etc.</p>
6522
6523           <p>The <code xmlns=
6524           "http://www.w3.org/TR/xhtml1/transitional" class=
6525           "filename">patch-*</code> files should be in
6526           <span><strong class="command">diff -bu</strong></span>
6527           format, and apply without a fuzz to avoid problems. (To
6528           force patches to apply with fuzz you can set <code class=
6529           "varname">PATCH_FUZZ_FACTOR=-F2</code>). Furthermore, do
6530           not put changes for more than one file into a single
6531           patch file, as this will make future modifications more
6532           difficult.</p>
6533
6534           <p>Similar, a file should be patched at most once, not
6535           several times by several different patches. If a file
6536           needs several patches, they should be combined into one
6537           file.</p>
6538
6539           <p>One important thing to mention is to pay attention
6540           that no RCS IDs get stored in the patch files, as these
6541           will cause problems when later checked into the NetBSD
6542           CVS tree. Use the <span><strong class=
6543           "command">pkgdiff</strong></span> from the <a xmlns=
6544           "http://www.w3.org/TR/xhtml1/transitional" href=
6545           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdiff/README.html"
6546           target="_top"><code xmlns="" class=
6547           "filename">pkgtools/pkgdiff</code></a> package to avoid
6548           these problems.</p>
6549
6550           <p>For even more automation, we recommend using
6551           <span><strong class="command">mkpatches</strong></span>
6552           from the same package to make a whole set of patches. You
6553           just have to backup files before you edit them to
6554           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
6555           class="filename">filename.orig</code>, e.g. with
6556           <span><strong class="command">cp -p filename
6557           filename.orig</strong></span> or, easier, by using
6558           <span><strong class="command">pkgvi</strong></span> again
6559           from the same package. If you upgrade a package this way,
6560           you can easily compare the new set of patches with the
6561           previously existing one with <span><strong class=
6562           "command">patchdiff</strong></span>.</p>
6563
6564           <p>When you have finished a package, remember to generate
6565           the checksums for the patch files by using the
6566           <span><strong class="command">make
6567           makepatchsum</strong></span> command, see <a href=
6568           "#components.distinfo" title=
6569           "8.2.&nbsp;distinfo">Section&nbsp;8.2,
6570           &#8220;<code xmlns="http://www.w3.org/TR/xhtml1/transitional"
6571           class="filename">distinfo</code>&#8221;</a>.</p>
6572
6573           <p>When adding a patch that corrects a problem in the
6574           distfile (rather than e.g. enforcing pkgsrc's view of
6575           where man pages should go), send the patch as a bug
6576           report to the maintainer. This benefits non-pkgsrc users
6577           of the package, and usually enables removing the patch in
6578           future version.</p>
6579
6580           <p>Patch files that are distributed by the author or
6581           other maintainers can be listed in <code class=
6582           "varname">$PATCHFILES</code>.</p>
6583
6584           <p>If it is desired to store any patches that should not
6585           be committed into pkgsrc, they can be kept outside the
6586           pkgsrc tree in the <code xmlns=
6587           "http://www.w3.org/TR/xhtml1/transitional" class=
6588           "filename">$LOCALPATCHES</code> directory. The directory
6589           tree there is expected to have the same
6590           &#8220;<span class="quote">category/package</span>&#8221;
6591           structure as pkgsrc, and patches are expected to be
6592           stored inside these dirs (also known as <code xmlns=
6593           "http://www.w3.org/TR/xhtml1/transitional" class=
6594           "filename">$LOCALPATCHES/$PKGPATH</code>). For example,
6595           if you want to keep a private patch for <code xmlns=
6596           "http://www.w3.org/TR/xhtml1/transitional" class=
6597           "filename">pkgsrc/graphics/png</code>, keep it in
6598           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
6599           class=
6600           "filename">$LOCALPATCHES/graphics/png/mypatch</code>. All
6601           files in the named directory are expected to be patch
6602           files, and <span class="emphasis"><em>they are applied
6603           after pkgsrc patches are applied</em></span>.</p>
6604         </div>
6605
6606         <div class="sect1" lang="en" xml:lang="en">
6607           <div class="titlepage">
6608             <div>
6609               <div>
6610                 <h2 class="title" style="clear: both"><a name=
6611                 "other-mandatory-files" id=
6612                 "other-mandatory-files"></a>8.4.&nbsp;Other
6613                 mandatory files</h2>
6614               </div>
6615             </div>
6616           </div>
6617
6618           <div class="variablelist">
6619             <dl>
6620               <dt><span class="term"><code xmlns=
6621               "http://www.w3.org/TR/xhtml1/transitional" class=
6622               "filename">DESCR</code></span></dt>
6623
6624               <dd>
6625                 <p>A multi-line description of the piece of
6626                 software. This should include any credits where
6627                 they are due. Please bear in mind that others do
6628                 not share your sense of humour (or spelling
6629                 idiosyncrasies), and that others will read
6630                 everything that you write here.</p>
6631               </dd>
6632
6633               <dt><span class="term"><code xmlns=
6634               "http://www.w3.org/TR/xhtml1/transitional" class=
6635               "filename">PLIST</code></span></dt>
6636
6637               <dd>
6638                 <p>This file governs the files that are installed
6639                 on your system: all the binaries, manual pages,
6640                 etc. There are other directives which may be
6641                 entered in this file, to control the creation and
6642                 deletion of directories, and the location of
6643                 inserted files. See <a href="#plist" title=
6644                 "Chapter&nbsp;10.&nbsp;PLIST issues">Chapter&nbsp;10,
6645                 <i>PLIST issues</i></a> for more information.</p>
6646               </dd>
6647             </dl>
6648           </div>
6649         </div>
6650
6651         <div class="sect1" lang="en" xml:lang="en">
6652           <div class="titlepage">
6653             <div>
6654               <div>
6655                 <h2 class="title" style="clear: both"><a name=
6656                 "components.optional" id=
6657                 "components.optional"></a>8.5.&nbsp;Optional
6658                 files</h2>
6659               </div>
6660             </div>
6661           </div>
6662
6663           <div class="variablelist">
6664             <dl>
6665               <dt><span class="term"><code xmlns=
6666               "http://www.w3.org/TR/xhtml1/transitional" class=
6667               "filename">INSTALL</code></span></dt>
6668
6669               <dd>
6670                 <p>This shell script is invoked twice by <a href=
6671                 "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
6672                 <span class="citerefentry"><span class=
6673                 "refentrytitle">pkg_add</span>(1)</span></a>. First
6674                 time after package extraction and before files are
6675                 moved in place, the second time after the files to
6676                 install are moved in place. This can be used to do
6677                 any custom procedures not possible with @exec
6678                 commands in <code xmlns=
6679                 "http://www.w3.org/TR/xhtml1/transitional" class=
6680                 "filename">PLIST</code>. See <a href=
6681                 "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
6682                 <span class="citerefentry"><span class=
6683                 "refentrytitle">pkg_add</span>(1)</span></a> and
6684                 <a href=
6685                 "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1+NetBSD-current">
6686                 <span class="citerefentry"><span class=
6687                 "refentrytitle">pkg_create</span>(1)</span></a> for
6688                 more information.</p>
6689               </dd>
6690
6691               <dt><span class="term"><code xmlns=
6692               "http://www.w3.org/TR/xhtml1/transitional" class=
6693               "filename">DEINSTALL</code></span></dt>
6694
6695               <dd>
6696                 <p>This script is executed before and after any
6697                 files are removed. It is this script's
6698                 responsibility to clean up any additional messy
6699                 details around the package's installation, since
6700                 all pkg_delete knows is how to delete the files
6701                 created in the original distribution. See <a href=
6702                 "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
6703                 <span class="citerefentry"><span class=
6704                 "refentrytitle">pkg_delete</span>(1)</span></a> and
6705                 <a href=
6706                 "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1+NetBSD-current">
6707                 <span class="citerefentry"><span class=
6708                 "refentrytitle">pkg_create</span>(1)</span></a> for
6709                 more information.</p>
6710               </dd>
6711
6712               <dt><span class="term"><code xmlns=
6713               "http://www.w3.org/TR/xhtml1/transitional" class=
6714               "filename">MESSAGE</code></span></dt>
6715
6716               <dd>
6717                 <p>This file is displayed after installation of the
6718                 package. Useful for things like legal notices on
6719                 almost-free software and hints for updating config
6720                 files after installing modules for apache, PHP etc.
6721                 Please note that you can modify variables in it
6722                 easily by using <code class=
6723                 "varname">MESSAGE_SUBST</code> in the package's
6724                 <code xmlns=
6725                 "http://www.w3.org/TR/xhtml1/transitional" class=
6726                 "filename">Makefile</code>:</p>
6727                 <pre class="programlisting">
6728     MESSAGE_SUBST+=  SOMEVAR="somevalue"
6729 </pre>
6730
6731                 <p>replaces "${SOMEVAR}" with &#8220;<span class=
6732                 "quote">somevalue</span>&#8221; in <code xmlns=
6733                 "http://www.w3.org/TR/xhtml1/transitional" class=
6734                 "filename">MESSAGE</code>.</p>
6735               </dd>
6736             </dl>
6737           </div>
6738         </div>
6739
6740         <div class="sect1" lang="en" xml:lang="en">
6741           <div class="titlepage">
6742             <div>
6743               <div>
6744                 <h2 class="title" style="clear: both"><a name=
6745                 "work-dir" id="work-dir"></a>8.6.&nbsp;<code xmlns=
6746                 "http://www.w3.org/TR/xhtml1/transitional" class=
6747                 "filename">work*</code></h2>
6748               </div>
6749             </div>
6750           </div>
6751
6752           <p>When you type <span><strong class=
6753           "command">make</strong></span>, the distribution files
6754           are unpacked into the directory denoted by <code class=
6755           "varname">WRKDIR</code>. It can be removed by running
6756           <span><strong class="command">make clean</strong></span>.
6757           Besides the sources, this directory is also used to keep
6758           various timestamp files. The directory gets <span class=
6759           "emphasis"><em>removed completely</em></span> on clean.
6760           The default is <code xmlns=
6761           "http://www.w3.org/TR/xhtml1/transitional" class=
6762           "filename">${.CURDIR}/work</code> or <code xmlns=
6763           "http://www.w3.org/TR/xhtml1/transitional" class=
6764           "filename">${.CURDIR}/work.${MACHINE_ARCH}</code> if
6765           <code class="varname">OBJMACHINE</code> is set.</p>
6766         </div>
6767
6768         <div class="sect1" lang="en" xml:lang="en">
6769           <div class="titlepage">
6770             <div>
6771               <div>
6772                 <h2 class="title" style="clear: both"><a name=
6773                 "files-dir" id=
6774                 "files-dir"></a>8.7.&nbsp;<code xmlns=
6775                 "http://www.w3.org/TR/xhtml1/transitional" class=
6776                 "filename">files/*</code></h2>
6777               </div>
6778             </div>
6779           </div>
6780
6781           <p>If you have any files that you wish to be placed in
6782           the package prior to configuration or building, you could
6783           place these files here and use a &#8220;<span class=
6784           "quote">${CP}</span>&#8221; command in the
6785           &#8220;<span class="quote">pre-configure</span>&#8221;
6786           target to achieve this. Alternatively, you could simply
6787           diff the file against <code xmlns=
6788           "http://www.w3.org/TR/xhtml1/transitional" class=
6789           "filename">/dev/null</code> and use the patch mechanism
6790           to manage the creation of this file.</p>
6791         </div>
6792       </div>
6793
6794       <div class="chapter" lang="en" xml:lang="en">
6795         <div class="titlepage">
6796           <div>
6797             <div>
6798               <h2 class="title"><a name="makefile" id=
6799               "makefile"></a>Chapter&nbsp;9.&nbsp;Programming in
6800               <code xmlns=
6801               "http://www.w3.org/TR/xhtml1/transitional" class=
6802               "filename">Makefile</code>s</h2>
6803             </div>
6804           </div>
6805         </div>
6806
6807         <div class="toc">
6808           <p><b>Table of Contents</b></p>
6809
6810           <dl>
6811             <dt><span class="sect1"><a href=
6812             "#makefile.variables">9.1. <code xmlns=
6813             "http://www.w3.org/TR/xhtml1/transitional" class=
6814             "filename">Makefile</code> variables</a></span></dt>
6815
6816             <dd>
6817               <dl>
6818                 <dt><span class="sect2"><a href=
6819                 "#makefile.variables.names">9.1.1. Naming
6820                 conventions</a></span></dt>
6821               </dl>
6822             </dd>
6823
6824             <dt><span class="sect1"><a href="#makefile.code">9.2.
6825             Code snippets</a></span></dt>
6826
6827             <dd>
6828               <dl>
6829                 <dt><span class="sect2"><a href=
6830                 "#adding-to-list">9.2.1. Adding things to a
6831                 list</a></span></dt>
6832
6833                 <dt><span class="sect2"><a href=
6834                 "#converting-internal-to-external">9.2.2.
6835                 Converting an internal list into an external
6836                 list</a></span></dt>
6837
6838                 <dt><span class="sect2"><a href=
6839                 "#passing-variable-to-shell">9.2.3. Passing
6840                 variables to a shell command</a></span></dt>
6841
6842                 <dt><span class="sect2"><a href=
6843                 "#quoting-guideline">9.2.4. Quoting
6844                 guideline</a></span></dt>
6845
6846                 <dt><span class="sect2"><a href=
6847                 "#bsd-make-bug-workaround">9.2.5. Workaround for a
6848                 bug in BSD Make</a></span></dt>
6849               </dl>
6850             </dd>
6851           </dl>
6852         </div>
6853
6854         <p>Pkgsrc consists of many <code xmlns=
6855         "http://www.w3.org/TR/xhtml1/transitional" class=
6856         "filename">Makefile</code> fragments, each of which forms a
6857         well-defined part of the pkgsrc system. Using the <a href=
6858         "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
6859         <span class="citerefentry"><span class=
6860         "refentrytitle">make</span>(1)</span></a> system as a
6861         programming language for a big system like pkgsrc requires
6862         some discipline to keep the code correct and
6863         understandable.</p>
6864
6865         <p>The basic ingredients for <code xmlns=
6866         "http://www.w3.org/TR/xhtml1/transitional" class=
6867         "filename">Makefile</code> programming are variables (which
6868         are actually macros) and shell commands. Among these shell
6869         commands may even be more complex ones like <a href=
6870         "http://netbsd.gw.com/cgi-bin/man-cgi?awk+1+NetBSD-current">
6871         <span class="citerefentry"><span class=
6872         "refentrytitle">awk</span>(1)</span></a> programs. To make
6873         sure that every shell command runs as intended it is
6874         necessary to quote all variables correctly when they are
6875         used.</p>
6876
6877         <p>This chapter describes some patterns, that appear quite
6878         often in <code xmlns=
6879         "http://www.w3.org/TR/xhtml1/transitional" class=
6880         "filename">Makefile</code>s, including the pitfalls that
6881         come along with them.</p>
6882
6883         <div class="sect1" lang="en" xml:lang="en">
6884           <div class="titlepage">
6885             <div>
6886               <div>
6887                 <h2 class="title" style="clear: both"><a name=
6888                 "makefile.variables" id=
6889                 "makefile.variables"></a>9.1.&nbsp;<code xmlns=
6890                 "http://www.w3.org/TR/xhtml1/transitional" class=
6891                 "filename">Makefile</code> variables</h2>
6892               </div>
6893             </div>
6894           </div>
6895
6896           <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional"
6897           class="filename">Makefile</code> variables contain
6898           strings that can be processed using the five operators
6899           ``='', ``+='', ``?='', ``:='', and ``!='', which are
6900           described in the <a href=
6901           "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
6902           <span class="citerefentry"><span class=
6903           "refentrytitle">make</span>(1)</span></a> man page.</p>
6904
6905           <p>When a variable's value is parsed from a <code xmlns=
6906           "http://www.w3.org/TR/xhtml1/transitional" class=
6907           "filename">Makefile</code>, the hash character ``#'' and
6908           the backslash character ``\'' are handled specially. If a
6909           backslash is followed by a newline, any whitespace
6910           immediately in front of the backslash, the backslash, the
6911           newline, and any whitespace immediately behind the
6912           newline are replaced with a single space. A backspace
6913           character and an immediately following hash character are
6914           replaced with a single hash character. Otherwise, the
6915           backslash is passed as is. In a variable assignment, any
6916           hash character that is not preceded by a backslash starts
6917           a comment that continues upto the end of the logical
6918           line.</p>
6919
6920           <p><span class="emphasis"><em>Note:</em></span> Because
6921           of this parsing algorithm the only way to create a
6922           variable consisting of a single backslash is using the
6923           ``!='' operator, for example: <code class=
6924           "varname">BACKSLASH!=echo "\\"</code>.</p>
6925
6926           <p>So far for defining variables. The other thing you can
6927           do with variables is evaluating them. A variable is
6928           evaluated when it is part of the right side of the ``:=''
6929           or the ``!='' operator, or directly before executing a
6930           shell command which the variable is part of. In all other
6931           cases, <a href=
6932           "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
6933           <span class="citerefentry"><span class=
6934           "refentrytitle">make</span>(1)</span></a> performs lazy
6935           evaluation, that is, variables are not evaluated until
6936           there's no other way. The ``modifiers'' mentioned in the
6937           man page also evaluate the variable.</p>
6938
6939           <p>Some of the modifiers split the string into words and
6940           then operate on the words, others operate on the string
6941           as a whole. When a string is split into words, it is
6942           split as you would expect it from <a href=
6943           "http://netbsd.gw.com/cgi-bin/man-cgi?sh+1+NetBSD-current">
6944           <span class="citerefentry"><span class=
6945           "refentrytitle">sh</span>(1)</span></a>.</p>
6946
6947           <p>No rule without exception&#8212;the
6948           <span><strong class="command">.for</strong></span> loop
6949           does not follow the shell quoting rules but splits at
6950           sequences of whitespace.</p>
6951
6952           <p>There are several types of variables that should be
6953           handled differently. Strings and two types of lists.</p>
6954
6955           <div class="itemizedlist">
6956             <ul type="disc">
6957               <li>
6958                 <p><span class="emphasis"><em>Strings</em></span>
6959                 can contain arbitrary characters. Nevertheless, you
6960                 should restrict yourself to only using printable
6961                 characters. Examples are <code class=
6962                 "varname">PREFIX</code> and <code class=
6963                 "varname">COMMENT</code>.</p>
6964               </li>
6965
6966               <li>
6967                 <p><span class="emphasis"><em>Internal
6968                 lists</em></span> are lists that are never exported
6969                 to any shell command. Their elements are separated
6970                 by whitespace. Therefore, the elements themselves
6971                 cannot have embedded whitespace. Any other
6972                 characters are allowed. Internal lists can be used
6973                 in <span><strong class=
6974                 "command">.for</strong></span> loops. Examples are
6975                 <code class="varname">DEPENDS</code> and
6976                 <code class="varname">BUILD_DEPENDS</code>.</p>
6977               </li>
6978
6979               <li>
6980                 <p><span class="emphasis"><em>External
6981                 lists</em></span> are lists that may be exported to
6982                 a shell command. Their elements can contain any
6983                 characters, including whitespace. That's why they
6984                 cannot be used in <span><strong class=
6985                 "command">.for</strong></span> loops. Examples are
6986                 <code class="varname">DISTFILES</code> and
6987                 <code class="varname">MASTER_SITES</code>.</p>
6988               </li>
6989             </ul>
6990           </div>
6991
6992           <div class="sect2" lang="en" xml:lang="en">
6993             <div class="titlepage">
6994               <div>
6995                 <div>
6996                   <h3 class="title"><a name=
6997                   "makefile.variables.names" id=
6998                   "makefile.variables.names"></a>9.1.1.&nbsp;Naming
6999                   conventions</h3>
7000                 </div>
7001               </div>
7002             </div>
7003
7004             <div class="itemizedlist">
7005               <ul type="disc">
7006                 <li>
7007                   <p>All variable names starting with an underscore
7008                   are reserved for use by the pkgsrc
7009                   infrastructure. They shall not be used by package
7010                   <code xmlns=
7011                   "http://www.w3.org/TR/xhtml1/transitional" class=
7012                   "filename">Makefile</code>s.</p>
7013                 </li>
7014
7015                 <li>
7016                   <p>In <span><strong class=
7017                   "command">.for</strong></span> loops you should
7018                   use lowercase variable names for the iteration
7019                   variables.</p>
7020                 </li>
7021
7022                 <li>
7023                   <p>All list variables should have a ``plural''
7024                   name, e.g. <code class=
7025                   "varname">PKG_OPTIONS</code> or <code class=
7026                   "varname">DISTFILES</code>.</p>
7027                 </li>
7028               </ul>
7029             </div>
7030           </div>
7031         </div>
7032
7033         <div class="sect1" lang="en" xml:lang="en">
7034           <div class="titlepage">
7035             <div>
7036               <div>
7037                 <h2 class="title" style="clear: both"><a name=
7038                 "makefile.code" id=
7039                 "makefile.code"></a>9.2.&nbsp;Code snippets</h2>
7040               </div>
7041             </div>
7042           </div>
7043
7044           <p>This section presents you with some code snippets you
7045           should use in your own code. If you don't find anything
7046           appropriate here, you should test your code and add it
7047           here.</p>
7048
7049           <div class="sect2" lang="en" xml:lang="en">
7050             <div class="titlepage">
7051               <div>
7052                 <div>
7053                   <h3 class="title"><a name="adding-to-list" id=
7054                   "adding-to-list"></a>9.2.1.&nbsp;Adding things to
7055                   a list</h3>
7056                 </div>
7057               </div>
7058             </div>
7059             <pre class="programlisting">
7060     STRING=                 foo * bar `date`
7061     INT_LIST=               # empty
7062     ANOTHER_INT_LIST=       apache-[0-9]*:../../www/apache
7063     EXT_LIST=               # empty
7064     ANOTHER_EXT_LIST=       a=b c=d
7065
7066     INT_LIST+=              ${STRING}               # 1
7067     INT_LIST+=              ${ANOTHER_INT_LIST}     # 2
7068     EXT_LIST+=              ${STRING:Q}             # 3
7069     EXT_LIST+=              ${ANOTHER_EXT_LIST}     # 4
7070 </pre>
7071
7072             <p>When you add a string to an external list (example
7073             3), it must be quoted. In all other cases, you must not
7074             add a quoting level. You must not merge internal and
7075             external lists, unless you are sure that all entries
7076             are correctly interpreted in both lists.</p>
7077           </div>
7078
7079           <div class="sect2" lang="en" xml:lang="en">
7080             <div class="titlepage">
7081               <div>
7082                 <div>
7083                   <h3 class="title"><a name=
7084                   "converting-internal-to-external" id=
7085                   "converting-internal-to-external"></a>9.2.2.&nbsp;Converting
7086                   an internal list into an external list</h3>
7087                 </div>
7088               </div>
7089             </div>
7090             <pre class="programlisting">
7091     EXT_LIST=       # empty
7092     .for i in ${INT_LIST}
7093     EXT_LIST+=      ${i:Q}""
7094     .endfor
7095 </pre>
7096
7097             <p>This code converts the internal list <code class=
7098             "varname">INT_LIST</code> into the external list
7099             <code class="varname">EXT_LIST</code>. As the elements
7100             of an internal list are unquoted they must be quoted
7101             here. The reason for appending <code class=
7102             "varname">""</code> is explained below.</p>
7103           </div>
7104
7105           <div class="sect2" lang="en" xml:lang="en">
7106             <div class="titlepage">
7107               <div>
7108                 <div>
7109                   <h3 class="title"><a name=
7110                   "passing-variable-to-shell" id=
7111                   "passing-variable-to-shell"></a>9.2.3.&nbsp;Passing
7112                   variables to a shell command</h3>
7113                 </div>
7114               </div>
7115             </div>
7116             <pre class="programlisting">
7117     STRING=         foo bar &lt;    &gt; * `date` $$HOME ' "
7118     EXT_LIST=       string=${STRING:Q} x=second\ item
7119
7120     all:
7121             echo ${STRING}                  # 1
7122             echo "${STRING}"                # 2
7123             echo "${STRING:Q}"              # 3
7124             echo ${STRING:Q}                # 4
7125             echo x${STRING:Q} | sed 1s,.,,  # 5
7126             env ${EXT_LIST} /bin/sh -c 'echo "$$string"; echo "$$x"'
7127 </pre>
7128
7129             <p>Example 1 leads to a syntax error in the shell, as
7130             the characters are just copied.</p>
7131
7132             <p>Example 2 leads to a syntax error too, and if you
7133             leave out the last " character from <code class=
7134             "varname">${STRING}</code>, <a href=
7135             "http://netbsd.gw.com/cgi-bin/man-cgi?date+1+NetBSD-current">
7136             <span class="citerefentry"><span class=
7137             "refentrytitle">date</span>(1)</span></a> will be
7138             executed. The <code class="varname">$HOME</code> shell
7139             variable would be evaluated, too.</p>
7140
7141             <p>Example 3 outputs each space character preceded by a
7142             backslash (or not), depending on the implementation of
7143             the <a href=
7144             "http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-current">
7145             <span class="citerefentry"><span class=
7146             "refentrytitle">echo</span>(1)</span></a> command.</p>
7147
7148             <p>Example 4 handles correctly every string that does
7149             not start with a dash. In that case, the result depends
7150             on the implementation of the <a href=
7151             "http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-current">
7152             <span class="citerefentry"><span class=
7153             "refentrytitle">echo</span>(1)</span></a> command. As
7154             long as you can guarantee that your input does not
7155             start with a dash, this form is appropriate.</p>
7156
7157             <p>Example 5 handles even the case of a leading dash
7158             correctly.</p>
7159
7160             <p>The <code class="varname">EXT_LIST</code> does not
7161             need to be quoted because the quoting has already been
7162             done when adding elements to the list.</p>
7163
7164             <p>As internal lists shall not be passed to the shell,
7165             there is no example for it.</p>
7166           </div>
7167
7168           <div class="sect2" lang="en" xml:lang="en">
7169             <div class="titlepage">
7170               <div>
7171                 <div>
7172                   <h3 class="title"><a name="quoting-guideline" id=
7173                   "quoting-guideline"></a>9.2.4.&nbsp;Quoting
7174                   guideline</h3>
7175                 </div>
7176               </div>
7177             </div>
7178
7179             <p>There are many possible sources of wrongly quoted
7180             variables. This section lists some of the commonly
7181             known ones.</p>
7182
7183             <div class="itemizedlist">
7184               <ul type="disc">
7185                 <li>
7186                   <p>Whenever you use the value of a list, think
7187                   about what happens to leading or trailing
7188                   whitespace. If the list is a well-formed shell
7189                   expression, you can apply the <code class=
7190                   "varname">:M*</code> modifier to strip leading
7191                   and trailing whitespace from each word. The
7192                   <code class="varname">:M</code> operator first
7193                   splits its argument according to the rules of the
7194                   shell, and then creates a new list consisting of
7195                   all words that match the shell glob expression
7196                   <code class="varname">*</code>, that is: all. One
7197                   class of situations where this is needed is when
7198                   adding a variable like <code class=
7199                   "varname">CPPFLAGS</code> to <code class=
7200                   "varname">CONFIGURE_ARGS</code>. If the configure
7201                   script invokes other configure scripts, it strips
7202                   the leading and trailing whitespace from the
7203                   variable and then passes it to the other
7204                   configure scripts. But these configure scripts
7205                   expect the (child) <code class=
7206                   "varname">CPPFLAGS</code> variable to be the same
7207                   as the parent <code class=
7208                   "varname">CPPFLAGS</code>. That's why we better
7209                   pass the <code class="varname">CPPFLAGS</code>
7210                   value properly trimmed. And here is how we do
7211                   it:</p>
7212                   <pre class="programlisting">
7213     CPPFLAGS=               # empty
7214     CPPFLAGS+=              -Wundef -DPREFIX=\"${PREFIX:Q}\"
7215     CPPFLAGS+=              ${MY_CPPFLAGS}
7216
7217     CONFIGURE_ARGS+=        CPPFLAGS=${CPPFLAGS:M*:Q}
7218
7219     all:
7220             echo x${CPPFLAGS:Q}x            # leading and trailing whitespace
7221             echo x${CONFIGURE_ARGS}x        # properly trimmed
7222 </pre>
7223                 </li>
7224
7225                 <li>
7226                   <p>The example above contains one bug: The
7227                   <code class="varname">${PREFIX}</code> is a
7228                   properly quoted shell expression, but there is
7229                   the C compiler after it, which also expects a
7230                   properly quoted string (this time in C syntax).
7231                   The version above is therefore only correct if
7232                   <code class="varname">${PREFIX}</code> does not
7233                   have embedded backslashes or double quotes. If
7234                   you want to allow these, you have to add another
7235                   layer of quoting to each variable that is used as
7236                   a C string literal. You cannot use the
7237                   <code class="varname">:Q</code> operator for it,
7238                   as this operator only works for the shell.</p>
7239                 </li>
7240
7241                 <li>
7242                   <p>Whenever a variable can be empty, the
7243                   <code class="varname">:Q</code> operator can have
7244                   surprising results. Here are two completely
7245                   different cases which can be solved with the same
7246                   trick.</p>
7247                   <pre class="programlisting">
7248     EMPTY=                  # empty
7249     empty_test:
7250             for i in a ${EMPTY:Q} c; do \
7251                     echo "$$i"; \
7252             done
7253
7254     for_test:
7255     .for i in a:\ a:\test.txt
7256             echo ${i:Q}
7257             echo "foo"
7258     .endfor
7259 </pre>
7260
7261                   <p>The first example will only print two of the
7262                   three lines we might have expected. This is
7263                   because <code class="varname">${EMPTY:Q}</code>
7264                   expands to the empty string, which the shell
7265                   cannot see. The workaround is to write
7266                   <code class="varname">${EMPTY:Q}""</code>. This
7267                   pattern can be often found as <code class=
7268                   "varname">${TEST} -z ${VAR:Q}</code> or as
7269                   <code class="varname">${TEST} -f
7270                   ${FNAME:Q}</code> (both of these are wrong).</p>
7271
7272                   <p>The second example will only print three lines
7273                   instead of four. The first line looks like
7274                   <code class="varname">a:\ echo foo</code>. This
7275                   is because the backslash of the value
7276                   <code class="varname">a:\</code> is interpreted
7277                   as a line-continuation by <a href=
7278                   "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
7279                   <span class="citerefentry"><span class=
7280                   "refentrytitle">make</span>(1)</span></a>, which
7281                   makes the second line the arguments of the
7282                   <a href=
7283                   "http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-current">
7284                   <span class="citerefentry"><span class=
7285                   "refentrytitle">echo</span>(1)</span></a> command
7286                   from the first line. To avoid this, write
7287                   <code class="varname">${i:Q}""</code>.</p>
7288                 </li>
7289               </ul>
7290             </div>
7291           </div>
7292
7293           <div class="sect2" lang="en" xml:lang="en">
7294             <div class="titlepage">
7295               <div>
7296                 <div>
7297                   <h3 class="title"><a name=
7298                   "bsd-make-bug-workaround" id=
7299                   "bsd-make-bug-workaround"></a>9.2.5.&nbsp;Workaround
7300                   for a bug in BSD Make</h3>
7301                 </div>
7302               </div>
7303             </div>
7304
7305             <p>The pkgsrc bmake program does not handle the
7306             following assignment correctly. In case <code class=
7307             "varname">_othervar_</code> contains a ``-'' character,
7308             one of the closing braces is included in <code class=
7309             "varname">${VAR}</code> after this code executes.</p>
7310             <pre class="programlisting">
7311     VAR:=   ${VAR:N${_othervar_:C/-//}}
7312 </pre>
7313
7314             <p>For a more complex code snippet and a workaround,
7315             see the package <a xmlns=
7316             "http://www.w3.org/TR/xhtml1/transitional" href=
7317             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/regress/make-quoting/README.html"
7318             target="_top"><code xmlns="" class=
7319             "filename">regress/make-quoting</code></a>, testcase
7320             <code class="varname">bug1</code>.</p>
7321           </div>
7322         </div>
7323       </div>
7324
7325       <div class="chapter" lang="en" xml:lang="en">
7326         <div class="titlepage">
7327           <div>
7328             <div>
7329               <h2 class="title"><a name="plist" id=
7330               "plist"></a>Chapter&nbsp;10.&nbsp;PLIST issues</h2>
7331             </div>
7332           </div>
7333         </div>
7334
7335         <div class="toc">
7336           <p><b>Table of Contents</b></p>
7337
7338           <dl>
7339             <dt><span class="sect1"><a href="#rcs-id">10.1. RCS
7340             ID</a></span></dt>
7341
7342             <dt><span class="sect1"><a href=
7343             "#automatic-plist-generation">10.2. Semi-automatic
7344             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
7345             class="filename">PLIST</code>
7346             generation</a></span></dt>
7347
7348             <dt><span class="sect1"><a href="#print-PLIST">10.3.
7349             Tweaking output of <span><strong class="command">make
7350             print-PLIST</strong></span></a></span></dt>
7351
7352             <dt><span class="sect1"><a href="#plist.misc">10.4.
7353             Variable substitution in PLIST</a></span></dt>
7354
7355             <dt><span class="sect1"><a href=
7356             "#manpage-compression">10.5. Man page
7357             compression</a></span></dt>
7358
7359             <dt><span class="sect1"><a href=
7360             "#using-PLIST_SRC">10.6. Changing PLIST source with
7361             <code class="varname">PLIST_SRC</code></a></span></dt>
7362
7363             <dt><span class="sect1"><a href=
7364             "#platform-specific-plist">10.7. Platform-specific and
7365             differing PLISTs</a></span></dt>
7366
7367             <dt><span class="sect1"><a href=
7368             "#faq.common-dirs">10.8. Sharing directories between
7369             packages</a></span></dt>
7370           </dl>
7371         </div>
7372
7373         <p>The <code xmlns=
7374         "http://www.w3.org/TR/xhtml1/transitional" class=
7375         "filename">PLIST</code> file contains a package's
7376         &#8220;<span class="quote">packing list</span>&#8221;, i.e.
7377         a list of files that belong to the package (relative to the
7378         <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
7379         class="filename">${PREFIX}</code> directory it's been
7380         installed in) plus some additional statements - see the
7381         <a href=
7382         "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1+NetBSD-current">
7383         <span class="citerefentry"><span class=
7384         "refentrytitle">pkg_create</span>(1)</span></a> man page
7385         for a full list. This chapter addresses some issues that
7386         need attention when dealing with the <code xmlns=
7387         "http://www.w3.org/TR/xhtml1/transitional" class=
7388         "filename">PLIST</code> file (or files, see below!).</p>
7389
7390         <div class="sect1" lang="en" xml:lang="en">
7391           <div class="titlepage">
7392             <div>
7393               <div>
7394                 <h2 class="title" style="clear: both"><a name=
7395                 "rcs-id" id="rcs-id"></a>10.1.&nbsp;RCS ID</h2>
7396               </div>
7397             </div>
7398           </div>
7399
7400           <p>Be sure to add a RCS ID line as the first thing in any
7401           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
7402           class="filename">PLIST</code> file you write:</p>
7403           <pre class="programlisting">
7404     @comment $NetBSD$
7405 </pre>
7406         </div>
7407
7408         <div class="sect1" lang="en" xml:lang="en">
7409           <div class="titlepage">
7410             <div>
7411               <div>
7412                 <h2 class="title" style="clear: both"><a name=
7413                 "automatic-plist-generation" id=
7414                 "automatic-plist-generation"></a>10.2.&nbsp;Semi-automatic
7415                 <code xmlns=
7416                 "http://www.w3.org/TR/xhtml1/transitional" class=
7417                 "filename">PLIST</code> generation</h2>
7418               </div>
7419             </div>
7420           </div>
7421
7422           <p>You can use the <span><strong class="command">make
7423           print-PLIST</strong></span> command to output a PLIST
7424           that matches any new files since the package was
7425           extracted. See <a href="#build.helpful-targets" title=
7426           "14.3.&nbsp;Other helpful targets">Section&nbsp;14.3,
7427           &#8220;Other helpful targets&#8221;</a> for more
7428           information on this target.</p>
7429         </div>
7430
7431         <div class="sect1" lang="en" xml:lang="en">
7432           <div class="titlepage">
7433             <div>
7434               <div>
7435                 <h2 class="title" style="clear: both"><a name=
7436                 "print-PLIST" id=
7437                 "print-PLIST"></a>10.3.&nbsp;Tweaking output of
7438                 <span><strong class="command">make
7439                 print-PLIST</strong></span></h2>
7440               </div>
7441             </div>
7442           </div>
7443
7444           <p>If you have used any of the *-dirs packages, as
7445           explained in <a href="#faq.common-dirs" title=
7446           "10.8.&nbsp;Sharing directories between packages">Section&nbsp;10.8,
7447           &#8220;Sharing directories between packages&#8221;</a>,
7448           you may have noticed that <span><strong class=
7449           "command">make print-PLIST</strong></span> outputs a set
7450           of <code class="varname">@comment</code>s instead of real
7451           <code class="varname">@dirrm</code> lines. You can also
7452           do this for specific directories and files, so that the
7453           results of that command are very close to reality. This
7454           helps <span class="emphasis"><em>a lot</em></span> during
7455           the update of packages.</p>
7456
7457           <p>The <code class="varname">PRINT_PLIST_AWK</code>
7458           variable takes a set of AWK patterns and actions that are
7459           used to filter the output of print-PLIST. You can
7460           <span class="emphasis"><em>append</em></span> any chunk
7461           of AWK scripting you like to it, but be careful with
7462           quoting.</p>
7463
7464           <p>For example, to get all files inside the <code xmlns=
7465           "http://www.w3.org/TR/xhtml1/transitional" class=
7466           "filename">libdata/foo</code> directory removed from the
7467           resulting PLIST:</p>
7468           <pre class="programlisting">
7469     PRINT_PLIST_AWK+=       /^libdata\/foo/ { next; }
7470 </pre>
7471
7472           <p>And to get all the <code class="varname">@dirrm</code>
7473           lines referring to a specific (shared) directory
7474           converted to <code class="varname">@comment</code>s:</p>
7475           <pre class="programlisting">
7476     PRINT_PLIST_AWK+=       /^@dirrm share\/specific/ { print "@comment " $$0; next; }
7477 </pre>
7478         </div>
7479
7480         <div class="sect1" lang="en" xml:lang="en">
7481           <div class="titlepage">
7482             <div>
7483               <div>
7484                 <h2 class="title" style="clear: both"><a name=
7485                 "plist.misc" id=
7486                 "plist.misc"></a>10.4.&nbsp;Variable substitution
7487                 in PLIST</h2>
7488               </div>
7489             </div>
7490           </div>
7491
7492           <p>A number of variables are substituted automatically in
7493           PLISTs when a package is installed on a system. This
7494           includes the following variables:</p>
7495
7496           <div class="variablelist">
7497             <dl>
7498               <dt><span class="term"><code class=
7499               "varname">${MACHINE_ARCH}</code>, <code class=
7500               "varname">${MACHINE_GNU_ARCH}</code></span></dt>
7501
7502               <dd>
7503                 <p>Some packages like emacs and perl embed
7504                 information about which architecture they were
7505                 built on into the pathnames where they install
7506                 their files. To handle this case, PLIST will be
7507                 preprocessed before actually used, and the symbol
7508                 &#8220;<span class="quote"><code class=
7509                 "varname">${MACHINE_ARCH}</code></span>&#8221; will
7510                 be replaced by what <span><strong class=
7511                 "command">uname -p</strong></span> gives. The same
7512                 is done if the string <code class=
7513                 "varname">${MACHINE_GNU_ARCH}</code> is embedded in
7514                 PLIST somewhere - use this on packages that have
7515                 GNU autoconf-created configure scripts.</p>
7516
7517                 <div class="note" style=
7518                 "margin-left: 0.5in; margin-right: 0.5in;">
7519                   <h3 class="title">Legacy note</h3>
7520
7521                   <p>There used to be a symbol &#8220;<span class=
7522                   "quote"><code class=
7523                   "varname">$ARCH</code></span>&#8221; that was
7524                   replaced by the output of <span><strong class=
7525                   "command">uname -m</strong></span>, but that's no
7526                   longer supported and has been removed.</p>
7527                 </div>
7528               </dd>
7529
7530               <dt><span class="term"><code class=
7531               "varname">${OPSYS}</code>, <code class=
7532               "varname">${LOWER_OPSYS}</code>, <code class=
7533               "varname">${OS_VERSION}</code></span></dt>
7534
7535               <dd>
7536                 <p>Some packages want to embed the OS name and
7537                 version into some paths. To do this, use these
7538                 variables in the <code xmlns=
7539                 "http://www.w3.org/TR/xhtml1/transitional" class=
7540                 "filename">PLIST</code>:</p>
7541
7542                 <div class="itemizedlist">
7543                   <ul type="disc">
7544                     <li>
7545                       <p><code class="varname">${OPSYS}</code> -
7546                       output of &#8220;<span class=
7547                       "quote"><span><strong class="command">uname
7548                       -s</strong></span></span>&#8221;</p>
7549                     </li>
7550
7551                     <li>
7552                       <p><code class=
7553                       "varname">${LOWER_OPSYS}</code> - lowercase
7554                       common name (eg. &#8220;<span class=
7555                       "quote">solaris</span>&#8221;)</p>
7556                     </li>
7557
7558                     <li>
7559                       <p><code class="varname">${OS_VERSION}</code>
7560                       - &#8220;<span class=
7561                       "quote"><span><strong class="command">uname
7562                       -r</strong></span></span>&#8221;</p>
7563                     </li>
7564                   </ul>
7565                 </div>
7566               </dd>
7567
7568               <dt><span class="term"><code class=
7569               "varname">${PKGLOCALEDIR}</code></span></dt>
7570
7571               <dd>
7572                 <p>Packages that install locale files should list
7573                 them in the PLIST as &#8220;<span class=
7574                 "quote">${PKGLOCALEDIR}/locale/de/LC_MESSAGES/...</span>&#8221;
7575                 instead of &#8220;<span class=
7576                 "quote">share/locale/de/LC_MESSAGES/...</span>&#8221;.
7577                 This properly handles the fact that different
7578                 operating systems expect locale files to be either
7579                 in <code xmlns=
7580                 "http://www.w3.org/TR/xhtml1/transitional" class=
7581                 "filename">share</code> or <code xmlns=
7582                 "http://www.w3.org/TR/xhtml1/transitional" class=
7583                 "filename">lib</code> by default.</p>
7584               </dd>
7585             </dl>
7586           </div>
7587
7588           <p>For a complete list of values which are replaced by
7589           default, please look in <code xmlns=
7590           "http://www.w3.org/TR/xhtml1/transitional" class=
7591           "filename">bsd.pkg.mk</code> (and search for <span class=
7592           "emphasis"><em>PLIST_SUBST</em></span>).</p>
7593
7594           <p>If you want to change other variables not listed
7595           above, you can add variables and their expansions to this
7596           variable in the following way, similar to <code class=
7597           "varname">MESSAGE_SUBST</code> (see <a href=
7598           "#components.optional" title=
7599           "8.5.&nbsp;Optional files">Section&nbsp;8.5,
7600           &#8220;Optional files&#8221;</a>):</p>
7601           <pre class="programlisting">
7602     PLIST_SUBST+=   SOMEVAR="somevalue"
7603 </pre>
7604
7605           <p>This replaces all occurrences of &#8220;<span class=
7606           "quote">${SOMEVAR}</span>&#8221; in the PLIST with
7607           &#8220;<span class="quote">somevalue</span>&#8221;.</p>
7608         </div>
7609
7610         <div class="sect1" lang="en" xml:lang="en">
7611           <div class="titlepage">
7612             <div>
7613               <div>
7614                 <h2 class="title" style="clear: both"><a name=
7615                 "manpage-compression" id=
7616                 "manpage-compression"></a>10.5.&nbsp;Man page
7617                 compression</h2>
7618               </div>
7619             </div>
7620           </div>
7621
7622           <p>Man pages should be installed in compressed form if
7623           <code class="varname">MANZ</code> is set (in <code xmlns=
7624           "http://www.w3.org/TR/xhtml1/transitional" class=
7625           "filename">bsd.own.mk</code>), and uncompressed
7626           otherwise. To handle this in the <code xmlns=
7627           "http://www.w3.org/TR/xhtml1/transitional" class=
7628           "filename">PLIST</code> file, the suffix
7629           &#8220;<span class="quote">.gz</span>&#8221; is
7630           appended/removed automatically for man pages according to
7631           <code class="varname">MANZ</code> and <code class=
7632           "varname">MANCOMPRESSED</code> being set or not, see
7633           above for details. This modification of the <code xmlns=
7634           "http://www.w3.org/TR/xhtml1/transitional" class=
7635           "filename">PLIST</code> file is done on a copy of it, not
7636           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
7637           class="filename">PLIST</code> itself.</p>
7638         </div>
7639
7640         <div class="sect1" lang="en" xml:lang="en">
7641           <div class="titlepage">
7642             <div>
7643               <div>
7644                 <h2 class="title" style="clear: both"><a name=
7645                 "using-PLIST_SRC" id=
7646                 "using-PLIST_SRC"></a>10.6.&nbsp;Changing PLIST
7647                 source with <code class=
7648                 "varname">PLIST_SRC</code></h2>
7649               </div>
7650             </div>
7651           </div>
7652
7653           <p>To use one or more files as source for the
7654           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
7655           class="filename">PLIST</code> used in generating the
7656           binary package, set the variable <code class=
7657           "varname">PLIST_SRC</code> to the names of that file(s).
7658           The files are later concatenated using <a href=
7659           "http://netbsd.gw.com/cgi-bin/man-cgi?cat+1+NetBSD-current">
7660           <span class="citerefentry"><span class=
7661           "refentrytitle">cat</span>(1)</span></a>, and order of
7662           things is important.</p>
7663         </div>
7664
7665         <div class="sect1" lang="en" xml:lang="en">
7666           <div class="titlepage">
7667             <div>
7668               <div>
7669                 <h2 class="title" style="clear: both"><a name=
7670                 "platform-specific-plist" id=
7671                 "platform-specific-plist"></a>10.7.&nbsp;Platform-specific
7672                 and differing PLISTs</h2>
7673               </div>
7674             </div>
7675           </div>
7676
7677           <p>Some packages decide to install a different set of
7678           files based on the operating system being used. These
7679           differences can be automatically handled by using the
7680           following files:</p>
7681
7682           <div class="itemizedlist">
7683             <ul type="disc">
7684               <li>
7685                 <p><code xmlns=
7686                 "http://www.w3.org/TR/xhtml1/transitional" class=
7687                 "filename">PLIST.common</code></p>
7688               </li>
7689
7690               <li>
7691                 <p><code xmlns=
7692                 "http://www.w3.org/TR/xhtml1/transitional" class=
7693                 "filename">PLIST.${OPSYS}</code></p>
7694               </li>
7695
7696               <li>
7697                 <p><code xmlns=
7698                 "http://www.w3.org/TR/xhtml1/transitional" class=
7699                 "filename">PLIST.${MACHINE_ARCH}</code></p>
7700               </li>
7701
7702               <li>
7703                 <p><code xmlns=
7704                 "http://www.w3.org/TR/xhtml1/transitional" class=
7705                 "filename">PLIST.${OPSYS}-${MACHINE_ARCH}</code></p>
7706               </li>
7707
7708               <li>
7709                 <p><code xmlns=
7710                 "http://www.w3.org/TR/xhtml1/transitional" class=
7711                 "filename">PLIST.common_end</code></p>
7712               </li>
7713             </ul>
7714           </div>
7715         </div>
7716
7717         <div class="sect1" lang="en" xml:lang="en">
7718           <div class="titlepage">
7719             <div>
7720               <div>
7721                 <h2 class="title" style="clear: both"><a name=
7722                 "faq.common-dirs" id=
7723                 "faq.common-dirs"></a>10.8.&nbsp;Sharing
7724                 directories between packages</h2>
7725               </div>
7726             </div>
7727           </div>
7728
7729           <p>A &#8220;<span class="quote">shared
7730           directory</span>&#8221; is a directory where multiple
7731           (and unrelated) packages install files. These directories
7732           are problematic because you have to add special tricks in
7733           the PLIST to conditionally remove them, or have some
7734           centralized package handle them.</p>
7735
7736           <p>Within pkgsrc, you'll find both approaches. If a
7737           directory is shared by a few unrelated packages, it's
7738           often not worth to add an extra package to remove it.
7739           Therefore, one simply does:</p>
7740           <pre class="programlisting">
7741     @unexec ${RMDIR} %D/path/to/shared/directory 2&gt;/dev/null || ${TRUE}
7742 </pre>
7743
7744           <p>in the PLISTs of all affected packages, instead of the
7745           regular "@dirrm" line.</p>
7746
7747           <p>However, if the directory is shared across many
7748           packages, two different solutions are available:</p>
7749
7750           <div class="orderedlist">
7751             <ol type="1">
7752               <li>
7753                 <p>If the packages have a common dependency, the
7754                 directory can be removed in that. For example, see
7755                 <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
7756                 href=
7757                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/textproc/scrollkeeper/README.html"
7758                 target="_top"><code xmlns="" class=
7759                 "filename">textproc/scrollkeeper</code></a>, which
7760                 removes the shared directory <code xmlns=
7761                 "http://www.w3.org/TR/xhtml1/transitional" class=
7762                 "filename">share/omf</code>.</p>
7763               </li>
7764
7765               <li>
7766                 <p>If the packages using the directory are not
7767                 related at all (they have no common dependencies),
7768                 a *-dirs package is used.</p>
7769               </li>
7770             </ol>
7771           </div>
7772
7773           <p>From now on, we'll discuss the second solution. To get
7774           an idea of the *-dirs packages available, issue:</p>
7775           <pre class="programlisting">
7776     <code class="prompt">%</code> cd .../pkgsrc
7777     <code class="prompt">%</code> ls -d */*-dirs
7778 </pre>
7779
7780           <p>Their use from other packages is very simple. The
7781           <code class="varname">USE_DIRS</code> variable takes a
7782           list of package names (without the &#8220;<span class=
7783           "quote">-dirs</span>&#8221; part) together with the
7784           required version number (always pick the latest one when
7785           writing new packages).</p>
7786
7787           <p>For example, if a package installs files under
7788           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
7789           class="filename">share/applications</code>, it should
7790           have the following line in it:</p>
7791           <pre class="programlisting">
7792     USE_DIRS+=      xdg-1.1
7793 </pre>
7794
7795           <p>After regenerating the PLIST using
7796           <span><strong class="command">make
7797           print-PLIST</strong></span>, you should get the right
7798           (commented out) lines.</p>
7799
7800           <p>Note that even if your package is using <code xmlns=
7801           "http://www.w3.org/TR/xhtml1/transitional" class=
7802           "filename">$X11BASE</code>, it must not depend on the
7803           *-x11-dirs packages. Just specify the name without that
7804           part and pkgsrc (in particular, <code xmlns=
7805           "http://www.w3.org/TR/xhtml1/transitional" class=
7806           "filename">mk/dirs.mk</code>) will take care of it.</p>
7807         </div>
7808       </div>
7809
7810       <div class="chapter" lang="en" xml:lang="en">
7811         <div class="titlepage">
7812           <div>
7813             <div>
7814               <h2 class="title"><a name="buildlink" id=
7815               "buildlink"></a>Chapter&nbsp;11.&nbsp;Buildlink
7816               methodology</h2>
7817             </div>
7818           </div>
7819         </div>
7820
7821         <div class="toc">
7822           <p><b>Table of Contents</b></p>
7823
7824           <dl>
7825             <dt><span class="sect1"><a href=
7826             "#converting-to-buildlink3">11.1. Converting packages
7827             to use buildlink3</a></span></dt>
7828
7829             <dt><span class="sect1"><a href=
7830             "#creating-buildlink3.mk">11.2. Writing <code xmlns=
7831             "http://www.w3.org/TR/xhtml1/transitional" class=
7832             "filename">buildlink3.mk</code> files</a></span></dt>
7833
7834             <dd>
7835               <dl>
7836                 <dt><span class="sect2"><a href=
7837                 "#anatomy-of-bl3">11.2.1. Anatomy of a
7838                 buildlink3.mk file</a></span></dt>
7839
7840                 <dt><span class="sect2"><a href=
7841                 "#updating-buildlink-depends">11.2.2. Updating
7842                 <code class="varname">BUILDLINK_DEPENDS.<em class=
7843                 "replaceable"><code>pkg</code></em></code> in
7844                 <code xmlns=
7845                 "http://www.w3.org/TR/xhtml1/transitional" class=
7846                 "filename">buildlink3.mk</code>
7847                 files</a></span></dt>
7848               </dl>
7849             </dd>
7850
7851             <dt><span class="sect1"><a href=
7852             "#writing-builtin.mk">11.3. Writing <code xmlns=
7853             "http://www.w3.org/TR/xhtml1/transitional" class=
7854             "filename">builtin.mk</code> files</a></span></dt>
7855
7856             <dd>
7857               <dl>
7858                 <dt><span class="sect2"><a href=
7859                 "#anatomy-of-builtin.mk">11.3.1. Anatomy of a
7860                 <code xmlns=
7861                 "http://www.w3.org/TR/xhtml1/transitional" class=
7862                 "filename">builtin.mk</code> file</a></span></dt>
7863
7864                 <dt><span class="sect2"><a href=
7865                 "#native-or-pkgsrc-preference">11.3.2. Global
7866                 preferences for native or pkgsrc
7867                 software</a></span></dt>
7868               </dl>
7869             </dd>
7870           </dl>
7871         </div>
7872
7873         <p>Buildlink is a framework in pkgsrc that controls what
7874         headers and libraries are seen by a package's configure and
7875         build processes. This is implemented in a two step
7876         process:</p>
7877
7878         <div class="orderedlist">
7879           <ol type="1">
7880             <li>
7881               <p>Symlink headers and libraries for dependencies
7882               into <code class="varname">BUILDLINK_DIR</code>,
7883               which by default is a subdirectory of <code class=
7884               "varname">WRKDIR</code>.</p>
7885             </li>
7886
7887             <li>
7888               <p>Create wrapper scripts that are used in place of
7889               the normal compiler tools that translate <code class=
7890               "option">-I${LOCALBASE}/include</code> and
7891               <code class="option">-L${LOCALBASE}/lib</code> into
7892               references to <code class=
7893               "varname">BUILDLINK_DIR</code>. The wrapper scripts
7894               also make native compiler on some operating systems
7895               look like GCC, so that packages that expect GCC won't
7896               require modifications to build with those native
7897               compilers.</p>
7898             </li>
7899           </ol>
7900         </div>
7901
7902         <p>This normalizes the environment in which a package is
7903         built so that the package may be built consistently despite
7904         what other software may be installed. Please note that the
7905         normal system header and library paths, e.g. <code xmlns=
7906         "http://www.w3.org/TR/xhtml1/transitional" class=
7907         "filename">/usr/include</code>, <code xmlns=
7908         "http://www.w3.org/TR/xhtml1/transitional" class=
7909         "filename">/usr/lib</code>, etc., are always searched --
7910         buildlink3 is designed to insulate the package build from
7911         non-system-supplied software.</p>
7912
7913         <div class="sect1" lang="en" xml:lang="en">
7914           <div class="titlepage">
7915             <div>
7916               <div>
7917                 <h2 class="title" style="clear: both"><a name=
7918                 "converting-to-buildlink3" id=
7919                 "converting-to-buildlink3"></a>11.1.&nbsp;Converting
7920                 packages to use buildlink3</h2>
7921               </div>
7922             </div>
7923           </div>
7924
7925           <p>The process of converting packages to use the
7926           buildlink3 framework (&#8220;<span class=
7927           "quote">bl3ifying</span>&#8221;) is fairly
7928           straightforward. The things to keep in mind are:</p>
7929
7930           <div class="orderedlist">
7931             <ol type="1">
7932               <li>
7933                 <p>Ensure that the build always calls the wrapper
7934                 scripts instead of the actual toolchain. Some
7935                 packages are tricky, and the only way to know for
7936                 sure is the check <code xmlns=
7937                 "http://www.w3.org/TR/xhtml1/transitional" class=
7938                 "filename">${WRKDIR}/.work.log</code> to see if the
7939                 wrappers are being invoked.</p>
7940               </li>
7941
7942               <li>
7943                 <p>Don't override <code class=
7944                 "varname">PREFIX</code> from within the package
7945                 Makefile, e.g. Java VMs, standalone shells, etc.,
7946                 because the code to symlink files into <code xmlns=
7947                 "http://www.w3.org/TR/xhtml1/transitional" class=
7948                 "filename">${BUILDLINK_DIR}</code> looks for files
7949                 relative to &#8220;<span class="quote">pkg_info -qp
7950                 <em class=
7951                 "replaceable"><code>pkgname</code></em></span>&#8221;.</p>
7952               </li>
7953
7954               <li>
7955                 <p>Remember that <span class=
7956                 "emphasis"><em>only</em></span> the <code xmlns=
7957                 "http://www.w3.org/TR/xhtml1/transitional" class=
7958                 "filename">buildlink3.mk</code> files that you list
7959                 in a package's Makefile are added as dependencies
7960                 for that package.</p>
7961               </li>
7962             </ol>
7963           </div>
7964
7965           <p>If a dependency on a particular package is required
7966           for its libraries and headers, then we replace:</p>
7967           <pre class="programlisting">
7968     DEPENDS+=   foo&gt;=1.1.0:../../category/foo
7969 </pre>
7970
7971           <p>with</p>
7972           <pre class="programlisting">
7973     .include "../../category/foo/buildlink3.mk"
7974 </pre>
7975
7976           <p>The buildlink3.mk files usually define the required
7977           dependencies. If you need a newer version of the
7978           dependency when using buildlink3.mk files, then you can
7979           define it in your Makefile; for example:</p>
7980           <pre class="programlisting">
7981     BUILDLINK_DEPENDS.foo+=   foo&gt;=1.1.0
7982     .include "../../category/foo/buildlink3.mk"
7983 </pre>
7984
7985           <p>There are several <code xmlns=
7986           "http://www.w3.org/TR/xhtml1/transitional" class=
7987           "filename">buildlink3.mk</code> files in <code xmlns=
7988           "http://www.w3.org/TR/xhtml1/transitional" class=
7989           "filename">pkgsrc/mk</code> that handle special package
7990           issues:</p>
7991
7992           <div class="itemizedlist">
7993             <ul type="disc">
7994               <li>
7995                 <p><code xmlns=
7996                 "http://www.w3.org/TR/xhtml1/transitional" class=
7997                 "filename">bdb.buildlink3.mk</code> chooses either
7998                 the native or a pkgsrc Berkeley DB implementation
7999                 based on the values of <code class=
8000                 "varname">BDB_ACCEPTED</code> and <code class=
8001                 "varname">BDB_DEFAULT</code>.</p>
8002               </li>
8003
8004               <li>
8005                 <p><code xmlns=
8006                 "http://www.w3.org/TR/xhtml1/transitional" class=
8007                 "filename">curses.buildlink3.mk</code>: If the
8008                 system comes with neither Curses nor NCurses, this
8009                 will take care to install the <a xmlns=
8010                 "http://www.w3.org/TR/xhtml1/transitional" href=
8011                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/ncurses/README.html"
8012                 target="_top"><code xmlns="" class=
8013                 "filename">devel/ncurses</code></a> package.</p>
8014               </li>
8015
8016               <li>
8017                 <p><code xmlns=
8018                 "http://www.w3.org/TR/xhtml1/transitional" class=
8019                 "filename">krb5.buildlink3.mk</code> uses the value
8020                 of <code class="varname">KRB5_ACCEPTED</code> to
8021                 choose between adding a dependency on Heimdal or
8022                 MIT-krb5 for packages that require a Kerberos 5
8023                 implementation.</p>
8024               </li>
8025
8026               <li>
8027                 <p><code xmlns=
8028                 "http://www.w3.org/TR/xhtml1/transitional" class=
8029                 "filename">motif.buildlink3.mk</code> checks for a
8030                 system-provided Motif installation or adds a
8031                 dependency on <a xmlns=
8032                 "http://www.w3.org/TR/xhtml1/transitional" href=
8033                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/lesstif/README.html"
8034                 target="_top"><code xmlns="" class=
8035                 "filename">x11/lesstif</code></a> or <a xmlns=
8036                 "http://www.w3.org/TR/xhtml1/transitional" href=
8037                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/openmotif/README.html"
8038                 target="_top"><code xmlns="" class=
8039                 "filename">x11/openmotif</code></a>.</p>
8040               </li>
8041
8042               <li>
8043                 <p><code xmlns=
8044                 "http://www.w3.org/TR/xhtml1/transitional" class=
8045                 "filename">ossaudio.buildlink3.mk</code> defines
8046                 several variables that may be used by packages that
8047                 use the Open Sound System (OSS) API.</p>
8048               </li>
8049
8050               <li>
8051                 <p><code xmlns=
8052                 "http://www.w3.org/TR/xhtml1/transitional" class=
8053                 "filename">pgsql.buildlink3.mk</code> will accept
8054                 either Postgres 7.3 or 7.4, whichever is found
8055                 installed. See the file for more information.</p>
8056               </li>
8057
8058               <li>
8059                 <p><code xmlns=
8060                 "http://www.w3.org/TR/xhtml1/transitional" class=
8061                 "filename">pthread.buildlink3.mk</code> uses the
8062                 value of <code class="varname">PTHREAD_OPTS</code>
8063                 and checks for native pthreads or adds a dependency
8064                 on <a xmlns=
8065                 "http://www.w3.org/TR/xhtml1/transitional" href=
8066                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/pth/README.html"
8067                 target="_top"><code xmlns="" class=
8068                 "filename">devel/pth</code></a> as needed.</p>
8069               </li>
8070
8071               <li>
8072                 <p><code xmlns=
8073                 "http://www.w3.org/TR/xhtml1/transitional" class=
8074                 "filename">xaw.buildlink3.mk</code> uses the value
8075                 of <code class="varname">XAW_TYPE</code> to choose
8076                 a particular Athena widgets library.</p>
8077               </li>
8078             </ul>
8079           </div>
8080
8081           <p>The comments in those <code xmlns=
8082           "http://www.w3.org/TR/xhtml1/transitional" class=
8083           "filename">buildlink3.mk</code> files provide a more
8084           complete description of how to use them properly.</p>
8085         </div>
8086
8087         <div class="sect1" lang="en" xml:lang="en">
8088           <div class="titlepage">
8089             <div>
8090               <div>
8091                 <h2 class="title" style="clear: both"><a name=
8092                 "creating-buildlink3.mk" id=
8093                 "creating-buildlink3.mk"></a>11.2.&nbsp;Writing
8094                 <code xmlns=
8095                 "http://www.w3.org/TR/xhtml1/transitional" class=
8096                 "filename">buildlink3.mk</code> files</h2>
8097               </div>
8098             </div>
8099           </div>
8100
8101           <p>A package's <code xmlns=
8102           "http://www.w3.org/TR/xhtml1/transitional" class=
8103           "filename">buildlink3.mk</code> file is included by
8104           Makefiles to indicate the need to compile and link
8105           against header files and libraries provided by the
8106           package. A <code xmlns=
8107           "http://www.w3.org/TR/xhtml1/transitional" class=
8108           "filename">buildlink3.mk</code> file should always
8109           provide enough information to add the correct type of
8110           dependency relationship and include any other
8111           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
8112           class="filename">buildlink3.mk</code> files that it needs
8113           to find headers and libraries that it needs in turn.</p>
8114
8115           <p>To generate an initial <code xmlns=
8116           "http://www.w3.org/TR/xhtml1/transitional" class=
8117           "filename">buildlink3.mk</code> file for further editing,
8118           Rene Hexel's <a xmlns=
8119           "http://www.w3.org/TR/xhtml1/transitional" href=
8120           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/createbuildlink/README.html"
8121           target="_top"><code xmlns="" class=
8122           "filename">pkgtools/createbuildlink</code></a> package is
8123           highly recommended. For most packages, the following
8124           command will generate a good starting point for
8125           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
8126           class="filename">buildlink3.mk</code> files:</p>
8127           <pre class="screen">
8128 <code class="prompt">%</code> <strong class=
8129 "userinput"><code>cd pkgsrc/<em class=
8130 "replaceable"><code>category</code></em>/<em class=
8131 "replaceable"><code>pkgdir</code></em>
8132 <code class=
8133 "prompt">%</code> createbuildlink &gt;buildlink3.mk</code></strong>
8134 </pre>
8135
8136           <div class="sect2" lang="en" xml:lang="en">
8137             <div class="titlepage">
8138               <div>
8139                 <div>
8140                   <h3 class="title"><a name="anatomy-of-bl3" id=
8141                   "anatomy-of-bl3"></a>11.2.1. Anatomy of a
8142                   buildlink3.mk file</h3>
8143                 </div>
8144               </div>
8145             </div>
8146
8147             <p>The following real-life example <code xmlns=
8148             "http://www.w3.org/TR/xhtml1/transitional" class=
8149             "filename">buildlink3.mk</code> is taken from
8150             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
8151             class="filename">pkgsrc/graphics/tiff</code>:</p>
8152             <pre class="programlisting">
8153     # $NetBSD: buildlink3.mk,v 1.7 2004/03/18 09:12:12 jlam Exp $
8154
8155     BUILDLINK_DEPTH:=       ${BUILDLINK_DEPTH}+
8156     TIFF_BUILDLINK3_MK:=    ${TIFF_BUILDLINK3_MK}+
8157
8158     .if !empty(BUILDLINK_DEPTH:M+)
8159     BUILDLINK_DEPENDS+=     tiff
8160     .endif
8161
8162     BUILDLINK_PACKAGES:=    ${BUILDLINK_PACKAGES:Ntiff}
8163     BUILDLINK_PACKAGES+=    tiff
8164
8165     .if !empty(TIFF_BUILDLINK3_MK:M+)
8166     BUILDLINK_DEPENDS.tiff+=        tiff&gt;=3.6.1
8167     BUILDLINK_PKGSRCDIR.tiff?=      ../../graphics/tiff
8168     .endif  # TIFF_BUILDLINK3_MK
8169
8170     .include "../../devel/zlib/buildlink3.mk"
8171     .include "../../graphics/jpeg/buildlink3.mk"
8172
8173     BUILDLINK_DEPTH:=       ${BUILDLINK_DEPTH:S/+$//}
8174 </pre>
8175
8176             <p>The header and footer manipulate <code class=
8177             "varname">BUILDLINK_DEPTH</code>, which is common
8178             across all <code xmlns=
8179             "http://www.w3.org/TR/xhtml1/transitional" class=
8180             "filename">buildlink3.mk</code> files and is used to
8181             track at what depth we are including <code xmlns=
8182             "http://www.w3.org/TR/xhtml1/transitional" class=
8183             "filename">buildlink3.mk</code> files.</p>
8184
8185             <p>The first section controls if the dependency on
8186             <em class="replaceable"><code>pkg</code></em> is added.
8187             <code class="varname">BUILDLINK_DEPENDS</code> is the
8188             global list of packages for which dependencies are
8189             added by buildlink3.</p>
8190
8191             <p>The second section advises pkgsrc that the
8192             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
8193             class="filename">buildlink3.mk</code> file for
8194             <em class="replaceable"><code>pkg</code></em> has been
8195             included at some point. <code class=
8196             "varname">BUILDLINK_PACKAGES</code> is the global list
8197             of packages for which <code xmlns=
8198             "http://www.w3.org/TR/xhtml1/transitional" class=
8199             "filename">buildlink3.mk</code> files have been
8200             included. It must <span class=
8201             "emphasis"><em>always</em></span> be appended to within
8202             a <code xmlns=
8203             "http://www.w3.org/TR/xhtml1/transitional" class=
8204             "filename">buildlink3.mk</code> file.</p>
8205
8206             <p>The third section is protected from multiple
8207             inclusion and controls how the dependency on <em class=
8208             "replaceable"><code>pkg</code></em> is added. Several
8209             important variables are set in the section:</p>
8210
8211             <div class="itemizedlist">
8212               <ul type="disc">
8213                 <li>
8214                   <p><code class=
8215                   "varname">BUILDLINK_DEPENDS.<em class=
8216                   "replaceable"><code>pkg</code></em></code> is the
8217                   actual dependency recorded in the installed
8218                   package; this should always be set using
8219                   <span><strong class="command">+=</strong></span>
8220                   to ensure that we're appending to any
8221                   pre-existing list of values. This variable should
8222                   be set to the first version of the package that
8223                   had the last change in the major number of a
8224                   shared library or that had a major API
8225                   change.</p>
8226                 </li>
8227
8228                 <li>
8229                   <p><code class=
8230                   "varname">BUILDLINK_PKGSRCDIR.<em class=
8231                   "replaceable"><code>pkg</code></em></code> is the
8232                   location of the <em class=
8233                   "replaceable"><code>pkg</code></em> pkgsrc
8234                   directory.</p>
8235                 </li>
8236
8237                 <li>
8238                   <p><code class=
8239                   "varname">BUILDLINK_DEPMETHOD.<em class=
8240                   "replaceable"><code>pkg</code></em></code> (not
8241                   shown above) controls whether we use <code class=
8242                   "varname">BUILD_DEPENDS</code> or <code class=
8243                   "varname">DEPENDS</code> to add the dependency on
8244                   <em class="replaceable"><code>pkg</code></em>.
8245                   The build dependency is selected by setting
8246                   <code class=
8247                   "varname">BUILDLINK_DEPMETHOD.<em class=
8248                   "replaceable"><code>pkg</code></em></code> to
8249                   &#8220;<span class="quote">build</span>&#8221;.
8250                   By default, the full dependency is used.</p>
8251                 </li>
8252
8253                 <li>
8254                   <p><code class=
8255                   "varname">BUILDLINK_INCDIRS.<em class=
8256                   "replaceable"><code>pkg</code></em></code> and
8257                   <code class=
8258                   "varname">BUILDLINK_LIBDIRS.<em class="replaceable">
8259                   <code>pkg</code></em></code> (not shown above)
8260                   are lists of subdirectories of <code xmlns=
8261                   "http://www.w3.org/TR/xhtml1/transitional" class=
8262                   "filename">${BUILDLINK_PREFIX.<em class=
8263                   "replaceable"><code>pkg</code></em>}</code> to
8264                   add to the header and library search paths. These
8265                   default to &#8220;<span class=
8266                   "quote">include</span>&#8221; and
8267                   &#8220;<span class="quote">lib</span>&#8221;
8268                   respectively.</p>
8269                 </li>
8270
8271                 <li>
8272                   <p><code class=
8273                   "varname">BUILDLINK_CPPFLAGS.<em class=
8274                   "replaceable"><code>pkg</code></em></code> (not
8275                   shown above) is the list of preprocessor flags to
8276                   add to <code class="varname">CPPFLAGS</code>,
8277                   which are passed on to the configure and build
8278                   phases. The &#8220;<span class=
8279                   "quote">-I</span>&#8221; option should be avoided
8280                   and instead be handled using <code class=
8281                   "varname">BUILDLINK_INCDIRS.<em class=
8282                   "replaceable"><code>pkg</code></em></code> as
8283                   above.</p>
8284                 </li>
8285               </ul>
8286             </div>
8287
8288             <p>The following variables are all optionally defined
8289             within this second section (protected against multiple
8290             inclusion) and control which package files are
8291             symlinked into <code xmlns=
8292             "http://www.w3.org/TR/xhtml1/transitional" class=
8293             "filename">${BUILDLINK_DIR}</code> and how their names
8294             are transformed during the symlinking:</p>
8295
8296             <div class="itemizedlist">
8297               <ul type="disc">
8298                 <li>
8299                   <p><code class=
8300                   "varname">BUILDLINK_FILES.<em class=
8301                   "replaceable"><code>pkg</code></em></code> (not
8302                   shown above) is a shell glob pattern relative to
8303                   <code xmlns=
8304                   "http://www.w3.org/TR/xhtml1/transitional" class=
8305                   "filename">${BUILDLINK_PREFIX.<em class=
8306                   "replaceable"><code>pkg</code></em>}</code> to be
8307                   symlinked into <code xmlns=
8308                   "http://www.w3.org/TR/xhtml1/transitional" class=
8309                   "filename">${BUILDLINK_DIR}</code>, e.g.
8310                   <code xmlns=
8311                   "http://www.w3.org/TR/xhtml1/transitional" class=
8312                   "filename">include/*.h</code>.</p>
8313                 </li>
8314
8315                 <li>
8316                   <p><code class=
8317                   "varname">BUILDLINK_FILES_CMD.<em class=
8318                   "replaceable"><code>pkg</code></em></code> (not
8319                   shown above) is a shell pipeline that outputs to
8320                   stdout a list of files relative to <code xmlns=
8321                   "http://www.w3.org/TR/xhtml1/transitional" class=
8322                   "filename">${BUILDLINK_PREFIX.<em class=
8323                   "replaceable"><code>pkg</code></em>}</code>. The
8324                   resulting files are to be symlinked into
8325                   <code xmlns=
8326                   "http://www.w3.org/TR/xhtml1/transitional" class=
8327                   "filename">${BUILDLINK_DIR}</code>. By default,
8328                   this takes the <code xmlns=
8329                   "http://www.w3.org/TR/xhtml1/transitional" class=
8330                   "filename">+CONTENTS</code> of a <em class=
8331                   "replaceable"><code>pkg</code></em> and filters
8332                   it through <code class=
8333                   "varname">${BUILDLINK_CONTENTS_FILTER.<em class=
8334                   "replaceable"><code>pkg</code></em>}</code>.</p>
8335                 </li>
8336
8337                 <li>
8338                   <p><code class=
8339                   "varname">BUILDLINK_CONTENTS_FILTER.<em class=
8340                   "replaceable"><code>pkg</code></em></code> (not
8341                   shown above) is a filter command that filters
8342                   <code xmlns=
8343                   "http://www.w3.org/TR/xhtml1/transitional" class=
8344                   "filename">+CONTENTS</code> input into a list of
8345                   files relative to <code xmlns=
8346                   "http://www.w3.org/TR/xhtml1/transitional" class=
8347                   "filename">${BUILDLINK_PREFIX.<em class=
8348                   "replaceable"><code>pkg</code></em>}</code> on
8349                   stdout. By default for overwrite packages,
8350                   <code class=
8351                   "varname">BUILDLINK_CONTENTS_FILTER.<em class=
8352                   "replaceable"><code>pkg</code></em></code>
8353                   outputs the contents of the <code xmlns=
8354                   "http://www.w3.org/TR/xhtml1/transitional" class=
8355                   "filename">include</code> and <code xmlns=
8356                   "http://www.w3.org/TR/xhtml1/transitional" class=
8357                   "filename">lib</code> directories in the package
8358                   <code xmlns=
8359                   "http://www.w3.org/TR/xhtml1/transitional" class=
8360                   "filename">+CONTENTS</code>, and for pkgviews
8361                   packages, it outputs any libtool archives in
8362                   <code xmlns=
8363                   "http://www.w3.org/TR/xhtml1/transitional" class=
8364                   "filename">lib</code> directories.</p>
8365                 </li>
8366
8367                 <li>
8368                   <p><code class=
8369                   "varname">BUILDLINK_TRANSFORM.<em class=
8370                   "replaceable"><code>pkg</code></em></code> (not
8371                   shown above) is a list of sed arguments used to
8372                   transform the name of the source filename into a
8373                   destination filename, e.g. <span><strong class=
8374                   "command">-e
8375                   "s|/curses.h|/ncurses.h|g"</strong></span>.</p>
8376                 </li>
8377               </ul>
8378             </div>
8379
8380             <p>The last section includes any <code xmlns=
8381             "http://www.w3.org/TR/xhtml1/transitional" class=
8382             "filename">buildlink3.mk</code> needed for <em class=
8383             "replaceable"><code>pkg</code></em>'s library
8384             dependencies. Including these <code xmlns=
8385             "http://www.w3.org/TR/xhtml1/transitional" class=
8386             "filename">buildlink3.mk</code> files means that the
8387             headers and libraries for these dependencies are also
8388             symlinked into <code xmlns=
8389             "http://www.w3.org/TR/xhtml1/transitional" class=
8390             "filename">${BUILDLINK_DIR}</code> whenever the
8391             <em class="replaceable"><code>pkg</code></em>
8392             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
8393             class="filename">buildlink3.mk</code> file is
8394             included.</p>
8395           </div>
8396
8397           <div class="sect2" lang="en" xml:lang="en">
8398             <div class="titlepage">
8399               <div>
8400                 <div>
8401                   <h3 class="title"><a name=
8402                   "updating-buildlink-depends" id=
8403                   "updating-buildlink-depends"></a>11.2.2. Updating
8404                   <code class=
8405                   "varname">BUILDLINK_DEPENDS.<em class="replaceable">
8406                   <code>pkg</code></em></code> in <code xmlns=
8407                   "http://www.w3.org/TR/xhtml1/transitional" class=
8408                   "filename">buildlink3.mk</code> files</h3>
8409                 </div>
8410               </div>
8411             </div>
8412
8413             <p>There are two situations that require increasing the
8414             dependency listed in <code class=
8415             "varname">BUILDLINK_DEPENDS.<em class=
8416             "replaceable"><code>pkg</code></em></code> after a
8417             package update:</p>
8418
8419             <div class="orderedlist">
8420               <ol type="1">
8421                 <li>
8422                   <p>if the sonames (major number of the library
8423                   version) of any installed shared libraries
8424                   change.</p>
8425                 </li>
8426
8427                 <li>
8428                   <p>if the API or interface to the header files
8429                   change.</p>
8430                 </li>
8431               </ol>
8432             </div>
8433
8434             <p>In these cases, <code class=
8435             "varname">BUILDLINK_DEPENDS.<em class=
8436             "replaceable"><code>pkg</code></em></code> should be
8437             adjusted to require at least the new package version.
8438             In some cases, the packages that depend on this new
8439             version may need their <code class=
8440             "varname">PKGREVISION</code>s increased and, if they
8441             have <code xmlns=
8442             "http://www.w3.org/TR/xhtml1/transitional" class=
8443             "filename">buildlink3.mk</code> files, their
8444             <code class="varname">BUILDLINK_DEPENDS.<em class=
8445             "replaceable"><code>pkg</code></em></code> adjusted,
8446             too. This is needed so that binary packages made using
8447             it will require the correct package dependency and not
8448             settle for an older one which will not contain the
8449             necessary shared libraries.</p>
8450
8451             <p>Please take careful consideration before adjusting
8452             <code class="varname">BUILDLINK_DEPENDS.<em class=
8453             "replaceable"><code>pkg</code></em></code> as we don't
8454             want to cause unneeded package deletions and rebuilds.
8455             In many cases, new versions of packages work just fine
8456             with older dependencies. See <a href="#dependencies"
8457             title="15.1.4.&nbsp;Handling dependencies">Section
8458             15.1.4, &#8220;Handling dependencies&#8221;</a> for
8459             more information about dependencies on other packages,
8460             including the <code class=
8461             "varname">BUILDLINK_RECOMMENDED</code> and <code class=
8462             "varname">RECOMMENDED</code> definitions.</p>
8463           </div>
8464         </div>
8465
8466         <div class="sect1" lang="en" xml:lang="en">
8467           <div class="titlepage">
8468             <div>
8469               <div>
8470                 <h2 class="title" style="clear: both"><a name=
8471                 "writing-builtin.mk" id=
8472                 "writing-builtin.mk"></a>11.3.&nbsp;Writing
8473                 <code xmlns=
8474                 "http://www.w3.org/TR/xhtml1/transitional" class=
8475                 "filename">builtin.mk</code> files</h2>
8476               </div>
8477             </div>
8478           </div>
8479
8480           <p>Some packages in pkgsrc install headers and libraries
8481           that coincide with headers and libraries present in the
8482           base system. Aside from a <code xmlns=
8483           "http://www.w3.org/TR/xhtml1/transitional" class=
8484           "filename">buildlink3.mk</code> file, these packages
8485           should also include a <code xmlns=
8486           "http://www.w3.org/TR/xhtml1/transitional" class=
8487           "filename">builtin.mk</code> file that includes the
8488           necessary checks to decide whether using the built-in
8489           software or the pkgsrc software is appropriate.</p>
8490
8491           <p>The only requirements of a builtin.mk file for
8492           <em class="replaceable"><code>pkg</code></em> are:</p>
8493
8494           <div class="orderedlist">
8495             <ol type="1">
8496               <li>
8497                 <p>It should set <code class=
8498                 "varname">USE_BUILTIN.<em class=
8499                 "replaceable"><code>pkg</code></em></code> to
8500                 either &#8220;<span class="quote">yes</span>&#8221;
8501                 or &#8220;<span class="quote">no</span>&#8221;
8502                 after it is included.</p>
8503               </li>
8504
8505               <li>
8506                 <p>It should <span class=
8507                 "emphasis"><em>not</em></span> override any
8508                 <code class="varname">USE_BUILTIN.<em class=
8509                 "replaceable"><code>pkg</code></em></code> which is
8510                 already set before the <code xmlns=
8511                 "http://www.w3.org/TR/xhtml1/transitional" class=
8512                 "filename">builtin.mk</code> file is included.</p>
8513               </li>
8514
8515               <li>
8516                 <p>It should be written to allow multiple
8517                 inclusion. This is <span class=
8518                 "emphasis"><em>very</em></span> important and takes
8519                 careful attention to <code xmlns=
8520                 "http://www.w3.org/TR/xhtml1/transitional" class=
8521                 "filename">Makefile</code> coding.</p>
8522               </li>
8523             </ol>
8524           </div>
8525
8526           <div class="sect2" lang="en" xml:lang="en">
8527             <div class="titlepage">
8528               <div>
8529                 <div>
8530                   <h3 class="title"><a name="anatomy-of-builtin.mk"
8531                   id=
8532                   "anatomy-of-builtin.mk"></a>11.3.1.&nbsp;Anatomy
8533                   of a <code xmlns=
8534                   "http://www.w3.org/TR/xhtml1/transitional" class=
8535                   "filename">builtin.mk</code> file</h3>
8536                 </div>
8537               </div>
8538             </div>
8539
8540             <p>The following is the recommended template for
8541             builtin.mk files:</p>
8542             <pre class="programlisting">
8543     .if !defined(IS_BUILTIN.foo)
8544     #
8545     # IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
8546     # genuinely exists in the system or not.
8547     #
8548     IS_BUILTIN.foo?=        no
8549
8550     # BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
8551     # version can be determined.
8552     #
8553     .  if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
8554     BUILTIN_PKG.foo?=       foo-1.0
8555     .  endif
8556     .endif  # IS_BUILTIN.foo
8557
8558     .if !defined(USE_BUILTIN.foo)
8559     USE_BUILTIN.foo?=       ${IS_BUILTIN.foo}
8560     .  if defined(BUILTIN_PKG.foo)
8561     .    for _depend_ in ${BUILDLINK_DEPENDS.foo}
8562     .      if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
8563     USE_BUILTIN.foo!=                                                       \
8564           if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then     \
8565                   ${ECHO} "yes";                                            \
8566           else                                                              \
8567                   ${ECHO} "no";                                             \
8568           fi
8569     .      endif
8570     .    endfor
8571     .  endif
8572     .endif  # USE_BUILTIN.foo
8573
8574     CHECK_BUILTIN.foo?=     no
8575     .if !empty(CHECK_BUILTIN.foo:M[nN][oO])
8576     #
8577     # Here we place code that depends on whether USE_BUILTIN.foo is set to
8578     # "yes" or "no".
8579     #
8580     .endif  # CHECK_BUILTIN.foo
8581 </pre>
8582
8583             <p>The first section sets <code class=
8584             "varname">IS_BUILTIN.<em class=
8585             "replaceable"><code>pkg</code></em></code> depending on
8586             if <em class="replaceable"><code>pkg</code></em> really
8587             exists in the base system. This should not be a base
8588             system software with similar functionality to
8589             <em class="replaceable"><code>pkg</code></em>; it
8590             should only be &#8220;<span class=
8591             "quote">yes</span>&#8221; if the actual package is
8592             included as part of the base system. This variable is
8593             only used internally within the <code xmlns=
8594             "http://www.w3.org/TR/xhtml1/transitional" class=
8595             "filename">builtin.mk</code> file.</p>
8596
8597             <p>The second section sets <code class=
8598             "varname">BUILTIN_PKG.<em class=
8599             "replaceable"><code>pkg</code></em></code> to the
8600             version of <em class=
8601             "replaceable"><code>pkg</code></em> in the base system
8602             if it exists (if <code class=
8603             "varname">IS_BUILTIN.<em class=
8604             "replaceable"><code>pkg</code></em></code> is
8605             &#8220;<span class="quote">yes</span>&#8221;). This
8606             variable is only used internally within the
8607             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
8608             class="filename">builtin.mk</code> file.</p>
8609
8610             <p>The third section sets <code class=
8611             "varname">USE_BUILTIN.<em class=
8612             "replaceable"><code>pkg</code></em></code> and is
8613             <span class="emphasis"><em>required</em></span> in all
8614             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
8615             class="filename">builtin.mk</code> files. The code in
8616             this section must make the determination whether the
8617             built-in software is adequate to satisfy the
8618             dependencies listed in <code class=
8619             "varname">BUILDLINK_DEPENDS.<em class=
8620             "replaceable"><code>pkg</code></em></code>. This is
8621             typically done by comparing <code class=
8622             "varname">BUILTIN_PKG.<em class=
8623             "replaceable"><code>pkg</code></em></code> against each
8624             of the dependencies in <code class=
8625             "varname">BUILDLINK_DEPENDS.<em class=
8626             "replaceable"><code>pkg</code></em></code>.
8627             <code class="varname">USE_BUILTIN.<em class=
8628             "replaceable"><code>pkg</code></em></code> <span class=
8629             "emphasis"><em>must</em></span> be set to the correct
8630             value by the end of the <code xmlns=
8631             "http://www.w3.org/TR/xhtml1/transitional" class=
8632             "filename">builtin.mk</code> file. Note that
8633             <code class="varname">USE_BUILTIN.<em class=
8634             "replaceable"><code>pkg</code></em></code> may be
8635             &#8220;<span class="quote">yes</span>&#8221; even if
8636             <code class="varname">IS_BUILTIN.<em class=
8637             "replaceable"><code>pkg</code></em></code> is
8638             &#8220;<span class="quote">no</span>&#8221; because we
8639             may make the determination that the built-in version of
8640             the software is similar enough to be used as a
8641             replacement.</p>
8642
8643             <p>The last section is guarded by <code class=
8644             "varname">CHECK_BUILTIN.<em class=
8645             "replaceable"><code>pkg</code></em></code>, and
8646             includes code that uses the value of <code class=
8647             "varname">USE_BUILTIN.<em class=
8648             "replaceable"><code>pkg</code></em></code> set in the
8649             previous section. This typically includes, e.g., adding
8650             additional dependency restrictions and listing
8651             additional files to symlink into <code xmlns=
8652             "http://www.w3.org/TR/xhtml1/transitional" class=
8653             "filename">${BUILDLINK_DIR}</code> (via <code class=
8654             "varname">BUILDLINK_FILES.<em class=
8655             "replaceable"><code>pkg</code></em></code>).</p>
8656           </div>
8657
8658           <div class="sect2" lang="en" xml:lang="en">
8659             <div class="titlepage">
8660               <div>
8661                 <div>
8662                   <h3 class="title"><a name=
8663                   "native-or-pkgsrc-preference" id=
8664                   "native-or-pkgsrc-preference"></a>11.3.2.&nbsp;Global
8665                   preferences for native or pkgsrc software</h3>
8666                 </div>
8667               </div>
8668             </div>
8669
8670             <p>When building packages, it's possible to choose
8671             whether to set a global preference for using either the
8672             built-in (native) version or the pkgsrc version of
8673             software to satisfy a dependency. This is controlled by
8674             setting <code class="varname">PREFER_PKGSRC</code> and
8675             <code class="varname">PREFER_NATIVE</code>. These
8676             variables take values of either &#8220;<span class=
8677             "quote">yes</span>&#8221;, &#8220;<span class=
8678             "quote">no</span>&#8221;, or a list of packages.
8679             <code class="varname">PREFER_PKGSRC</code> tells pkgsrc
8680             to use the pkgsrc versions of software, while
8681             <code class="varname">PREFER_NATIVE</code> tells pkgsrc
8682             to use the built-in versions. Preferences are
8683             determined by the most specific instance of the package
8684             in either <code class="varname">PREFER_PKGSRC</code> or
8685             <code class="varname">PREFER_NATIVE</code>. If a
8686             package is specified in neither or in both variables,
8687             then <code class="varname">PREFER_PKGSRC</code> has
8688             precedence over <code class=
8689             "varname">PREFER_NATIVE</code>. For example, to require
8690             using pkgsrc versions of software for all but the most
8691             basic bits on a NetBSD system, you can set:</p>
8692             <pre class="programlisting">
8693     PREFER_PKGSRC=  yes
8694     PREFER_NATIVE=  getopt skey tcp_wrappers
8695 </pre>
8696
8697             <p>A package <span class=
8698             "emphasis"><em>must</em></span> have a <code xmlns=
8699             "http://www.w3.org/TR/xhtml1/transitional" class=
8700             "filename">builtin.mk</code> file to be listed in
8701             <code class="varname">PREFER_NATIVE</code>, otherwise
8702             it is simply ignored in that list.</p>
8703           </div>
8704         </div>
8705       </div>
8706
8707       <div class="chapter" lang="en" xml:lang="en">
8708         <div class="titlepage">
8709           <div>
8710             <div>
8711               <h2 class="title"><a name="pkginstall" id=
8712               "pkginstall"></a>Chapter&nbsp;12.&nbsp;The pkginstall
8713               framework</h2>
8714             </div>
8715           </div>
8716         </div>
8717
8718         <div class="toc">
8719           <p><b>Table of Contents</b></p>
8720
8721           <dl>
8722             <dt><span class="sect1"><a href=
8723             "#files-and-dirs-outside-prefix">12.1. Files and
8724             directories outside the installation
8725             prefix</a></span></dt>
8726
8727             <dd>
8728               <dl>
8729                 <dt><span class="sect2"><a href=
8730                 "#dirs-outside-prefix">12.1.1. Directory
8731                 manipulation</a></span></dt>
8732
8733                 <dt><span class="sect2"><a href=
8734                 "#files-outside-prefix">12.1.2. File
8735                 manipulation</a></span></dt>
8736               </dl>
8737             </dd>
8738
8739             <dt><span class="sect1"><a href="#conf-files">12.2.
8740             Configuration files</a></span></dt>
8741
8742             <dd>
8743               <dl>
8744                 <dt><span class="sect2"><a href=
8745                 "#conf-files-sysconfdir">12.2.1. How <code class=
8746                 "varname">PKG_SYSCONFDIR</code> is
8747                 set</a></span></dt>
8748
8749                 <dt><span class="sect2"><a href=
8750                 "#conf-files-configure">12.2.2. Telling the
8751                 software where configuration files
8752                 are</a></span></dt>
8753
8754                 <dt><span class="sect2"><a href=
8755                 "#conf-files-patching">12.2.3. Patching
8756                 installations</a></span></dt>
8757
8758                 <dt><span class="sect2"><a href=
8759                 "#conf-files-disable">12.2.4. Disabling handling of
8760                 configuration files</a></span></dt>
8761               </dl>
8762             </dd>
8763
8764             <dt><span class="sect1"><a href="#rcd-scripts">12.3.
8765             System startup scripts</a></span></dt>
8766
8767             <dd>
8768               <dl>
8769                 <dt><span class="sect2"><a href=
8770                 "#rcd-scripts-disable">12.3.1. Disabling handling
8771                 of system startup scripts</a></span></dt>
8772               </dl>
8773             </dd>
8774
8775             <dt><span class="sect1"><a href=
8776             "#users-and-groups">12.4. System users and
8777             groups</a></span></dt>
8778
8779             <dt><span class="sect1"><a href="#shells">12.5. System
8780             shells</a></span></dt>
8781
8782             <dd>
8783               <dl>
8784                 <dt><span class="sect2"><a href=
8785                 "#shells-disable">12.5.1. Disabling handling of
8786                 configuration files</a></span></dt>
8787               </dl>
8788             </dd>
8789           </dl>
8790         </div>
8791
8792         <p>This chapter describes the framework known as
8793         <code class="literal">pkginstall</code>, whose key features
8794         are:</p>
8795
8796         <div class="itemizedlist">
8797           <ul type="disc">
8798             <li>
8799               <p>Generic installation and manipulation of
8800               directories and files outside the pkgsrc-handled
8801               tree, <code class="varname">LOCALBASE</code>.</p>
8802             </li>
8803
8804             <li>
8805               <p>Automatic handling of configuration files during
8806               installation, provided that packages are correctly
8807               designed.</p>
8808             </li>
8809
8810             <li>
8811               <p>Generation and installation of system startup
8812               scripts.</p>
8813             </li>
8814
8815             <li>
8816               <p>Registration of system users and groups.</p>
8817             </li>
8818
8819             <li>
8820               <p>Registration of system shells.</p>
8821             </li>
8822           </ul>
8823         </div>
8824
8825         <p>The following sections inspect each of the above points
8826         in detail. Note that in order to use any of the described
8827         functionalities, you must add the following to your
8828         package's <code xmlns=
8829         "http://www.w3.org/TR/xhtml1/transitional" class=
8830         "filename">Makefile</code>:</p>
8831         <pre class="programlisting">
8832     USE_PKGINSTALL= YES
8833 </pre>
8834
8835         <p>You may be thinking that many of the things described
8836         here could be easily done with simple code in the package's
8837         post-installation target (<code class=
8838         "literal">post-install</code>). <span class=
8839         "emphasis"><em>This is incorrect</em></span>, as the code
8840         in them is only executed when building from source.
8841         Machines using binary packages could not benefit from it at
8842         all (as the code itself could be unavailable). Therefore,
8843         the only way to achieve any of the items described above is
8844         by means of the installation scripts, which are
8845         automatically generated by pkginstall.</p>
8846
8847         <div class="sect1" lang="en" xml:lang="en">
8848           <div class="titlepage">
8849             <div>
8850               <div>
8851                 <h2 class="title" style="clear: both"><a name=
8852                 "files-and-dirs-outside-prefix" id=
8853                 "files-and-dirs-outside-prefix"></a>12.1. Files and
8854                 directories outside the installation prefix</h2>
8855               </div>
8856             </div>
8857           </div>
8858
8859           <p>As you already know, the <code xmlns=
8860           "http://www.w3.org/TR/xhtml1/transitional" class=
8861           "filename">PLIST</code> file holds a list of files and
8862           directories that belong to a package. The names used in
8863           it are relative to the installation prefix (<code xmlns=
8864           "http://www.w3.org/TR/xhtml1/transitional" class=
8865           "filename">${PREFIX}</code>), which means that it cannot
8866           register files outside this directory (absolute path
8867           names are not allowed). Despite this restriction, some
8868           packages need to install files outside this location;
8869           e.g., under <code xmlns=
8870           "http://www.w3.org/TR/xhtml1/transitional" class=
8871           "filename">${VARBASE}</code> or <code xmlns=
8872           "http://www.w3.org/TR/xhtml1/transitional" class=
8873           "filename">${PKG_SYSCONFDIR}</code>.</p>
8874
8875           <p>The only way to achieve this is to create such files
8876           during installation time by using the installation
8877           scripts. These scripts can run arbitrary commands, so
8878           they have the potential to create and manage files
8879           anywhere in the file system. Here is where pkginstall
8880           comes into play: it provides generic scripts to abstract
8881           the manipulation of such files and directories based on
8882           variables set in the package's <code xmlns=
8883           "http://www.w3.org/TR/xhtml1/transitional" class=
8884           "filename">Makefile</code>. The rest of this section
8885           describes these variables.</p>
8886
8887           <div class="sect2" lang="en" xml:lang="en">
8888             <div class="titlepage">
8889               <div>
8890                 <div>
8891                   <h3 class="title"><a name="dirs-outside-prefix"
8892                   id="dirs-outside-prefix"></a>12.1.1. Directory
8893                   manipulation</h3>
8894                 </div>
8895               </div>
8896             </div>
8897
8898             <p>The following variables can be set to request the
8899             creation of directories anywhere in the file
8900             system:</p>
8901
8902             <div class="itemizedlist">
8903               <ul type="disc">
8904                 <li>
8905                   <p><code class="varname">MAKE_DIRS</code> and
8906                   <code class="varname">OWN_DIRS</code> contain a
8907                   list of directories that should be created and
8908                   should attempt to be destroyed by the
8909                   installation scripts. The difference between the
8910                   two is that the latter prompts the administrator
8911                   to remove any directories that may be left after
8912                   deinstallation (because they were not empty),
8913                   while the former does not.</p>
8914                 </li>
8915
8916                 <li>
8917                   <p><code class="varname">MAKE_DIRS_PERMS</code>
8918                   and <code class="varname">OWN_DIRS_PERMS</code>
8919                   contain a list of tuples describing which
8920                   directories should be created and should attempt
8921                   to be destroyed by the installation scripts. Each
8922                   tuple holds the following values, separated by
8923                   spaces: the directory name, its owner, its group
8924                   and its numerical mode. For example:</p>
8925                   <pre class="programlisting">
8926     MAKE_DIRS_PERMS+=         ${VARBASE}/foo/private ${ROOT_USER} ${ROOT_GROUP} 0700
8927 </pre>
8928
8929                   <p>The difference between the two is exactly the
8930                   same as their non-<code class=
8931                   "varname">PERMS</code> counterparts.</p>
8932                 </li>
8933               </ul>
8934             </div>
8935           </div>
8936
8937           <div class="sect2" lang="en" xml:lang="en">
8938             <div class="titlepage">
8939               <div>
8940                 <div>
8941                   <h3 class="title"><a name="files-outside-prefix"
8942                   id="files-outside-prefix"></a>12.1.2. File
8943                   manipulation</h3>
8944                 </div>
8945               </div>
8946             </div>
8947
8948             <p>Creating non-empty files outside the installation
8949             prefix is tricky because the <code xmlns=
8950             "http://www.w3.org/TR/xhtml1/transitional" class=
8951             "filename">PLIST</code> forces all files to be inside
8952             it. To overcome this problem, the only solution is to
8953             extract the file in the known place (i.e., inside the
8954             installation prefix) and copy it to the appropriate
8955             location during installation (done by the installation
8956             scripts generated by pkginstall). We will call the
8957             former the <span class="emphasis"><em>master
8958             file</em></span> in the following paragraphs, which
8959             describe the variables that can be used to
8960             automatically and consistently handle files outside the
8961             installation prefix:</p>
8962
8963             <div class="itemizedlist">
8964               <ul type="disc">
8965                 <li>
8966                   <p><code class="varname">CONF_FILES</code> and
8967                   <code class="varname">SUPPORT_FILES</code> are
8968                   pairs of master and target files. During
8969                   installation time, the master file is copied to
8970                   the target one if and only if the latter does not
8971                   exist. Upon deinstallation, the target file is
8972                   removed provided that it was not modified by the
8973                   installation.</p>
8974
8975                   <p>The difference between the two is that the
8976                   latter prompts the administrator to remove any
8977                   files that may be left after deinstallation
8978                   (because they were not empty), while the former
8979                   does not.</p>
8980                 </li>
8981
8982                 <li>
8983                   <p><code class="varname">CONF_FILES_PERMS</code>
8984                   and <code class=
8985                   "varname">SUPPORT_FILES_PERMS</code> contain
8986                   tuples describing master files as well as their
8987                   target locations. For each of them, it also
8988                   specifies their owner, their group and their
8989                   numeric permissions, in this order. For
8990                   example:</p>
8991                   <pre class="programlisting">
8992     SUPPORT_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile ${ROOT_USER} ${ROOT_GROUP} 0700
8993 </pre>
8994
8995                   <p>The difference between the two is exactly the
8996                   same as their non-<code class=
8997                   "varname">PERMS</code> counterparts.</p>
8998                 </li>
8999               </ul>
9000             </div>
9001           </div>
9002         </div>
9003
9004         <div class="sect1" lang="en" xml:lang="en">
9005           <div class="titlepage">
9006             <div>
9007               <div>
9008                 <h2 class="title" style="clear: both"><a name=
9009                 "conf-files" id="conf-files"></a>12.2.
9010                 Configuration files</h2>
9011               </div>
9012             </div>
9013           </div>
9014
9015           <p>Configuration files are special in the sense that they
9016           are installed in their own specific directory,
9017           <code class="varname">PKG_SYSCONFDIR</code>, and need
9018           special treatment during installation (most of which is
9019           automated by pkginstall). The main concept you must bear
9020           in mind is that files marked as configuration files are
9021           automatically copied to the right place (somewhere inside
9022           <code class="varname">PKG_SYSCONFDIR</code>) during
9023           installation <span class="emphasis"><em>if and only
9024           if</em></span> they didn't exist before. Similarly, they
9025           will not be removed if they have local modifications.
9026           This ensures that administrators never lose any custom
9027           changes they may have made.</p>
9028
9029           <div class="sect2" lang="en" xml:lang="en">
9030             <div class="titlepage">
9031               <div>
9032                 <div>
9033                   <h3 class="title"><a name="conf-files-sysconfdir"
9034                   id="conf-files-sysconfdir"></a>12.2.1. How
9035                   <code class="varname">PKG_SYSCONFDIR</code> is
9036                   set</h3>
9037                 </div>
9038               </div>
9039             </div>
9040
9041             <p>As said before, the <code class=
9042             "varname">PKG_SYSCONFDIR</code> variable specifies
9043             where configuration files shall be installed. Its
9044             contents are set based upon the following
9045             variables:</p>
9046
9047             <div class="itemizedlist">
9048               <ul type="disc">
9049                 <li>
9050                   <p><code class="varname">PKG_SYSCONFBASE</code>:
9051                   The configuration's root directory. Defaults to
9052                   <code xmlns=
9053                   "http://www.w3.org/TR/xhtml1/transitional" class=
9054                   "filename">${PREFIX}/etc</code> although it may
9055                   be overridden by the user to point to his
9056                   preferred location (e.g., <code xmlns=
9057                   "http://www.w3.org/TR/xhtml1/transitional" class=
9058                   "filename">/etc</code>, <code xmlns=
9059                   "http://www.w3.org/TR/xhtml1/transitional" class=
9060                   "filename">/etc/pkg</code>, etc.). Packages must
9061                   not use it directly.</p>
9062                 </li>
9063
9064                 <li>
9065                   <p><code class=
9066                   "varname">PKG_SYSCONFSUBDIR</code>: A
9067                   subdirectory of <code class=
9068                   "varname">PKG_SYSCONFBASE</code> under which the
9069                   configuration files for the package being built
9070                   shall be installed. The definition of this
9071                   variable only makes sense in the package's
9072                   <code xmlns=
9073                   "http://www.w3.org/TR/xhtml1/transitional" class=
9074                   "filename">Makefile</code> (i.e., it is not
9075                   user-customizable).</p>
9076
9077                   <p>As an example, consider the Apache package,
9078                   <a xmlns=
9079                   "http://www.w3.org/TR/xhtml1/transitional" href=
9080                   "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/apache2/README.html"
9081                   target="_top"><code xmlns="" class=
9082                   "filename">www/apache2</code></a>, which places
9083                   its configuration files under the <code xmlns=
9084                   "http://www.w3.org/TR/xhtml1/transitional" class=
9085                   "filename">httpd/</code> subdirectory of
9086                   <code class="varname">PKG_SYSCONFBASE</code>.
9087                   This should be set in the package Makefile.</p>
9088                 </li>
9089
9090                 <li>
9091                   <p><code class="varname">PKG_SYSCONFVAR</code>:
9092                   Specifies the name of the variable that holds
9093                   this package's configuration directory (if
9094                   different from <code class=
9095                   "varname">PKG_SYSCONFBASE</code>). It defaults to
9096                   <code class="varname">PKGBASE</code>'s value, and
9097                   is always prefixed with <code class=
9098                   "literal">PKG_SYSCONFDIR</code>.</p>
9099                 </li>
9100
9101                 <li>
9102                   <p><code class=
9103                   "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>:
9104                   Holds the directory where the configuration files
9105                   for the package identified by <code class=
9106                   "varname">PKG_SYSCONFVAR</code>'s shall be
9107                   placed.</p>
9108                 </li>
9109               </ul>
9110             </div>
9111
9112             <p>Based on the above variables, pkginstall determines
9113             the value of <code class=
9114             "varname">PKG_SYSCONFDIR</code>, which is the
9115             <span class="emphasis"><em>only</em></span> variable
9116             that can be used within a package to refer to its
9117             configuration directory. The algorithm used to set its
9118             value is basically the following:</p>
9119
9120             <div class="orderedlist">
9121               <ol type="1">
9122                 <li>
9123                   <p>If <code class=
9124                   "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>
9125                   is set, its value is used.</p>
9126                 </li>
9127
9128                 <li>
9129                   <p>If the previous variable is not defined but
9130                   <code class="varname">PKG_SYSCONFSUBDIR</code> is
9131                   set in the package's <code xmlns=
9132                   "http://www.w3.org/TR/xhtml1/transitional" class=
9133                   "filename">Makefile</code>, the resulting value
9134                   is <code xmlns=
9135                   "http://www.w3.org/TR/xhtml1/transitional" class=
9136                   "filename">${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</code>.</p>
9137                 </li>
9138
9139                 <li>
9140                   <p>Otherwise, it is set to <code xmlns=
9141                   "http://www.w3.org/TR/xhtml1/transitional" class=
9142                   "filename">${PKG_SYSCONFBASE}</code>.</p>
9143                 </li>
9144               </ol>
9145             </div>
9146
9147             <p>It is worth mentioning that <code xmlns=
9148             "http://www.w3.org/TR/xhtml1/transitional" class=
9149             "filename">${PKG_SYSCONFDIR}</code> is automatically
9150             added to <code xmlns=
9151             "http://www.w3.org/TR/xhtml1/transitional" class=
9152             "filename">OWN_DIRS</code>. See <a href=
9153             "#dirs-outside-prefix" title=
9154             "12.1.1.&nbsp;Directory manipulation">Section 12.1.1,
9155             &#8220;Directory manipulation&#8221;</a> what this
9156             means.</p>
9157           </div>
9158
9159           <div class="sect2" lang="en" xml:lang="en">
9160             <div class="titlepage">
9161               <div>
9162                 <div>
9163                   <h3 class="title"><a name="conf-files-configure"
9164                   id="conf-files-configure"></a>12.2.2. Telling the
9165                   software where configuration files are</h3>
9166                 </div>
9167               </div>
9168             </div>
9169
9170             <p>Given that pkgsrc (and users!) expect configuration
9171             files to be in a known place, you need to teach each
9172             package where it shall install its files. In some cases
9173             you will have to patch the package Makefiles to achieve
9174             it. If you are lucky, though, it may be as easy as
9175             passing an extra flag to the configuration script; this
9176             is the case of GNU Autoconf- generated files:</p>
9177             <pre class="programlisting">
9178     CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}
9179 </pre>
9180
9181             <p>Note that this specifies where the package has to
9182             <span class="emphasis"><em>look for</em></span> its
9183             configuration files, not where they will be originally
9184             installed (although the difference is never explicit,
9185             unfortunately).</p>
9186           </div>
9187
9188           <div class="sect2" lang="en" xml:lang="en">
9189             <div class="titlepage">
9190               <div>
9191                 <div>
9192                   <h3 class="title"><a name="conf-files-patching"
9193                   id="conf-files-patching"></a>12.2.3. Patching
9194                   installations</h3>
9195                 </div>
9196               </div>
9197             </div>
9198
9199             <p>As said before, pkginstall automatically handles
9200             configuration files. This means that <span class=
9201             "strong"><strong>the packages themselves must not touch
9202             the contents of <code xmlns=
9203             "http://www.w3.org/TR/xhtml1/transitional" class=
9204             "filename">${PKG_SYSCONFDIR}</code>
9205             directly</strong></span>. Bad news is that many
9206             software installation scripts will, out of the box,
9207             mess with the contents of that directory. So what is
9208             the correct procedure to fix this issue?</p>
9209
9210             <p>You must teach the package (usually by manually
9211             patching it) to install any configuration files under
9212             the examples hierarchy, <code xmlns=
9213             "http://www.w3.org/TR/xhtml1/transitional" class=
9214             "filename">share/examples/${PKGBASE}/</code>. This way,
9215             the <code xmlns=
9216             "http://www.w3.org/TR/xhtml1/transitional" class=
9217             "filename">PLIST</code> registers them and the
9218             administrator always has the original copies
9219             available.</p>
9220
9221             <p>Once the required configuration files are in place
9222             (i.e., under the examples hierarchy), the pkginstall
9223             framework can use them as master copies during the
9224             package installation to update what is in <code xmlns=
9225             "http://www.w3.org/TR/xhtml1/transitional" class=
9226             "filename">${PKG_SYSCONFDIR}</code>. To achieve this,
9227             the variables <code class="varname">CONF_FILES</code>
9228             and <code class="varname">CONF_FILES_PERMS</code> are
9229             used. Check out <a href="#files-outside-prefix" title=
9230             "12.1.2.&nbsp;File manipulation">Section 12.1.2,
9231             &#8220;File manipulation&#8221;</a> for information
9232             about their syntax and their purpose. Here is an
9233             example, taken from the <a xmlns=
9234             "http://www.w3.org/TR/xhtml1/transitional" href=
9235             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/mail/mutt/README.html"
9236             target="_top"><code xmlns="" class=
9237             "filename">mail/mutt</code></a> package:</p>
9238             <pre class="programlisting">
9239     EGDIR=        ${PREFIX}/share/doc/mutt/samples
9240     CONF_FILES=   ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
9241 </pre>
9242
9243             <p>Note that the <code class="varname">EGDIR</code>
9244             variable is specific to that package and has no meaning
9245             outside it.</p>
9246           </div>
9247
9248           <div class="sect2" lang="en" xml:lang="en">
9249             <div class="titlepage">
9250               <div>
9251                 <div>
9252                   <h3 class="title"><a name="conf-files-disable"
9253                   id="conf-files-disable"></a>12.2.4. Disabling
9254                   handling of configuration files</h3>
9255                 </div>
9256               </div>
9257             </div>
9258
9259             <p>The automatic copying of config files can be toggled
9260             by setting the environment variable <code class=
9261             "varname">PKG_CONFIG</code> prior to package
9262             installation.</p>
9263           </div>
9264         </div>
9265
9266         <div class="sect1" lang="en" xml:lang="en">
9267           <div class="titlepage">
9268             <div>
9269               <div>
9270                 <h2 class="title" style="clear: both"><a name=
9271                 "rcd-scripts" id="rcd-scripts"></a>12.3. System
9272                 startup scripts</h2>
9273               </div>
9274             </div>
9275           </div>
9276
9277           <p>System startup scripts are special files because they
9278           must be installed in a place known by the underlying OS,
9279           usually outside the installation prefix. Therefore, the
9280           same rules described in <a href=
9281           "#files-and-dirs-outside-prefix" title=
9282           "12.1.&nbsp;Files and directories outside the installation prefix">
9283           Section 12.1, &#8220;Files and directories outside the
9284           installation prefix&#8221;</a> apply, and the same
9285           solutions can be used. However, pkginstall provides a
9286           special mechanism to handle these files.</p>
9287
9288           <p>In order to provide system startup scripts, the
9289           package has to:</p>
9290
9291           <div class="orderedlist">
9292             <ol type="1">
9293               <li>
9294                 <p>Store the script inside <code xmlns=
9295                 "http://www.w3.org/TR/xhtml1/transitional" class=
9296                 "filename">${FILESDIR}</code>, with the
9297                 <code class="literal">.sh</code> suffix appended.
9298                 Considering the <a xmlns=
9299                 "http://www.w3.org/TR/xhtml1/transitional" href=
9300                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/cups/README.html"
9301                 target="_top"><code xmlns="" class=
9302                 "filename">print/cups</code></a> package as an
9303                 example, it has a <code xmlns=
9304                 "http://www.w3.org/TR/xhtml1/transitional" class=
9305                 "filename">cupsd.sh</code> in its files
9306                 directory.</p>
9307               </li>
9308
9309               <li>
9310                 <p>Tell pkginstall to handle it, appending the name
9311                 of the script, without its extension, to the
9312                 <code class="varname">RCD_SCRIPTS</code> variable.
9313                 Continuing the previous example:</p>
9314                 <pre class="programlisting">
9315     RCD_SCRIPTS+=   cupsd
9316 </pre>
9317               </li>
9318             </ol>
9319           </div>
9320
9321           <p>Once this is done, pkginstall will do the following
9322           steps for each script in an automated fashion:</p>
9323
9324           <div class="orderedlist">
9325             <ol type="1">
9326               <li>
9327                 <p>Process the file found in the files directory
9328                 applying all the substitutions described in the
9329                 <code xmlns=
9330                 "http://www.w3.org/TR/xhtml1/transitional" class=
9331                 "filename">FILES_SUBST</code> variable.</p>
9332               </li>
9333
9334               <li>
9335                 <p>Copy the script from the files directory to the
9336                 examples hierarchy, <code xmlns=
9337                 "http://www.w3.org/TR/xhtml1/transitional" class=
9338                 "filename">${PREFIX}/share/examples/rc.d/</code>.
9339                 Note that this master file must be explicitly
9340                 registered in the <code xmlns=
9341                 "http://www.w3.org/TR/xhtml1/transitional" class=
9342                 "filename">PLIST</code>.</p>
9343               </li>
9344
9345               <li>
9346                 <p>Add code to the installation scripts to copy the
9347                 startup script from the examples hierarchy into the
9348                 system-wide startup scripts directory.</p>
9349               </li>
9350             </ol>
9351           </div>
9352
9353           <div class="sect2" lang="en" xml:lang="en">
9354             <div class="titlepage">
9355               <div>
9356                 <div>
9357                   <h3 class="title"><a name="rcd-scripts-disable"
9358                   id="rcd-scripts-disable"></a>12.3.1. Disabling
9359                   handling of system startup scripts</h3>
9360                 </div>
9361               </div>
9362             </div>
9363
9364             <p>The automatic copying of config files can be toggled
9365             by setting the environment variable <code class=
9366             "varname">PKG_RCD_SCRIPTS</code> prior to package
9367             installation. Note that the scripts will be always
9368             copied inside the examples hierarchy, <code xmlns=
9369             "http://www.w3.org/TR/xhtml1/transitional" class=
9370             "filename">${PREFIX}/share/examples/rc.d/</code>, no
9371             matter what the value of this variable is.</p>
9372           </div>
9373         </div>
9374
9375         <div class="sect1" lang="en" xml:lang="en">
9376           <div class="titlepage">
9377             <div>
9378               <div>
9379                 <h2 class="title" style="clear: both"><a name=
9380                 "users-and-groups" id="users-and-groups"></a>12.4.
9381                 System users and groups</h2>
9382               </div>
9383             </div>
9384           </div>
9385
9386           <p>If a package needs to create special users and/or
9387           groups during installation, it can do so by using the
9388           pkginstall framework.</p>
9389
9390           <p>Users can be created by adding entries to the
9391           <code class="varname">PKG_USERS</code> variable. Each
9392           entry has the following syntax, which mimics <code xmlns=
9393           "http://www.w3.org/TR/xhtml1/transitional" class=
9394           "filename">/etc/passwd</code>:</p>
9395           <pre class="programlisting">
9396     user:group[:[userid][:[descr][:[home][:shell]]]]
9397 </pre>
9398
9399           <p>Only the user and group are required; everything else
9400           is optional, but the colons must be in the right places
9401           when specifying optional bits. By default, a new user
9402           will have home directory <code xmlns=
9403           "http://www.w3.org/TR/xhtml1/transitional" class=
9404           "filename">/nonexistent</code>, and login shell
9405           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
9406           class="filename">/sbin/nologin</code> unless they are
9407           specified as part of the user element. Note that if the
9408           description contains spaces, then spaces should be
9409           backslash-escaped, as in:</p>
9410           <pre class="programlisting">
9411     foo:foogrp::The\ Foomister
9412 </pre>
9413
9414           <p>Similarly, groups can be created using the
9415           <code class="varname">PKG_GROUPS</code> variable, whose
9416           syntax is:</p>
9417           <pre class="programlisting">
9418     group[:groupid]
9419 </pre>
9420
9421           <p>As before, only the group name is required; the
9422           numeric identifier is optional.</p>
9423         </div>
9424
9425         <div class="sect1" lang="en" xml:lang="en">
9426           <div class="titlepage">
9427             <div>
9428               <div>
9429                 <h2 class="title" style="clear: both"><a name=
9430                 "shells" id="shells"></a>12.5. System shells</h2>
9431               </div>
9432             </div>
9433           </div>
9434
9435           <p>Packages that install system shells should register
9436           them in the shell database, <code xmlns=
9437           "http://www.w3.org/TR/xhtml1/transitional" class=
9438           "filename">/etc/shells</code>, to make things easier to
9439           the administrator. This must be done from the
9440           installation scripts to keep binary packages working on
9441           any system. pkginstall provides an easy way to accomplish
9442           this task.</p>
9443
9444           <p>When a package provides a shell interpreter, it has to
9445           set the <code class="varname">PKG_SHELL</code> variable
9446           to its absolute file name. This will add some hooks to
9447           the installation scripts to handle it. Consider the
9448           following example, taken from <a xmlns=
9449           "http://www.w3.org/TR/xhtml1/transitional" href=
9450           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/shells/zsh/README.html"
9451           target="_top"><code xmlns="" class=
9452           "filename">shells/zsh</code></a>:</p>
9453           <pre class="programlisting">
9454     USE_PKGINSTALL= YES
9455     PKG_SHELL=      ${PREFIX}/bin/zsh
9456 </pre>
9457
9458           <div class="sect2" lang="en" xml:lang="en">
9459             <div class="titlepage">
9460               <div>
9461                 <div>
9462                   <h3 class="title"><a name="shells-disable" id=
9463                   "shells-disable"></a>12.5.1. Disabling handling
9464                   of configuration files</h3>
9465                 </div>
9466               </div>
9467             </div>
9468
9469             <p>The automatic registration of shell interpreters can
9470             be disabled by the administrator by setting the
9471             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
9472             class="filename">PKG_REGISTER_SHELLS</code> environment
9473             variable to <code class="literal">NO</code>.</p>
9474           </div>
9475         </div>
9476       </div>
9477
9478       <div class="chapter" lang="en" xml:lang="en">
9479         <div class="titlepage">
9480           <div>
9481             <div>
9482               <h2 class="title"><a name="options" id=
9483               "options"></a>Chapter&nbsp;13.&nbsp;Options
9484               handling</h2>
9485             </div>
9486           </div>
9487         </div>
9488
9489         <div class="toc">
9490           <p><b>Table of Contents</b></p>
9491
9492           <dl>
9493             <dt><span class="sect1"><a href=
9494             "#global-default-options">13.1. Global default
9495             options</a></span></dt>
9496
9497             <dt><span class="sect1"><a href=
9498             "#converting-to-options">13.2. Converting packages to
9499             use <code xmlns=
9500             "http://www.w3.org/TR/xhtml1/transitional" class=
9501             "filename">bsd.options.mk</code></a></span></dt>
9502
9503             <dt><span class="sect1"><a href="#option-names">13.3.
9504             Option Names</a></span></dt>
9505           </dl>
9506         </div>
9507
9508         <p>Many packages have the ability to be built to support
9509         different sets of features. <code xmlns=
9510         "http://www.w3.org/TR/xhtml1/transitional" class=
9511         "filename">bsd.options.mk</code> is a framework in pkgsrc
9512         that provides generic handling of those options that
9513         determine different ways in which the packages can be
9514         built. It's possible for the user to specify exactly which
9515         sets of options will be built into a package or to allow a
9516         set of global default options apply.</p>
9517
9518         <div class="sect1" lang="en" xml:lang="en">
9519           <div class="titlepage">
9520             <div>
9521               <div>
9522                 <h2 class="title" style="clear: both"><a name=
9523                 "global-default-options" id=
9524                 "global-default-options"></a>13.1.&nbsp;Global
9525                 default options</h2>
9526               </div>
9527             </div>
9528           </div>
9529
9530           <p>Global default options are listed in <code class=
9531           "varname">PKG_DEFAULT_OPTIONS</code>, which is a list of
9532           the options that should be built into every package if
9533           that option is supported. This variable should be set in
9534           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
9535           class="filename">/etc/mk.conf</code>.</p>
9536         </div>
9537
9538         <div class="sect1" lang="en" xml:lang="en">
9539           <div class="titlepage">
9540             <div>
9541               <div>
9542                 <h2 class="title" style="clear: both"><a name=
9543                 "converting-to-options" id=
9544                 "converting-to-options"></a>13.2.&nbsp;Converting
9545                 packages to use <code xmlns=
9546                 "http://www.w3.org/TR/xhtml1/transitional" class=
9547                 "filename">bsd.options.mk</code></h2>
9548               </div>
9549             </div>
9550           </div>
9551
9552           <p>The following example shows how <code xmlns=
9553           "http://www.w3.org/TR/xhtml1/transitional" class=
9554           "filename">bsd.options.mk</code> should be used by the
9555           hypothetical ``wibble'' package, either in the package
9556           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
9557           class="filename">Makefile</code>, or in a file, e.g.
9558           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
9559           class="filename">options.mk</code>, that is included by
9560           the main package <code xmlns=
9561           "http://www.w3.org/TR/xhtml1/transitional" class=
9562           "filename">Makefile</code>.</p>
9563           <pre class="programlisting">
9564     PKG_OPTIONS_VAR=            PKG_OPTIONS.wibble
9565     PKG_SUPPORTED_OPTIONS=              wibble-foo ldap
9566     PKG_OPTIONS_OPTIONAL_GROUPS=        database
9567     PKG_OPTIONS_GROUP.database= mysql pgsql
9568     PKG_SUGGESTED_OPTIONS=              wibble-foo
9569     PKG_OPTIONS_LEGACY_VARS+=   WIBBLE_USE_OPENLDAP:ldap
9570     PKG_OPTIONS_LEGACY_OPTS+=   foo:wibble-foo
9571
9572     .include "../../mk/bsd.prefs.mk"
9573
9574     # this package was previously named wibble2
9575     .if defined(PKG_OPTIONS.wibble2)
9576     PKG_LEGACY_OPTIONS+=  ${PKG_OPTIONS.wibble2}
9577     PKG_OPTIONS_DEPRECATED_WARNINGS+= \
9578             "Deprecated variable PKG_OPTIONS.wibble2 used, use "${PKG_OPTIONS_VAR:Q}" instead."
9579     .endif
9580
9581     .include "../../mk/bsd.options.mk"
9582
9583     # Package-specific option-handling
9584
9585     ###
9586     ### FOO support
9587     ###
9588     .if !empty(PKG_OPTIONS:Mwibble-foo)
9589     CONFIGURE_ARGS+=    --enable-foo
9590     .endif
9591
9592     ###
9593     ### LDAP support
9594     ###
9595     .if !empty(PKG_OPTIONS:Mldap)
9596     .  include "../../databases/openldap/buildlink3.mk"
9597     CONFIGURE_ARGS+=    --enable-ldap=${BUILDLINK_PREFIX.openldap}
9598     .endif
9599
9600     ###
9601     ### database support
9602     ###
9603     .if !empty(PKG_OPTIONS:Mmysql)
9604     .  include "../../mk/mysql.buildlink3.mk"
9605     .endif
9606     .if !empty(PKG_OPTIONS:Mpgsql)
9607     .  include "../../mk/pgsql.buildlink3.mk"
9608     .endif
9609 </pre>
9610
9611           <p>The first section contains the information about which
9612           build options are supported by the package, and any
9613           default options settings if needed.</p>
9614
9615           <div class="orderedlist">
9616             <ol type="1">
9617               <li>
9618                 <p><code class="varname">PKG_OPTIONS_VAR</code> is
9619                 the name of the <a href=
9620                 "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
9621                 <span class="citerefentry"><span class=
9622                 "refentrytitle">make</span>(1)</span></a> variable
9623                 that the user can set to override the default
9624                 options. It should be set to &#8220;<span class=
9625                 "quote">PKG_OPTIONS.<em class=
9626                 "replaceable"><code>pkgbase</code></em></span>&#8221;.</p>
9627               </li>
9628
9629               <li>
9630                 <p><code class=
9631                 "varname">PKG_SUPPORTED_OPTIONS</code> is a list of
9632                 build options supported by the package.</p>
9633               </li>
9634
9635               <li>
9636                 <p><code class=
9637                 "varname">PKG_OPTIONS_OPTIONAL_GROUPS</code> is a
9638                 list of names of groups of mutually exclusive
9639                 options. The options in each group are listed in
9640                 <code class="varname">PKG_OPTIONS_GROUP.<em class=
9641                 "replaceable"><code>groupname</code></em></code>.
9642                 The most specific setting of any option from the
9643                 group takes precedence over all other options in
9644                 the group. Options from the groups will be
9645                 automatically added to <code class=
9646                 "varname">PKG_SUPPORTED_OPTIONS</code>.</p>
9647               </li>
9648
9649               <li>
9650                 <p><code class=
9651                 "varname">PKG_OPTIONS_REQUIRED_GROUPS</code> is
9652                 like <code class=
9653                 "varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, but
9654                 building the packages will fail if no option from
9655                 the group is selected.</p>
9656               </li>
9657
9658               <li>
9659                 <p><code class=
9660                 "varname">PKG_OPTIONS_NONEMPTY_SETS</code> is a
9661                 list of names of sets of options. At least one
9662                 option from each set must be selected. The options
9663                 in each set are listed in <code class=
9664                 "varname">PKG_OPTIONS_SET.<em class=
9665                 "replaceable"><code>setname</code></em></code>.
9666                 Options from the sets will be automatically added
9667                 to <code class=
9668                 "varname">PKG_SUPPORTED_OPTIONS</code>. Building
9669                 the package will fail if no option from the set is
9670                 selected.</p>
9671               </li>
9672
9673               <li>
9674                 <p><code class=
9675                 "varname">PKG_SUGGESTED_OPTIONS</code> is a list of
9676                 build options which are enabled by default.</p>
9677               </li>
9678
9679               <li>
9680                 <p><code class=
9681                 "varname">PKG_OPTIONS_LEGACY_VARS</code> is a list
9682                 of &#8220;<span class="quote"><em class=
9683                 "replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable">
9684                 <code>option</code></em></span>&#8221; pairs that
9685                 map legacy <code xmlns=
9686                 "http://www.w3.org/TR/xhtml1/transitional" class=
9687                 "filename">/etc/mk.conf</code> variables to their
9688                 option counterparts. Pairs should be added with
9689                 &#8220;<span class="quote">+=</span>&#8221; to keep
9690                 the listing of global legacy variables. A warning
9691                 will be issued if the user uses a legacy
9692                 variable.</p>
9693               </li>
9694
9695               <li>
9696                 <p><code class=
9697                 "varname">PKG_OPTIONS_LEGACY_OPTS</code> is a list
9698                 of &#8220;<span class="quote"><em class=
9699                 "replaceable"><code>old-option</code></em>:<em class="replaceable">
9700                 <code>new-option</code></em></span>&#8221; pairs
9701                 that map options that have been renamed to their
9702                 new counterparts. Pairs should be added with
9703                 &#8220;<span class="quote">+=</span>&#8221; to keep
9704                 the listing of global legacy options. A warning
9705                 will be issued if the user uses a legacy
9706                 option.</p>
9707               </li>
9708
9709               <li>
9710                 <p><code class="varname">PKG_LEGACY_OPTIONS</code>
9711                 is a list of options implied by deprecated
9712                 variables used. This can be used for cases that
9713                 neither <code class=
9714                 "varname">PKG_OPTIONS_LEGACY_VARS</code> nor
9715                 <code class=
9716                 "varname">PKG_OPTIONS_LEGACY_OPTS</code> can
9717                 handle, e. g. when <code class=
9718                 "varname">PKG_OPTIONS_VAR</code> is renamed.</p>
9719               </li>
9720
9721               <li>
9722                 <p><code class=
9723                 "varname">PKG_OPTIONS_DEPRECATED_WARNINGS</code> is
9724                 a list of warnings about deprecated variables or
9725                 options used, and what to use instead.</p>
9726               </li>
9727             </ol>
9728           </div>
9729
9730           <p>A package should never modify <code class=
9731           "varname">PKG_DEFAULT_OPTIONS</code> or the variable
9732           named in <code class="varname">PKG_OPTIONS_VAR</code>.
9733           These are strictly user-settable. To suggest a default
9734           set of options, use <code class=
9735           "varname">PKG_SUGGESTED_OPTIONS</code>.</p>
9736
9737           <p><code class="varname">PKG_OPTIONS_VAR</code> must be
9738           defined before including <code xmlns=
9739           "http://www.w3.org/TR/xhtml1/transitional" class=
9740           "filename">bsd.options.mk</code>. If none of <code class=
9741           "varname">PKG_SUPPORTED_OPTIONS</code>, <code class=
9742           "varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, and
9743           <code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code>
9744           are defined (as can happen with platform-specific options
9745           if none of them is supported on the current platform),
9746           <code class="varname">PKG_OPTIONS</code> is set to the
9747           empty list and the package is otherwise treated as not
9748           using the options framework.</p>
9749
9750           <p>After the inclusion of <code xmlns=
9751           "http://www.w3.org/TR/xhtml1/transitional" class=
9752           "filename">bsd.options.mk</code>, the variable
9753           <code class="varname">PKG_OPTIONS</code> contains the
9754           list of selected build options, properly filtered to
9755           remove unsupported and duplicate options.</p>
9756
9757           <p>The remaining sections contain the logic that is
9758           specific to each option. The correct way to check for an
9759           option is to check whether it is listed in <code class=
9760           "varname">PKG_OPTIONS</code>:</p>
9761           <pre class="programlisting">
9762     .if !empty(PKG_OPTIONS:M<em class=
9763 "replaceable"><code>option</code></em>)
9764 </pre>
9765         </div>
9766
9767         <div class="sect1" lang="en" xml:lang="en">
9768           <div class="titlepage">
9769             <div>
9770               <div>
9771                 <h2 class="title" style="clear: both"><a name=
9772                 "option-names" id=
9773                 "option-names"></a>13.3.&nbsp;Option Names</h2>
9774               </div>
9775             </div>
9776           </div>
9777
9778           <p>Options that enable similar features in different
9779           packages (like optional support for a library) should use
9780           a common name in all packages that support it (like the
9781           name of the library). If another package already has an
9782           option with the same meaning, use the same name.</p>
9783
9784           <p>Options that enable features specific to one package,
9785           where it's unlikely that another (unrelated) package has
9786           the same (or a similar) optional feature, should use a
9787           name prefixed with <code class="varname"><em class=
9788           "replaceable"><code>pkgname</code></em>-</code>.</p>
9789
9790           <p>If a group of related packages share an optional
9791           feature specific to that group, prefix it with the name
9792           of the &#8220;<span class="quote">main</span>&#8221;
9793           package (e. g. <code class=
9794           "varname">djbware-errno-hack</code>).</p>
9795
9796           <p>For new options, add a line to <code xmlns=
9797           "http://www.w3.org/TR/xhtml1/transitional" class=
9798           "filename">mk/defaults/options.description</code>. Lines
9799           have two fields, separated by tab. The first field is the
9800           option name, the second its description. The description
9801           should be a whole sentence (starting with an uppercase
9802           letter and ending with a period) that describes what
9803           enabling the option does. E. g. &#8220;<span class=
9804           "quote">Enable ispell support.</span>&#8221; The file is
9805           sorted by option names.</p>
9806         </div>
9807       </div>
9808
9809       <div class="chapter" lang="en" xml:lang="en">
9810         <div class="titlepage">
9811           <div>
9812             <div>
9813               <h2 class="title"><a name="build" id=
9814               "build"></a>Chapter&nbsp;14.&nbsp;The build
9815               process</h2>
9816             </div>
9817           </div>
9818         </div>
9819
9820         <div class="toc">
9821           <p><b>Table of Contents</b></p>
9822
9823           <dl>
9824             <dt><span class="sect1"><a href="#build.prefix">14.1.
9825             Program location</a></span></dt>
9826
9827             <dt><span class="sect1"><a href="#main-targets">14.2.
9828             Main targets</a></span></dt>
9829
9830             <dt><span class="sect1"><a href=
9831             "#build.helpful-targets">14.3. Other helpful
9832             targets</a></span></dt>
9833           </dl>
9834         </div>
9835
9836         <p>The basic steps for building a program are always the
9837         same. First the program's source (<span class=
9838         "emphasis"><em>distfile</em></span>) must be brought to the
9839         local system and then extracted. After any patches to
9840         compile properly on NetBSD are applied, the software can be
9841         configured, then built (usually by compiling), and finally
9842         the generated binaries, etc. can be put into place on the
9843         system. These are exactly the steps performed by the NetBSD
9844         package system, which is implemented as a series of targets
9845         in a central Makefile, <code xmlns=
9846         "http://www.w3.org/TR/xhtml1/transitional" class=
9847         "filename">pkgsrc/mk/bsd.pkg.mk</code>.</p>
9848
9849         <div class="sect1" lang="en" xml:lang="en">
9850           <div class="titlepage">
9851             <div>
9852               <div>
9853                 <h2 class="title" style="clear: both"><a name=
9854                 "build.prefix" id=
9855                 "build.prefix"></a>14.1.&nbsp;Program location</h2>
9856               </div>
9857             </div>
9858           </div>
9859
9860           <p>Before outlining the process performed by the NetBSD
9861           package system in the next section, here's a brief
9862           discussion on where programs are installed, and which
9863           variables influence this.</p>
9864
9865           <p>The automatic variable <code class=
9866           "varname">PREFIX</code> indicates where all files of the
9867           final program shall be installed. It is usually set to
9868           <code class="varname">LOCALBASE</code> (<code xmlns=
9869           "http://www.w3.org/TR/xhtml1/transitional" class=
9870           "filename">/usr/pkg</code>), or <code class=
9871           "varname">CROSSBASE</code> for pkgs in the
9872           &#8220;<span class="quote">cross</span>&#8221; category.
9873           The value of <code class="varname">PREFIX</code> needs to
9874           be put into the various places in the program's source
9875           where paths to these files are encoded. See <a href=
9876           "#components.patches" title=
9877           "8.3.&nbsp;patches/*">Section&nbsp;8.3,
9878           &#8220;patches/*&#8221;</a> and <a href="#fixes.libtool"
9879           title=
9880           "15.3.1.&nbsp;Shared libraries - libtool">Section&nbsp;15.3.1,
9881           &#8220;Shared libraries - libtool&#8221;</a> for more
9882           details.</p>
9883
9884           <p>When choosing which of these variables to use, follow
9885           the following rules:</p>
9886
9887           <div class="itemizedlist">
9888             <ul type="disc">
9889               <li>
9890                 <p><code class="varname">PREFIX</code> always
9891                 points to the location where the current pkg will
9892                 be installed. When referring to a pkg's own
9893                 installation path, use &#8220;<span class=
9894                 "quote">${PREFIX}</span>&#8221;.</p>
9895               </li>
9896
9897               <li>
9898                 <p><code class="varname">LOCALBASE</code> is where
9899                 all non-X11 pkgs are installed. If you need to
9900                 construct a -I or -L argument to the compiler to
9901                 find includes and libraries installed by another
9902                 non-X11 pkg, use &#8220;<span class=
9903                 "quote">${LOCALBASE}</span>&#8221;.</p>
9904               </li>
9905
9906               <li>
9907                 <p><code class="varname">X11BASE</code> is where
9908                 the actual X11 distribution (from xsrc, etc.) is
9909                 installed. When looking for <span class=
9910                 "emphasis"><em>standard</em></span> X11 includes
9911                 (not those installed by a pkg), use
9912                 &#8220;<span class=
9913                 "quote">${X11BASE}</span>&#8221;.</p>
9914               </li>
9915
9916               <li>
9917                 <p>X11-based packages are special in that they may
9918                 be installed in either <code class=
9919                 "varname">X11BASE</code> or <code class=
9920                 "varname">LOCALBASE</code>.</p>
9921
9922                 <p>Usually, X11 packages should be installed under
9923                 <code class="varname">LOCALBASE</code> whenever
9924                 possible. Note that you will need to include
9925                 <code xmlns=
9926                 "http://www.w3.org/TR/xhtml1/transitional" class=
9927                 "filename">../../mk/x11.buildlink3.mk</code> in
9928                 them to request the presence of X11 and to get the
9929                 right compilation flags.</p>
9930
9931                 <p>Even though, there are some packages that cannot
9932                 be installed under <code class=
9933                 "varname">LOCALBASE</code>: those that come with
9934                 app-defaults files. These packages are special and
9935                 they must be placed under <code class=
9936                 "varname">X11BASE</code>. To accomplish this, set
9937                 either <code class="varname">USE_X11BASE</code> or
9938                 <code class="varname">USE_IMAKE</code> in your
9939                 package.</p>
9940
9941                 <p>Some notes: If you need to find includes or
9942                 libraries installed by a pkg that has <code class=
9943                 "varname">USE_IMAKE</code> or <code class=
9944                 "varname">USE_X11BASE</code> in its pkg
9945                 <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
9946                 class="filename">Makefile</code>, you need to look
9947                 in <span class="emphasis"><em>both</em></span>
9948                 <code xmlns=
9949                 "http://www.w3.org/TR/xhtml1/transitional" class=
9950                 "filename">${X11BASE}</code> and <code xmlns=
9951                 "http://www.w3.org/TR/xhtml1/transitional" class=
9952                 "filename">${LOCALBASE}</code>. To force
9953                 installation of all X11 packages in <code class=
9954                 "varname">LOCALBASE</code>, the <a xmlns=
9955                 "http://www.w3.org/TR/xhtml1/transitional" href=
9956                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/xpkgwedge/README.html"
9957                 target="_top"><code xmlns="" class=
9958                 "filename">pkgtools/xpkgwedge</code></a> package is
9959                 enabled by default.</p>
9960               </li>
9961
9962               <li>
9963                 <p><code class="varname">X11PREFIX</code> should be
9964                 used to refer to the installed location of an X11
9965                 package. <code class="varname">X11PREFIX</code>
9966                 will be set to <code class="varname">X11BASE</code>
9967                 if xpkgwedge is not installed, and to <code class=
9968                 "varname">LOCALBASE</code> if xpkgwedge is
9969                 installed.</p>
9970               </li>
9971
9972               <li>
9973                 <p>If xpkgwedge is installed, it is possible to
9974                 have some packages installed in <code class=
9975                 "varname">X11BASE</code> and some in <code class=
9976                 "varname">LOCALBASE</code>. To determine the prefix
9977                 of an installed package, the <code class=
9978                 "varname">EVAL_PREFIX</code> definition can be
9979                 used. It takes pairs in the format
9980                 &#8220;<span class=
9981                 "quote">DIRNAME=&lt;package&gt;</span>&#8221;, and
9982                 the <a href=
9983                 "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
9984                 <span class="citerefentry"><span class=
9985                 "refentrytitle">make</span>(1)</span></a> variable
9986                 <code class="varname">DIRNAME</code> will be set to
9987                 the prefix of the installed package
9988                 &lt;package&gt;, or &#8220;<span class=
9989                 "quote">${X11PREFIX}</span>&#8221; if the package
9990                 is not installed.</p>
9991
9992                 <p>This is best illustrated by example.</p>
9993
9994                 <p>The following lines are taken from <code xmlns=
9995                 "http://www.w3.org/TR/xhtml1/transitional" class=
9996                 "filename">pkgsrc/wm/scwm/Makefile</code>:</p>
9997                 <pre class="programlisting">
9998     EVAL_PREFIX+=           GTKDIR=gtk+
9999     CONFIGURE_ARGS+=        --with-guile-prefix=${LOCALBASE}        \
10000                             --with-gtk-prefix="${GTKDIR}"           \
10001                             --enable-multibyte
10002 </pre>
10003
10004                 <p>Specific defaults can be defined for the
10005                 packages evaluated using <code class=
10006                 "varname">EVAL_PREFIX</code>, by using a definition
10007                 of the form:</p>
10008                 <pre class="programlisting">
10009     GTKDIR_DEFAULT= ${LOCALBASE}
10010 </pre>
10011
10012                 <p>where <code class="varname">GTKDIR</code>
10013                 corresponds to the first definition in the
10014                 <code class="varname">EVAL_PREFIX</code> pair.</p>
10015               </li>
10016
10017               <li>
10018                 <p>Within <code xmlns=
10019                 "http://www.w3.org/TR/xhtml1/transitional" class=
10020                 "filename">${PREFIX}</code>, packages should
10021                 install files according to <a href=
10022                 "http://netbsd.gw.com/cgi-bin/man-cgi?hier+7+NetBSD-current">
10023                 <span class="citerefentry"><span class=
10024                 "refentrytitle">hier</span>(7)</span></a>, with the
10025                 exception that manual pages go into <code xmlns=
10026                 "http://www.w3.org/TR/xhtml1/transitional" class=
10027                 "filename">${PREFIX}/man</code>, not <code xmlns=
10028                 "http://www.w3.org/TR/xhtml1/transitional" class=
10029                 "filename">${PREFIX}/share/man</code>.</p>
10030               </li>
10031             </ul>
10032           </div>
10033         </div>
10034
10035         <div class="sect1" lang="en" xml:lang="en">
10036           <div class="titlepage">
10037             <div>
10038               <div>
10039                 <h2 class="title" style="clear: both"><a name=
10040                 "main-targets" id=
10041                 "main-targets"></a>14.2.&nbsp;Main targets</h2>
10042               </div>
10043             </div>
10044           </div>
10045
10046           <p>The main targets used during the build process defined
10047           in <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
10048           class="filename">bsd.pkg.mk</code> are:</p>
10049
10050           <div class="variablelist">
10051             <dl>
10052               <dt><span class="term">fetch</span></dt>
10053
10054               <dd>
10055                 <p>This will check if the file(s) given in the
10056                 variables <code class="varname">DISTFILES</code>
10057                 and <code class="varname">PATCHFILES</code> (as
10058                 defined in the package's Makefile) are present on
10059                 the local system in <code xmlns=
10060                 "http://www.w3.org/TR/xhtml1/transitional" class=
10061                 "filename">/usr/pkgsrc/distfiles</code>. If they
10062                 are not present, an attempt will be made to fetch
10063                 them using commands of the form:</p>
10064                 <pre class="programlisting">
10065     ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
10066 </pre>
10067
10068                 <p>where ${site} varies through several
10069                 possibilities in turn: first, <code class=
10070                 "varname">MASTER_SITE_OVERRIDE</code> is tried,
10071                 then the sites specified in either <code class=
10072                 "varname">SITES_file</code> if defined, else
10073                 <code class="varname">MASTER_SITES</code> or
10074                 <code class="varname">PATCH_SITES</code>, as
10075                 applies, then finally the value of <code class=
10076                 "varname">MASTER_SITE_BACKUP</code>. The order of
10077                 all except the first can be optionally sorted by
10078                 the user, via setting either <code class=
10079                 "varname">MASTER_SORT_AWK</code> or <code class=
10080                 "varname">MASTER_SORT_REGEX</code>.</p>
10081               </dd>
10082
10083               <dt><span class="term">checksum</span></dt>
10084
10085               <dd>
10086                 <p>After the distfile(s) are fetched, their
10087                 checksum is generated and compared with the
10088                 checksums stored in the distinfo file. If the
10089                 checksums don't match, the build is aborted. This
10090                 is to ensure the same distfile is used for
10091                 building, and that the distfile wasn't changed,
10092                 e.g. by some malign force, deliberately changed
10093                 distfiles on the master distribution site or
10094                 network lossage.</p>
10095               </dd>
10096
10097               <dt><span class="term">extract</span></dt>
10098
10099               <dd>
10100                 <p>When the distfiles are present on the local
10101                 system, they need to be extracted, as they are
10102                 usually in the form of some compressed archive
10103                 format, most commonly <code xmlns=
10104                 "http://www.w3.org/TR/xhtml1/transitional" class=
10105                 "filename">.tar.gz</code>.</p>
10106
10107                 <p>If only some of the distfiles need to be
10108                 uncompressed, the files to be uncompressed should
10109                 be put into <code class=
10110                 "varname">EXTRACT_ONLY</code>.</p>
10111
10112                 <p>If the distfiles are not in <code xmlns=
10113                 "http://www.w3.org/TR/xhtml1/transitional" class=
10114                 "filename">.tar.gz</code> format, they can be
10115                 extracted by setting either <code class=
10116                 "varname">EXTRACT_SUFX</code>, or <code class=
10117                 "varname">EXTRACT_CMD</code>, <code class=
10118                 "varname">EXTRACT_BEFORE_ARGS</code> and
10119                 <code class="varname">EXTRACT_AFTER_ARGS</code>. In
10120                 the former case, pkgsrc knows how to extract a
10121                 number of suffixes (<code xmlns=
10122                 "http://www.w3.org/TR/xhtml1/transitional" class=
10123                 "filename">.tar.gz</code>, <code xmlns=
10124                 "http://www.w3.org/TR/xhtml1/transitional" class=
10125                 "filename">.tgz</code>, <code xmlns=
10126                 "http://www.w3.org/TR/xhtml1/transitional" class=
10127                 "filename">.tar.gz2</code>, <code xmlns=
10128                 "http://www.w3.org/TR/xhtml1/transitional" class=
10129                 "filename">.tbz</code>, <code xmlns=
10130                 "http://www.w3.org/TR/xhtml1/transitional" class=
10131                 "filename">.tar.Z</code>, <code xmlns=
10132                 "http://www.w3.org/TR/xhtml1/transitional" class=
10133                 "filename">.tar</code>, <code xmlns=
10134                 "http://www.w3.org/TR/xhtml1/transitional" class=
10135                 "filename">.shar.gz</code>, <code xmlns=
10136                 "http://www.w3.org/TR/xhtml1/transitional" class=
10137                 "filename">.shar.bz2</code>, <code xmlns=
10138                 "http://www.w3.org/TR/xhtml1/transitional" class=
10139                 "filename">.shar.Z</code>, <code xmlns=
10140                 "http://www.w3.org/TR/xhtml1/transitional" class=
10141                 "filename">.shar</code>, <code xmlns=
10142                 "http://www.w3.org/TR/xhtml1/transitional" class=
10143                 "filename">.Z</code>, <code xmlns=
10144                 "http://www.w3.org/TR/xhtml1/transitional" class=
10145                 "filename">.bz2</code> and <code xmlns=
10146                 "http://www.w3.org/TR/xhtml1/transitional" class=
10147                 "filename">.gz</code>; see the definition of the
10148                 various <code class="varname">DECOMPRESS_CMD</code>
10149                 variables in <code xmlns=
10150                 "http://www.w3.org/TR/xhtml1/transitional" class=
10151                 "filename">bsd.pkg.extract.mk</code> for a complete
10152                 list). Here's an example on how to use the other
10153                 variables for a program that comes with a
10154                 compressed shell archive whose name ends in
10155                 <code xmlns=
10156                 "http://www.w3.org/TR/xhtml1/transitional" class=
10157                 "filename">.msg.gz</code>:</p>
10158                 <pre class="programlisting">
10159     EXTRACT_SUFX=           .msg.gz
10160     EXTRACT_CMD=            zcat
10161     EXTRACT_BEFORE_ARGS=
10162     EXTRACT_AFTER_ARGS=     |sh
10163 </pre>
10164               </dd>
10165
10166               <dt><span class="term">patch</span></dt>
10167
10168               <dd>
10169                 <p>After extraction, all the patches named by the
10170                 <code class="varname">PATCHFILES</code>, those
10171                 present in the patches subdirectory of the package
10172                 as well as in $LOCALPATCHES/$PKGPATH (e.g.
10173                 <code xmlns=
10174                 "http://www.w3.org/TR/xhtml1/transitional" class=
10175                 "filename">/usr/local/patches/graphics/png</code>)
10176                 are applied. Patchfiles ending in <code xmlns=
10177                 "http://www.w3.org/TR/xhtml1/transitional" class=
10178                 "filename">.Z</code> or <code xmlns=
10179                 "http://www.w3.org/TR/xhtml1/transitional" class=
10180                 "filename">.gz</code> are uncompressed before they
10181                 are applied, files ending in <code xmlns=
10182                 "http://www.w3.org/TR/xhtml1/transitional" class=
10183                 "filename">.orig</code> or <code xmlns=
10184                 "http://www.w3.org/TR/xhtml1/transitional" class=
10185                 "filename">.rej</code> are ignored. Any special
10186                 options to <a href=
10187                 "http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current">
10188                 <span class="citerefentry"><span class=
10189                 "refentrytitle">patch</span>(1)</span></a> can be
10190                 handed in <code class=
10191                 "varname">PATCH_DIST_ARGS</code>. See <a href=
10192                 "#components.patches" title=
10193                 "8.3.&nbsp;patches/*">Section&nbsp;8.3,
10194                 &#8220;patches/*&#8221;</a> for more details.</p>
10195
10196                 <p>By default <a href=
10197                 "http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current">
10198                 <span class="citerefentry"><span class=
10199                 "refentrytitle">patch</span>(1)</span></a> is given
10200                 special args to make it fail if the patches apply
10201                 with some lines of fuzz. Please fix (regen) the
10202                 patches so that they apply cleanly. The rationale
10203                 behind this is that patches that don't apply
10204                 cleanly may end up being applied in the wrong
10205                 place, and cause severe harm there.</p>
10206               </dd>
10207
10208               <dt><span class="term">configure</span></dt>
10209
10210               <dd>
10211                 <p>Most pieces of software need information on the
10212                 header files, system calls, and library routines
10213                 which are available in NetBSD. This is the process
10214                 known as configuration, and is usually automated.
10215                 In most cases, a script is supplied with the
10216                 source, and its invocation results in generation of
10217                 header files, Makefiles, etc.</p>
10218
10219                 <p>If the program's distfile contains its own
10220                 configure script, this can be invoked by setting
10221                 <code class="varname">HAS_CONFIGURE</code>. If the
10222                 configure script is a GNU autoconf script,
10223                 <code class="varname">GNU_CONFIGURE</code> should
10224                 be specified instead. In either case, any arguments
10225                 to the configure script can be specified in the
10226                 <code class="varname">CONFIGURE_ARGS</code>
10227                 variable, and the configure script's name can be
10228                 set in <code class=
10229                 "varname">CONFIGURE_SCRIPT</code> if it differs
10230                 from the default &#8220;<span class=
10231                 "quote">configure</span>&#8221;. Here's an example
10232                 from the <a xmlns=
10233                 "http://www.w3.org/TR/xhtml1/transitional" href=
10234                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/top/README.html"
10235                 target="_top"><code xmlns="" class=
10236                 "filename">sysutils/top</code></a> package:</p>
10237                 <pre class="programlisting">
10238     HAS_CONFIGURE=          yes
10239     CONFIGURE_SCRIPT=       Configure
10240     CONFIGURE_ARGS+=        netbsd13
10241 </pre>
10242
10243                 <p>If the program uses an Imakefile for
10244                 configuration, the appropriate steps can be invoked
10245                 by setting <code class="varname">USE_IMAKE</code>
10246                 to &#8220;<span class="quote">YES</span>&#8221;.
10247                 (If you only want the package installed in
10248                 <code class="varname">$X11PREFIX</code> but xmkmf
10249                 not being run, set <code class=
10250                 "varname">USE_X11BASE</code> instead!)</p>
10251               </dd>
10252
10253               <dt><span class="term">build</span></dt>
10254
10255               <dd>
10256                 <p>Once configuration has taken place, the software
10257                 will be built by invoking <code class=
10258                 "varname">$MAKE_PROGRAM</code> on <code class=
10259                 "varname">$MAKEFILE</code> with <code class=
10260                 "varname">$BUILD_TARGET</code> as the target to
10261                 build. The default <code class=
10262                 "varname">MAKE_PROGRAM</code> is
10263                 &#8220;<span class="quote">gmake</span>&#8221; if
10264                 <code class="varname">USE_TOOLS</code> contains
10265                 &#8220;<span class="quote">gmake</span>&#8221;,
10266                 &#8220;<span class="quote">make</span>&#8221;
10267                 otherwise. <code class="varname">MAKEFILE</code> is
10268                 set to &#8220;<span class=
10269                 "quote">Makefile</span>&#8221; by default, and
10270                 <code class="varname">BUILD_TARGET</code> defaults
10271                 to &#8220;<span class="quote">all</span>&#8221;.
10272                 Any of these variables can be set in the package's
10273                 Makefile to change the default build process.</p>
10274               </dd>
10275
10276               <dt><span class="term">install</span></dt>
10277
10278               <dd>
10279                 <p>Once the build stage has completed, the final
10280                 step is to install the software in public
10281                 directories, so users can access the programs and
10282                 files. As in the build-target, <code class=
10283                 "varname">$MAKE_PROGRAM</code> is invoked on
10284                 <code class="varname">$MAKEFILE</code> here, but
10285                 with the <code class=
10286                 "varname">$INSTALL_TARGET</code> instead, the
10287                 latter defaulting to &#8220;<span class=
10288                 "quote">install</span>&#8221; (plus
10289                 &#8220;<span class=
10290                 "quote">install.man</span>&#8221;, if <code class=
10291                 "varname">USE_IMAKE</code> is set).</p>
10292               </dd>
10293             </dl>
10294           </div>
10295
10296           <p>If no target is specified, the default is
10297           &#8220;<span class="quote">build</span>&#8221;. If a
10298           subsequent stage is requested, all prior stages are made:
10299           e.g. <span><strong class="command">make
10300           build</strong></span> will also perform the equivalent
10301           of:</p>
10302           <pre class="programlisting">
10303     make fetch
10304     make checksum
10305     make extract
10306     make patch
10307     make configure
10308     make build
10309 </pre>
10310         </div>
10311
10312         <div class="sect1" lang="en" xml:lang="en">
10313           <div class="titlepage">
10314             <div>
10315               <div>
10316                 <h2 class="title" style="clear: both"><a name=
10317                 "build.helpful-targets" id=
10318                 "build.helpful-targets"></a>14.3.&nbsp;Other
10319                 helpful targets</h2>
10320               </div>
10321             </div>
10322           </div>
10323
10324           <div class="variablelist">
10325             <dl>
10326               <dt><span class="term">pre/post-*</span></dt>
10327
10328               <dd>
10329                 <p>For any of the main targets described in the
10330                 previous section, two auxiliary targets exist with
10331                 &#8220;<span class="quote">pre-</span>&#8221; and
10332                 &#8220;<span class="quote">post-</span>&#8221; used
10333                 as a prefix for the main target's name. These
10334                 targets are invoked before and after the main
10335                 target is called, allowing extra configuration or
10336                 installation steps be performed from a package's
10337                 Makefile, for example, which a program's configure
10338                 script or install target omitted.</p>
10339               </dd>
10340
10341               <dt><span class="term">do-*</span></dt>
10342
10343               <dd>
10344                 <p>Should one of the main targets do the wrong
10345                 thing, and should there be no variable to fix this,
10346                 you can redefine it with the do-* target. (Note
10347                 that redefining the target itself instead of the
10348                 do-* target is a bad idea, as the pre-* and post-*
10349                 targets won't be called anymore, etc.) You will not
10350                 usually need to do this.</p>
10351               </dd>
10352
10353               <dt><span class="term">reinstall</span></dt>
10354
10355               <dd>
10356                 <p>If you did a <span><strong class="command">make
10357                 install</strong></span> and you noticed some file
10358                 was not installed properly, you can repeat the
10359                 installation with this target, which will ignore
10360                 the &#8220;<span class="quote">already
10361                 installed</span>&#8221; flag.</p>
10362               </dd>
10363
10364               <dt><span class="term">deinstall</span></dt>
10365
10366               <dd>
10367                 <p>This target does a <a href=
10368                 "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
10369                 <span class="citerefentry"><span class=
10370                 "refentrytitle">pkg_delete</span>(1)</span></a> in
10371                 the current directory, effectively de-installing
10372                 the package. The following variables can be used to
10373                 tune the behaviour:</p>
10374
10375                 <div class="variablelist">
10376                   <dl>
10377                     <dt><span class="term"><code class=
10378                     "varname">PKG_VERBOSE</code></span></dt>
10379
10380                     <dd>
10381                       <p>Add a "-v" to the <a href=
10382                       "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
10383                       <span class="citerefentry"><span class=
10384                       "refentrytitle">pkg_delete</span>(1)</span></a>
10385                       command.</p>
10386                     </dd>
10387
10388                     <dt><span class="term"><code class=
10389                     "varname">DEINSTALLDEPENDS</code></span></dt>
10390
10391                     <dd>
10392                       <p>Remove all packages that require (depend
10393                       on) the given package. This can be used to
10394                       remove any packages that may have been pulled
10395                       in by a given package, e.g. if
10396                       <span><strong class="command">make deinstall
10397                       DEINSTALLDEPENDS=1</strong></span> is done in
10398                       <code xmlns=
10399                       "http://www.w3.org/TR/xhtml1/transitional"
10400                       class="filename">pkgsrc/x11/kde</code>, this
10401                       is likely to remove whole KDE. Works by
10402                       adding &#8220;<span class=
10403                       "quote">-R</span>&#8221; to the <a href=
10404                       "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
10405                       <span class="citerefentry"><span class=
10406                       "refentrytitle">pkg_delete</span>(1)</span></a>
10407                       command line.</p>
10408                     </dd>
10409                   </dl>
10410                 </div>
10411               </dd>
10412
10413               <dt><span class="term">update</span></dt>
10414
10415               <dd>
10416                 <p>This target causes the current package to be
10417                 updated to the latest version. The package and all
10418                 depending packages first get de-installed, then
10419                 current versions of the corresponding packages get
10420                 compiled and installed. This is similar to manually
10421                 noting which packages are currently installed, then
10422                 performing a series of <span><strong class=
10423                 "command">make deinstall</strong></span> and
10424                 <span><strong class="command">make
10425                 install</strong></span> (or whatever <code class=
10426                 "varname">UPDATE_TARGET</code> is set to) for these
10427                 packages.</p>
10428
10429                 <p>You can use the &#8220;<span class=
10430                 "quote">update</span>&#8221; target to resume
10431                 package updating in case a previous
10432                 <span><strong class="command">make
10433                 update</strong></span> was interrupted for some
10434                 reason. However, in this case, make sure you don't
10435                 call <span><strong class="command">make
10436                 clean</strong></span> or otherwise remove the list
10437                 of dependent packages in <code class=
10438                 "varname">WRKDIR</code>. Otherwise, you lose the
10439                 ability to automatically update the current package
10440                 along with the dependent packages you have
10441                 installed.</p>
10442
10443                 <p>Resuming an interrupted <span><strong class=
10444                 "command">make update</strong></span> will only
10445                 work as long as the package tree remains unchanged.
10446                 If the source code for one of the packages to be
10447                 updated has been changed, resuming
10448                 <span><strong class="command">make
10449                 update</strong></span> will most certainly
10450                 fail!</p>
10451
10452                 <p>The following variables can be used either on
10453                 the command line or in <code xmlns=
10454                 "http://www.w3.org/TR/xhtml1/transitional" class=
10455                 "filename">/etc/mk.conf</code> to alter the
10456                 behaviour of <span><strong class="command">make
10457                 update</strong></span>:</p>
10458
10459                 <div class="variablelist">
10460                   <dl>
10461                     <dt><span class="term"><code class=
10462                     "varname">UPDATE_TARGET</code></span></dt>
10463
10464                     <dd>
10465                       <p>Install target to recursively use for the
10466                       updated package and the dependent packages.
10467                       Defaults to <code class=
10468                       "varname">DEPENDS_TARGET</code> if set,
10469                       &#8220;<span class=
10470                       "quote">install</span>&#8221; otherwise for
10471                       <span><strong class="command">make
10472                       update</strong></span>. e.g.
10473                       <span><strong class="command">make update
10474                       UPDATE_TARGET=package</strong></span></p>
10475                     </dd>
10476
10477                     <dt><span class="term"><code class=
10478                     "varname">NOCLEAN</code></span></dt>
10479
10480                     <dd>
10481                       <p>Don't clean up after updating. Useful if
10482                       you want to leave the work sources of the
10483                       updated packages around for inspection or
10484                       other purposes. Be sure you eventually clean
10485                       up the source tree (see the
10486                       &#8220;<span class=
10487                       "quote">clean-update</span>&#8221; target
10488                       below) or you may run into troubles with old
10489                       source code still lying around on your next
10490                       <span><strong class=
10491                       "command">make</strong></span> or
10492                       <span><strong class="command">make
10493                       update</strong></span>.</p>
10494                     </dd>
10495
10496                     <dt><span class="term"><code class=
10497                     "varname">REINSTALL</code></span></dt>
10498
10499                     <dd>
10500                       <p>Deinstall each package before installing
10501                       (making <code class=
10502                       "varname">DEPENDS_TARGET</code>). This may be
10503                       necessary if the &#8220;<span class=
10504                       "quote">clean-update</span>&#8221; target
10505                       (see below) was called after interrupting a
10506                       running <span><strong class="command">make
10507                       update</strong></span>.</p>
10508                     </dd>
10509
10510                     <dt><span class="term"><code class=
10511                     "varname">DEPENDS_TARGET</code></span></dt>
10512
10513                     <dd>
10514                       <p>Allows you to disable recursion and
10515                       hardcode the target for packages. The default
10516                       is &#8220;<span class=
10517                       "quote">update</span>&#8221; for the update
10518                       target, facilitating a recursive update of
10519                       prerequisite packages. Only set <code class=
10520                       "varname">DEPENDS_TARGET</code> if you want
10521                       to disable recursive updates. Use
10522                       <code class="varname">UPDATE_TARGET</code>
10523                       instead to just set a specific target for
10524                       each package to be installed during
10525                       <span><strong class="command">make
10526                       update</strong></span> (see above).</p>
10527                     </dd>
10528                   </dl>
10529                 </div>
10530               </dd>
10531
10532               <dt><span class="term">clean-update</span></dt>
10533
10534               <dd>
10535                 <p>Clean the source tree for all packages that
10536                 would get updated if <span><strong class=
10537                 "command">make update</strong></span> was called
10538                 from the current directory. This target should not
10539                 be used if the current package (or any of its
10540                 depending packages) have already been de-installed
10541                 (e.g., after calling <span><strong class=
10542                 "command">make update</strong></span>) or you may
10543                 lose some packages you intended to update. As a
10544                 rule of thumb: only use this target <span class=
10545                 "emphasis"><em>before</em></span> the first time
10546                 you run <span><strong class="command">make
10547                 update</strong></span> and only if you have a dirty
10548                 package tree (e.g., if you used <code class=
10549                 "varname">NOCLEAN</code>).</p>
10550
10551                 <p>If you are unsure about whether your tree is
10552                 clean, you can either perform a
10553                 <span><strong class="command">make
10554                 clean</strong></span> at the top of the tree, or
10555                 use the following sequence of commands from the
10556                 directory of the package you want to update
10557                 (<span class="emphasis"><em>before</em></span>
10558                 running <span><strong class="command">make
10559                 update</strong></span> for the first time,
10560                 otherwise you lose all the packages you wanted to
10561                 update!):</p>
10562                 <pre class="screen">
10563 <code class="prompt">#</code> <strong class=
10564 "userinput"><code>make clean-update</code></strong>
10565 <code class="prompt">#</code> <strong class=
10566 "userinput"><code>make clean CLEANDEPENDS=YES</code></strong>
10567 <code class="prompt">#</code> <strong class=
10568 "userinput"><code>make update</code></strong>
10569 </pre>
10570
10571                 <p>The following variables can be used either on
10572                 the command line or in <code xmlns=
10573                 "http://www.w3.org/TR/xhtml1/transitional" class=
10574                 "filename">/etc/mk.conf</code> to alter the
10575                 behaviour of <span><strong class="command">make
10576                 clean-update</strong></span>:</p>
10577
10578                 <div class="variablelist">
10579                   <dl>
10580                     <dt><span class="term"><code class=
10581                     "varname">CLEAR_DIRLIST</code></span></dt>
10582
10583                     <dd>
10584                       <p>After <span><strong class="command">make
10585                       clean</strong></span>, do not reconstruct the
10586                       list of directories to update for this
10587                       package. Only use this if
10588                       <span><strong class="command">make
10589                       update</strong></span> successfully installed
10590                       all packages you wanted to update. Normally,
10591                       this is done automatically on
10592                       <span><strong class="command">make
10593                       update</strong></span>, but may have been
10594                       suppressed by the <code class=
10595                       "varname">NOCLEAN</code> variable (see
10596                       above).</p>
10597                     </dd>
10598                   </dl>
10599                 </div>
10600               </dd>
10601
10602               <dt><span class="term">info</span></dt>
10603
10604               <dd>
10605                 <p>This target invokes <a href=
10606                 "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1+NetBSD-current">
10607                 <span class="citerefentry"><span class=
10608                 "refentrytitle">pkg_info</span>(1)</span></a> for
10609                 the current package. You can use this to check
10610                 which version of a package is installed.</p>
10611               </dd>
10612
10613               <dt><span class="term">readme</span></dt>
10614
10615               <dd>
10616                 <p>This target generates a <code xmlns=
10617                 "http://www.w3.org/TR/xhtml1/transitional" class=
10618                 "filename">README.html</code> file, which can be
10619                 viewed using a browser such as <a xmlns=
10620                 "http://www.w3.org/TR/xhtml1/transitional" href=
10621                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/mozilla/README.html"
10622                 target="_top"><code xmlns="" class=
10623                 "filename">www/mozilla</code></a> or <a xmlns=
10624                 "http://www.w3.org/TR/xhtml1/transitional" href=
10625                 "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/links/README.html"
10626                 target="_top"><code xmlns="" class=
10627                 "filename">www/links</code></a>. The generated
10628                 files contain references to any packages which are
10629                 in the <code class="varname">PACKAGES</code>
10630                 directory on the local host. The generated files
10631                 can be made to refer to URLs based on <code class=
10632                 "varname">FTP_PKG_URL_HOST</code> and <code class=
10633                 "varname">FTP_PKG_URL_DIR</code>. For example, if I
10634                 wanted to generate <code xmlns=
10635                 "http://www.w3.org/TR/xhtml1/transitional" class=
10636                 "filename">README.html</code> files which pointed
10637                 to binary packages on the local machine, in the
10638                 directory <code xmlns=
10639                 "http://www.w3.org/TR/xhtml1/transitional" class=
10640                 "filename">/usr/packages</code>, set <code class=
10641                 "varname">FTP_PKG_URL_HOST=file://localhost</code>
10642                 and <code class=
10643                 "varname">FTP_PKG_URL_DIR=/usr/packages</code>. The
10644                 <code class="varname">${PACKAGES}</code> directory
10645                 and its subdirectories will be searched for all the
10646                 binary packages.</p>
10647               </dd>
10648
10649               <dt><span class="term">readme-all</span></dt>
10650
10651               <dd>
10652                 <p>Use this target to create a file <code xmlns=
10653                 "http://www.w3.org/TR/xhtml1/transitional" class=
10654                 "filename">README-all.html</code> which contains a
10655                 list of all packages currently available in the
10656                 NetBSD Packages Collection, together with the
10657                 category they belong to and a short description.
10658                 This file is compiled from the <code xmlns=
10659                 "http://www.w3.org/TR/xhtml1/transitional" class=
10660                 "filename">pkgsrc/*/README.html</code> files, so be
10661                 sure to run this <span class=
10662                 "emphasis"><em>after</em></span> a
10663                 <span><strong class="command">make
10664                 readme</strong></span>.</p>
10665               </dd>
10666
10667               <dt><span class="term">cdrom-readme</span></dt>
10668
10669               <dd>
10670                 <p>This is very much the same as the
10671                 &#8220;<span class="quote">readme</span>&#8221;
10672                 target (see above), but is to be used when
10673                 generating a pkgsrc tree to be written to a CD-ROM.
10674                 This target also produces <code xmlns=
10675                 "http://www.w3.org/TR/xhtml1/transitional" class=
10676                 "filename">README.html</code> files, and can be
10677                 made to refer to URLs based on <code class=
10678                 "varname">CDROM_PKG_URL_HOST</code> and
10679                 <code class="varname">CDROM_PKG_URL_DIR</code>.</p>
10680               </dd>
10681
10682               <dt><span class="term">show-distfiles</span></dt>
10683
10684               <dd>
10685                 <p>This target shows which distfiles and patchfiles
10686                 are needed to build the package. (<code class=
10687                 "varname">DISTFILES</code> and <code class=
10688                 "varname">PATCHFILES</code>, but not <code xmlns=
10689                 "http://www.w3.org/TR/xhtml1/transitional" class=
10690                 "filename">patches/*</code>)</p>
10691               </dd>
10692
10693               <dt><span class="term">show-downlevel</span></dt>
10694
10695               <dd>
10696                 <p>This target shows nothing if the package is not
10697                 installed. If a version of this package is
10698                 installed, but is not the version provided in this
10699                 version of pkgsrc, then a warning message is
10700                 displayed. This target can be used to show which of
10701                 your installed packages are downlevel, and so the
10702                 old versions can be deleted, and the current ones
10703                 added.</p>
10704               </dd>
10705
10706               <dt><span class="term">show-pkgsrc-dir</span></dt>
10707
10708               <dd>
10709                 <p>This target shows the directory in the pkgsrc
10710                 hierarchy from which the package can be built and
10711                 installed. This may not be the same directory as
10712                 the one from which the package was installed. This
10713                 target is intended to be used by people who may
10714                 wish to upgrade many packages on a single host, and
10715                 can be invoked from the top-level pkgsrc Makefile
10716                 by using the &#8220;<span class=
10717                 "quote">show-host-specific-pkgs</span>&#8221;
10718                 target.</p>
10719               </dd>
10720
10721               <dt><span class=
10722               "term">show-installed-depends</span></dt>
10723
10724               <dd>
10725                 <p>This target shows which installed packages match
10726                 the current package's <code class=
10727                 "varname">DEPENDS</code>. Useful if out of date
10728                 dependencies are causing build problems.</p>
10729               </dd>
10730
10731               <dt><span class="term">check-shlibs</span></dt>
10732
10733               <dd>
10734                 <p>After a package is installed, check all its
10735                 binaries and (on ELF platforms) shared libraries to
10736                 see if they find the shared libs they need. Run by
10737                 default if <code class=
10738                 "varname">PKG_DEVELOPER</code> is set in
10739                 <code xmlns=
10740                 "http://www.w3.org/TR/xhtml1/transitional" class=
10741                 "filename">/etc/mk.conf</code>.</p>
10742               </dd>
10743
10744               <dt><span class="term">print-PLIST</span></dt>
10745
10746               <dd>
10747                 <p>After a &#8220;<span class="quote">make
10748                 install</span>&#8221; from a new or upgraded pkg,
10749                 this prints out an attempt to generate a new
10750                 <code xmlns=
10751                 "http://www.w3.org/TR/xhtml1/transitional" class=
10752                 "filename">PLIST</code> from a <span><strong class=
10753                 "command">find -newer
10754                 work/.extract_done</strong></span>. An attempt is
10755                 made to care for shared libs etc., but it is
10756                 <span class="emphasis"><em>strongly</em></span>
10757                 recommended to review the result before putting it
10758                 into <code xmlns=
10759                 "http://www.w3.org/TR/xhtml1/transitional" class=
10760                 "filename">PLIST</code>. On upgrades, it's useful
10761                 to diff the output of this command against an
10762                 already existing <code xmlns=
10763                 "http://www.w3.org/TR/xhtml1/transitional" class=
10764                 "filename">PLIST</code> file.</p>
10765
10766                 <p>If the package installs files via <a href=
10767                 "http://netbsd.gw.com/cgi-bin/man-cgi?tar+1+NetBSD-current">
10768                 <span class="citerefentry"><span class=
10769                 "refentrytitle">tar</span>(1)</span></a> or other
10770                 methods that don't update file access times, be
10771                 sure to add these files manually to your
10772                 <code xmlns=
10773                 "http://www.w3.org/TR/xhtml1/transitional" class=
10774                 "filename">PLIST</code>, as the &#8220;<span class=
10775                 "quote">find -newer</span>&#8221; command used by
10776                 this target won't catch them!</p>
10777
10778                 <p>See <a href="#print-PLIST" title=
10779                 "10.3.&nbsp;Tweaking output of make print-PLIST">Section&nbsp;10.3,
10780                 &#8220;Tweaking output of <span><strong class=
10781                 "command">make
10782                 print-PLIST</strong></span>&#8221;</a> for more
10783                 information on this target.</p>
10784               </dd>
10785
10786               <dt><span class="term">bulk-package</span></dt>
10787
10788               <dd>
10789                 <p>Used to do bulk builds. If an appropriate binary
10790                 package already exists, no action is taken. If not,
10791                 this target will compile, install and package it
10792                 (and its depends, if <code class=
10793                 "varname">PKG_DEPENDS</code> is set properly. See
10794                 <a href="#binary.configuration" title=
10795                 "6.3.1.&nbsp;Configuration">Section&nbsp;6.3.1,
10796                 &#8220;Configuration&#8221;</a>). After creating
10797                 the binary package, the sources, the just-installed
10798                 package and its required packages are removed,
10799                 preserving free disk space.</p>
10800
10801                 <p><span class="emphasis"><em>Beware that this
10802                 target may deinstall all packages installed on a
10803                 system!</em></span></p>
10804               </dd>
10805
10806               <dt><span class="term">bulk-install</span></dt>
10807
10808               <dd>
10809                 <p>Used during bulk-installs to install required
10810                 packages. If an up-to-date binary package is
10811                 available, it will be installed via <a href=
10812                 "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
10813                 <span class="citerefentry"><span class=
10814                 "refentrytitle">pkg_add</span>(1)</span></a>. If
10815                 not, <span><strong class="command">make
10816                 bulk-package</strong></span> will be executed, but
10817                 the installed binary won't be removed.</p>
10818
10819                 <p>A binary package is considered
10820                 &#8220;<span class="quote">up-to-date</span>&#8221;
10821                 to be installed via <a href=
10822                 "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
10823                 <span class="citerefentry"><span class=
10824                 "refentrytitle">pkg_add</span>(1)</span></a>
10825                 if:</p>
10826
10827                 <div class="itemizedlist">
10828                   <ul type="disc">
10829                     <li>
10830                       <p>None of the package's files (<code xmlns=
10831                       "http://www.w3.org/TR/xhtml1/transitional"
10832                       class="filename">Makefile</code>, ...) were
10833                       modified since it was built.</p>
10834                     </li>
10835
10836                     <li>
10837                       <p>None of the package's required (binary)
10838                       packages were modified since it was
10839                       built.</p>
10840                     </li>
10841                   </ul>
10842                 </div>
10843
10844                 <p><span class="emphasis"><em>Beware that this
10845                 target may deinstall all packages installed on a
10846                 system!</em></span></p>
10847               </dd>
10848             </dl>
10849           </div>
10850         </div>
10851       </div>
10852
10853       <div class="chapter" lang="en" xml:lang="en">
10854         <div class="titlepage">
10855           <div>
10856             <div>
10857               <h2 class="title"><a name="fixes" id=
10858               "fixes"></a>Chapter&nbsp;15.&nbsp;Notes on fixes for
10859               packages</h2>
10860             </div>
10861           </div>
10862         </div>
10863
10864         <div class="toc">
10865           <p><b>Table of Contents</b></p>
10866
10867           <dl>
10868             <dt><span class="sect1"><a href=
10869             "#general-operation">15.1. General
10870             operation</a></span></dt>
10871
10872             <dd>
10873               <dl>
10874                 <dt><span class="sect2"><a href=
10875                 "#pulling-vars-from-etc-mk.conf">15.1.1. How to
10876                 pull in variables from /etc/mk.conf</a></span></dt>
10877
10878                 <dt><span class="sect2"><a href=
10879                 "#where-to-install-documentation">15.1.2. Where to
10880                 install documentation</a></span></dt>
10881
10882                 <dt><span class="sect2"><a href=
10883                 "#restricted-packages">15.1.3. Restricted
10884                 packages</a></span></dt>
10885
10886                 <dt><span class="sect2"><a href=
10887                 "#dependencies">15.1.4. Handling
10888                 dependencies</a></span></dt>
10889
10890                 <dt><span class="sect2"><a href=
10891                 "#conflicts">15.1.5. Handling conflicts with other
10892                 packages</a></span></dt>
10893
10894                 <dt><span class="sect2"><a href=
10895                 "#not-building-packages">15.1.6. Packages that
10896                 cannot or should not be built</a></span></dt>
10897
10898                 <dt><span class="sect2"><a href=
10899                 "#undeletable-packages">15.1.7. Packages which
10900                 should not be deleted, once
10901                 installed</a></span></dt>
10902
10903                 <dt><span class="sect2"><a href=
10904                 "#security-handling">15.1.8. Handling packages with
10905                 security problems</a></span></dt>
10906
10907                 <dt><span class="sect2"><a href=
10908                 "#compiler-bugs">15.1.9. How to handle compiler
10909                 bugs</a></span></dt>
10910
10911                 <dt><span class="sect2"><a href=
10912                 "#bumping-pkgrevision">15.1.10. How to handle
10913                 incrementing versions when fixing an existing
10914                 package</a></span></dt>
10915
10916                 <dt><span class="sect2"><a href=
10917                 "#portability-of-packages">15.1.11. Portability of
10918                 packages</a></span></dt>
10919               </dl>
10920             </dd>
10921
10922             <dt><span class="sect1"><a href=
10923             "#downloading-issues">15.2. Possible downloading
10924             issues</a></span></dt>
10925
10926             <dd>
10927               <dl>
10928                 <dt><span class="sect2"><a href=
10929                 "#no-plain-download">15.2.1. Packages whose
10930                 distfiles aren't available for plain
10931                 downloading</a></span></dt>
10932
10933                 <dt><span class="sect2"><a href=
10934                 "#modified-distfiles-same-name">15.2.2. How to
10935                 handle modified distfiles with the 'old'
10936                 name</a></span></dt>
10937               </dl>
10938             </dd>
10939
10940             <dt><span class="sect1"><a href=
10941             "#configuration-gotchas">15.3. Configuration
10942             gotchas</a></span></dt>
10943
10944             <dd>
10945               <dl>
10946                 <dt><span class="sect2"><a href=
10947                 "#fixes.libtool">15.3.1. Shared libraries -
10948                 libtool</a></span></dt>
10949
10950                 <dt><span class="sect2"><a href=
10951                 "#using-libtool">15.3.2. Using libtool on GNU
10952                 packages that already support
10953                 libtool</a></span></dt>
10954
10955                 <dt><span class="sect2"><a href=
10956                 "#autoconf-automake">15.3.3. GNU
10957                 Autoconf/Automake</a></span></dt>
10958               </dl>
10959             </dd>
10960
10961             <dt><span class="sect1"><a href=
10962             "#building-considerations">15.4. Building
10963             considerations</a></span></dt>
10964
10965             <dd>
10966               <dl>
10967                 <dt><span class="sect2"><a href=
10968                 "#cpp-defines">15.4.1. CPP defines</a></span></dt>
10969
10970                 <dt><span class="sect2"><a href="#cpp-list">15.4.2.
10971                 Getting a list of CPP defines</a></span></dt>
10972               </dl>
10973             </dd>
10974
10975             <dt><span class="sect1"><a href=
10976             "#package-specific-actions">15.5. Package specific
10977             actions</a></span></dt>
10978
10979             <dd>
10980               <dl>
10981                 <dt><span class="sect2"><a href=
10982                 "#user-interaction">15.5.1. User
10983                 interaction</a></span></dt>
10984
10985                 <dt><span class="sect2"><a href=
10986                 "#handling-licenses">15.5.2. Handling
10987                 licenses</a></span></dt>
10988
10989                 <dt><span class="sect2"><a href=
10990                 "#installing-score-files">15.5.3. Installing score
10991                 files</a></span></dt>
10992
10993                 <dt><span class="sect2"><a href=
10994                 "#perl-scripts">15.5.4. Packages containing perl
10995                 scripts</a></span></dt>
10996
10997                 <dt><span class="sect2"><a href=
10998                 "#hardcoded-paths">15.5.5. Packages with hardcoded
10999                 paths to other interpreters</a></span></dt>
11000
11001                 <dt><span class="sect2"><a href=
11002                 "#perl-modules">15.5.6. Packages installing perl
11003                 modules</a></span></dt>
11004
11005                 <dt><span class="sect2"><a href=
11006                 "#faq.info-files">15.5.7. Packages installing info
11007                 files</a></span></dt>
11008
11009                 <dt><span class="sect2"><a href=
11010                 "#gconf2-data-files">15.5.8. Packages installing
11011                 GConf2 data files</a></span></dt>
11012
11013                 <dt><span class="sect2"><a href=
11014                 "#scrollkeeper-data-files">15.5.9. Packages
11015                 installing scrollkeeper data files</a></span></dt>
11016
11017                 <dt><span class="sect2"><a href=
11018                 "#x11-fonts">15.5.10. Packages installing X11
11019                 fonts</a></span></dt>
11020
11021                 <dt><span class="sect2"><a href=
11022                 "#gtk2-modules">15.5.11. Packages installing GTK2
11023                 modules</a></span></dt>
11024
11025                 <dt><span class="sect2"><a href=
11026                 "#sgml-xml-data">15.5.12. Packages installing SGML
11027                 or XML data</a></span></dt>
11028
11029                 <dt><span class="sect2"><a href=
11030                 "#mime-database">15.5.13. Packages installing
11031                 extensions to the MIME database</a></span></dt>
11032
11033                 <dt><span class="sect2"><a href=
11034                 "#intltool">15.5.14. Packages using
11035                 intltool</a></span></dt>
11036
11037                 <dt><span class="sect2"><a href=
11038                 "#startup-scripts">15.5.15. Packages installing
11039                 startup scripts</a></span></dt>
11040               </dl>
11041             </dd>
11042
11043             <dt><span class="sect1"><a href=
11044             "#feedback-to-author">15.6. Feedback to the
11045             author</a></span></dt>
11046           </dl>
11047         </div>
11048
11049         <div class="sect1" lang="en" xml:lang="en">
11050           <div class="titlepage">
11051             <div>
11052               <div>
11053                 <h2 class="title" style="clear: both"><a name=
11054                 "general-operation" id=
11055                 "general-operation"></a>15.1.&nbsp;General
11056                 operation</h2>
11057               </div>
11058             </div>
11059           </div>
11060
11061           <div class="sect2" lang="en" xml:lang="en">
11062             <div class="titlepage">
11063               <div>
11064                 <div>
11065                   <h3 class="title"><a name=
11066                   "pulling-vars-from-etc-mk.conf" id=
11067                   "pulling-vars-from-etc-mk.conf"></a>15.1.1.&nbsp;How
11068                   to pull in variables from /etc/mk.conf</h3>
11069                 </div>
11070               </div>
11071             </div>
11072
11073             <p>The problem with package-defined variables that can
11074             be overridden via <code class="varname">MAKECONF</code>
11075             or <code xmlns=
11076             "http://www.w3.org/TR/xhtml1/transitional" class=
11077             "filename">/etc/mk.conf</code> is that <a href=
11078             "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
11079             <span class="citerefentry"><span class=
11080             "refentrytitle">make</span>(1)</span></a> expands a
11081             variable as it is used, but evaluates preprocessor-like
11082             statements (.if, .ifdef and .ifndef) as they are read.
11083             So, to use any variable (which may be set in
11084             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
11085             class="filename">/etc/mk.conf</code>) in one of the
11086             .if* statements, the file <code xmlns=
11087             "http://www.w3.org/TR/xhtml1/transitional" class=
11088             "filename">/etc/mk.conf</code> must be included before
11089             that .if* statement.</p>
11090
11091             <p>Rather than having a number of ad-hoc ways of
11092             including <code xmlns=
11093             "http://www.w3.org/TR/xhtml1/transitional" class=
11094             "filename">/etc/mk.conf</code>, should it exist, or
11095             <code class="varname">MAKECONF</code>, should it exist,
11096             include the <code xmlns=
11097             "http://www.w3.org/TR/xhtml1/transitional" class=
11098             "filename">pkgsrc/mk/bsd.prefs.mk</code> file in the
11099             package Makefile before any preprocessor-like .if,
11100             .ifdef, or .ifndef statements:</p>
11101             <pre class="programlisting">
11102     .include "../../mk/bsd.prefs.mk"
11103
11104     .if defined(USE_MENUS)
11105     # ...
11106     .endif
11107 </pre>
11108
11109             <p>If you wish to set the <code class=
11110             "varname">CFLAGS</code> variable in <code xmlns=
11111             "http://www.w3.org/TR/xhtml1/transitional" class=
11112             "filename">/etc/mk.conf</code>, please make sure to
11113             use:</p>
11114             <pre class="programlisting">
11115     CFLAGS+=  -your -flags
11116 </pre>
11117
11118             <p>Using <code class="varname">CFLAGS=</code> (i.e.
11119             without the &#8220;<span class="quote">+</span>&#8221;)
11120             may lead to problems with packages that need to add
11121             their own flags. Also, you may want to take a look at
11122             the <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
11123             href=
11124             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/cpuflags/README.html"
11125             target="_top"><code xmlns="" class=
11126             "filename">devel/cpuflags</code></a> package if you're
11127             interested in optimization for the current CPU.</p>
11128           </div>
11129
11130           <div class="sect2" lang="en" xml:lang="en">
11131             <div class="titlepage">
11132               <div>
11133                 <div>
11134                   <h3 class="title"><a name=
11135                   "where-to-install-documentation" id=
11136                   "where-to-install-documentation"></a>15.1.2.&nbsp;Where
11137                   to install documentation</h3>
11138                 </div>
11139               </div>
11140             </div>
11141
11142             <p>Documentation should be installed into <code xmlns=
11143             "http://www.w3.org/TR/xhtml1/transitional" class=
11144             "filename">${PREFIX}/share/doc/${PKGBASE}</code> or
11145             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
11146             class="filename">${PREFIX}/share/doc/${PKGNAME}</code>
11147             (the latter includes the version number of the
11148             package).</p>
11149           </div>
11150
11151           <div class="sect2" lang="en" xml:lang="en">
11152             <div class="titlepage">
11153               <div>
11154                 <div>
11155                   <h3 class="title"><a name="restricted-packages"
11156                   id=
11157                   "restricted-packages"></a>15.1.3.&nbsp;Restricted
11158                   packages</h3>
11159                 </div>
11160               </div>
11161             </div>
11162
11163             <p>Some licenses restrict how software may be
11164             re-distributed. In order to satisfy these restrictions,
11165             the package system defines five make variables that can
11166             be set to note these restrictions:</p>
11167
11168             <div class="itemizedlist">
11169               <ul type="disc">
11170                 <li>
11171                   <p><code class="varname">RESTRICTED</code></p>
11172
11173                   <p>This variable should be set whenever a
11174                   restriction exists (regardless of its kind). Set
11175                   this variable to a string containing the reason
11176                   for the restriction.</p>
11177                 </li>
11178
11179                 <li>
11180                   <p><code class=
11181                   "varname">NO_BIN_ON_CDROM</code></p>
11182
11183                   <p>Binaries may not be placed on CD-ROM. Set this
11184                   variable to <code class=
11185                   "varname">${RESTRICTED}</code> whenever a binary
11186                   package may not be included on a CD-ROM.</p>
11187                 </li>
11188
11189                 <li>
11190                   <p><code class="varname">NO_BIN_ON_FTP</code></p>
11191
11192                   <p>Binaries may not be placed on an FTP server.
11193                   Set this variable to <code class=
11194                   "varname">${RESTRICTED}</code> whenever a binary
11195                   package may not not be made available on the
11196                   Internet.</p>
11197                 </li>
11198
11199                 <li>
11200                   <p><code class=
11201                   "varname">NO_SRC_ON_CDROM</code></p>
11202
11203                   <p>Distfiles may not be placed on CD-ROM. Set
11204                   this variable to <code class=
11205                   "varname">${RESTRICTED}</code> if re-distribution
11206                   of the source code or other distfile(s) is not
11207                   allowed on CD-ROMs.</p>
11208                 </li>
11209
11210                 <li>
11211                   <p><code class="varname">NO_SRC_ON_FTP</code></p>
11212
11213                   <p>Distfiles may not be placed on FTP. Set this
11214                   variable to <code class=
11215                   "varname">${RESTRICTED}</code> if re-distribution
11216                   of the source code or other distfile(s) via the
11217                   Internet is not allowed.</p>
11218                 </li>
11219               </ul>
11220             </div>
11221
11222             <p>Please note that the use of <code class=
11223             "varname">NO_PACKAGE</code>, <code class=
11224             "varname">IGNORE</code>, <code class=
11225             "varname">NO_CDROM</code>, or other generic make
11226             variables to denote restrictions is deprecated, because
11227             they unconditionally prevent users from generating
11228             binary packages!</p>
11229           </div>
11230
11231           <div class="sect2" lang="en" xml:lang="en">
11232             <div class="titlepage">
11233               <div>
11234                 <div>
11235                   <h3 class="title"><a name="dependencies" id=
11236                   "dependencies"></a>15.1.4.&nbsp;Handling
11237                   dependencies</h3>
11238                 </div>
11239               </div>
11240             </div>
11241
11242             <p>Your package may depend on some other package being
11243             present - and there are various ways of expressing this
11244             dependency. pkgsrc supports the <code class=
11245             "varname">BUILD_DEPENDS</code> and <code class=
11246             "varname">DEPENDS</code> definitions, the <code class=
11247             "varname">USE_TOOLS</code> definition, as well as
11248             dependencies via <code xmlns=
11249             "http://www.w3.org/TR/xhtml1/transitional" class=
11250             "filename">buildlink3.mk</code>, which is the preferred
11251             way to handle dependencies, and which uses the
11252             variables named above. See <a href="#buildlink" title=
11253             "Chapter&nbsp;11.&nbsp;Buildlink methodology">Chapter&nbsp;11,
11254             <i>Buildlink methodology</i></a> for more
11255             information.</p>
11256
11257             <p>The basic difference between the two variables is as
11258             follows: The <code class="varname">DEPENDS</code>
11259             definition registers that pre-requisite in the binary
11260             package so it will be pulled in when the binary package
11261             is later installed, whilst the <code class=
11262             "varname">BUILD_DEPENDS</code> definition does not,
11263             marking a dependency that is only needed for building
11264             the package.</p>
11265
11266             <p>This means that if you only need a package present
11267             whilst you are building, it should be noted as a
11268             <code class="varname">BUILD_DEPENDS</code>.</p>
11269
11270             <p>The format for a <code class=
11271             "varname">BUILD_DEPENDS</code> and a <code class=
11272             "varname">DEPENDS</code> definition is:</p>
11273             <pre class="programlisting">
11274     &lt;pre-req-package-name&gt;:../../&lt;category&gt;/&lt;pre-req-package&gt;
11275 </pre>
11276
11277             <p>Please note that the &#8220;<span class=
11278             "quote">pre-req-package-name</span>&#8221; may include
11279             any of the wildcard version numbers recognized by
11280             <a href=
11281             "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1+NetBSD-current">
11282             <span class="citerefentry"><span class=
11283             "refentrytitle">pkg_info</span>(1)</span></a>.</p>
11284
11285             <div class="orderedlist">
11286               <ol type="1">
11287                 <li>
11288                   <p>If your package needs another package's
11289                   binaries or libraries to build or run, and if
11290                   that package has a <code xmlns=
11291                   "http://www.w3.org/TR/xhtml1/transitional" class=
11292                   "filename">buildlink3.mk</code> file available,
11293                   use it:</p>
11294                   <pre class="programlisting">
11295     .include "../../graphics/jpeg/buildlink3.mk"
11296 </pre>
11297                 </li>
11298
11299                 <li>
11300                   <p>If your package needs to use another package
11301                   to build itself and there is no <code xmlns=
11302                   "http://www.w3.org/TR/xhtml1/transitional" class=
11303                   "filename">buildlink3.mk</code> file available,
11304                   use the <code class=
11305                   "varname">BUILD_DEPENDS</code> definition:</p>
11306                   <pre class="programlisting">
11307     BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf
11308 </pre>
11309                 </li>
11310
11311                 <li>
11312                   <p>If your package needs a library with which to
11313                   link and again there is no <code xmlns=
11314                   "http://www.w3.org/TR/xhtml1/transitional" class=
11315                   "filename">buildlink3.mk</code> file available,
11316                   this is specified using the <code class=
11317                   "varname">DEPENDS</code> definition. An example
11318                   of this is the <a xmlns=
11319                   "http://www.w3.org/TR/xhtml1/transitional" href=
11320                   "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/lyx/README.html"
11321                   target="_top"><code xmlns="" class=
11322                   "filename">print/lyx</code></a> package, which
11323                   uses the xpm library, version 3.4j to build:</p>
11324                   <pre class="programlisting">
11325     DEPENDS+=       xpm-3.4j:../../graphics/xpm
11326 </pre>
11327
11328                   <p>You can also use wildcards in package
11329                   dependences:</p>
11330                   <pre class="programlisting">
11331     DEPENDS+=       xpm-[0-9]*:../../graphics/xpm
11332 </pre>
11333
11334                   <p>Note that such wildcard dependencies are
11335                   retained when creating binary packages. The
11336                   dependency is checked when installing the binary
11337                   package and any package which matches the pattern
11338                   will be used. Wildcard dependencies should be
11339                   used with care.</p>
11340
11341                   <p>The &#8220;<span class=
11342                   "quote">-[0-9]*</span>&#8221; should be used
11343                   instead of &#8220;<span class=
11344                   "quote">-*</span>&#8221; to avoid potentially
11345                   ambiguous matches such as &#8220;<span class=
11346                   "quote">tk-postgresql</span>&#8221; matching a
11347                   &#8220;<span class="quote">tk-*</span>&#8221;
11348                   <code class="varname">DEPENDS</code>.</p>
11349
11350                   <p>Wildcards can also be used to specify that a
11351                   package will only build against a certain minimum
11352                   version of a pre-requisite:</p>
11353                   <pre class="programlisting">
11354     DEPENDS+=       tiff&gt;=3.5.4:../../graphics/tiff
11355 </pre>
11356
11357                   <p>This means that the package will build against
11358                   version 3.5.4 of the tiff library or newer. Such
11359                   a dependency may be warranted if, for example,
11360                   the API of the library has changed with version
11361                   3.5.4 and a package would not compile against an
11362                   earlier version of tiff.</p>
11363
11364                   <p>Please note that such dependencies should only
11365                   be updated if a package requires a newer
11366                   pre-requisite, but not to denote recommendations
11367                   such as security updates or ABI changes that do
11368                   not prevent a package from building correctly.
11369                   Such recommendations can be expressed using
11370                   <code class="varname">RECOMMENDED</code>:</p>
11371                   <pre class="programlisting">
11372     RECOMMENDED+=   tiff&gt;=3.6.1:../../graphics/tiff
11373 </pre>
11374
11375                   <p>In addition to the above <code class=
11376                   "varname">DEPENDS</code> line, this denotes that
11377                   while a package will build against
11378                   tiff&gt;=3.5.4, at least version 3.6.1 is
11379                   recommended. <code class=
11380                   "varname">RECOMMENDED</code> entries will be
11381                   turned into dependencies unless explicitly
11382                   ignored (in which case a warning will be
11383                   printed).</p>
11384
11385                   <p>To ignore these dependency recommendations and
11386                   just use the required <code class=
11387                   "varname">DEPENDS</code>, set <code class=
11388                   "varname">IGNORE_RECOMMENDED=YES</code>. This may
11389                   make it easier and faster to update packages
11390                   built using pkgsrc, since older compatible
11391                   dependencies can continue to be used. This is
11392                   useful for people who watch their rebuilds very
11393                   carefully; it is not very good as a
11394                   general-purpose hammer. If you use it, you need
11395                   to be mindful of possible ABI changes, including
11396                   those from the underlying OS.</p>
11397
11398                   <p>Packages that are built with recommendations
11399                   ignored may not be uploaded to ftp.NetBSD.org by
11400                   developers and should not be used across
11401                   different systems that may have different
11402                   versions of binary packages installed.</p>
11403
11404                   <p>For security fixes, please update the package
11405                   vulnerabilities file as well as setting
11406                   <code class="varname">RECOMMENDED</code>, see
11407                   <a href="#security-handling" title=
11408                   "15.1.8.&nbsp;Handling packages with security problems">
11409                   Section 15.1.8, &#8220;Handling packages with
11410                   security problems&#8221;</a> for more
11411                   information.</p>
11412                 </li>
11413
11414                 <li>
11415                   <p>If your package needs some executable to be
11416                   able to run correctly and if there's no
11417                   <code xmlns=
11418                   "http://www.w3.org/TR/xhtml1/transitional" class=
11419                   "filename">buildlink3.mk</code> file, this is
11420                   specified using the <code class=
11421                   "varname">DEPENDS</code> variable. The <a xmlns=
11422                   "http://www.w3.org/TR/xhtml1/transitional" href=
11423                   "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/lyx/README.html"
11424                   target="_top"><code xmlns="" class=
11425                   "filename">print/lyx</code></a> package needs to
11426                   be able to execute the latex binary from the
11427                   teTeX package when it runs, and that is
11428                   specified:</p>
11429                   <pre class="programlisting">
11430     DEPENDS+=        teTeX-[0-9]*:../../print/teTeX
11431 </pre>
11432
11433                   <p>The comment about wildcard dependencies from
11434                   previous paragraph applies here, too.</p>
11435                 </li>
11436               </ol>
11437             </div>
11438
11439             <p>If your package needs files from another package to
11440             build, see the first part of the &#8220;<span class=
11441             "quote">do-configure</span>&#8221; target <a xmlns=
11442             "http://www.w3.org/TR/xhtml1/transitional" href=
11443             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/ghostscript5/README.html"
11444             target="_top"><code xmlns="" class=
11445             "filename">print/ghostscript5</code></a> package (it
11446             relies on the jpeg sources being present in source form
11447             during the build):</p>
11448             <pre class="programlisting">
11449     if [ ! -e ${_PKGSRCDIR}/graphics/jpeg/${WRKDIR:T}/jpeg-6b ]; then    \
11450         cd ${_PKGSRCDIR}/../../graphics/jpeg &amp;&amp; ${MAKE} extract; \
11451     fi
11452 </pre>
11453
11454             <p>If you build any other packages that way, please
11455             make sure the working files are deleted too when this
11456             package's working files are cleaned up. The easiest way
11457             to do so is by adding a pre-clean target:</p>
11458             <pre class="programlisting">
11459     pre-clean:
11460             cd ${_PKGSRCDIR}/../../graphics/jpeg &amp;&amp; ${MAKE} clean
11461 </pre>
11462
11463             <p>Please also note the <code class=
11464             "varname">BUILD_USES_MSGFMT</code> and <code class=
11465             "varname">BUILD_USES_GETTEXT_M4</code> definitions,
11466             which are provided as convenience definitions. The
11467             former works out whether <a href=
11468             "http://netbsd.gw.com/cgi-bin/man-cgi?msgfmt+1+NetBSD-current">
11469             <span class="citerefentry"><span class=
11470             "refentrytitle">msgfmt</span>(1)</span></a> is part of
11471             the base system, and, if it isn't, installs the
11472             <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
11473             href=
11474             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/gettext/README.html"
11475             target="_top"><code xmlns="" class=
11476             "filename">devel/gettext</code></a> package. The latter
11477             adds a build dependency on either an installed version
11478             of an older gettext package, or if it isn't, installs
11479             the <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
11480             href=
11481             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/gettext-m4/README.html"
11482             target="_top"><code xmlns="" class=
11483             "filename">devel/gettext-m4</code></a> package.</p>
11484           </div>
11485
11486           <div class="sect2" lang="en" xml:lang="en">
11487             <div class="titlepage">
11488               <div>
11489                 <div>
11490                   <h3 class="title"><a name="conflicts" id=
11491                   "conflicts"></a>15.1.5.&nbsp;Handling conflicts
11492                   with other packages</h3>
11493                 </div>
11494               </div>
11495             </div>
11496
11497             <p>Your package may conflict with other packages a user
11498             might already have installed on his system, e.g. if
11499             your package installs the same set of files like
11500             another package in our pkgsrc tree.</p>
11501
11502             <p>In this case you can set <code class=
11503             "varname">CONFLICTS</code> to a space-separated list of
11504             packages (including version string) your package
11505             conflicts with.</p>
11506
11507             <p>For example, <a xmlns=
11508             "http://www.w3.org/TR/xhtml1/transitional" href=
11509             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/Xaw3d/README.html"
11510             target="_top"><code xmlns="" class=
11511             "filename">x11/Xaw3d</code></a> and <a xmlns=
11512             "http://www.w3.org/TR/xhtml1/transitional" href=
11513             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/Xaw-Xpm/README.html"
11514             target="_top"><code xmlns="" class=
11515             "filename">x11/Xaw-Xpm</code></a> install the same
11516             shared library, thus you set in <code xmlns=
11517             "http://www.w3.org/TR/xhtml1/transitional" class=
11518             "filename">pkgsrc/x11/Xaw3d/Makefile</code>:</p>
11519             <pre class="programlisting">
11520     CONFLICTS=      Xaw-Xpm-[0-9]*
11521 </pre>
11522
11523             <p>and in <code xmlns=
11524             "http://www.w3.org/TR/xhtml1/transitional" class=
11525             "filename">pkgsrc/x11/Xaw-Xpm/Makefile</code>:</p>
11526             <pre class="programlisting">
11527     CONFLICTS=      Xaw3d-[0-9]*
11528 </pre>
11529
11530             <p>Packages will automatically conflict with other
11531             packages with the name prefix and a different version
11532             string. &#8220;<span class=
11533             "quote">Xaw3d-1.5</span>&#8221; e.g. will automatically
11534             conflict with the older version &#8220;<span class=
11535             "quote">Xaw3d-1.3</span>&#8221;.</p>
11536           </div>
11537
11538           <div class="sect2" lang="en" xml:lang="en">
11539             <div class="titlepage">
11540               <div>
11541                 <div>
11542                   <h3 class="title"><a name="not-building-packages"
11543                   id=
11544                   "not-building-packages"></a>15.1.6.&nbsp;Packages
11545                   that cannot or should not be built</h3>
11546                 </div>
11547               </div>
11548             </div>
11549
11550             <p>There are several reasons why a package might be
11551             instructed to not build under certain circumstances. If
11552             the package builds and runs on most platforms, the
11553             exceptions should be noted with <code class=
11554             "varname">NOT_FOR_PLATFORM</code>. If the package
11555             builds and runs on a small handful of platforms, set
11556             <code class="varname">ONLY_FOR_PLATFORM</code> instead.
11557             Both <code class="varname">ONLY_FOR_PLATFORM</code> and
11558             <code class="varname">NOT_FOR_PLATFORM</code> are OS
11559             triples (OS-version-platform) that can use glob-style
11560             wildcards.</p>
11561
11562             <p>If the package should be skipped (for example,
11563             because it provides functionality already provided by
11564             the system), set <code class=
11565             "varname">PKG_SKIP_REASON</code> to a descriptive
11566             message. If the package should fail because some
11567             preconditions are not met, set <code class=
11568             "varname">PKG_FAIL_REASON</code> to a descriptive
11569             message.</p>
11570           </div>
11571
11572           <div class="sect2" lang="en" xml:lang="en">
11573             <div class="titlepage">
11574               <div>
11575                 <div>
11576                   <h3 class="title"><a name="undeletable-packages"
11577                   id=
11578                   "undeletable-packages"></a>15.1.7.&nbsp;Packages
11579                   which should not be deleted, once installed</h3>
11580                 </div>
11581               </div>
11582             </div>
11583
11584             <p>To ensure that a package may not be deleted, once it
11585             has been installed, the <code class=
11586             "varname">PKG_PRESERVE</code> definition should be set
11587             in the package Makefile. This will be carried into any
11588             binary package that is made from this pkgsrc entry. A
11589             &#8220;<span class="quote">preserved</span>&#8221;
11590             package will not be deleted using <a href=
11591             "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
11592             <span class="citerefentry"><span class=
11593             "refentrytitle">pkg_delete</span>(1)</span></a> unless
11594             the &#8220;<span class="quote">-f</span>&#8221; option
11595             is used.</p>
11596           </div>
11597
11598           <div class="sect2" lang="en" xml:lang="en">
11599             <div class="titlepage">
11600               <div>
11601                 <div>
11602                   <h3 class="title"><a name="security-handling" id=
11603                   "security-handling"></a>15.1.8.&nbsp;Handling
11604                   packages with security problems</h3>
11605                 </div>
11606               </div>
11607             </div>
11608
11609             <p>When a vulnerability is found, this should be noted
11610             in <code xmlns=
11611             "http://www.w3.org/TR/xhtml1/transitional" class=
11612             "filename">localsrc/security/advisories/pkg-vulnerabilities</code>,
11613             and after committing that file, use
11614             <span><strong class="command">make
11615             upload</strong></span> in the same directory to update
11616             the file on ftp.NetBSD.org.</p>
11617
11618             <p>After fixing the vulnerability by a patch, its
11619             <code class="varname">PKGREVISION</code> should be
11620             increased (this is of course not necessary if the
11621             problem is fixed by using a newer release of the
11622             software). In addition, if a <code xmlns=
11623             "http://www.w3.org/TR/xhtml1/transitional" class=
11624             "filename">buildlink3.mk</code> file exists for an
11625             affected package, a corresponding <code class=
11626             "varname">BUILDLINK_RECOMMENDED.<em class=
11627             "replaceable"><code>pkg</code></em></code> entry should
11628             be added or updated in it.</p>
11629
11630             <p>Also, if the fix should be applied to the stable
11631             pkgsrc branch, be sure to submit a pullup request!</p>
11632
11633             <p>Binary packages already on ftp.NetBSD.org will be
11634             handled semi-automatically by a weekly cron job.</p>
11635           </div>
11636
11637           <div class="sect2" lang="en" xml:lang="en">
11638             <div class="titlepage">
11639               <div>
11640                 <div>
11641                   <h3 class="title"><a name="compiler-bugs" id=
11642                   "compiler-bugs"></a>15.1.9.&nbsp;How to handle
11643                   compiler bugs</h3>
11644                 </div>
11645               </div>
11646             </div>
11647
11648             <p>Some source files trigger bugs in the compiler,
11649             based on combinations of compiler version and
11650             architecture and almost always relation to optimisation
11651             being enabled. Common symptoms are gcc internal errors
11652             or never finishing compiling a file.</p>
11653
11654             <p>Typically, a workaround involves testing the
11655             <code class="varname">MACHINE_ARCH</code> and compiler
11656             version, disabling optimisation for that
11657             file/<code class="varname">MACHINE_ARCH</code>/compiler
11658             combination, and documenting it in <code xmlns=
11659             "http://www.w3.org/TR/xhtml1/transitional" class=
11660             "filename">pkgsrc/doc/HACKS</code>. See that file for a
11661             number of examples!</p>
11662           </div>
11663
11664           <div class="sect2" lang="en" xml:lang="en">
11665             <div class="titlepage">
11666               <div>
11667                 <div>
11668                   <h3 class="title"><a name="bumping-pkgrevision"
11669                   id="bumping-pkgrevision"></a>15.1.10.&nbsp;How to
11670                   handle incrementing versions when fixing an
11671                   existing package</h3>
11672                 </div>
11673               </div>
11674             </div>
11675
11676             <p>When making fixes to an existing package it can be
11677             useful to change the version number in <code class=
11678             "varname">PKGNAME</code>. To avoid conflicting with
11679             future versions by the original author, a
11680             &#8220;<span class="quote">nb1</span>&#8221;,
11681             &#8220;<span class="quote">nb2</span>&#8221;, ...
11682             suffix can be used on package versions by setting
11683             <code class="varname">PKGREVISION=1</code> (2, ...).
11684             The &#8220;<span class="quote">nb</span>&#8221; is
11685             treated like a &#8220;<span class=
11686             "quote">.</span>&#8221; by the pkg tools. e.g.</p>
11687             <pre class="programlisting">
11688     DISTNAME=       foo-17.42
11689     PKGREVISION=    9
11690 </pre>
11691
11692             <p>will result in a <code class=
11693             "varname">PKGNAME</code> of &#8220;<span class=
11694             "quote">foo-17.42nb9</span>&#8221;.</p>
11695
11696             <p>When a new release of the package is released, the
11697             <code class="varname">PKGREVISION</code> should be
11698             removed, e.g. on a new minor release of the above
11699             package, things should be like:</p>
11700             <pre class="programlisting">
11701     DISTNAME=       foo-17.43
11702 </pre>
11703           </div>
11704
11705           <div class="sect2" lang="en" xml:lang="en">
11706             <div class="titlepage">
11707               <div>
11708                 <div>
11709                   <h3 class="title"><a name=
11710                   "portability-of-packages" id=
11711                   "portability-of-packages"></a>15.1.11.&nbsp;Portability
11712                   of packages</h3>
11713                 </div>
11714               </div>
11715             </div>
11716
11717             <p>One appealing feature of pkgsrc is that it runs on
11718             many different platforms. As a result, it is important
11719             to ensure, where possible, that packages in pkgsrc are
11720             portable. There are some particular details you should
11721             pay attention to while working on pkgsrc.</p>
11722
11723             <div class="sect3" lang="en" xml:lang="en">
11724               <div class="titlepage">
11725                 <div>
11726                   <div>
11727                     <h4 class="title"><a name="install-scripts" id=
11728                     "install-scripts"></a>15.1.11.1.&nbsp;${INSTALL},
11729                     ${INSTALL_DATA_DIR}, ...</h4>
11730                   </div>
11731                 </div>
11732               </div>
11733
11734               <p>The BSD-compatible <span><strong class=
11735               "command">install</strong></span> supplied with some
11736               operating systems will not perform more than one
11737               operation at a time. As such, you should call
11738               &#8220;<span class="quote">${INSTALL}</span>&#8221;,
11739               etc. like this:</p>
11740               <pre class="programlisting">
11741     ${INSTALL_DATA_DIR} ${PREFIX}/dir1
11742     ${INSTALL_DATA_DIR} ${PREFIX}/dir2
11743 </pre>
11744             </div>
11745           </div>
11746         </div>
11747
11748         <div class="sect1" lang="en" xml:lang="en">
11749           <div class="titlepage">
11750             <div>
11751               <div>
11752                 <h2 class="title" style="clear: both"><a name=
11753                 "downloading-issues" id=
11754                 "downloading-issues"></a>15.2.&nbsp;Possible
11755                 downloading issues</h2>
11756               </div>
11757             </div>
11758           </div>
11759
11760           <div class="sect2" lang="en" xml:lang="en">
11761             <div class="titlepage">
11762               <div>
11763                 <div>
11764                   <h3 class="title"><a name="no-plain-download" id=
11765                   "no-plain-download"></a>15.2.1.&nbsp;Packages
11766                   whose distfiles aren't available for plain
11767                   downloading</h3>
11768                 </div>
11769               </div>
11770             </div>
11771
11772             <p>If you need to download from a dynamic URL you can
11773             set <code class="varname">DYNAMIC_MASTER_SITES</code>
11774             and a <span><strong class="command">make
11775             fetch</strong></span> will call <code xmlns=
11776             "http://www.w3.org/TR/xhtml1/transitional" class=
11777             "filename">files/getsite.sh</code> with the name of
11778             each file to download as an argument, expecting it to
11779             output the URL of the directory from which to download
11780             it. <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
11781             href=
11782             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/graphics/ns-cult3d/README.html"
11783             target="_top"><code xmlns="" class=
11784             "filename">graphics/ns-cult3d</code></a> is an example
11785             of this usage.</p>
11786
11787             <p>If the download can't be automated, because the user
11788             must submit personal information to apply for a
11789             password, or must pay for the source, or whatever, you
11790             can set <code class="varname">_FETCH_MESSAGE</code> to
11791             a macro which displays a message explaining the
11792             situation. <code class="varname">_FETCH_MESSAGE</code>
11793             must be executable shell commands, not just a message.
11794             (Generally, it executes <code class=
11795             "varname">${ECHO}</code>). As of this writing, the
11796             following packages use this: <a xmlns=
11797             "http://www.w3.org/TR/xhtml1/transitional" href=
11798             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/cad/simian/README.html"
11799             target="_top"><code xmlns="" class=
11800             "filename">cad/simian</code></a>, <a xmlns=
11801             "http://www.w3.org/TR/xhtml1/transitional" href=
11802             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/ipv6socket/README.html"
11803             target="_top"><code xmlns="" class=
11804             "filename">devel/ipv6socket</code></a>, <a xmlns=
11805             "http://www.w3.org/TR/xhtml1/transitional" href=
11806             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/emulators/vmware-module/README.html"
11807             target="_top"><code xmlns="" class=
11808             "filename">emulators/vmware-module</code></a>,
11809             <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
11810             href=
11811             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/fonts/acroread-jpnfont/README.html"
11812             target="_top"><code xmlns="" class=
11813             "filename">fonts/acroread-jpnfont</code></a>, <a xmlns=
11814             "http://www.w3.org/TR/xhtml1/transitional" href=
11815             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/multimedia/realplayer/README.html"
11816             target="_top"><code xmlns="" class=
11817             "filename">multimedia/realplayer</code></a>, <a xmlns=
11818             "http://www.w3.org/TR/xhtml1/transitional" href=
11819             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/storage-manager/README.html"
11820             target="_top"><code xmlns="" class=
11821             "filename">sysutils/storage-manager</code></a>,
11822             <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
11823             href=
11824             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/ap-aolserver/README.html"
11825             target="_top"><code xmlns="" class=
11826             "filename">www/ap-aolserver</code></a>, <a xmlns=
11827             "http://www.w3.org/TR/xhtml1/transitional" href=
11828             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/openacs/README.html"
11829             target="_top"><code xmlns="" class=
11830             "filename">www/openacs</code></a>. Try to be consistent
11831             with them.</p>
11832           </div>
11833
11834           <div class="sect2" lang="en" xml:lang="en">
11835             <div class="titlepage">
11836               <div>
11837                 <div>
11838                   <h3 class="title"><a name=
11839                   "modified-distfiles-same-name" id=
11840                   "modified-distfiles-same-name"></a>15.2.2.&nbsp;How
11841                   to handle modified distfiles with the 'old'
11842                   name</h3>
11843                 </div>
11844               </div>
11845             </div>
11846
11847             <p>Sometimes authors of a software package make some
11848             modifications after the software was released, and they
11849             put up a new distfile without changing the package's
11850             version number. If a package is already in pkgsrc at
11851             that time, the checksum will no longer match. The
11852             contents of the new distfile should be compared against
11853             the old one before changing anything, to make sure the
11854             distfile was really updated on purpose, and that no
11855             trojan horse or so crept in. Then, the correct way to
11856             work around this is to set <code class=
11857             "varname">DIST_SUBDIR</code> to a unique directory
11858             name, usually based on <code class=
11859             "varname">PKGNAME_NOREV</code>. In case this happens
11860             more often, <code class="varname">PKGNAME</code> can be
11861             used (thus including the <code xmlns=
11862             "http://www.w3.org/TR/xhtml1/transitional" class=
11863             "filename">nbX</code> suffix) or a date stamp can be
11864             appended, like <code class=
11865             "varname">${PKGNAME_NOREV}-YYYYMMDD</code>. Do not
11866             forget regenerating the <code xmlns=
11867             "http://www.w3.org/TR/xhtml1/transitional" class=
11868             "filename">distinfo</code> file after that, since it
11869             contains the <code class="varname">DIST_SUBDIR</code>
11870             path in the filenames. Furthermore, a mail to the
11871             package's authors seems appropriate telling them that
11872             changing distfiles after releases without changing the
11873             file names is not good practice.</p>
11874           </div>
11875         </div>
11876
11877         <div class="sect1" lang="en" xml:lang="en">
11878           <div class="titlepage">
11879             <div>
11880               <div>
11881                 <h2 class="title" style="clear: both"><a name=
11882                 "configuration-gotchas" id=
11883                 "configuration-gotchas"></a>15.3.&nbsp;Configuration
11884                 gotchas</h2>
11885               </div>
11886             </div>
11887           </div>
11888
11889           <div class="sect2" lang="en" xml:lang="en">
11890             <div class="titlepage">
11891               <div>
11892                 <div>
11893                   <h3 class="title"><a name="fixes.libtool" id=
11894                   "fixes.libtool"></a>15.3.1.&nbsp;Shared libraries
11895                   - libtool</h3>
11896                 </div>
11897               </div>
11898             </div>
11899
11900             <p>pkgsrc supports many different machines, with
11901             different object formats like a.out and ELF, and
11902             varying abilities to do shared library and dynamic
11903             loading at all. To accompany this, varying commands and
11904             options have to be passed to the compiler, linker, etc.
11905             to get the Right Thing, which can be pretty annoying
11906             especially if you don't have all the machines at your
11907             hand to test things. The <a xmlns=
11908             "http://www.w3.org/TR/xhtml1/transitional" href=
11909             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/libtool/README.html"
11910             target="_top"><code xmlns="" class=
11911             "filename">devel/libtool</code></a> pkg can help here,
11912             as it just &#8220;<span class=
11913             "quote">knows</span>&#8221; how to build both static
11914             and dynamic libraries from a set of source files, thus
11915             being platform-independent.</p>
11916
11917             <p>Here's how to use libtool in a pkg in seven simple
11918             steps:</p>
11919
11920             <div class="orderedlist">
11921               <ol type="1">
11922                 <li>
11923                   <p>Add <code class=
11924                   "varname">USE_LIBTOOL=yes</code> to the package
11925                   Makefile.</p>
11926                 </li>
11927
11928                 <li>
11929                   <p>For library objects, use &#8220;<span class=
11930                   "quote">${LIBTOOL} --mode=compile
11931                   ${CC}</span>&#8221; in place of
11932                   &#8220;<span class="quote">${CC}</span>&#8221;.
11933                   You could even add it to the definition of
11934                   <code class="varname">CC</code>, if only
11935                   libraries are being built in a given Makefile.
11936                   This one command will build both PIC and non-PIC
11937                   library objects, so you need not have separate
11938                   shared and non-shared library rules.</p>
11939                 </li>
11940
11941                 <li>
11942                   <p>For the linking of the library, remove any
11943                   &#8220;<span class="quote">ar</span>&#8221;,
11944                   &#8220;<span class="quote">ranlib</span>&#8221;,
11945                   and &#8220;<span class="quote">ld
11946                   -Bshareable</span>&#8221; commands, and instead
11947                   use:</p>
11948                   <pre class="programlisting">
11949     ${LIBTOOL} --mode=link ${CC} -o ${.TARGET:.a=.la} ${OBJS:.o=.lo} \
11950         -rpath ${PREFIX}/lib -version-info major:minor
11951 </pre>
11952
11953                   <p>Note that the library is changed to have a
11954                   <code xmlns=
11955                   "http://www.w3.org/TR/xhtml1/transitional" class=
11956                   "filename">.la</code> extension, and the objects
11957                   are changed to have a <code xmlns=
11958                   "http://www.w3.org/TR/xhtml1/transitional" class=
11959                   "filename">.lo</code> extension. Change
11960                   <code class="varname">OBJS</code> as necessary.
11961                   This automatically creates all of the
11962                   <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
11963                   class="filename">.a</code>, <code xmlns=
11964                   "http://www.w3.org/TR/xhtml1/transitional" class=
11965                   "filename">.so.major.minor</code>, and ELF
11966                   symlinks (if necessary) in the build directory.
11967                   Be sure to include &#8220;<span class=
11968                   "quote">-version-info</span>&#8221;, especially
11969                   when major and minor are zero, as libtool will
11970                   otherwise strip off the shared library
11971                   version.</p>
11972
11973                   <p>From the libtool manual:</p>
11974                   <pre class="programlisting">
11975     So, libtool library versions are described by three integers:
11976
11977     CURRENT
11978         The most recent interface number that this library implements.
11979
11980     REVISION
11981         The implementation number of the CURRENT interface.
11982
11983     AGE
11984         The difference between the newest and oldest interfaces that
11985         this library implements.  In other words, the library implements
11986         all the interface numbers in the range from number `CURRENT -
11987         AGE' to `CURRENT'.
11988
11989     If two libraries have identical CURRENT and AGE numbers, then the
11990     dynamic linker chooses the library with the greater REVISION number.
11991 </pre>
11992
11993                   <p>The &#8220;<span class=
11994                   "quote">-release</span>&#8221; option will
11995                   produce different results for a.out and ELF
11996                   (excluding symlinks) in only one case. An ELF
11997                   library of the form &#8220;<span class=
11998                   "quote">libfoo-release.so.<span class=
11999                   "emphasis"><em>x</em></span>.<span class=
12000                   "emphasis"><em>y</em></span></span>&#8221; will
12001                   have a symlink of &#8220;<span class=
12002                   "quote">libfoo.so.<span class=
12003                   "emphasis"><em>x</em></span>.<span class=
12004                   "emphasis"><em>y</em></span></span>&#8221; on an
12005                   a.out platform. This is handled
12006                   automatically.</p>
12007
12008                   <p>The &#8220;<span class="quote">-rpath
12009                   argument</span>&#8221; is the install directory
12010                   of the library being built.</p>
12011
12012                   <p>In the <code xmlns=
12013                   "http://www.w3.org/TR/xhtml1/transitional" class=
12014                   "filename">PLIST</code>, include only the
12015                   <code xmlns=
12016                   "http://www.w3.org/TR/xhtml1/transitional" class=
12017                   "filename">.la</code> file, the other files will
12018                   be added automatically.</p>
12019                 </li>
12020
12021                 <li>
12022                   <p>When linking shared object (<code xmlns=
12023                   "http://www.w3.org/TR/xhtml1/transitional" class=
12024                   "filename">.so</code>) files, i.e. files that are
12025                   loaded via <a href=
12026                   "http://netbsd.gw.com/cgi-bin/man-cgi?dlopen+3+NetBSD-current">
12027                   <span class="citerefentry"><span class=
12028                   "refentrytitle">dlopen</span>(3)</span></a>, NOT
12029                   shared libraries, use &#8220;<span class=
12030                   "quote">-module -avoid-version</span>&#8221; to
12031                   prevent them getting version tacked on.</p>
12032
12033                   <p>The <code xmlns=
12034                   "http://www.w3.org/TR/xhtml1/transitional" class=
12035                   "filename">PLIST</code> file gets the
12036                   <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
12037                   class="filename">foo.so</code> entry.</p>
12038                 </li>
12039
12040                 <li>
12041                   <p>When linking programs that depend on these
12042                   libraries <span class=
12043                   "emphasis"><em>before</em></span> they are
12044                   installed, preface the <a href=
12045                   "http://netbsd.gw.com/cgi-bin/man-cgi?cc+1+NetBSD-current">
12046                   <span class="citerefentry"><span class=
12047                   "refentrytitle">cc</span>(1)</span></a> or
12048                   <a href=
12049                   "http://netbsd.gw.com/cgi-bin/man-cgi?ld+1+NetBSD-current">
12050                   <span class="citerefentry"><span class=
12051                   "refentrytitle">ld</span>(1)</span></a> line with
12052                   &#8220;<span class="quote">${LIBTOOL}
12053                   --mode=link</span>&#8221;, and it will find the
12054                   correct libraries (static or shared), but please
12055                   be aware that libtool will not allow you to
12056                   specify a relative path in -L (such as
12057                   &#8220;<span class=
12058                   "quote">-L../somelib</span>&#8221;), because it
12059                   expects you to change that argument to be the
12060                   <code xmlns=
12061                   "http://www.w3.org/TR/xhtml1/transitional" class=
12062                   "filename">.la</code> file. e.g.</p>
12063                   <pre class="programlisting">
12064     ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
12065 </pre>
12066
12067                   <p>should be changed to:</p>
12068                   <pre class="programlisting">
12069     ${LIBTOOL} --mode=link ${CC} -o <em class=
12070 "replaceable"><code>someprog</code></em> <em class=
12071 "replaceable"><code>../somelib/somelib.la</code></em>
12072 </pre>
12073
12074                   <p>and it will do the right thing with the
12075                   libraries.</p>
12076                 </li>
12077
12078                 <li>
12079                   <p>When installing libraries, preface the
12080                   <a href="http://netbsd.gw.com/cgi-bin/man-cgi?install+1+NetBSD-current">
12081                   <span class="citerefentry"><span class=
12082                   "refentrytitle">install</span>(1)</span></a> or
12083                   <a href=
12084                   "http://netbsd.gw.com/cgi-bin/man-cgi?cp+1+NetBSD-current">
12085                   <span class="citerefentry"><span class=
12086                   "refentrytitle">cp</span>(1)</span></a> command
12087                   with &#8220;<span class="quote">${LIBTOOL}
12088                   --mode=install</span>&#8221;, and change the
12089                   library name to <code xmlns=
12090                   "http://www.w3.org/TR/xhtml1/transitional" class=
12091                   "filename">.la</code>. e.g.</p>
12092                   <pre class="programlisting">
12093     ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib
12094 </pre>
12095
12096                   <p>This will install the static <code xmlns=
12097                   "http://www.w3.org/TR/xhtml1/transitional" class=
12098                   "filename">.a</code>, shared library, any needed
12099                   symlinks, and run <a href=
12100                   "http://netbsd.gw.com/cgi-bin/man-cgi?ldconfig+8+NetBSD-current">
12101                   <span class="citerefentry"><span class=
12102                   "refentrytitle">ldconfig</span>(8)</span></a>.</p>
12103                 </li>
12104
12105                 <li>
12106                   <p>In your <code xmlns=
12107                   "http://www.w3.org/TR/xhtml1/transitional" class=
12108                   "filename">PLIST</code>, include only the
12109                   <code xmlns=
12110                   "http://www.w3.org/TR/xhtml1/transitional" class=
12111                   "filename">.la</code> file (this is a change from
12112                   previous behaviour).</p>
12113                 </li>
12114               </ol>
12115             </div>
12116           </div>
12117
12118           <div class="sect2" lang="en" xml:lang="en">
12119             <div class="titlepage">
12120               <div>
12121                 <div>
12122                   <h3 class="title"><a name="using-libtool" id=
12123                   "using-libtool"></a>15.3.2.&nbsp;Using libtool on
12124                   GNU packages that already support libtool</h3>
12125                 </div>
12126               </div>
12127             </div>
12128
12129             <p>Add <code class="varname">USE_LIBTOOL=yes</code> to
12130             the package Makefile. This will override the package's
12131             own libtool in most cases. For older libtool using
12132             packages, libtool is made by ltconfig script during the
12133             do-configure step; you can check the libtool script
12134             location by doing <span><strong class="command">make
12135             configure; find work*/ -name
12136             libtool</strong></span>.</p>
12137
12138             <p><code class="varname">LIBTOOL_OVERRIDE</code>
12139             specifies which libtool scripts, relative to
12140             <code class="varname">WRKSRC</code>, to override. By
12141             default, it is set to &#8220;<span class=
12142             "quote">libtool */libtool */*/libtool</span>&#8221;. If
12143             this does not match the location of the package's
12144             libtool script(s), set it as appropriate.</p>
12145
12146             <p>If you do not need <code xmlns=
12147             "http://www.w3.org/TR/xhtml1/transitional" class=
12148             "filename">*.a</code> static libraries built and
12149             installed, then use <code class=
12150             "varname">SHLIBTOOL_OVERRIDE</code> instead.</p>
12151
12152             <p>If your package makes use of the
12153             platform-independent library for loading dynamic shared
12154             objects, that comes with libtool (libltdl), you should
12155             include devel/libltdl/buildlink3.mk.</p>
12156
12157             <p>Some packages use libtool incorrectly so that the
12158             package may not work or build in some circumstances.
12159             Some of the more common errors are:</p>
12160
12161             <div class="itemizedlist">
12162               <ul type="disc">
12163                 <li>
12164                   <p>The inclusion of a shared object (-module) as
12165                   a dependent library in an executable or library.
12166                   This in itself isn't a problem if one of two
12167                   things has been done:</p>
12168
12169                   <div class="orderedlist">
12170                     <ol type="1">
12171                       <li>
12172                         <p>The shared object is named correctly,
12173                         i.e. <code xmlns=
12174                         "http://www.w3.org/TR/xhtml1/transitional"
12175                         class="filename">libfoo.la</code>, not
12176                         <code xmlns=
12177                         "http://www.w3.org/TR/xhtml1/transitional"
12178                         class="filename">foo.la</code></p>
12179                       </li>
12180
12181                       <li>
12182                         <p>The -dlopen option is used when linking
12183                         an executable.</p>
12184                       </li>
12185                     </ol>
12186                   </div>
12187                 </li>
12188
12189                 <li>
12190                   <p>The use of libltdl without the correct calls
12191                   to initialisation routines. The function
12192                   lt_dlinit() should be called and the macro
12193                   <code class=
12194                   "varname">LTDL_SET_PRELOADED_SYMBOLS</code>
12195                   included in executables.</p>
12196                 </li>
12197               </ul>
12198             </div>
12199           </div>
12200
12201           <div class="sect2" lang="en" xml:lang="en">
12202             <div class="titlepage">
12203               <div>
12204                 <div>
12205                   <h3 class="title"><a name="autoconf-automake" id=
12206                   "autoconf-automake"></a>15.3.3.&nbsp;GNU
12207                   Autoconf/Automake</h3>
12208                 </div>
12209               </div>
12210             </div>
12211
12212             <p>If a package needs GNU autoconf or automake to be
12213             executed to regenerate the configure script and
12214             Makefile.in makefile templates, then they should be
12215             executed in a pre-configure target.</p>
12216
12217             <p>For packages that need only autoconf:</p>
12218             <pre class="programlisting">
12219     AUTOCONF_REQD=  2.50            # if default version is not good enough
12220     USE_TOOLS+=     autoconf        # use "autoconf213" for autoconf-2.13
12221     ...
12222
12223     pre-configure:
12224             cd ${WRKSRC}; autoconf
12225
12226     ...
12227 </pre>
12228
12229             <p>and for packages that need automake and
12230             autoconf:</p>
12231             <pre class="programlisting">
12232     AUTOMAKE_REQD=  1.7.1           # if default version is not good enough
12233     USE_TOOLS+=     automake        # use "automake14" for automake-1.4
12234     ...
12235
12236     pre-configure:
12237             cd ${WRKSRC};                          \
12238             aclocal; autoheader;                   \
12239             automake -a --foreign -i; autoconf
12240
12241     ...
12242 </pre>
12243
12244             <p>Packages which use GNU Automake will almost
12245             certainly require GNU Make.</p>
12246
12247             <p>There are times when the configure process makes
12248             additional changes to the generated files, which then
12249             causes the build process to try to re-execute the
12250             automake sequence. This is prevented by touching
12251             various files in the configure stage. If this causes
12252             problems with your package you can set <code class=
12253             "varname">AUTOMAKE_OVERRIDE=NO</code> in the package
12254             Makefile.</p>
12255           </div>
12256         </div>
12257
12258         <div class="sect1" lang="en" xml:lang="en">
12259           <div class="titlepage">
12260             <div>
12261               <div>
12262                 <h2 class="title" style="clear: both"><a name=
12263                 "building-considerations" id=
12264                 "building-considerations"></a>15.4.&nbsp;Building
12265                 considerations</h2>
12266               </div>
12267             </div>
12268           </div>
12269
12270           <div class="sect2" lang="en" xml:lang="en">
12271             <div class="titlepage">
12272               <div>
12273                 <div>
12274                   <h3 class="title"><a name="cpp-defines" id=
12275                   "cpp-defines"></a>15.4.1.&nbsp;CPP defines</h3>
12276                 </div>
12277               </div>
12278             </div>
12279
12280             <p>To port an application to NetBSD, it's usually
12281             necessary for the compiler to be able to judge the
12282             system on which it's compiling, and we use definitions
12283             so that the C pre-processor can do this.</p>
12284
12285             <p>To test whether you are working on a 4.4 BSD-derived
12286             system, you should use the BSD definition, which is
12287             defined in <code xmlns=
12288             "http://www.w3.org/TR/xhtml1/transitional" class=
12289             "filename">&lt;sys/param.h&gt;</code> on said
12290             systems.</p>
12291             <pre class="programlisting">
12292     #include &lt;sys/param.h&gt;
12293 </pre>
12294
12295             <p>and then you can surround the BSD-specific parts of
12296             your package's C/C++ code using this conditional:</p>
12297             <pre class="programlisting">
12298     #if (defined(BSD) &amp;&amp; BSD &gt;= 199306)
12299     ...
12300     #endif
12301 </pre>
12302
12303             <p>Please use the &#8220;<span class=
12304             "quote">__NetBSD__</span>&#8221; definition sparingly -
12305             it should only apply to features of NetBSD that are not
12306             present in other 4.4-lite-derived BSDs.</p>
12307           </div>
12308
12309           <div class="sect2" lang="en" xml:lang="en">
12310             <div class="titlepage">
12311               <div>
12312                 <div>
12313                   <h3 class="title"><a name="cpp-list" id=
12314                   "cpp-list"></a>15.4.2.&nbsp;Getting a list of CPP
12315                   defines</h3>
12316                 </div>
12317               </div>
12318             </div>
12319
12320             <p>When your system uses the GNU C Compiler, you can
12321             get a list of symbols that are defined by default, e.g.
12322             to identify the platform, with the following
12323             command:</p>
12324             <pre class="programlisting">
12325     gcc -E -dM - &lt; /dev/null
12326 </pre>
12327           </div>
12328         </div>
12329
12330         <div class="sect1" lang="en" xml:lang="en">
12331           <div class="titlepage">
12332             <div>
12333               <div>
12334                 <h2 class="title" style="clear: both"><a name=
12335                 "package-specific-actions" id=
12336                 "package-specific-actions"></a>15.5.&nbsp;Package
12337                 specific actions</h2>
12338               </div>
12339             </div>
12340           </div>
12341
12342           <div class="sect2" lang="en" xml:lang="en">
12343             <div class="titlepage">
12344               <div>
12345                 <div>
12346                   <h3 class="title"><a name="user-interaction" id=
12347                   "user-interaction"></a>15.5.1.&nbsp;User
12348                   interaction</h3>
12349                 </div>
12350               </div>
12351             </div>
12352
12353             <p>Occasionally, packages require interaction from the
12354             user, and this can be in a number of ways:</p>
12355
12356             <div class="itemizedlist">
12357               <ul type="disc">
12358                 <li>
12359                   <p>help in fetching the distfiles</p>
12360                 </li>
12361
12362                 <li>
12363                   <p>help to configure the package before it is
12364                   built</p>
12365                 </li>
12366
12367                 <li>
12368                   <p>help during the build process</p>
12369                 </li>
12370
12371                 <li>
12372                   <p>help during the installation of a package</p>
12373                 </li>
12374               </ul>
12375             </div>
12376
12377             <p>The <code class="varname">INTERACTIVE_STAGE</code>
12378             definition is provided to notify the pkgsrc mechanism
12379             of an interactive stage which will be needed, and this
12380             should be set in the package's <code xmlns=
12381             "http://www.w3.org/TR/xhtml1/transitional" class=
12382             "filename">Makefile</code>, e.g.:</p>
12383             <pre class="programlisting">
12384     INTERACTIVE_STAGE=      build
12385 </pre>
12386
12387             <p>Multiple interactive stages can be specified:</p>
12388             <pre class="programlisting">
12389     INTERACTIVE_STAGE=      configure install
12390 </pre>
12391           </div>
12392
12393           <div class="sect2" lang="en" xml:lang="en">
12394             <div class="titlepage">
12395               <div>
12396                 <div>
12397                   <h3 class="title"><a name="handling-licenses" id=
12398                   "handling-licenses"></a>15.5.2.&nbsp;Handling
12399                   licenses</h3>
12400                 </div>
12401               </div>
12402             </div>
12403
12404             <p>A package may be covered by a license which the user
12405             has or has not agreed to accept. For these cases,
12406             pkgsrc contains a mechanism to note that a package is
12407             covered by a particular license, and the package cannot
12408             be built unless the user has accepted the license.
12409             (Installation of binary packages are not currently
12410             subject to this mechanism.) Packages with licenses that
12411             are either Open Source according to the Open Source
12412             Initiative or Free according to the Free Software
12413             Foundation will not be marked with a license tag.
12414             Packages with licenses that have not been determined to
12415             meet either definition will be marked with a license
12416             tag referring to the license. This will prevent
12417             building unless pkgsrc is informed that the license is
12418             acceptable, and enables displaying the license.</p>
12419
12420             <p>The license tag mechanism is intended to address
12421             copyright-related issues surrounding building,
12422             installing and using a package, and not to address
12423             redistribution issues (see <code class=
12424             "varname">RESTRICTED</code> and <code class=
12425             "varname">NO_SRC_ON_FTP</code>, etc.). However, the
12426             above definition of licenses for which tags are not
12427             needed implies that packages with redistribution
12428             restrictions should have tags.</p>
12429
12430             <p>Denoting that a package is covered by a particular
12431             license is done by placing the license in <code xmlns=
12432             "http://www.w3.org/TR/xhtml1/transitional" class=
12433             "filename">pkgsrc/licenses</code> and setting the
12434             <code class="varname">LICENSE</code> variable to a
12435             string identifying the license, e.g. in <a xmlns=
12436             "http://www.w3.org/TR/xhtml1/transitional" href=
12437             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/graphics/xv/README.html"
12438             target="_top"><code xmlns="" class=
12439             "filename">graphics/xv</code></a>:</p>
12440             <pre class="programlisting">
12441     LICENSE=        xv-license
12442 </pre>
12443
12444             <p>When trying to build, the user will get a notice
12445             that the package is covered by a license which has not
12446             been accepted:</p>
12447             <pre class="programlisting">
12448     <code class="prompt">%</code> <strong class=
12449 "userinput"><code>make</code></strong>
12450     ===&gt; xv-3.10anb9 has an unacceptable license: xv-license.
12451     ===&gt;     To view the license, enter "/usr/bin/make show-license".
12452     ===&gt;     To indicate acceptance, add this line to your /etc/mk.conf:
12453     ===&gt;     ACCEPTABLE_LICENSES+=xv-license
12454     *** Error code 1
12455 </pre>
12456
12457             <p>The license can be viewed with <span><strong class=
12458             "command">make show-license</strong></span>, and if it
12459             is considered appropriate, the line printed above can
12460             be added to <code xmlns=
12461             "http://www.w3.org/TR/xhtml1/transitional" class=
12462             "filename">/etc/mk.conf</code> to indicate acceptance
12463             of the particular license:</p>
12464             <pre class="programlisting">
12465     ACCEPTABLE_LICENSES+=xv-license
12466 </pre>
12467
12468             <p>When adding a package with a new license, the
12469             license text should be added to <code xmlns=
12470             "http://www.w3.org/TR/xhtml1/transitional" class=
12471             "filename">pkgsrc/licenses</code> for displaying. A
12472             list of known licenses can be seen in this directory as
12473             well as by looking at the list of (commented out)
12474             <code class="varname">ACCEPTABLE_LICENSES</code>
12475             variable settings in <code xmlns=
12476             "http://www.w3.org/TR/xhtml1/transitional" class=
12477             "filename">pkgsrc/mk/defaults/mk.conf</code>.</p>
12478
12479             <p>The use of <code class=
12480             "varname">LICENSE=shareware</code>, <code class=
12481             "varname">LICENSE=no-commercial-use</code>, and similar
12482             language is deprecated because it does not crisply
12483             refer to a particular license text. Another problem
12484             with such usage is that it does not enable a user to
12485             denote acceptance of the license for a single package
12486             without accepting the same license text for another
12487             package. In particular, this can be inappropriate when
12488             e.g. one accepts a particular license to indicate to
12489             pkgsrc that a fee has been paid.</p>
12490           </div>
12491
12492           <div class="sect2" lang="en" xml:lang="en">
12493             <div class="titlepage">
12494               <div>
12495                 <div>
12496                   <h3 class="title"><a name=
12497                   "installing-score-files" id=
12498                   "installing-score-files"></a>15.5.3.&nbsp;Installing
12499                   score files</h3>
12500                 </div>
12501               </div>
12502             </div>
12503
12504             <p>Certain packages, most of them in the games
12505             category, install a score file that allows all users on
12506             the system to record their highscores. In order for
12507             this to work, the binaries need to be installed setgid
12508             and the score files owned by the appropriate group
12509             and/or owner (traditionally the "games" user/group).
12510             The following variables, documented in more detail in
12511             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
12512             class="filename">mk/defaults/mk.conf</code>, control
12513             this behaviour: <code class=
12514             "varname">SETGIDGAME</code>, <code class=
12515             "varname">GAMEDATAMODE</code>, <code class=
12516             "varname">GAMEGRP</code>, <code class=
12517             "varname">GAMEMODE</code>, <code class=
12518             "varname">GAMEOWN</code>.</p>
12519
12520             <p>Note that per default, setgid installation of games
12521             is disabled; setting <code class=
12522             "varname">SETGIDGAME=YES</code> will set all the other
12523             variables accordingly.</p>
12524
12525             <p>A package should therefor never hard code file
12526             ownership or access permissions but rely on
12527             <code class="varname">INSTALL_GAME</code> and
12528             <code class="varname">INSTALL_GAME_DATA</code> to set
12529             these correctly.</p>
12530           </div>
12531
12532           <div class="sect2" lang="en" xml:lang="en">
12533             <div class="titlepage">
12534               <div>
12535                 <div>
12536                   <h3 class="title"><a name="perl-scripts" id=
12537                   "perl-scripts"></a>15.5.4.&nbsp;Packages
12538                   containing perl scripts</h3>
12539                 </div>
12540               </div>
12541             </div>
12542
12543             <p>If your package contains interpreted perl scripts,
12544             set <code class="varname">REPLACE_PERL</code> to ensure
12545             that the proper interpreter path is set. <code class=
12546             "varname">REPLACE_PERL</code> should contain a list of
12547             scripts, relative to <code class=
12548             "varname">WRKSRC</code>, that you want adjusted.</p>
12549           </div>
12550
12551           <div class="sect2" lang="en" xml:lang="en">
12552             <div class="titlepage">
12553               <div>
12554                 <div>
12555                   <h3 class="title"><a name="hardcoded-paths" id=
12556                   "hardcoded-paths"></a>15.5.5.&nbsp;Packages with
12557                   hardcoded paths to other interpreters</h3>
12558                 </div>
12559               </div>
12560             </div>
12561
12562             <p>Your package may also contain scripts with hardcoded
12563             paths to other interpreters besides (or as well as)
12564             perl. To correct the full pathname to the script
12565             interpreter, you need to set the following definitions
12566             in your <code xmlns=
12567             "http://www.w3.org/TR/xhtml1/transitional" class=
12568             "filename">Makefile</code> (we shall use
12569             <span><strong class="command">tclsh</strong></span> in
12570             this example):</p>
12571             <pre class="programlisting">
12572     REPLACE_INTERPRETER+=   tcl
12573     _REPLACE.tcl.old=       .*/bin/tclsh
12574     _REPLACE.tcl.new=       ${PREFIX}/bin/tclsh
12575     _REPLACE_FILES.tcl=     # list of tcl scripts which need to be fixed,
12576                             # relative to ${WRKSRC}, just as in REPLACE_PERL
12577 </pre>
12578           </div>
12579
12580           <div class="sect2" lang="en" xml:lang="en">
12581             <div class="titlepage">
12582               <div>
12583                 <div>
12584                   <h3 class="title"><a name="perl-modules" id=
12585                   "perl-modules"></a>15.5.6.&nbsp;Packages
12586                   installing perl modules</h3>
12587                 </div>
12588               </div>
12589             </div>
12590
12591             <p>Makefiles of packages providing perl5 modules should
12592             include the Makefile fragment <code xmlns=
12593             "http://www.w3.org/TR/xhtml1/transitional" class=
12594             "filename">../../lang/perl5/module.mk</code>. It
12595             provides a <span><strong class=
12596             "command">do-configure</strong></span> target for the
12597             standard perl configuration for such modules as well as
12598             various hooks to tune this configuration. See comments
12599             in this file for details.</p>
12600
12601             <p>Perl5 modules will install into different places
12602             depending on the version of perl used during the build
12603             process. To address this, pkgsrc will append lines to
12604             the <code xmlns=
12605             "http://www.w3.org/TR/xhtml1/transitional" class=
12606             "filename">PLIST</code> corresponding to the files
12607             listed in the installed <code xmlns=
12608             "http://www.w3.org/TR/xhtml1/transitional" class=
12609             "filename">.packlist</code> file generated by most
12610             perl5 modules. This is invoked by defining <code class=
12611             "varname">PERL5_PACKLIST</code> to a space-separated
12612             list of paths to packlist files, e.g.:</p>
12613             <pre class="programlisting">
12614     PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
12615 </pre>
12616
12617             <p>The variables <code class=
12618             "varname">PERL5_SITELIB</code>, <code class=
12619             "varname">PERL5_SITEARCH</code>, and <code class=
12620             "varname">PERL5_ARCHLIB</code> represent the three
12621             locations in which perl5 modules may be installed, and
12622             may be used by perl5 packages that don't have a
12623             packlist. These three variables are also substituted
12624             for in the <code xmlns=
12625             "http://www.w3.org/TR/xhtml1/transitional" class=
12626             "filename">PLIST</code>.</p>
12627           </div>
12628
12629           <div class="sect2" lang="en" xml:lang="en">
12630             <div class="titlepage">
12631               <div>
12632                 <div>
12633                   <h3 class="title"><a name="faq.info-files" id=
12634                   "faq.info-files"></a>15.5.7.&nbsp;Packages
12635                   installing info files</h3>
12636                 </div>
12637               </div>
12638             </div>
12639
12640             <p>Some packages install info files or use the
12641             &#8220;<span class="quote">makeinfo</span>&#8221; or
12642             &#8220;<span class="quote">install-info</span>&#8221;
12643             commands. Each of the info files:</p>
12644
12645             <div class="itemizedlist">
12646               <ul type="disc">
12647                 <li>
12648                   <p>is considered to be installed in the directory
12649                   <code xmlns=
12650                   "http://www.w3.org/TR/xhtml1/transitional" class=
12651                   "filename">${PREFIX}/${INFO_DIR}</code>,</p>
12652                 </li>
12653
12654                 <li>
12655                   <p>is registered in the Info directory file
12656                   <code xmlns=
12657                   "http://www.w3.org/TR/xhtml1/transitional" class=
12658                   "filename">${PREFIX}/${INFO_DIR}/dir</code>,</p>
12659                 </li>
12660
12661                 <li>
12662                   <p>and must be listed as a filename in the
12663                   <code class="varname">INFO_FILES</code> variable
12664                   in the package Makefile.</p>
12665                 </li>
12666               </ul>
12667             </div>
12668
12669             <p><code class="varname">INFO_DIR</code> defaults to
12670             &#8220;<span class="quote">info</span>&#8221; and can
12671             be overridden in the package Makefile. <code xmlns=
12672             "http://www.w3.org/TR/xhtml1/transitional" class=
12673             "filename">INSTALL</code> and <code xmlns=
12674             "http://www.w3.org/TR/xhtml1/transitional" class=
12675             "filename">DEINSTALL</code> scripts will be generated
12676             to handle registration of the info files in the Info
12677             directory file. The &#8220;<span class=
12678             "quote">install-info</span>&#8221; command used for the
12679             info files registration is either provided by the
12680             system, or by a special purpose package automatically
12681             added as dependency if needed.</p>
12682
12683             <p>A package which needs the &#8220;<span class=
12684             "quote">makeinfo</span>&#8221; command at build time
12685             must define the variable <code class=
12686             "varname">USE_MAKEINFO</code> in its Makefile. If a
12687             minimum version of the &#8220;<span class=
12688             "quote">makeinfo</span>&#8221; command is needed it
12689             should be noted with the <code class=
12690             "varname">TEXINFO_REQD</code> variable in the package
12691             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
12692             class="filename">Makefile</code>. By default, a minimum
12693             version of 3.12 is required. If the system does not
12694             provide a <span><strong class=
12695             "command">makeinfo</strong></span> command or if it
12696             does not match the required minimum, a build dependency
12697             on the <a xmlns=
12698             "http://www.w3.org/TR/xhtml1/transitional" href=
12699             "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/gtexinfo/README.html"
12700             target="_top"><code xmlns="" class=
12701             "filename">devel/gtexinfo</code></a> package will be
12702             added automatically.</p>
12703
12704             <p>The build and installation process of the software
12705             provided by the package should not use the
12706             <span><strong class=
12707             "command">install-info</strong></span> command as the
12708             registration of info files is the task of the package
12709             <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
12710             class="filename">INSTALL</code> script, and it must use
12711             the appropriate <span><strong class=
12712             "command">makeinfo</strong></span> command.</p>
12713
12714             <p>To achieve this goal, the pkgsrc infrastructure
12715             creates overriding scripts for the <span><strong class=
12716             "command">install-info</strong></span> and
12717             <span><strong class="command">makeinfo</strong></span>
12718             commands in a directory listed early in <code class=
12719             "varname">PATH</code>.</p>
12720
12721             <p>The script overriding <span><strong class=
12722             "command">install-info</strong></span> has no effect
12723             except the logging of a message. The script overriding
12724             <span><strong class="command">makeinfo</strong></span>
12725             logs a message and according to the value of
12726             <code class="varname">USE_MAKEINFO</code> and
12727             <code class="varname">TEXINFO_REQD</code> either run
12728             the appropriate <span><strong class=
12729             "command">makeinfo</strong></span> command or exit on
12730             error.</p>
12731           </div>
12732
12733           <div class="sect2" lang="en" xml:lang="en">
12734             <div class="titlepage">
12735               <div>
12736                 <div>
12737                   <h3 class="title"><a name="gconf2-data-files" id=
12738                   "gconf2-data-files"></a>15.5.8.&nbsp;Packages
12739                   installing GConf2 data files</h3>
12740                 </div>
12741               </div>
12742             </div>
12743
12744             <p>If a package installs <code xmlns=
12745             "http://www.w3.org/TR/xhtml1/transitional" class=
12746             "filename">.schemas</code> or <code xmlns=
12747             "http://www.w3.org/TR/xhtml1/transitional" class=
12748             "filename">.entries</code> files, used by GConf2, you
12749             need to take some extra steps to make sure they get
12750             registered in the database:</p>
12751
12752             <div class="orderedlist">
12753               <ol type="1">
12754                 <li>
12755                   <p>Include <code xmlns=
12756                   "http://www.w3.org/TR/xhtml1/transitional" class=
12757                   "filename">../../devel/GConf2/schemas.mk</code>
12758                   instead of its <code xmlns=
12759                   "http://www.w3.org/TR/xhtml1/transitional" class=
12760                   "filename">buildlink3.mk</code> file. This takes
12761                   care of rebuilding the GConf2 database at
12762                   installation and deinstallation time, and tells
12763                   the package where to install GConf2 data files
12764                   using some standard configure arguments. It also
12765                   disallows any access to the database directly
12766                   from the package.</p>
12767                 </li>
12768
12769                 <li>
12770                   <p>Ensure that the package installs its
12771                   <code xmlns=
12772                   "http://www.w3.org/TR/xhtml1/transitional" class=
12773                   "filename">.schemas</code> files under
12774                   <code xmlns=
12775                   "http://www.w3.org/TR/xhtml1/transitional" class=
12776                   "filename">${PREFIX}/share/gconf/schemas</code>.
12777                   If they get installed under <code xmlns=
12778                   "http://www.w3.org/TR/xhtml1/transitional" class=
12779                   "filename">${PREFIX}/etc</code>, you will need to
12780                   manually patch the package.</p>
12781                 </li>
12782
12783                 <li>
12784                   <p>Check the PLIST and remove any entries under
12785                   the etc/gconf directory, as they will be handled
12786                   automatically. See <a href="#faq.conf" title=
12787                   "7.14.&nbsp;How do I change the location of configuration files?">
12788                   Section&nbsp;7.14, &#8220;How do I change the
12789                   location of configuration files?&#8221;</a> for
12790                   more information.</p>
12791                 </li>
12792
12793                 <li>
12794                   <p>Define the <code class=
12795                   "varname">GCONF2_SCHEMAS</code> variable in your
12796                   <code xmlns=
12797                   "http://www.w3.org/TR/xhtml1/transitional" class=
12798                   "filename">Makefile</code> with a list of all
12799                   <code xmlns=
12800                   "http://www.w3.org/TR/xhtml1/transitional" class=
12801                   "filename">.schemas</code> files installed by the
12802                   package, if any. Names must not contain any
12803                   directories in them.</p>
12804                 </li>
12805
12806                 <li>
12807                   <p>Define the <code class=
12808                   "varname">GCONF2_ENTRIES</code> variable in your
12809                   <code xmlns=
12810                   "http://www.w3.org/TR/xhtml1/transitional" class=
12811                   "filename">Makefile</code> with a list of all
12812                   <code xmlns=
12813                   "http://www.w3.org/TR/xhtml1/transitional" class=
12814                   "filename">.entries</code> files installed by the
12815                   package, if any. Names must not contain any
12816                   directories in them.</p>
12817                 </li>
12818               </ol>
12819             </div>
12820           </div>
12821
12822           <div class="sect2" lang="en" xml:lang="en">
12823             <div class="titlepage">
12824               <div>
12825                 <div>
12826                   <h3 class="title"><a name=
12827                   "scrollkeeper-data-files" id=
12828                   "scrollkeeper-data-files"></a>15.5.9.&nbsp;Packages
12829                   installing scrollkeeper data files</h3>
12830                 </div>
12831               </div>
12832             </div>
12833
12834             <p>If a package installs <code xmlns=
12835             "http://www.w3.org/TR/xhtml1/transitional" class=
12836             "filename">.omf</code> files, used by scrollkeeper, you
12837             need to take some extra steps to make sure they get
12838             registered in the database:</p>
12839
12840             <div class="orderedlist">
12841               <ol type="1">
12842                 <li>
12843                   <p>Include <code xmlns=
12844                   "http://www.w3.org/TR/xhtml1/transitional" class=
12845                   "filename">../../textproc/scrollkeeper/omf.mk</code>
12846                   instead of its <code xmlns=
12847                   "http://www.w3.org/TR/xhtml1/transitional" class=
12848                   "filename">buildlink3.mk</code> file. This takes
12849                   care of rebuilding the scrollkeeper database at
12850                   installation and deinstallation time, and
12851                   disallows any access to it directly from the
12852                   package.</p>
12853                 </li>
12854
12855                 <li>
12856                   <p>Check the PLIST and remove any entries under
12857                   the <code xmlns=
12858                   "http://www.w3.org/TR/xhtml1/transitional" class=
12859                   "filename">libdata/scrollkeeper</code> directory,
12860                   as they will be handled automatically.</p>
12861                 </li>
12862
12863                 <li>
12864                   <p>Remove the <code xmlns=
12865                   "http://www.w3.org/TR/xhtml1/transitional" class=
12866                   "filename">share/omf</code> directory from the
12867                   PLIST. It will be handled by scrollkeeper.</p>
12868                 </li>
12869               </ol>
12870             </div>
12871           </div>
12872
12873           <div class="sect2" lang="en" xml:lang="en">
12874             <div class="titlepage">
12875               <div>
12876                 <div>
12877                   <h3 class="title"><a name="x11-fonts" id=
12878                   "x11-fonts"></a>15.5.10.&nbsp;Packages installing
12879                   X11 fonts</h3>
12880                 </div>
12881               </div>
12882             </div>
12883
12884             <p>If a package installs font files, you will need to
12885             rebuild the fonts database in the directory where they
12886             get installed at installation and deinstallation time.
12887             This can be automatically done by using <code xmlns=
12888             "http://www.w3.org/TR/xhtml1/transitional" class=
12889             "filename">mk/fonts.mk</code>, which you need to
12890             include in your <code xmlns=
12891             "http://www.w3.org/TR/xhtml1/transitional" class=
12892             "filename">Makefile</code>.</p>
12893
12894             <p>When the file is included, you can list the
12895             directories where fonts are installed in the
12896             <code class="varname">FONTS_<em class=
12897             "replaceable"><code>type</code></em>_DIRS</code>
12898             variables, where <em class=
12899             "replaceable"><code>type</code></em> can be one of
12900             &#8220;<span class="quote">TTF</span>&#8221;,
12901             &#8220;<span class="quote">TYPE1</span>&#8221; or
12902             &#8220;<span class="quote">X11</span>&#8221;. Also make
12903             sure that the database file <code xmlns=
12904             "http://www.w3.org/TR/xhtml1/transitional" class=
12905             "filename">fonts.dir</code> is not listed in the
12906             PLIST.</p>
12907
12908             <p>Note that you should not create new directories for
12909             fonts; instead use the standard ones to avoid that the
12910             user needs to manually configure his X server to find
12911             them.</p>
12912           </div>
12913
12914           <div class="sect2" lang="en" xml:lang="en">
12915             <div class="titlepage">
12916               <div>
12917                 <div>
12918                   <h3 class="title"><a name="gtk2-modules" id=
12919                   "gtk2-modules"></a>15.5.11.&nbsp;Packages
12920                   installing GTK2 modules</h3>
12921                 </div>
12922               </div>
12923             </div>
12924
12925             <p>If a package installs GTK2 immodules or loaders, you
12926             need to take some extra steps to get them registered in
12927             the GTK2 database properly:</p>
12928
12929             <div class="orderedlist">
12930               <ol type="1">
12931                 <li>
12932                   <p>Include <code xmlns=
12933                   "http://www.w3.org/TR/xhtml1/transitional" class=
12934                   "filename">../../x11/gtk2/modules.mk</code>
12935                   instead of its <code xmlns=
12936                   "http://www.w3.org/TR/xhtml1/transitional" class=
12937                   "filename">buildlink3.mk</code> file. This takes
12938                   care of rebuilding the database at installation
12939                   and deinstallation time.</p>
12940                 </li>
12941
12942                 <li>
12943                   <p>Set <code class=
12944                   "varname">GTK2_IMMODULES=YES</code> if your
12945                   package installs GTK2 immodules.</p>
12946                 </li>
12947
12948                 <li>
12949                   <p>Set <code class=
12950                   "varname">GTK2_LOADERS=YES</code> if your package
12951                   installs GTK2 loaders.</p>
12952                 </li>
12953
12954                 <li>
12955                   <p>Patch the package to not touch any of the GTK2
12956                   databases directly. These are:</p>
12957
12958                   <div class="itemizedlist">
12959                     <ul type="disc">
12960                       <li>
12961                         <p><code xmlns=
12962                         "http://www.w3.org/TR/xhtml1/transitional"
12963                         class=
12964                         "filename">libdata/gtk-2.0/gdk-pixbuf.loaders</code></p>
12965                       </li>
12966
12967                       <li>
12968                         <p><code xmlns=
12969                         "http://www.w3.org/TR/xhtml1/transitional"
12970                         class=
12971                         "filename">libdata/gtk-2.0/gtk.immodules</code></p>
12972                       </li>
12973                     </ul>
12974                   </div>
12975                 </li>
12976
12977                 <li>
12978                   <p>Check the PLIST and remove any entries under
12979                   the <code xmlns=
12980                   "http://www.w3.org/TR/xhtml1/transitional" class=
12981                   "filename">libdata/gtk-2.0</code> directory, as
12982                   they will be handled automatically.</p>
12983                 </li>
12984               </ol>
12985             </div>
12986           </div>
12987
12988           <div class="sect2" lang="en" xml:lang="en">
12989             <div class="titlepage">
12990               <div>
12991                 <div>
12992                   <h3 class="title"><a name="sgml-xml-data" id=
12993                   "sgml-xml-data"></a>15.5.12.&nbsp;Packages
12994                   installing SGML or XML data</h3>
12995                 </div>
12996               </div>
12997             </div>
12998
12999             <p>If a package installs SGML or XML data files that
13000             need to be registered in system-wide catalogs (like
13001             DTDs, sub-catalogs, etc.), you need to take some extra
13002             steps:</p>
13003
13004             <div class="orderedlist">
13005               <ol type="1">
13006                 <li>
13007                   <p>Include <code xmlns=
13008                   "http://www.w3.org/TR/xhtml1/transitional" class=
13009                   "filename">../../textproc/xmlcatmgr/catalogs.mk</code>
13010                   in your <code xmlns=
13011                   "http://www.w3.org/TR/xhtml1/transitional" class=
13012                   "filename">Makefile</code>, which takes care of
13013                   registering those files in system-wide catalogs
13014                   at installation and deinstallation time.</p>
13015                 </li>
13016
13017                 <li>
13018                   <p>Set <code class="varname">SGML_CATALOGS</code>
13019                   to the full path of any SGML catalogs installed
13020                   by the package.</p>
13021                 </li>
13022
13023                 <li>
13024                   <p>Set <code class="varname">XML_CATALOGS</code>
13025                   to the full path of any XML catalogs installed by
13026                   the package.</p>
13027                 </li>
13028
13029                 <li>
13030                   <p>Set <code class="varname">SGML_ENTRIES</code>
13031                   to individual entries to be added to the SGML
13032                   catalog. These come in groups of three strings;
13033                   see xmlcatmgr(1) for more information
13034                   (specifically, arguments recognized by the 'add'
13035                   action). Note that you will normally not use this
13036                   variable.</p>
13037                 </li>
13038
13039                 <li>
13040                   <p>Set <code class="varname">XML_ENTRIES</code>
13041                   to individual entries to be added to the XML
13042                   catalog. These come in groups of three strings;
13043                   see xmlcatmgr(1) for more information
13044                   (specifically, arguments recognized by the 'add'
13045                   action). Note that you will normally not use this
13046                   variable.</p>
13047                 </li>
13048               </ol>
13049             </div>
13050           </div>
13051
13052           <div class="sect2" lang="en" xml:lang="en">
13053             <div class="titlepage">
13054               <div>
13055                 <div>
13056                   <h3 class="title"><a name="mime-database" id=
13057                   "mime-database"></a>15.5.13.&nbsp;Packages
13058                   installing extensions to the MIME database</h3>
13059                 </div>
13060               </div>
13061             </div>
13062
13063             <p>If a package provides extensions to the MIME
13064             database by installing <code xmlns=
13065             "http://www.w3.org/TR/xhtml1/transitional" class=
13066             "filename">.xml</code> files inside <code xmlns=
13067             "http://www.w3.org/TR/xhtml1/transitional" class=
13068             "filename">${PREFIX}/share/mime/packages</code>, you
13069             need to take some extra steps to ensure that the
13070             database is kept consistent with respect to these new
13071             files:</p>
13072
13073             <div class="orderedlist">
13074               <ol type="1">
13075                 <li>
13076                   <p>Include <code xmlns=
13077                   "http://www.w3.org/TR/xhtml1/transitional" class=
13078                   "filename">../../databases/shared-mime-info/mimedb.mk</code>
13079                   (avoid using the <code xmlns=
13080                   "http://www.w3.org/TR/xhtml1/transitional" class=
13081                   "filename">buildlink3.mk</code> file from this
13082                   same directory, which is reserved for inclusion
13083                   from other <code xmlns=
13084                   "http://www.w3.org/TR/xhtml1/transitional" class=
13085                   "filename">buildlink3.mk</code> files). It takes
13086                   care of rebuilding the MIME database at
13087                   installation and deinstallation time, and
13088                   disallows any access to it directly from the
13089                   package.</p>
13090                 </li>
13091
13092                 <li>
13093                   <p>Check the PLIST and remove any entries under
13094                   the <code xmlns=
13095                   "http://www.w3.org/TR/xhtml1/transitional" class=
13096                   "filename">share/mime</code> directory,
13097                   <span class="emphasis"><em>except</em></span> for
13098                   files saved under <code xmlns=
13099                   "http://www.w3.org/TR/xhtml1/transitional" class=
13100                   "filename">share/mime/packages</code>. The former
13101                   are handled automatically by the
13102                   update-mime-database program, but the latter are
13103                   package-dependent and must be removed by the
13104                   package that installed them in the first
13105                   place.</p>
13106                 </li>
13107
13108                 <li>
13109                   <p>Remove any <code xmlns=
13110                   "http://www.w3.org/TR/xhtml1/transitional" class=
13111                   "filename">share/mime/*</code> directories from
13112                   the PLIST. They will be handled by the
13113                   shared-mime-info package.</p>
13114                 </li>
13115               </ol>
13116             </div>
13117           </div>
13118
13119           <div class="sect2" lang="en" xml:lang="en">
13120             <div class="titlepage">
13121               <div>
13122                 <div>
13123                   <h3 class="title"><a name="intltool" id=
13124                   "intltool"></a>15.5.14.&nbsp;Packages using
13125                   intltool</h3>
13126                 </div>
13127               </div>
13128             </div>
13129
13130             <p>If a package uses intltool during its build, include
13131             the <code xmlns=
13132             "http://www.w3.org/TR/xhtml1/transitional" class=
13133             "filename">../../textproc/intltool/buildlink3.mk</code>
13134             file, which forces it to use the intltool package
13135             provided by pkgsrc, instead of the one bundled with the
13136             distribution file.</p>
13137
13138             <p>This tracks intltool's build-time dependencies and
13139             uses the latest available version; this way, the
13140             package benefits of any bug fixes that may have
13141             appeared since it was released.</p>
13142           </div>
13143
13144           <div class="sect2" lang="en" xml:lang="en">
13145             <div class="titlepage">
13146               <div>
13147                 <div>
13148                   <h3 class="title"><a name="startup-scripts" id=
13149                   "startup-scripts"></a>15.5.15.&nbsp;Packages
13150                   installing startup scripts</h3>
13151                 </div>
13152               </div>
13153             </div>
13154
13155             <p>If a package contains a rc.d script, it won't be
13156             copied into the startup directory by default, but you
13157             can enable it, by adding the option <code class=
13158             "varname">PKG_RCD_SCRIPTS=YES</code> in <code xmlns=
13159             "http://www.w3.org/TR/xhtml1/transitional" class=
13160             "filename">/etc/mk.conf</code>. This option will copy
13161             the scripts into <code xmlns=
13162             "http://www.w3.org/TR/xhtml1/transitional" class=
13163             "filename">/etc/rc.d</code> when a package is
13164             installed, and it will automatically remove the scripts
13165             when the package is deinstalled.</p>
13166           </div>
13167         </div>
13168
13169         <div class="sect1" lang="en" xml:lang="en">
13170           <div class="titlepage">
13171             <div>
13172               <div>
13173                 <h2 class="title" style="clear: both"><a name=
13174                 "feedback-to-author" id=
13175                 "feedback-to-author"></a>15.6.&nbsp;Feedback to the
13176                 author</h2>
13177               </div>
13178             </div>
13179           </div>
13180
13181           <p>If you have found any bugs in the package you make
13182           available, if you had to do special steps to make it run
13183           under NetBSD or if you enhanced the software in various
13184           other ways, be sure to report these changes back to the
13185           original author of the program! With that kind of
13186           support, the next release of the program can incorporate
13187           these fixes, and people not using the NetBSD packages
13188           system can win from your efforts.</p>
13189
13190           <p>Support the idea of free software!</p>
13191         </div>
13192       </div>
13193
13194       <div class="chapter" lang="en" xml:lang="en">
13195         <div class="titlepage">
13196           <div>
13197             <div>
13198               <h2 class="title"><a name="debug" id=
13199               "debug"></a>Chapter&nbsp;16.&nbsp;Debugging</h2>
13200             </div>
13201           </div>
13202         </div>
13203
13204         <p>To check out all the gotchas when building a package,
13205         here are the steps that I do in order to get a package
13206         working. Please note this is basically the same as what was
13207         explained in the previous sections, only with some
13208         debugging aids.</p>
13209
13210         <div class="itemizedlist">
13211           <ul type="disc">
13212             <li>
13213               <p>Be sure to set <code class=
13214               "varname">PKG_DEVELOPER=1</code> in <code xmlns=
13215               "http://www.w3.org/TR/xhtml1/transitional" class=
13216               "filename">/etc/mk.conf</code></p>
13217             </li>
13218
13219             <li>
13220               <p>Install <a xmlns=
13221               "http://www.w3.org/TR/xhtml1/transitional" href=
13222               "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/url2pkg/README.html"
13223               target="_top"><code xmlns="" class=
13224               "filename">pkgtools/url2pkg</code></a>, create a
13225               directory for a new package, change into it, then run
13226               <span><strong class=
13227               "command">url2pkg</strong></span>:</p>
13228               <pre class="screen">
13229 <code class="prompt">%</code> <strong class=
13230 "userinput"><code>mkdir /usr/pkgsrc/<em class=
13231 "replaceable"><code>category</code></em>/<em class=
13232 "replaceable"><code>examplepkg</code></em></code></strong>
13233 <code class="prompt">%</code> <strong class=
13234 "userinput"><code>cd /usr/pkgsrc/<em class=
13235 "replaceable"><code>category</code></em>/<em class=
13236 "replaceable"><code>examplepkg</code></em></code></strong>
13237 <code class="prompt">%</code> <strong class=
13238 "userinput"><code>url2pkg http://www.example.com/path/to/distfile.tar.gz</code></strong>
13239 </pre>
13240             </li>
13241
13242             <li>
13243               <p>Edit the <code xmlns=
13244               "http://www.w3.org/TR/xhtml1/transitional" class=
13245               "filename">Makefile</code> as requested.</p>
13246             </li>
13247
13248             <li>
13249               <p>Fill in the <code xmlns=
13250               "http://www.w3.org/TR/xhtml1/transitional" class=
13251               "filename">DESCR</code> file</p>
13252             </li>
13253
13254             <li>
13255               <p>Run <span><strong class="command">make
13256               configure</strong></span></p>
13257             </li>
13258
13259             <li>
13260               <p>Add any dependencies glimpsed from documentation
13261               and the configure step to the package's <code xmlns=
13262               "http://www.w3.org/TR/xhtml1/transitional" class=
13263               "filename">Makefile</code>.</p>
13264             </li>
13265
13266             <li>
13267               <p>Make the package compile, doing multiple rounds
13268               of</p>
13269               <pre class="screen">
13270 <code class="prompt">%</code> <strong class=
13271 "userinput"><code>make</code></strong>
13272 <code class="prompt">%</code> <strong class=
13273 "userinput"><code>pkgvi ${WRKSRC}/some/file/that/does/not/compile</code></strong>
13274 <code class="prompt">%</code> <strong class=
13275 "userinput"><code>mkpatches</code></strong>
13276 <code class="prompt">%</code> <strong class=
13277 "userinput"><code>patchdiff</code></strong>
13278 <code class="prompt">%</code> <strong class=
13279 "userinput"><code>mv ${WRKDIR}/.newpatches/* patches</code></strong>
13280 <code class="prompt">%</code> <strong class=
13281 "userinput"><code>make mps</code></strong>
13282 <code class="prompt">%</code> <strong class=
13283 "userinput"><code>make clean</code></strong>
13284 </pre>
13285
13286               <p>Doing as non-root user will ensure that no files
13287               are modified that shouldn't be, especially during the
13288               build phase. <span><strong class=
13289               "command">mkpatches</strong></span>,
13290               <span><strong class=
13291               "command">patchdiff</strong></span> and
13292               <span><strong class="command">pkgvi</strong></span>
13293               are from the <a xmlns=
13294               "http://www.w3.org/TR/xhtml1/transitional" href=
13295               "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdiff/README.html"
13296               target="_top"><code xmlns="" class=
13297               "filename">pkgtools/pkgdiff</code></a> package.</p>
13298             </li>
13299
13300             <li>
13301               <p>Look at the <code xmlns=
13302               "http://www.w3.org/TR/xhtml1/transitional" class=
13303               "filename">Makefile</code>, fix if necessary; see
13304               <a href="#components.Makefile" title=
13305               "8.1.&nbsp;Makefile">Section&nbsp;8.1,
13306               &#8220;<code xmlns=
13307               "http://www.w3.org/TR/xhtml1/transitional" class=
13308               "filename">Makefile</code>&#8221;</a>.</p>
13309             </li>
13310
13311             <li>
13312               <p>Generate a <code xmlns=
13313               "http://www.w3.org/TR/xhtml1/transitional" class=
13314               "filename">PLIST</code>:</p>
13315               <pre class="screen">
13316 <code class="prompt">#</code> <strong class=
13317 "userinput"><code>make install</code></strong>
13318 <code class="prompt">#</code> <strong class=
13319 "userinput"><code>make print-PLIST &gt;PLIST</code></strong>
13320 <code class="prompt">#</code> <strong class=
13321 "userinput"><code>make deinstall</code></strong>
13322 <code class="prompt">#</code> <strong class=
13323 "userinput"><code>make install</code></strong>
13324 <code class="prompt">#</code> <strong class=
13325 "userinput"><code>make deinstall</code></strong>
13326 </pre>
13327
13328               <p>You usually need to be <code xmlns=
13329               "http://www.w3.org/TR/xhtml1/transitional" class=
13330               "username">root</code> to do this. Look if there are
13331               any files left:</p>
13332               <pre class="screen">
13333 <code class="prompt">#</code> <strong class=
13334 "userinput"><code>make print-PLIST</code></strong>
13335 </pre>
13336
13337               <p>If this reveals any files that are missing in
13338               <code xmlns=
13339               "http://www.w3.org/TR/xhtml1/transitional" class=
13340               "filename">PLIST</code>, add them.</p>
13341             </li>
13342
13343             <li>
13344               <p>Now that the <code xmlns=
13345               "http://www.w3.org/TR/xhtml1/transitional" class=
13346               "filename">PLIST</code> is OK, install the package
13347               again and make a binary package:</p>
13348               <pre class="screen">
13349 <code class="prompt">#</code> <strong class=
13350 "userinput"><code>make reinstall</code></strong>
13351 <code class="prompt">#</code> <strong class=
13352 "userinput"><code>make package</code></strong>
13353 </pre>
13354             </li>
13355
13356             <li>
13357               <p>Delete the installed package:</p>
13358               <pre class="screen">
13359 <code class="prompt">#</code> <strong class=
13360 "userinput"><code>pkg_delete blub</code></strong>
13361 </pre>
13362             </li>
13363
13364             <li>
13365               <p>Repeat the above <span><strong class=
13366               "command">make print-PLIST</strong></span> command,
13367               which shouldn't find anything now:</p>
13368               <pre class="screen">
13369 <code class="prompt">#</code> <strong class=
13370 "userinput"><code>make print-PLIST</code></strong>
13371 </pre>
13372             </li>
13373
13374             <li>
13375               <p>Reinstall the binary package:</p>
13376               <pre class="screen">
13377 <code class="prompt">#</code> <strong class=
13378 "userinput"><code>pkgadd .../blub.tgz</code></strong>
13379 </pre>
13380             </li>
13381
13382             <li>
13383               <p>Play with it. Make sure everything works.</p>
13384             </li>
13385
13386             <li>
13387               <p>Run <span><strong class=
13388               "command">pkglint</strong></span> from <a xmlns=
13389               "http://www.w3.org/TR/xhtml1/transitional" href=
13390               "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html"
13391               target="_top"><code xmlns="" class=
13392               "filename">pkgtools/pkglint</code></a>, and fix the
13393               problems it reports:</p>
13394               <pre class="screen">
13395 <code class="prompt">#</code> <strong class=
13396 "userinput"><code>pkglint</code></strong>
13397 </pre>
13398             </li>
13399
13400             <li>
13401               <p>Submit (or commit, if you have cvs access); see
13402               <a href="#submit" title=
13403               "Chapter&nbsp;17.&nbsp;Submitting and Committing">Chapter&nbsp;17,
13404               <i>Submitting and Committing</i></a>.</p>
13405             </li>
13406           </ul>
13407         </div>
13408       </div>
13409
13410       <div class="chapter" lang="en" xml:lang="en">
13411         <div class="titlepage">
13412           <div>
13413             <div>
13414               <h2 class="title"><a name="submit" id=
13415               "submit"></a>Chapter&nbsp;17.&nbsp;Submitting and
13416               Committing</h2>
13417             </div>
13418           </div>
13419         </div>
13420
13421         <div class="toc">
13422           <p><b>Table of Contents</b></p>
13423
13424           <dl>
13425             <dt><span class="sect1"><a href=
13426             "#submitting-your-package">17.1. Submitting your
13427             packages</a></span></dt>
13428
13429             <dt><span class="sect1"><a href=
13430             "#general-notes-for-changes">17.2. General notes when
13431             adding, updating, or removing packages</a></span></dt>
13432
13433             <dt><span class="sect1"><a href=
13434             "#committing-importing">17.3. Committing: Importing a
13435             package into CVS</a></span></dt>
13436
13437             <dt><span class="sect1"><a href=
13438             "#updating-package">17.4. Updating a package to a newer
13439             version</a></span></dt>
13440
13441             <dt><span class="sect1"><a href="#moving-package">17.5.
13442             Moving a package in pkgsrc</a></span></dt>
13443           </dl>
13444         </div>
13445
13446         <div class="sect1" lang="en" xml:lang="en">
13447           <div class="titlepage">
13448             <div>
13449               <div>
13450                 <h2 class="title" style="clear: both"><a name=
13451                 "submitting-your-package" id=
13452                 "submitting-your-package"></a>17.1.&nbsp;Submitting
13453                 your packages</h2>
13454               </div>
13455             </div>
13456           </div>
13457
13458           <p>You have to separate between binary and
13459           &#8220;<span class="quote">normal</span>&#8221; (source)
13460           packages here:</p>
13461
13462           <div class="itemizedlist">
13463             <ul type="disc">
13464               <li>
13465                 <p>precompiled binary packages</p>
13466
13467                 <p>Our policy is that we accept binaries only from
13468                 pkgsrc developers to guarantee that the packages
13469                 don't contain any trojan horses etc. This is not to
13470                 annoy anyone but rather to protect our users!
13471                 You're still free to put up your home-made binary
13472                 packages and tell the world where to get them.
13473                 NetBSD developers doing bulk builds and wanting to
13474                 upload them please see <a href="#bulk-upload"
13475                 title="6.3.8.&nbsp;Uploading results of a bulk build">
13476                 Section&nbsp;6.3.8, &#8220;Uploading results of a
13477                 bulk build&#8221;</a>.</p>
13478               </li>
13479
13480               <li>
13481                 <p>packages</p>
13482
13483                 <p>First, check that your package is complete,
13484                 compiles and runs well; see <a href="#debug" title=
13485                 "Chapter&nbsp;16.&nbsp;Debugging">Chapter&nbsp;16,
13486                 <i>Debugging</i></a> and the rest of this document.
13487                 Next, generate an uuencoded gzipped <a href=
13488                 "http://netbsd.gw.com/cgi-bin/man-cgi?tar+1+NetBSD-current">
13489                 <span class="citerefentry"><span class=
13490                 "refentrytitle">tar</span>(1)</span></a> archive,
13491                 preferably with all files in a single directory.
13492                 Finally, <span><strong class=
13493                 "command">send-pr</strong></span> with category
13494                 &#8220;<span class="quote">pkg</span>&#8221;, a
13495                 synopsis which includes the package name and
13496                 version number, a short description of your package
13497                 (contents of the COMMENT variable or DESCR file are
13498                 OK) and attach the archive to your PR.</p>
13499
13500                 <p>If you want to submit several packages, please
13501                 send a separate PR for each one, it's easier for us
13502                 to track things that way.</p>
13503
13504                 <p>Alternatively, you can also import new packages
13505                 into pkgsrc-wip (&#8220;<span class="quote">pkgsrc
13506                 work-in-progress</span>&#8221;); see the homepage
13507                 at <a href="http://pkgsrc-wip.sourceforge.net/"
13508                 target=
13509                 "_top">http://pkgsrc-wip.sourceforge.net/</a> for
13510                 details.</p>
13511               </li>
13512             </ul>
13513           </div>
13514         </div>
13515
13516         <div class="sect1" lang="en" xml:lang="en">
13517           <div class="titlepage">
13518             <div>
13519               <div>
13520                 <h2 class="title" style="clear: both"><a name=
13521                 "general-notes-for-changes" id=
13522                 "general-notes-for-changes"></a>17.2.&nbsp;General
13523                 notes when adding, updating, or removing
13524                 packages</h2>
13525               </div>
13526             </div>
13527           </div>
13528
13529           <p>Please note all package additions, updates, moves, and
13530           removals in <code xmlns=
13531           "http://www.w3.org/TR/xhtml1/transitional" class=
13532           "filename">pkgsrc/doc/CHANGES</code>. It's very important
13533           to keep this file up to date and conforming to the
13534           existing format, because it will be used by scripts to
13535           automatically update pages on <a href=
13536           "http://www.NetBSD.org/" target="_top">www.NetBSD.org</a>
13537           and other sites. Additionally, check the <code xmlns=
13538           "http://www.w3.org/TR/xhtml1/transitional" class=
13539           "filename">pkgsrc/doc/TODO</code> file and remove the
13540           entry for the package you updated or removed, in case it
13541           was mentioned there.</p>
13542
13543           <p>There is a make target that helps in creating proper
13544           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
13545           class="filename">CHANGES</code> entries:
13546           <span><strong class="command">make
13547           changes-entry</strong></span>. It uses the optional
13548           <code class="varname">CTYPE</code> and <code class=
13549           "varname">NETBSD_LOGIN_NAME</code> variables. The general
13550           usage is to first make sure that your <code xmlns=
13551           "http://www.w3.org/TR/xhtml1/transitional" class=
13552           "filename">CHANGES</code> file is up-to-date (to avoid
13553           having to resolve conflicts later-on) and then to
13554           <span><strong class="command">cd</strong></span> to the
13555           package directory. For package updates,
13556           <span><strong class="command">make
13557           changes-entry</strong></span> is enough. For new
13558           packages, or package moves or removals, set the
13559           <code class="varname">CTYPE</code> variable on the
13560           command line to "Added", "Moved", or "Removed". You can
13561           set <code class="varname">NETBSD_LOGIN_NAME</code> in
13562           <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
13563           class="filename">/etc/mk.conf</code> if your local login
13564           name is not the same as your NetBSD login name. Don't
13565           forget to commit the changes to <code xmlns=
13566           "http://www.w3.org/TR/xhtml1/transitional" class=
13567           "filename">pkgsrc/doc/CHANGES</code>!</p>
13568         </div>
13569
13570         <div class="sect1" lang="en" xml:lang="en">
13571           <div class="titlepage">
13572             <div>
13573               <div>
13574                 <h2 class="title" style="clear: both"><a name=
13575                 "committing-importing" id=
13576                 "committing-importing"></a>17.3.&nbsp;Committing:
13577                 Importing a package into CVS</h2>
13578               </div>
13579             </div>
13580           </div>
13581
13582           <p>This section is only of interest for pkgsrc developers
13583           with write access to the pkgsrc repository. Please
13584           remember that cvs imports files relative to the current
13585           working directory, and that the pathname that you give
13586           the <span><strong class="command">cvs
13587           import</strong></span> command is so that it knows where
13588           to place the files in the repository. Newly created
13589           packages should be imported with a vendor tag of
13590           &#8220;<span class="quote">TNF</span>&#8221; and a
13591           release tag of &#8220;<span class=
13592           "quote">pkgsrc-base</span>&#8221;, e.g:</p>
13593           <pre class="programlisting">
13594     <code class="prompt">$</code> cd .../pkgsrc/category/pkgname
13595     <code class=
13596 "prompt">$</code> cvs import pkgsrc/category/pkgname TNF pkgsrc-base
13597 </pre>
13598
13599           <p>Remember to move the directory from which you imported
13600           out of the way, or cvs will complain the next time you
13601           &#8220;<span class="quote">cvs update</span>&#8221; your
13602           source tree. Also don't forget to add the new package to
13603           the category's <code xmlns=
13604           "http://www.w3.org/TR/xhtml1/transitional" class=
13605           "filename">Makefile</code>.</p>
13606
13607           <p>The commit message of the initial import should
13608           include part of the <code xmlns=
13609           "http://www.w3.org/TR/xhtml1/transitional" class=
13610           "filename">DESCR</code> file, so people reading the
13611           mailing lists know what the package is/does.</p>
13612
13613           <p>For new packages, &#8220;<span class="quote">cvs
13614           import</span>&#8221; is preferred to &#8220;<span class=
13615           "quote">cvs add</span>&#8221; because the former gets
13616           everything with a single command, and provides a
13617           consistent tag.</p>
13618         </div>
13619
13620         <div class="sect1" lang="en" xml:lang="en">
13621           <div class="titlepage">
13622             <div>
13623               <div>
13624                 <h2 class="title" style="clear: both"><a name=
13625                 "updating-package" id=
13626                 "updating-package"></a>17.4.&nbsp;Updating a
13627                 package to a newer version</h2>
13628               </div>
13629             </div>
13630           </div>
13631
13632           <p>Please always put a concise, appropriate and relevant
13633           summary of the changes between old and new versions into
13634           the commit log when updating a package. There are various
13635           reasons for this:</p>
13636
13637           <div class="itemizedlist">
13638             <ul type="disc">
13639               <li>
13640                 <p>A URL is volatile, and can change over time. It
13641                 may go away completely or its information may be
13642                 overwritten by newer information.</p>
13643               </li>
13644
13645               <li>
13646                 <p>Having the change information between old and
13647                 new versions in our CVS repository is very useful
13648                 for people who use either cvs or anoncvs.</p>
13649               </li>
13650
13651               <li>
13652                 <p>Having the change information between old and
13653                 new versions in our CVS repository is very useful
13654                 for people who read the pkgsrc-changes mailing
13655                 list, so that they can make tactical decisions
13656                 about when to upgrade the package.</p>
13657               </li>
13658             </ul>
13659           </div>
13660
13661           <p>Please also recognize that, just because a new version
13662           of a package has been released, it should not
13663           automatically be upgraded in the CVS repository. We
13664           prefer to be conservative in the packages that are
13665           included in pkgsrc - development or beta packages are not
13666           really the best thing for most places in which pkgsrc is
13667           used. Please use your judgement about what should go into
13668           pkgsrc, and bear in mind that stability is to be
13669           preferred above new and possibly untested features.</p>
13670         </div>
13671
13672         <div class="sect1" lang="en" xml:lang="en">
13673           <div class="titlepage">
13674             <div>
13675               <div>
13676                 <h2 class="title" style="clear: both"><a name=
13677                 "moving-package" id=
13678                 "moving-package"></a>17.5.&nbsp;Moving a package in
13679                 pkgsrc</h2>
13680               </div>
13681             </div>
13682           </div>
13683
13684           <div class="orderedlist">
13685             <ol type="1">
13686               <li>
13687                 <p>Make a copy of the directory somewhere else.</p>
13688               </li>
13689
13690               <li>
13691                 <p>Remove all CVS dirs.</p>
13692
13693                 <p>Alternatively to the first two steps you can
13694                 also do:</p>
13695                 <pre class="screen">
13696 <code class="prompt">%</code> <strong class=
13697 "userinput"><code>cvs -d user@cvs.NetBSD.org:/cvsroot export -D today pkgsrc/category/package</code></strong>
13698 </pre>
13699
13700                 <p>and use that for further work.</p>
13701               </li>
13702
13703               <li>
13704                 <p>Fix <code class="varname">CATEGORIES</code> and
13705                 any <code class="varname">DEPENDS</code> paths that
13706                 just did &#8220;<span class=
13707                 "quote">../package</span>&#8221; instead of
13708                 &#8220;<span class=
13709                 "quote">../../category/package</span>&#8221;.</p>
13710               </li>
13711
13712               <li>
13713                 <p><span><strong class="command">cvs
13714                 import</strong></span> the modified package in the
13715                 new place.</p>
13716               </li>
13717
13718               <li>
13719                 <p>Check if any package depends on it:</p>
13720                 <pre class="screen">
13721 <code class="prompt">%</code> <strong class=
13722 "userinput"><code>cd /usr/pkgsrc</code></strong>
13723 <code class="prompt">%</code> <strong class=
13724 "userinput"><code>grep /package */*/Makefile* */*/buildlink*</code></strong>
13725 </pre>
13726               </li>
13727
13728               <li>
13729                 <p>Fix paths in packages from step 5 to point to
13730                 new location.</p>
13731               </li>
13732
13733               <li>
13734                 <p><span><strong class="command">cvs rm
13735                 (-f)</strong></span> the package at the old
13736                 location.</p>
13737               </li>
13738
13739               <li>
13740                 <p>Remove from <code xmlns=
13741                 "http://www.w3.org/TR/xhtml1/transitional" class=
13742                 "filename">oldcategory/Makefile</code>.</p>
13743               </li>
13744
13745               <li>
13746                 <p>Add to <code xmlns=
13747                 "http://www.w3.org/TR/xhtml1/transitional" class=
13748                 "filename">newcategory/Makefile</code>.</p>
13749               </li>
13750
13751               <li>
13752                 <p>Commit the changed and removed files:</p>
13753                 <pre class="screen">
13754 <code class="prompt">%</code> <strong class=
13755 "userinput"><code>cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile</code></strong>
13756 </pre>
13757
13758                 <p>(and any packages from step 5, of course).</p>
13759               </li>
13760             </ol>
13761           </div>
13762         </div>
13763       </div>
13764     </div>
13765
13766     <div class="appendix" lang="en" xml:lang="en">
13767       <div class="titlepage">
13768         <div>
13769           <div>
13770             <h2 class="title"><a name="examples" id=
13771             "examples"></a>Appendix&nbsp;A.&nbsp;A simple example
13772             package: bison</h2>
13773           </div>
13774         </div>
13775       </div>
13776
13777       <div class="toc">
13778         <p><b>Table of Contents</b></p>
13779
13780         <dl>
13781           <dt><span class="sect1"><a href="#example-files">A.1.
13782           files</a></span></dt>
13783
13784           <dd>
13785             <dl>
13786               <dt><span class="sect2"><a href=
13787               "#example-Makefile">A.1.1. Makefile</a></span></dt>
13788
13789               <dt><span class="sect2"><a href=
13790               "#example-descr">A.1.2. DESCR</a></span></dt>
13791
13792               <dt><span class="sect2"><a href=
13793               "#example-plist">A.1.3. PLIST</a></span></dt>
13794
13795               <dt><span class="sect2"><a href=
13796               "#checking-package-with-pkglint">A.1.4. Checking a
13797               package with <span><strong class=
13798               "command">pkglint</strong></span></a></span></dt>
13799             </dl>
13800           </dd>
13801
13802           <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2.
13803           Steps for building, installing, packaging</a></span></dt>
13804         </dl>
13805       </div>
13806
13807       <p>We checked to find a piece of software that wasn't in the
13808       packages collection, and picked GNU bison. Quite why someone
13809       would want to have <span><strong class=
13810       "command">bison</strong></span> when Berkeley
13811       <span><strong class="command">yacc</strong></span> is already
13812       present in the tree is beyond us, but it's useful for the
13813       purposes of this exercise.</p>
13814
13815       <div class="sect1" lang="en" xml:lang="en">
13816         <div class="titlepage">
13817           <div>
13818             <div>
13819               <h2 class="title" style="clear: both"><a name=
13820               "example-files" id=
13821               "example-files"></a>A.1.&nbsp;files</h2>
13822             </div>
13823           </div>
13824         </div>
13825
13826         <div class="sect2" lang="en" xml:lang="en">
13827           <div class="titlepage">
13828             <div>
13829               <div>
13830                 <h3 class="title"><a name="example-Makefile" id=
13831                 "example-Makefile"></a>A.1.1.&nbsp;Makefile</h3>
13832               </div>
13833             </div>
13834           </div>
13835           <pre class="programlisting">
13836     # $NetBSD$
13837     #
13838
13839     DISTNAME=       bison-1.25
13840     CATEGORIES=     devel
13841     MASTER_SITES=   ${MASTER_SITE_GNU}
13842
13843     MAINTAINER=     thorpej@NetBSD.org
13844     HOMEPAGE=       http://www.gnu.org/software/bison/bison.html
13845     COMMENT=        GNU yacc clone
13846
13847     GNU_CONFIGURE=  yes
13848     INFO_FILES=     bison.info
13849
13850     .include "../../mk/bsd.pkg.mk"
13851 </pre>
13852         </div>
13853
13854         <div class="sect2" lang="en" xml:lang="en">
13855           <div class="titlepage">
13856             <div>
13857               <div>
13858                 <h3 class="title"><a name="example-descr" id=
13859                 "example-descr"></a>A.1.2.&nbsp;DESCR</h3>
13860               </div>
13861             </div>
13862           </div>
13863           <pre class="programlisting">
13864     GNU version of yacc.  Can make re-entrant parsers, and numerous other
13865     improvements.  Why you would want this when Berkeley <a href=
13866 "http://netbsd.gw.com/cgi-bin/man-cgi?yacc+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">yacc</span>(1)</span></a> is part
13867     of the NetBSD source tree is beyond me.
13868 </pre>
13869         </div>
13870
13871         <div class="sect2" lang="en" xml:lang="en">
13872           <div class="titlepage">
13873             <div>
13874               <div>
13875                 <h3 class="title"><a name="example-plist" id=
13876                 "example-plist"></a>A.1.3.&nbsp;PLIST</h3>
13877               </div>
13878             </div>
13879           </div>
13880           <pre class="programlisting">
13881     @comment $NetBSD$
13882     bin/bison
13883     man/man1/bison.1.gz
13884     share/bison.simple
13885     share/bison.hairy
13886 </pre>
13887         </div>
13888
13889         <div class="sect2" lang="en" xml:lang="en">
13890           <div class="titlepage">
13891             <div>
13892               <div>
13893                 <h3 class="title"><a name=
13894                 "checking-package-with-pkglint" id=
13895                 "checking-package-with-pkglint"></a>A.1.4.&nbsp;Checking
13896                 a package with <span><strong class=
13897                 "command">pkglint</strong></span></h3>
13898               </div>
13899             </div>
13900           </div>
13901
13902           <p>The NetBSD package system comes with <a xmlns=
13903           "http://www.w3.org/TR/xhtml1/transitional" href=
13904           "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html"
13905           target="_top"><code xmlns="" class=
13906           "filename">pkgtools/pkglint</code></a> which helps to
13907           check the contents of these files. After installation it
13908           is quite easy to use, just change to the directory of the
13909           package you wish to examine and execute
13910           <span><strong class=
13911           "command">pkglint</strong></span>:</p>
13912           <pre class="screen">
13913 <code class="prompt">$</code> <strong class=
13914 "userinput"><code>pkglint</code></strong>
13915 looks fine.
13916 </pre>
13917
13918           <p>Depending on the supplied command line arguments (see
13919           pkglint(1)), more verbose checks will be performed. Use
13920           e.g. <span><strong class="command">pkglint
13921           -v</strong></span> for a very verbose check.</p>
13922         </div>
13923       </div>
13924
13925       <div class="sect1" lang="en" xml:lang="en">
13926         <div class="titlepage">
13927           <div>
13928             <div>
13929               <h2 class="title" style="clear: both"><a name=
13930               "steps-for-b-i-p" id=
13931               "steps-for-b-i-p"></a>A.2.&nbsp;Steps for building,
13932               installing, packaging</h2>
13933             </div>
13934           </div>
13935         </div>
13936
13937         <p>Create the directory where the package lives, plus any
13938         auxiliary directories:</p>
13939         <pre class="screen">
13940 <code class="prompt">#</code> <strong class=
13941 "userinput"><code>cd /usr/pkgsrc/lang</code></strong>
13942 <code class="prompt">#</code> <strong class=
13943 "userinput"><code>mkdir bison</code></strong>
13944 <code class="prompt">#</code> <strong class=
13945 "userinput"><code>cd bison</code></strong>
13946 <code class="prompt">#</code> <strong class=
13947 "userinput"><code>mkdir patches</code></strong>
13948 </pre>
13949
13950         <p>Create <code xmlns=
13951         "http://www.w3.org/TR/xhtml1/transitional" class=
13952         "filename">Makefile</code>, <code xmlns=
13953         "http://www.w3.org/TR/xhtml1/transitional" class=
13954         "filename">DESCR</code> and <code xmlns=
13955         "http://www.w3.org/TR/xhtml1/transitional" class=
13956         "filename">PLIST</code> (see <a href="#components" title=
13957         "Chapter&nbsp;8.&nbsp;Package components - files, directories and contents">
13958         Chapter 8, <i>Package components - files, directories and
13959         contents</i></a>) then continue with fetching the
13960         distfile:</p>
13961         <pre class="screen">
13962 <code class="prompt">#</code> <strong class=
13963 "userinput"><code>make fetch</code></strong>
13964 &gt;&gt; bison-1.25.tar.gz doesn't seem to exist on this system.
13965 &gt;&gt; Attempting to fetch from ftp://prep.ai.mit.edu/pub/gnu//.
13966 Requesting ftp://prep.ai.mit.edu/pub/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
13967 ftp: Error retrieving file: 500 Internal error
13968
13969 &gt;&gt; Attempting to fetch from ftp://wuarchive.wustl.edu/systems/gnu//.
13970 Requesting ftp://wuarchive.wustl.edu/systems/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
13971 ftp: Error retrieving file: 500 Internal error
13972
13973 &gt;&gt; Attempting to fetch from ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//.
13974 Requesting ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
13975 Successfully retrieved file.
13976 </pre>
13977
13978         <p>Generate the checksum of the distfile into <code xmlns=
13979         "http://www.w3.org/TR/xhtml1/transitional" class=
13980         "filename">distinfo</code>:</p>
13981         <pre class="screen">
13982 <code class="prompt">#</code> <strong class=
13983 "userinput"><code>make makesum</code></strong>
13984 </pre>
13985
13986         <p>Now compile:</p>
13987         <pre class="screen">
13988 <code class="prompt">#</code> <strong class=
13989 "userinput"><code>make</code></strong>
13990 &gt;&gt; Checksum OK for bison-1.25.tar.gz.
13991 ===&gt;  Extracting for bison-1.25
13992 ===&gt;  Patching for bison-1.25
13993 ===&gt;   Ignoring empty patch directory
13994 ===&gt;  Configuring for bison-1.25
13995 creating cache ./config.cache
13996 checking for gcc... cc
13997 checking whether we are using GNU C... yes
13998 checking for a BSD compatible install... /usr/bin/install -c -o bin -g bin
13999 checking how to run the C preprocessor... cc -E
14000 checking for minix/config.h... no
14001 checking for POSIXized ISC... no
14002 checking whether cross-compiling... no
14003 checking for ANSI C header files... yes
14004 checking for string.h... yes
14005 checking for stdlib.h... yes
14006 checking for memory.h... yes
14007 checking for working const... yes
14008 checking for working alloca.h... no
14009 checking for alloca... yes
14010 checking for strerror... yes
14011 updating cache ./config.cache
14012 creating ./config.status
14013 creating Makefile
14014 ===&gt;  Building for bison-1.25
14015 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g LR0.c
14016 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g allocate.c
14017 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g closure.c
14018 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g conflicts.c
14019 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g derives.c
14020 cc -c -DXPFILE=\"/usr/pkg/share/bison.simple\"  -DXPFILE1=\"/usr/pkg/share/bison.hairy\" -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1  -g  ./files.c
14021 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g getargs.c
14022 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g gram.c
14023 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g lalr.c
14024 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g lex.c
14025 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g main.c
14026 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g nullable.c
14027 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g output.c
14028 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g print.c
14029 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g reader.c
14030 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g reduce.c
14031 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g symtab.c
14032 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g warshall.c
14033 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g version.c
14034 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g getopt.c
14035 cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g getopt1.c
14036 cc  -g -o bison LR0.o allocate.o closure.o conflicts.o derives.o files.o         getargs.o gram.o lalr.o lex.o                                   main.o nullable.o output.o print.o reader.o reduce.o symtab.o   warshall.o version.o getopt.o getopt1.o
14037 ./files.c:240: warning: mktemp() possibly used unsafely, consider using mkstemp()
14038 rm -f bison.s1
14039 sed -e "/^#line/ s|bison|/usr/pkg/share/bison|" &lt; ./bison.simple &gt; bison.s1
14040 </pre>
14041
14042         <p>Everything seems OK, so install the files:</p>
14043         <pre class="screen">
14044 <code class="prompt">#</code> <strong class=
14045 "userinput"><code>make install</code></strong>
14046 &gt;&gt; Checksum OK for bison-1.25.tar.gz.
14047 ===&gt;  Installing for bison-1.25
14048 sh ./mkinstalldirs /usr/pkg/bin /usr/pkg/share  /usr/pkg/info /usr/pkg/man/man1
14049 rm -f /usr/pkg/bin/bison
14050 cd /usr/pkg/share; rm -f bison.simple bison.hairy
14051 rm -f /usr/pkg/man/man1/bison.1 /usr/pkg/info/bison.info*
14052 install -c  -o bin -g bin -m 555 bison /usr/pkg/bin/bison
14053 /usr/bin/install -c -o bin -g bin -m 644 bison.s1 /usr/pkg/share/bison.simple
14054 /usr/bin/install -c -o bin -g bin -m 644 ./bison.hairy /usr/pkg/share/bison.hairy
14055 cd .; for f in bison.info*;  do /usr/bin/install -c -o bin -g bin -m 644 $f /usr/pkg/info/$f; done
14056 /usr/bin/install -c -o bin -g bin -m 644 ./bison.1 /usr/pkg/man/man1/bison.1
14057 ===&gt;  Registering installation for bison-1.25
14058 </pre>
14059
14060         <p>You can now use bison, and also - if you decide so -
14061         remove it with <span><strong class="command">pkg_delete
14062         bison</strong></span>. Should you decide that you want a
14063         binary package, do this now:</p>
14064         <pre class="screen">
14065 <code class="prompt">#</code> <strong class=
14066 "userinput"><code>make package</code></strong>
14067 &gt;&gt; Checksum OK for bison-1.25.tar.gz.
14068 ===&gt;  Building package for bison-1.25
14069 Creating package bison-1.25.tgz
14070 Registering depends:.
14071 Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz'
14072 </pre>
14073
14074         <p>Now that you don't need the source and object files any
14075         more, clean up:</p>
14076         <pre class="screen">
14077 <code class="prompt">#</code> <strong class=
14078 "userinput"><code>make clean</code></strong>
14079 ===&gt;  Cleaning for bison-1.25
14080 </pre>
14081       </div>
14082     </div>
14083
14084     <div class="appendix" lang="en" xml:lang="en">
14085       <div class="titlepage">
14086         <div>
14087           <div>
14088             <h2 class="title"><a name="logs" id=
14089             "logs"></a>Appendix&nbsp;B.&nbsp;Build logs</h2>
14090           </div>
14091         </div>
14092       </div>
14093
14094       <div class="toc">
14095         <p><b>Table of Contents</b></p>
14096
14097         <dl>
14098           <dt><span class="sect1"><a href="#logs.building">B.1.
14099           Building figlet</a></span></dt>
14100
14101           <dt><span class="sect1"><a href="#logs.package">B.2.
14102           Packaging figlet</a></span></dt>
14103         </dl>
14104       </div>
14105
14106       <div class="sect1" lang="en" xml:lang="en">
14107         <div class="titlepage">
14108           <div>
14109             <div>
14110               <h2 class="title" style="clear: both"><a name=
14111               "logs.building" id=
14112               "logs.building"></a>B.1.&nbsp;Building figlet</h2>
14113             </div>
14114           </div>
14115         </div>
14116         <pre class="screen">
14117 <code class="prompt">#</code> <strong class=
14118 "userinput"><code>make</code></strong>
14119 ===&gt; Checking for vulnerabilities in figlet-2.2.1nb2
14120 =&gt; figlet221.tar.gz doesn't seem to exist on this system.
14121 =&gt; Attempting to fetch figlet221.tar.gz from ftp://ftp.figlet.org/pub/figlet/program/unix/.
14122 =&gt; [172219 bytes]
14123 Connected to ftp.plig.net.
14124 220 ftp.plig.org NcFTPd Server (licensed copy) ready.
14125 331 Guest login ok, send your complete e-mail address as password.
14126 230-You are user #5 of 500 simultaneous users allowed.
14127 230-
14128 230-  ___ _             _ _
14129 230- |  _| |_ ___   ___| |_|___   ___ ___ ___
14130 230- |  _|  _| . |_| . | | | . |_| . |  _| . |
14131 230- |_| |_| |  _|_|  _|_|_|_  |_|___|_| |_  |
14132 230-         |_|   |_|     |___|         |___|
14133 230-
14134 230-** Welcome to ftp.plig.org **
14135 230-
14136 230-Please note that all transfers from this FTP site are logged. If you
14137 230-do not like this, please disconnect now.
14138 230-
14139 230-This arhive is available via
14140 230-
14141 230-HTTP:  http://ftp.plig.org/
14142 230-FTP:   ftp://ftp.plig.org/     (max 500 connections)
14143 230-RSYNC: rsync://ftp.plig.org/   (max  30 connections)
14144 230-
14145 230-Please email comments, bug reports and requests for packages to be
14146 230-mirrored to ftp-admin@plig.org.
14147 230-
14148 230-
14149 230 Logged in anonymously.
14150 Remote system type is UNIX.
14151 Using binary mode to transfer files.
14152 200 Type okay.
14153 250 "/pub" is new cwd.
14154 250-"/pub/figlet" is new cwd.
14155 250-
14156 250-Welcome to the figlet archive at ftp.figlet.org
14157 250-
14158 250-    ftp://ftp.figlet.org/pub/figlet/
14159 250-
14160 250-The official FIGlet web page is:
14161 250-    http://www.figlet.org/
14162 250-
14163 250-If you have questions, please mailto:info@figlet.org. If you want to
14164 250-contribute a font or something else, you can email us.
14165 250
14166 250 "/pub/figlet/program" is new cwd.
14167 250 "/pub/figlet/program/unix" is new cwd.
14168 local: figlet221.tar.gz remote: figlet221.tar.gz
14169 502 Unimplemented command.
14170 227 Entering Passive Mode (195,40,6,41,246,104)
14171 150 Data connection accepted from 84.128.86.72:65131; transfer starting for figlet221.tar.gz (172219 bytes).
14172 38% |**************                       | 65800      64.16 KB/s    00:01 ETA
14173 226 Transfer completed.
14174 172219 bytes received in 00:02 (75.99 KB/s)
14175 221 Goodbye.
14176 =&gt; Checksum OK for figlet221.tar.gz.
14177 ===&gt; Extracting for figlet-2.2.1nb2
14178 ===&gt; Required installed package ccache-[0-9]*: ccache-2.3nb1 found
14179 ===&gt; Patching for figlet-2.2.1nb2
14180 ===&gt; Applying pkgsrc patches for figlet-2.2.1nb2
14181 ===&gt; Overriding tools for figlet-2.2.1nb2
14182 ===&gt; Creating toolchain wrappers for figlet-2.2.1nb2
14183 ===&gt; Configuring for figlet-2.2.1nb2
14184 ===&gt; Building for figlet-2.2.1nb2
14185 gcc -O2 -DDEFAULTFONTDIR=\"/usr/pkg/share/figlet\"  -DDEFAULTFONTFILE=\"standard.flf\"  figlet.c zipio.c crc.c inflate.c -o figlet
14186 chmod a+x figlet
14187 gcc -O2 -o chkfont chkfont.c
14188 =&gt; Unwrapping files-to-be-installed.
14189 <code class="prompt">#</code>
14190 <code class="prompt">#</code> <strong class=
14191 "userinput"><code>make install</code></strong>
14192 ===&gt; Checking for vulnerabilities in figlet-2.2.1nb2
14193 ===&gt; Installing for figlet-2.2.1nb2
14194 install -d -o root -g wheel -m 755 /usr/pkg/bin
14195 install -d -o root -g wheel -m 755 /usr/pkg/man/man6
14196 mkdir -p /usr/pkg/share/figlet
14197 cp figlet /usr/pkg/bin
14198 cp chkfont /usr/pkg/bin
14199 chmod 555 figlist showfigfonts
14200 cp figlist /usr/pkg/bin
14201 cp showfigfonts /usr/pkg/bin
14202 cp fonts/*.flf /usr/pkg/share/figlet
14203 cp fonts/*.flc /usr/pkg/share/figlet
14204 cp figlet.6 /usr/pkg/man/man6
14205 ===&gt; Registering installation for figlet-2.2.1nb2
14206 <code class="prompt">#</code>
14207 </pre>
14208       </div>
14209
14210       <div class="sect1" lang="en" xml:lang="en">
14211         <div class="titlepage">
14212           <div>
14213             <div>
14214               <h2 class="title" style="clear: both"><a name=
14215               "logs.package" id=
14216               "logs.package"></a>B.2.&nbsp;Packaging figlet</h2>
14217             </div>
14218           </div>
14219         </div>
14220         <pre class="screen">
14221 <code class="prompt">#</code> <strong class=
14222 "userinput"><code>make package</code></strong>
14223 ===&gt; Checking for vulnerabilities in figlet-2.2.1nb2
14224 ===&gt; Packaging figlet-2.2.1nb2
14225 ===&gt; Building binary package for figlet-2.2.1nb2
14226 Creating package /home/cvs/pkgsrc/packages/i386/All/figlet-2.2.1nb2.tgz
14227 Using SrcDir value of /usr/pkg
14228 Registering depends:.
14229 <code class="prompt">#</code>
14230 </pre>
14231       </div>
14232     </div>
14233
14234     <div class="appendix" lang="en" xml:lang="en">
14235       <div class="titlepage">
14236         <div>
14237           <div>
14238             <h2 class="title"><a name="ftp-layout" id=
14239             "ftp-layout"></a>Appendix&nbsp;C.&nbsp;Layout of the
14240             FTP server's package archive</h2>
14241           </div>
14242         </div>
14243       </div>
14244
14245       <p>Layout for precompiled binary packages on
14246       ftp.NetBSD.org:</p>
14247       <pre class="programlisting">
14248     /pub/NetBSD/packages/
14249         distfiles/
14250
14251         # Unpacked pkgsrc trees
14252         pkgsrc-current -&gt; /pub/NetBSD/NetBSD-current/pkgsrc
14253         pkgsrc-2003Q4 -&gt; N/A
14254         pkgsrc-2004Q1/pkgsrc
14255
14256         # pkgsrc archives
14257         pkgsrc-current.tar.gz -&gt; ../NetBSD-current/tar_files/pkgsrc.tar.gz
14258         pkgsrc-2003Q4.tar.gz -&gt; N/A
14259         pkgsrc-2004Q1.tar.gz -&gt; N/A
14260
14261         # Per pkgsrc-release/OS-release/arch package archives
14262         pkgsrc-2003Q4/
14263             NetBSD-1.6.2/
14264                 i386/
14265                     All/
14266                     archivers/
14267                         foo -&gt; ../All/foo
14268                     ...
14269         pkgsrc-2004Q1/
14270             NetBSD-1.6.2/
14271                 i386/
14272                     All/
14273                     ...
14274             NetBSD-2.0/
14275                 i386/
14276                     All/
14277                     ...
14278             SunOS-5.9/
14279                 sparc/
14280                     All/
14281                     ...
14282                 x86/
14283                     All/
14284                     ...
14285
14286         # Per os-release package archive convenience links
14287         NetBSD-1.6.2 -&gt; 1.6.2
14288         1.6.2/
14289             i386 -&gt; ../pkgsrc-2004Q1/NetBSD-1.6.2/i386
14290             m68k/
14291                 All/
14292                 archivers/
14293                     foo -&gt; ../All/foo
14294                 ...
14295             amiga -&gt; m68k
14296             atari -&gt; m68k
14297             ...
14298
14299         2.0 -&gt; NetBSD-2.0       # backward compat, historic
14300         NetBSD-2.0/
14301             i386 -&gt; ../pkgsrc-2004Q1/NetBSD-2.0/i386
14302         SunOS-5.9/
14303             sparc -&gt; ../pkgsrc-2004Q1/SunOS-5.9/sparc
14304             x86 -&gt; ../pkgsrc-2004Q1/SunOS-5.9/x86
14305 </pre>
14306
14307       <p>To create:</p>
14308
14309       <div class="orderedlist">
14310         <ol type="1">
14311           <li>
14312             <p>Run bulk build, see <a href="#bulkbuild" title=
14313             "6.3.&nbsp;Doing a bulk build of all packages">Section
14314             6.3, &#8220;Doing a bulk build of all
14315             packages&#8221;</a></p>
14316           </li>
14317
14318           <li>
14319             <p>Upload /usr/pkgsrc/packages to</p>
14320             <pre class="programlisting">
14321     ftp://ftp.NetBSD.org/pub/NetBSD/packages/\
14322         pkgsrc-2004Q4/\             # pkgsrc-branch
14323         `uname -s`-`uname -r`/\     # OS &amp; version
14324         `uname -p`                  # architecture
14325 </pre>
14326           </li>
14327
14328           <li>
14329             <p>If necessary, create a symlink <span><strong class=
14330             "command">ln -s `uname -m` `uname -p`</strong></span>
14331             (amiga -&gt; m68k, ...)</p>
14332           </li>
14333         </ol>
14334       </div>
14335     </div>
14336
14337     <div class="appendix" lang="en" xml:lang="en">
14338       <div class="titlepage">
14339         <div>
14340           <div>
14341             <h2 class="title"><a name="editing" id=
14342             "editing"></a>Appendix&nbsp;D.&nbsp;Editing guidelines
14343             for the pkgsrc guide</h2>
14344           </div>
14345         </div>
14346       </div>
14347
14348       <div class="toc">
14349         <p><b>Table of Contents</b></p>
14350
14351         <dl>
14352           <dt><span class="sect1"><a href="#targets">D.1.
14353           Targets</a></span></dt>
14354
14355           <dt><span class="sect1"><a href="#procedure">D.2.
14356           Procedure</a></span></dt>
14357         </dl>
14358       </div>
14359
14360       <p>This section contains information on editing the pkgsrc
14361       guide itself.</p>
14362
14363       <div class="sect1" lang="en" xml:lang="en">
14364         <div class="titlepage">
14365           <div>
14366             <div>
14367               <h2 class="title" style="clear: both"><a name=
14368               "targets" id="targets"></a>D.1.&nbsp;Targets</h2>
14369             </div>
14370           </div>
14371         </div>
14372
14373         <p>The pkgsrc guide's source code is stored in <code xmlns=
14374         "http://www.w3.org/TR/xhtml1/transitional" class=
14375         "filename">pkgsrc/doc/guide/files</code>, and several files
14376         are created from it:</p>
14377
14378         <div class="itemizedlist">
14379           <ul type="disc">
14380             <li>
14381               <p><code xmlns=
14382               "http://www.w3.org/TR/xhtml1/transitional" class=
14383               "filename">pkgsrc/doc/pkgsrc.txt</code></p>
14384             </li>
14385
14386             <li>
14387               <p><code xmlns=
14388               "http://www.w3.org/TR/xhtml1/transitional" class=
14389               "filename">pkgsrc/doc/pkgsrc.html</code></p>
14390             </li>
14391
14392             <li>
14393               <p><code xmlns=
14394               "http://www.w3.org/TR/xhtml1/transitional" class=
14395               "filename">http://www.NetBSD.org/Documentation/pkgsrc/</code>:
14396               the documentation on the NetBSD website will be built
14397               from pkgsrc and kept up to date on the web server
14398               itself. This means you <span class=
14399               "emphasis"><em>must</em></span> make sure that your
14400               changes haven't broken the build!</p>
14401             </li>
14402
14403             <li>
14404               <p><code xmlns=
14405               "http://www.w3.org/TR/xhtml1/transitional" class=
14406               "filename">http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.pdf</code>:
14407               PDF version of the pkgsrc guide.</p>
14408             </li>
14409
14410             <li>
14411               <p><code xmlns=
14412               "http://www.w3.org/TR/xhtml1/transitional" class=
14413               "filename">http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.ps</code>:
14414               PostScript version of the pkgsrc guide.</p>
14415             </li>
14416           </ul>
14417         </div>
14418       </div>
14419
14420       <div class="sect1" lang="en" xml:lang="en">
14421         <div class="titlepage">
14422           <div>
14423             <div>
14424               <h2 class="title" style="clear: both"><a name=
14425               "procedure" id=
14426               "procedure"></a>D.2.&nbsp;Procedure</h2>
14427             </div>
14428           </div>
14429         </div>
14430
14431         <p>The procedure to edit the pkgsrc guide is:</p>
14432
14433         <div class="itemizedlist">
14434           <ul type="disc">
14435             <li>
14436               <p>Make sure you have the packages needed to
14437               re-generate the pkgsrc guide (and other XML-based
14438               NetBSD documentation) installed. These are
14439               &#8220;<span class="quote">netbsd-doc</span>&#8221;
14440               for creating the ASCII and HTML versions, and
14441               &#8220;<span class=
14442               "quote">netbsd-doc-print</span>&#8221; for the
14443               PostScript and PDF versions. You will need both
14444               packages installed, to make sure documentation is
14445               consistent across all formats. The packages can be
14446               found in <code xmlns=
14447               "http://www.w3.org/TR/xhtml1/transitional" class=
14448               "filename">pkgsrc/meta-pkgs/netbsd-doc</code> and
14449               <code xmlns=
14450               "http://www.w3.org/TR/xhtml1/transitional" class=
14451               "filename">pkgsrc/meta-pkgs/netbsd-doc-print</code>.</p>
14452             </li>
14453
14454             <li>
14455               <p>Edit the XML file(s) in <code xmlns=
14456               "http://www.w3.org/TR/xhtml1/transitional" class=
14457               "filename">pkgsrc/doc/guide/files</code>.</p>
14458             </li>
14459
14460             <li>
14461               <p>Run <span><strong class="command">make extract
14462               &amp;&amp; make do-lint</strong></span> in
14463               <code xmlns=
14464               "http://www.w3.org/TR/xhtml1/transitional" class=
14465               "filename">pkgsrc/doc/guide</code> to check the XML
14466               syntax, and fix it if needed.</p>
14467             </li>
14468
14469             <li>
14470               <p>Run <span><strong class=
14471               "command">make</strong></span> in <code xmlns=
14472               "http://www.w3.org/TR/xhtml1/transitional" class=
14473               "filename">pkgsrc/doc/guide</code> to build the HTML
14474               and ASCII version.</p>
14475             </li>
14476
14477             <li>
14478               <p>If all is well, run <span><strong class=
14479               "command">make install-doc</strong></span> to put the
14480               generated files into <code xmlns=
14481               "http://www.w3.org/TR/xhtml1/transitional" class=
14482               "filename">pkgsrc/doc</code>.</p>
14483             </li>
14484
14485             <li>
14486               <p><span><strong class="command">cvs commit
14487               pkgsrc/doc/guide/files</strong></span></p>
14488             </li>
14489
14490             <li>
14491               <p><span><strong class="command">cvs commit -m
14492               re-generate
14493               pkgsrc/doc/pkgsrc.{html,txt}</strong></span></p>
14494             </li>
14495
14496             <li>
14497               <p>Until the webserver on www.NetBSD.org is really
14498               updated automatically to pick up changes to the
14499               pkgsrc guide automatically, also run
14500               <span><strong class="command">make install-htdocs
14501               HTDOCSDIR=../../../htdocs</strong></span> (or
14502               similar, adjust <code class=
14503               "varname">HTDOCSDIR</code>!).</p>
14504             </li>
14505
14506             <li>
14507               <p><span><strong class="command">cvs commit
14508               htdocs/Documentation/pkgsrc</strong></span></p>
14509             </li>
14510           </ul>
14511         </div>
14512       </div>
14513     </div>
14514   </div>
14515 </body>
14516 </html>