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