usr/src/pkg/README.pkg

   1 #
   2 # CDDL HEADER START
   3 #
   4 # The contents of this file are subject to the terms of the
   5 # Common Development and Distribution License (the "License").
   6 # You may not use this file except in compliance with the License.
   7 #
   8 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 # or http://www.opensolaris.org/os/licensing.
  10 # See the License for the specific language governing permissions
  11 # and limitations under the License.
  12 #
  13 # When distributing Covered Code, include this CDDL HEADER in each
  14 # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 # If applicable, add the following below this CDDL HEADER, with the
  16 # fields enclosed by brackets "[]" replaced with your own identifying
  17 # information: Portions Copyright [yyyy] [name of copyright owner]
  18 #
  19 # CDDL HEADER END
  20 #
  21
  22 #
  23 # Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
  24 #
  25
  26 Introduction
  27 ------------
  28
  29 This README describes some basics about creating, modifying, and
  30 building packages in ON.  All package creation in ON is done using
  31 tools available to our customers.  If terminology in this document
  32 is confusing, you may wish to review the pkg(5) manpage.
  33
  34 Packaging Overview
  35 ------------------
  36
  37 usr/src/pkg/ contains the definitions and rules needed to build an IPS
  38 repository which contain the deliverables from an ON build.
  39
  40 The manifests directory contains all manifests, and has one file
  41 per package.  For most packaging changes you only need to add or
  42 change the packaging manifests themselves.
  43
  44 The build rules create a package repository.  Separate DEBUG and
  45 non-DEBUG versions are built, and are available at:
  46     $CODEMGR_WS/packages/$MACH/nightly[-nd]/repo.redist
  47
  48 Building Packages
  49 -----------------
  50
  51 The -p option to nightly will build the IPS repository.
  52
  53 Alternatively, in usr/src/pkg/Makefile there are make targets for:
  54
  55         all
  56             Process manifests into their final form with unresolved
  57             dependencies before publication.
  58
  59         install
  60             Publish packages.
  61
  62         gendeps
  63             Run `pkgdepend resolve`.  See Dependencies section.
  64
  65         protocmp
  66             Compare the proto area against package definitions for
  67             missing or incorrect files.
  68
  69         pmodes
  70             Check file and directory modes for best practices.
  71
  72         check
  73             Run protocmp and pmodes.
  74
  75 The build behavior may modified by the following variables:
  76
  77         SUPPRESSPKGDEP
  78             If SUPPRESSPKGDEP is set to "true" in your environment,
  79             package dependencies will not be generated.  This variable
  80             should not be set in normal builds as it will mask product
  81             bugs.
  82
  83         PKGDEBUG
  84             If PKGDEBUG is set in your environment, $MAKE will print
  85             detailed information about the commands it executes to
  86             process and publish packages.
  87
  88         ONNV_BUILDNUM
  89             If ONNV_BUILDNUM is set to an older ON build number,
  90             your packages will be published at that version instead
  91             of the one defined in usr/src/Makefile.buildnum, which
  92             is managed by the gatekeepers.
  93
  94 A set of intermediate build products are placed in
  95 usr/src/pkg/packages.$MACH/.  These can be useful during development.
  96
  97         .mog
  98             The resulting package manifest after running pkgmogrify(1)
  99             on the supplied manifest.  See below for details on
 100             pkgmogrify(1) use in ON.
 101
 102         .dep
 103             The resulting manifest after running `pkgdepend generate`
 104             on the .mog manifest.
 105
 106         .res
 107             The resulting manifest after running `pkgdepend resolve`
 108             on the .dep manifest.
 109
 110 Incremental Builds
 111 ------------------
 112
 113    If you want to process a subset of manifests, simply set PKGS on the
 114    make command line and specify the "all" target.  If you want to process
 115    them all, simply specify the "all" target.
 116
 117         % dmake -e PKGS="BRCMbnx BRCMbnxe" all
 118         % dmake -e all
 119
 120    If you want to publish a subset of packages, simply set PKGS on the
 121    make command line and specify the "install" target.  Overriding PKGS
 122    will cause dependency resolution to be limited to PKGS from the
 123    current build, with a fallback to packages installed on the build
 124    system.  If you want to publish them all, simply specify the
 125    "install" target.
 126
 127         % dmake -e PKGS="BRCMbnx BRCMbnxe" install
 128         % dmake -e install
 129
 130    You can also use package names, or package names with ".pub"
 131    extensions, as build targets.  This will cause processing or
 132    publication of the specified package(s).
 133
 134    The on-disk repository will be initialized when it does not exist,
 135    or when you run nightly -p.  If you build incrementally,
 136    packages will simply be added to the existing repository.
 137
 138    To do cross-platform packaging, prefix your target with (for
 139    example) "sparc/", as in "dmake sparc/install".  Note that we
 140    currently pull some license files directly from a built source
 141    tree, so if you do this in a workspace that had proto area copied
 142    in via nightly -U, then you'll need to set $SRC to point to the
 143    workspace that was actually built.
 144
 145 Testing Packages
 146 ----------------
 147
 148 To test the generated repository, you should use the "onu" tool
 149 available from /opt/onbld/bin or usr/src/tools/scripts/ to setup and
 150 upgrade your system.  A manpage is available in /opt/onbld/man
 151 or usr/src/tools/scripts/onu.1.
 152
 153 Alternatively, you can manually start a pkg.depot(1M) server to
 154 serve the generated repository to multiple test machines.
 155
 156         Start up a depot on your build machine.
 157             cd $CODEMGR_WS/packages/$MACH/nightly[-nd]
 158             /usr/lib/pkg.depotd -d repo.redist -p <port> &
 159
 160             Make SURE you choose an unused port and the depot
 161             starts successfully.
 162
 163             The depot can be started across NFS as well if you
 164             have a fast pipe.
 165
 166         Configure your test system.
 167             pkg set-publisher -P -g http://<your server host>:<port> on-nightly
 168             pkg set-publisher --non-sticky opensolaris.org
 169             pkg uninstall entire
 170
 171         pkg image-update your test system.
 172             pkg image-update will upgrade all packages on your test system
 173
 174 Always make sure your bits are installed with image-update.
 175         Check your versions.
 176             pkg info osnet-incorporation
 177
 178         Multiple packages should be updated.
 179             If you did a full build, all ON packages will be updated.
 180             When image-update tells you that only one or two packages has
 181             been updated, you likely did not get the updates you expected.
 182
 183 There are various tactics for troubleshooting a failed upgrade.
 184         Make sure entire is uninstalled.
 185
 186         pkg install -nv osnet-incorporation@<your version>
 187             Ask IPS to explicitly check if ON can be installed, and
 188             if it can't, tell you why not.
 189
 190         Obsolete and renamed packages can cause trouble.
 191             pkg search -l ::pkg.renamed:true
 192             pkg search -l ::pkg.obsolete:true
 193
 194
 195 Making Packaging Changes
 196 ------------------------
 197
 198 Package definitions are in usr/src/pkg/manifests/, and have one
 199 file per package, including for multi-architecture packages.  For
 200 most packaging changes you only need to add or change the packaging
 201 manifests themselves.  No packaging metadata may be kept outside of the
 202 manifests. If you find yourself needing to modify usr/src/pkg/Makefile,
 203 you're almost certainly doing something wrong.
 204
 205 Remember that the "check" target is available to check many of
 206 your packaging changes.
 207
 208 We run pkgmogrify(1) over the manifests before publication.  This
 209 allows us to apply a set of macros and package transformations in
 210 order to make the manifests themselves easier to maintain.
 211
 212 We supply a set of commonly-used macros for use in package manifests.
 213 These are the PKGMOG_DEFINES in usr/src/pkg/Makefile.
 214
 215         $(i386_ONLY)
 216         $(sparc_ONLY)
 217         $(ARCH)
 218         $(ARCH32)
 219         $(ARCH64)
 220         $(PKGVERS), which is set to
 221            $(PKGVERS_COMPONENT),$(PKGVERS_BUILTON)-0.$(PKGVERS_BRANCH)
 222
 223 pkgmogrify(1) also allows us to include a set of default transformations.
 224 The definitions for these transforms are in usr/src/pkg/transforms/.  An
 225 overview of their use is supplied here, but for a full accounting, please
 226 read pkmogrify(1) and the files themselves.
 227
 228         defaults
 229             This transform is applied to all manifests.  It specifies
 230             a set of sensible default permissions, a set of
 231             directory locations for which the reboot-needed actuator
 232             is always applied to files, and some other basic defaults.
 233
 234         publish
 235             This transform is applied to all manifests.  It ensures
 236             that manifest lines which don't apply to the current
 237             architecture are stripped.
 238
 239         restart_fmri
 240             This transform is applied to all manifests.  It modifies
 241             all package manifest lines for SMF manifests in standard
 242             locations to include an actuator which runs manifest-import
 243             on installation/update/removal, as well as some others.  If
 244             you're adding a new class of file that would benefit from
 245             a restart or refresh of a specific SMF service, please add
 246             it here.
 247
 248         extract_metadata
 249             This transform is applied to all manifests.  It deals with
 250             manipulations required for packaging metadata like
 251             pkg.renamed, and pkg.obsolete.
 252
 253         hollow_zone_pkg
 254             This transform is available for explicit inclusion in
 255             some manifests.  It ensures that all contents of the
 256             package are not installed within a non-global zone, but the
 257             package and its metadata are available in order to satisfy
 258             packaging dependencies.
 259
 260 pkgmogrify(1) also allows us to use comments and continuation lines
 261 in our manifests.
 262
 263 Zones and Packages
 264 ------------------
 265
 266 pkg(5) uses variants to implement zones.  If a package is marked
 267 with both global and non-global zone variants, the package contents will
 268 be installed in both global and non-global by default.
 269         set name=variant.opensolaris.zone value=global value=nonglobal
 270
 271 Specific actions within a package can be tagged as applying to only
 272 the global zone or only the non-global zones.
 273
 274 The hollow_zone_pkg transform described above is also available to
 275 simplify a common packaging scenario.
 276
 277 Dependencies
 278 ------------
 279
 280 Package dependencies are automatically calculated during build time
 281 using pkgdepend(1).  After you've done a build, you can verify your
 282 dependencies in the <package>.res file described above.  If the
 283 file is missing a dependency that you believe could be auto-detected,
 284 please file a bug against pkgdepend(1).
 285
 286 Dependencies can be added manually using the "depend" action.  Please
 287 add a comment describing why the dependency is required.
 288
 289 Moving Content Between Packages and Removing Content
 290 ----------------------------------------------------
 291
 292 pkg(5) tracks when content is removed from packages, and automatically
 293 removes it.
 294
 295 If you need to move content between packages, there are two primary
 296 things to do.
 297
 298         "preserve" files must be marked with original_name.
 299             The first time a "preserve" file moves between packages,
 300             you must set original_name=<original package>:<file>
 301             in that file's action.  Subsequent moves do not require
 302             modification.
 303
 304         Consider adding a dependency on the new package.
 305             The only way a system will end up with a new package
 306             after upgrade is if an existing package depends on it.
 307
 308 Renaming a Package
 309 ------------------
 310
 311 To rename a package, leave the old package manifest in place, but
 312 empty it of all delivered content.  The old package should include:
 313
 314         set name=pkg.fmri with the version set explicitly to the
 315             build you're integrating into.  For example, if you wanted
 316             to rename SUNWrmodu in build 133 you'd change the pkg.fmri
 317             line to read
 318             set name=pkg.fmri value=pkg:/SUNWrmodu@0.5.11,5.11-0.133
 319
 320         set name=pkg.renamed value=true
 321
 322         The architectures and variants you're renaming.  These
 323             should just be copied from your old package, as you
 324             must rename a package on all architectures and
 325             variants simultaneously.
 326
 327         A dependency on the new package.
 328
 329 If there were "preserve" files in the package you're renaming, make
 330 sure to create original_name settings in the new package.
 331
 332 If there was a org.opensolaris.noincorp property in the package being
 333 renamed, make sure you keep it in both the original and the renamed
 334 packages.
 335
 336 EOFs and Removals
 337 -----------------
 338
 339 To remove files, directories, drivers, or anything else within a package,
 340 simply stop delivering them in the package.  IPS will manage the removal
 341 of no longer delivered content.
 342
 343 Package removals have impact on the rest of the system.  Before marking
 344 a package as obsolete, search in the OpenSolaris development
 345 repository (http://pkg.opensolaris.org/dev or http://ipkg.sfbay/dev)
 346 to find out if any other packages depend on the software you intend
 347 to EOF.  If any packages do, you need to coordinate with those
 348 consolidations.
 349
 350 The "slim_install" package may depend on ON packages.  If it does,
 351 you must send a FLAG DAY message for ON users and PIT who test
 352 install.  You must also file an installation bug to get that package
 353 updated in the same build or earlier than you intend to integrate.
 354 You should also test install yourself.  You can do this by replacing
 355 the "slim_install" in your Distro Constructor manifest with the
 356 explicit list of packages to install.
 357
 358 To remove a package, you must mark it as obsolete.  You must *also* mark
 359 as obsolete any packages which are renamed ancestors of this package, and
 360 remove their rename dependencies.  Here is what you must do.
 361
 362 To find rename ancestors, select all of the manifests which are renames,
 363 then look for the one which was renamed to the package you care about.
 364 For example, to find rename ancestors of 'system/zones', do the following:
 365
 366     $ cd usr/src/pkg/manifests
 367     $ mypkgname=system/zones
 368     $ grep -l "fmri=pkg:/$mypkgname@" `grep -l pkg.renamed *.mf` /dev/null
 369     SUNWzone.mf
 370
 371 Make sure to check that the package has not undergone multiple renames!
 372
 373     $ mypkgname=SUNWzone
 374     $ grep -l "fmri=pkg:/$mypkgname@" `grep -l pkg.renamed *.mf` /dev/null
 375     $
 376
 377 Once you have the renamed ancestor list, for *each* of the packages (the
 378 newly obsolete package, and its renamed ancestors), edit the package as
 379 follows:
 380
 381         Update 'set name=pkg.fmri' with the version set explicitly to the
 382             build you're integrating into.  For example, if you wanted
 383             to remove SUNWwbsd in build 133 you'd change the pkg.fmri
 384             line to read:
 385             'set name=pkg.fmri value=pkg:/SUNWwbsd@0.5.11,5.11-0.133'
 386
 387         Add 'set name=pkg.obsolete value=true'.
 388
 389         Maintain the architecture and variant declarations in the
 390             package you are obsoleting.  Note that you must obsolete a
 391             package on all architectures and variants simultaneously.
 392
 393         Delete everything else.
 394
 395         If the package is a renamed ancestor, leave a comment behind as
 396         follows:
 397
 398            # Was renamed to <other-pkg-name>, both now obsolete.
 399
 400 Here is a complete example.  SUNWfoobar was a package which was renamed
 401 to system/foobar in build 140, and then later obsoleted in build 150.
 402 Note that in all cases the package FMRI is updated to the obsoletion
 403 build, 150.
 404
 405     SUNWfoobar.mf:
 406         # Was renamed to system/foobar, both now obsolete.
 407         set name=pkg.fmri value=pkg:/SUNWfoobar@0.5.11,5.11-0.150
 408         set name=pkg.obsolete value=true
 409         set name=variant.arch value=$(ARCH)
 410
 411     system-foobar.mf:
 412         set name=pkg.fmri value=pkg:/system/foobar@0.5.11,5.11-0.150
 413         set name=pkg.obsolete value=true
 414         set name=variant.arch value=$(ARCH)
 415
 416 Creating a Package
 417 ------------------
 418
 419 The easiest thing is to copy a package similar to the one you're
 420 trying to create.  Note that packages are no longer split on the
 421 /usr and / boundary.
 422
 423 The following actions are required for all packages in ON.
 424         set name=pkg.fmri
 425             Every package must have an FMRI.  That is the package's
 426             name.
 427
 428         set name=pkg.summary
 429             Every package must have a short summary of its purpose.
 430
 431         set name=pkg.description
 432             Every package must have a one-sentence description of
 433             its purpose.
 434
 435         set name=variant.arch
 436             Every package must specify which architectures it delivers.
 437
 438         set name=info.classification
 439             Every package must specify a category for the packaging GUI.
 440             You must use an existing category, and may not invent new ones.
 441             Existing categories and their subcategories are listed
 442             in /usr/share/package-manager/data/opensolaris.org.sections.
 443
 444         license
 445             All packages must specify a set of license actions.  If
 446             you're adding items here that are not already included in
 447             usr/src/pkg/license_files, then you will also need to modify
 448             usr/src/tools/opensolaris/license-list.
 449
 450 You don't need to set the following.  They're taken care of for all OS/Net
 451 packages in the transforms/common_actions file.
 452
 453         set name=variant.opensolaris.zone
 454             Every package must specify whether it can be installed in
 455             global zones, non-global zones, or both.  All ON packages are
 456             delivered in both global and non-global zones.
 457
 458         set name=org.opensolaris.consolidation value=osnet
 459             All packages from OS/Net come from OS/Net...
 460
 461 Drivers and Packages
 462 --------------------
 463
 464 Scripting is no longer required to deal with addition or removal of
 465 drivers in ON.  A "driver" action should be specified for each driver,
 466 and IPS will handle updates to all the driver files.