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