8895 libtsol man pages are out of step with reality
[unleashed.git] / usr / src / pkg / README.pkg
blob823e3cf152ea454a646f194ba8cf90a12695d2d9
2 # CDDL HEADER START
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.
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.
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]
19 # CDDL HEADER END
23 # Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
26 Introduction
27 ------------
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.
34 Packaging Overview
35 ------------------
37 usr/src/pkg/ contains the definitions and rules needed to build an IPS
38 repository which contain the deliverables from an ON build.
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.
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
48 Building Packages
49 -----------------
51 The -p option to nightly will build the IPS repository.
53 Alternatively, in usr/src/pkg/Makefile there are make targets for:
55         all
56             Process manifests into their final form with unresolved
57             dependencies before publication.
59         install
60             Publish packages.
62         gendeps
63             Run `pkgdepend resolve`.  See Dependencies section.
65         protocmp
66             Compare the proto area against package definitions for
67             missing or incorrect files.
69         pmodes
70             Check file and directory modes for best practices.
72         check
73             Run protocmp and pmodes.
75 The build behavior may modified by the following variables:
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.
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.
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.
94 A set of intermediate build products are placed in
95 usr/src/pkg/packages.$MACH/.  These can be useful during development.
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.
102         .dep
103             The resulting manifest after running `pkgdepend generate`
104             on the .mog manifest.
106         .res
107             The resulting manifest after running `pkgdepend resolve`
108             on the .dep manifest.
110 Incremental Builds
111 ------------------
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.
117         % dmake -e PKGS="BRCMbnx BRCMbnxe" all
118         % dmake -e all
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.
127         % dmake -e PKGS="BRCMbnx BRCMbnxe" install
128         % dmake -e install
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).
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.
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.
145 Testing Packages
146 ----------------
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.
153 Alternatively, you can manually start a pkg.depot(1M) server to
154 serve the generated repository to multiple test machines.
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> &
160             Make SURE you choose an unused port and the depot
161             starts successfully.
163             The depot can be started across NFS as well if you
164             have a fast pipe.
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
171         pkg image-update your test system.
172             pkg image-update will upgrade all packages on your test system
174 Always make sure your bits are installed with image-update.
175         Check your versions.
176             pkg info osnet-incorporation
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.
183 There are various tactics for troubleshooting a failed upgrade.
184         Make sure entire is uninstalled.
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.
190         Obsolete and renamed packages can cause trouble.
191             pkg search -l ::pkg.renamed:true
192             pkg search -l ::pkg.obsolete:true
195 Making Packaging Changes
196 ------------------------
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.
205 Remember that the "check" target is available to check many of
206 your packaging changes.
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.
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.
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)
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.
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.
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.
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.
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.
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.
260 pkgmogrify(1) also allows us to use comments and continuation lines
261 in our manifests.
263 Zones and Packages
264 ------------------
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
271 Specific actions within a package can be tagged as applying to only
272 the global zone or only the non-global zones.
274 The hollow_zone_pkg transform described above is also available to
275 simplify a common packaging scenario.
277 Dependencies
278 ------------
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).
286 Dependencies can be added manually using the "depend" action.  Please
287 add a comment describing why the dependency is required.
289 Moving Content Between Packages and Removing Content
290 ----------------------------------------------------
292 pkg(5) tracks when content is removed from packages, and automatically
293 removes it.
295 If you need to move content between packages, there are two primary
296 things to do.
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.
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.
308 Renaming a Package
309 ------------------
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:
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
320         set name=pkg.renamed value=true
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.
327         A dependency on the new package.
329 If there were "preserve" files in the package you're renaming, make
330 sure to create original_name settings in the new package.
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.
336 EOFs and Removals
337 -----------------
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.
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.
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.
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.
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:
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
371 Make sure to check that the package has not undergone multiple renames!
373     $ mypkgname=SUNWzone
374     $ grep -l "fmri=pkg:/$mypkgname@" `grep -l pkg.renamed *.mf` /dev/null
375     $
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:
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'
387         Add 'set name=pkg.obsolete value=true'.
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.
393         Delete everything else.
395         If the package is a renamed ancestor, leave a comment behind as
396         follows:
398            # Was renamed to <other-pkg-name>, both now obsolete.
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.
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)
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)
416 Creating a Package
417 ------------------
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.
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.
428         set name=pkg.summary
429             Every package must have a short summary of its purpose.
431         set name=pkg.description
432             Every package must have a one-sentence description of
433             its purpose.
435         set name=variant.arch
436             Every package must specify which architectures it delivers.
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.
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.
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.
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.
458         set name=org.opensolaris.consolidation value=osnet
459             All packages from OS/Net come from OS/Net...
461 Drivers and Packages
462 --------------------
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.