pkg/doc/README.src

This hg repository is a child of the ON gate.  In order to build it,
take a clone of it as you would the normal ON gate.  It allows ON
developers to experiment with creating an IPS repository from the ON
source bits.

Questions should be sent to on-ips-dev (a] opensolaris.org.  Users of this
gate are required 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.
Bugs in bugster which are resolved as a side-effect of this putback
are being marked with the "on_ips" keyword.  Feel free to add to them.

Prerequisites

  You must be running at least build 131 of OpenSolaris from
  ipkg.sfbay/dev (SWAN) or pkg.opensolaris.org/dev repository.
  We expect to relax this requirement some for initial putback,
  but that work's not done yet, and Nevada has stopped releasing
  new bits, so you'll have to upgrade your build machines soon
  anyways.  It's a good time to install OpenSolaris on your build
  machines.

Building

   1. hg clone ssh://anon (a] hg.opensolaris.org/hg/pkg/on_ips
   1'. If you're running closed builds, you need the closed bits as well.
       If you're external to SWAN, this isn't available nor necessary,
       and you should keep running the open build.

       hg clone ssh://mrliberal.central//export/gates/on-ips-closed

   2. Do a normal ON build, including the -t and -p options, using
      the nightly script in the gate you pulled above.  (If you haven't
      done so before, use 'ws' or your normal 'bldenv',
      cd usr/src/tools/scripts; make.  That will build nightly for
      your use.)

   3. Your repos should now be in
      $CODEMGR_WS/packages/$MACH/nightly[-nd]/repo.(extra|redist)

      repo.redist contains the bulk of ON, and is what is delivered
      to the main OpenSolaris 'dev' and 'release' repositories.

      repo.extra will only be built for Closed builds, and contains
      non-redistributable (without a proper legal agreement) pieces
      which may or may not be suitable for inclusion in the
      pkg.sun.com/opensolaris/extra repository, including the
      SUNWcryptoint bits necessary for working crypto in a Closed
      build.  Do not distribute any of the bits in repo.extra
      without prior agreement from the appropriate lawyers.

Testing

   0. Make sure your test system is running latest OpenSolaris bits
      from ipkg.sfbay/dev (SWAN) or pkg.opensolaris.org/dev.

   1. On your test system, you can use the "onu" script from
      usr/src/tools/scripts/onu.  (This script will be available
      in the normal SUNWonbld locations after putback.)

      onu -t mybits-1 -d <nfs path to repo directory>

      If you're building Open bits only, add the -O flag to the above.

   1'. Or, if you plan to upgrade lots of test systems to these bits,
      or if there's a relatively slow pipe between the two machines,
      setup a repository server manually.

      a. On your build server,

         $ cd $CODEMGR_WS/packages/$MACH/nightly[-nd]
         $ /usr/lib/pkg.depotd -d repo.redist -p 13000 &
         (or another unused port)

         And if you're not building Open bits, you'll need SUNWcryptoint,
         which isn't available in redist.
         $ /usr/lib/pkg.depotd -d repo.extra -p 13001 &
         (or another unused port)

      b. On your test system,

       # pkg set-publisher -P -O http://<your server host>:13000 on-nightly
       # pkg set-publisher --non-sticky opensolaris.org
       # pkg uninstall entire

       (And again, only if you're building non-Open bits:
       # pkg set-publisher -O http://<your server host>:13001 on-extra
       )

       # pkg image-update
       # reboot

   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.

   If you've been upgrading from pre-January on-nightly repositories,
   please look at README.repo in this directory for some important,
   though easy to resolve gotchas.

Making Packaging Changes

  You'll need to make corresponding packaging changes to the IPS
  manifests.  Here's how.  In all cases, the ".mf" manifest files live
  in usr/src/pkg/manifests.

  For modifications to existing prototype_* files:
	* Add appropriate actions to the .mf 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 existing
	  action.

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

  For new packages:
	* Create a new .mf file, using another package as a template.
	  The metadata mostly comes from pkginfo.tmpl.
	* 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.

  For deleted packages:
	* Edit the manifest; grep for "pkg.obsolete" for an example.

  For renamed packages:
	* Edit the manifest; grep for "pkg.renamed" for an example.

  Remember, you can check your work with "make check" in usr/src/pkg.

Incremental Builds

   If you want to process a subset of manifests, simply set PKGS on the
   make command line and specify the "all" target.  If you want to process
   them all, simply specify the "all" target.

   	% dmake -e PKGS="BRCMbnx BRCMbnxe" all
	% dmake -e all

   If you want to publish a subset of packages, simply set PKGS on the
   make command line and specify the "install" target.  If you want to
   publish them all, simply specify the "install" target.

   	% dmake -e PKGS="BRCMbnx BRCMbnxe" install
	% dmake -e install

   You can also use package names, or package names with ".pub"
   extensions, as build targets.  This will cause processing or
   publication of the specified package(s).  This differs from using
   the "all" or "install" targets and overriding PKGS in that it will
   not clear out the target repositories, and it will not build
   synthetic packages or package lists.

   The on-disk repository will be initialized when it does not exist,
   or when you use the "install" target.  If you publish individual
   packages, they will simply be added to the existing repository.

   To do cross-platform packaging, prefix your target with (for
   example) "sparc/", as in "dmake sparc/install"  Note that we
   currently pull some license files directly from a built source
   tree, so if you do this in a workspace that had proto area copied
   in via nightly -U, then you'll need to set $SRC to point to the
   workspace that was actually built.