pkg/doc/README.src

This hg repository is intended to be a sub-repository of the ON gate,
similar to closed.  It allows ON developers to experiment with
creating an IPS repository from their source changes.

Questions should be sent to on-ips-dev (a] opensolaris.org.  Users of this
gate are *strongly* encouraged to sign up for this alias as the code
is experimental and procedures may change rapidly.

Bugs can be filed at defect.opensolaris.org in
  Development / osnet-pkg / build.

Currently, only x86 builds are supported.

1. Prerequisites

  You must be running an OpenSolaris system, preferably of relatively
  recent vintage from the ipkg.sfbay/dev (SWAN) or pkg.opensolaris.org/dev
  repository.

2. Getting Started

   1. hg clone ssh://anon (a] hg.opensolaris.org/hg/pkg/on_ips
      A. This is the onnv open source, plus the pkg bits
      B. If you want closed bits, get 'em from "the normal place"
         (We're not yet maintaining closed project bits, though we
	 will need to do so prior to integration.)
   2. Populate your proto area via one of the following methods
      A. Do a normal ON build, including the -t option
      B. rsync -av elpaso.eng::onnv-proto/root_i386 ${ROOT}/..
         rsync -av elpaso.eng::onnv-gate/usr/src/tools/proto ${SRC}/tools
   3. Use ws or bldenv to setup your build environment.
   4. cd ${SRC)/pkg
   5. dmake all check
      Realy building "check" is optional, but it gets you validate_pkg
      (the new protocmp) output, and you shouldn't skip it.
   6. /usr/lib/pkg.depotd -d `pwd`/manifests/repo.redist -p 13000
      /usr/lib/pkg.depotd -d `pwd`/manifests/repo.extra -p 13001
        (or any other appropriate port)
   7. On your test system,
       # pkg set-publisher -P -O http://<your server host>:13000 on-nightly
       # pkg set-publisher -O http://<your server host>:13001 on-extra
       # pkg image-update

   If you're doing an external (or internal, open-only) build, you should
   omit the second pkg.depotd and set-publisher commands.  If you're
   planning on sharing your repositories outside of Sun, you must
   build open-only and you should never distribute the extra repository
   generated from an internal build, and without it, the redist
   repository from a closed build won't install.

   Or, you can archive (tar, cpio, whatever) the "repo" directories, and
   have people copy your depot to a local machine and start pkg.depotd
   there.  The pkg.depotd can even be running on the system you're
   updating.

   We attempt to update the package definitions in usr/src/pkg/manifests
   daily to match the ON nightly build from that morning.  That means
   that if your workspace is sourced from ON on a different day than
   the usr/src/pkg contents, you may not have properly packaged bits.  You
   can choose to ignore this mismatch if it doesn't effect your work, or
   pull the proper revision of the on_ips gate. When we do putbacks to
   sync-up the IPS manifests with the ON contents, we capture the changeid
   of the putback we synced with so you can match the two by browsing
   on_ips' hg log.

3. How incremental builds work, because it's not necessarily intuitive

   If you want to build a subset of packages, simply specify them on
   the command line.  If you want to build them all, simply specify
   the "all" target.  If you want to build just one of the two
   repositories, specify either "redist" or "extra":

   	% dmake BRCMbnx BRCMbnxe
	% dmake all
	% dmake redist

   No matter which approach you take (subset, all, or repo), each
   package will be published to the on-disk repository iff it meets one
   or both of the following criteria:

     1. The corresponding manifest has changed since it was last
        published.
     2. The on-disk repository is has been created more recently than
        the last publication time for the package.

   Furthermore, the on-disk repository will only be initialized when
   it does not exist.  Which means that you must build the clobber
   target if you don't want to accumulate published packages in your
   repository.

   The build dependencies do NOT extend to the binary objects being
   packaged, but rather to the manifests that describe collections of
   deliverable objects.  If your proto area changes, a pkg build will
   not detect it.  So if you want to republish a set of packages,
   simply remove the <pkg-name>.pub file from usr/src/pkg/manifests.
   If you want to republish all of 'em, then build the clean target.

   So that's the difference between "clean" and "clobber" under the
   usr/src/pkg/manifests directory: both remove the processed
   manifests, thus causing all packages to be republished.  In
   addition, the clobber target causes the repository to be reset, so
   you won't continue to accumulate published versions of the same
   packages.

4. If your ON changes include packaging changes

  A caveat: currently there's no double checking of your work by
  protocmp.  That will be fixed, but for now you'll need to make
  sure you've packaged all your files and haven't missed any
  manually.

  You'll need to make corresponding packaging changes to the IPS
  manifests.  Here's how.

  For modifications to existing prototype_com and prototype_i386 files:
	* Add appropriate actions to the .manifest files.

  For driver modifications to postinstall scripts:
	* Translate the postinstall invocation into an appropriate
	  "driver" action in the proper usr/src/pkg/manifests/*.manifest
	  file.

	* Often, this just requires adding alias= entries to the exiting
	  action.

  For other modifications to postinstall scripts:
	* Generally, they must be ignored for now.

  For new packages:
	* Create a new .manifest file, and modify manifests/Makefile,
	  using another package as a template.  The metadata mostly comes
	  from pkginfo.
	* If at all possible, model your work on a similar, existing
	  package manifest.  Ie a different audio driver, etc.
	* Make sure to consider whether the package should be combined with
	  any others.  The u/r package split is explicitly gone now, so
	  no need to create new packages to contain files in /usr when
	  there's already an appropriate root package.
	* Add your new package to the list in manifests/Makefile.

  For deleted packages:
	* Delete the .manifest file.
	* Remove the package from the list in manifests/Makefile.

  If you're changing any of the files in usr/src/pkg/opensolaris_overrides
  (e.g. rbac files, passwd, shadow, devicedb/master), updates will need
  to be made there, as they are currently expanded clones of the ON
  contents.

5. To upgrade your non-ON software

  Soon the main OpenSolaris development train will release an updated
  build.  At that time, you'll probably have to fallback to the full
  OpenSolaris build you were running before you started upgrading your ON
  bits, then upgrade that.  e.g.

    $ pfexec beadm mount snv_118 /mnt
    $ pfexec pkg set-publisher -P opensolaris.org
    $ pfexec pkg set-publisher -d on
    $ pfexec pkg -R /mnt image-update