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.
29This README describes some basics about creating, modifying, and
30building packages in ON. All package creation in ON is done using
31tools available to our customers. If terminology in this document
32is confusing, you may wish to review the pkg(7) manpage.
37usr/src/pkg/ contains the definitions and rules needed to build an IPS
38repository which contain the deliverables from an ON build.
40The manifests directory contains all manifests, and has one file
41per package. For most packaging changes you only need to add or
42change the packaging manifests themselves.
44The build rules create a package repository. Separate DEBUG and
45non-DEBUG versions are built, and are available at:
51The -p option to nightly will build the IPS repository.
53Alternatively, in usr/src/pkg/Makefile there are make targets for:
56 Process manifests into their final form with unresolved
57 dependencies before publication.
60 Publish packages.
63 Run `pkgdepend resolve`. See Dependencies section.
66 Compare the proto area against package definitions for
67 missing or incorrect files.
70 Check file and directory modes for best practices.
73 Run protocmp and pmodes.
75The build behavior may modified by the following variables:
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
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.
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.
94A set of intermediate build products are placed in
95usr/src/pkg/packages.$MACH/. These can be useful during development.
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.
103 The resulting manifest after running `pkgdepend generate`
104 on the .mog manifest.
107 The resulting manifest after running `pkgdepend resolve`
108 on the .dep manifest.
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.
148To test the generated repository, you should use the "onu" tool
149available from /opt/onbld/bin or usr/src/tools/scripts/ to setup and
150upgrade your system. A manpage is available in /opt/onbld/man
153Alternatively, you can manually start a pkg.depot(8) server to
154serve 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
174Always 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.
183There 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
195Making Packaging Changes
198Package definitions are in usr/src/pkg/manifests/, and have one
199file per package, including for multi-architecture packages. For
200most packaging changes you only need to add or change the packaging
201manifests themselves. No packaging metadata may be kept outside of the
202manifests. If you find yourself needing to modify usr/src/pkg/Makefile,
203you're almost certainly doing something wrong.
205Remember that the "check" target is available to check many of
206your packaging changes.
208We run pkgmogrify(1) over the manifests before publication. This
209allows us to apply a set of macros and package transformations in
210order to make the manifests themselves easier to maintain.
212We supply a set of commonly-used macros for use in package manifests.
213These are the PKGMOG_DEFINES in usr/src/pkg/Makefile.
220 $(PKGVERS), which is set to
223pkgmogrify(1) also allows us to include a set of default transformations.
224The definitions for these transforms are in usr/src/pkg/transforms/. An
225overview of their use is supplied here, but for a full accounting, please
226read pkmogrify(1) and the files themselves.
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.
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.
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.
249 This transform is applied to all manifests. It deals with
250 manipulations required for packaging metadata like
251 pkg.renamed, and pkg.obsolete.
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.
260pkgmogrify(1) also allows us to use comments and continuation lines
261in our manifests.
263Zones and Packages
266pkg(7) uses variants to implement zones. If a package is marked
267with both global and non-global zone variants, the package contents will
268be installed in both global and non-global by default.
269 set name=variant.opensolaris.zone value=global value=nonglobal
271Specific actions within a package can be tagged as applying to only
272the global zone or only the non-global zones.
274The hollow_zone_pkg transform described above is also available to
275simplify a common packaging scenario.
280Package dependencies are automatically calculated during build time
281using pkgdepend(1). After you've done a build, you can verify your
282dependencies in the <package>.res file described above. If the
283file is missing a dependency that you believe could be auto-detected,
284please file a bug against pkgdepend(1).
286Dependencies can be added manually using the "depend" action. Please
287add a comment describing why the dependency is required.
289Moving Content Between Packages and Removing Content
292pkg(7) tracks when content is removed from packages, and automatically
295If you need to move content between packages, there are two primary
296things 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
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.
308Renaming a Package
311To rename a package, leave the old package manifest in place, but
312empty 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.
329If there were "preserve" files in the package you're renaming, make
330sure to create original_name settings in the new package.
332If there was a org.opensolaris.noincorp property in the package being
333renamed, make sure you keep it in both the original and the renamed
336EOFs and Removals
339To remove files, directories, drivers, or anything else within a package,
340simply stop delivering them in the package. IPS will manage the removal
341of no longer delivered content.
343Package removals have impact on the rest of the system. Before marking
344a package as obsolete, search in the OpenSolaris development
345repository (http://pkg.opensolaris.org/dev or http://ipkg.sfbay/dev)
346to find out if any other packages depend on the software you intend
347to EOF. If any packages do, you need to coordinate with those
350The "slim_install" package may depend on ON packages. If it does,
351you must send a FLAG DAY message for ON users and PIT who test
352install. You must also file an installation bug to get that package
353updated in the same build or earlier than you intend to integrate.
354You should also test install yourself. You can do this by replacing
355the "slim_install" in your Distro Constructor manifest with the
356explicit list of packages to install.
358To remove a package, you must mark it as obsolete. You must *also* mark
359as obsolete any packages which are renamed ancestors of this package, and
360remove their rename dependencies. Here is what you must do.
362To find rename ancestors, select all of the manifests which are renames,
363then look for the one which was renamed to the package you care about.
364For 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 *.p5m` /dev/null
371Make sure to check that the package has not undergone multiple renames!
373 $ mypkgname=SUNWzone
374 $ grep -l "fmri=pkg:/$mypkgname@" `grep -l pkg.renamed *.p5m` /dev/null
377Once you have the renamed ancestor list, for *each* of the packages (the
378newly obsolete package, and its renamed ancestors), edit the package as
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
398 # Was renamed to <other-pkg-name>, both now obsolete.
400Here is a complete example. SUNWfoobar was a package which was renamed
401to system/foobar in build 140, and then later obsoleted in build 150.
402Note that in all cases the package FMRI is updated to the obsoletion
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)
412 set name=pkg.fmri value=pkg:/firstname.lastname@example.org,5.11-0.150
413 set name=pkg.obsolete value=true
414 set name=variant.arch value=$(ARCH)
416Creating a Package
419The easiest thing is to copy a package similar to the one you're
420trying to create. Note that packages are no longer split on the
421/usr and / boundary.
423The 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
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.
445 All packages must specify a set of license actions.
447You don't need to set the following. They're taken care of for all OS/Net
448packages in the transforms/common_actions file.
450 set name=variant.opensolaris.zone
451 Every package must specify whether it can be installed in
452 global zones, non-global zones, or both. All ON packages are
453 delivered in both global and non-global zones.
455 set name=org.opensolaris.consolidation value=osnet
456 All packages from OS/Net come from OS/Net...
458Drivers and Packages
461Scripting is no longer required to deal with addition or removal of
462drivers in ON. A "driver" action should be specified for each driver,
463and IPS will handle updates to all the driver files.