Explain staging

[Matthew Seaman]

On 03/10/2013 08:56, Anton Shterenlikht wrote:
> sorry, I still don't get it.
> What is achived by staging?

There are 4 main advantages:

   1) You can build a port and then create a package from the stage
      directory without having to install it on your build system.  You
      usually don't need root privileges to do this.

This actually makes it a lot easier to eg. build ports away from your
frontline servers and then quickly install them from packages, thus
minimizing disruption to live services.

   2) Instead of (typically) just running the install target of the
      piece of software, and then trusting that the pkg-plist contains
      an accurate list of what gets installed, now we take the pkg-plist
      and extract the matching items from the stage directory to make a
      package.  Only things on the plist get installed, and things on
      the plist but not present in the staging dir will flag up as an
      error in the port.

ie. leftovers or other unrecorded files cluttering up your system are
now a thing of the past.  Because there's only one port installed into
the staging dir, there's no ambiguity about which file belongs to which
package.

This also enables the potential for a future enhancement: creating
several different packages from one stage directory.  In the simplest
case, this would mean being able to create a separate package for the
docs or examples, so you could avoid having to install that stuff if
using binary packages.  Beyond that, there could be separate packages
for eg. the shared libraries from a package. So, for something like
mysql-client: at the moment, mysql-client packages for different
versions of mysql conflict.  Having separate mysql-shlibs packages for
different versions of mysql should not suffer from such conflicts.

   3) Because there's just the result of building one port in the
      staging directory, it makes it much easier to run various
      heuristics and quality assurance tests against the build results
      without getting mixed up with files from other packages.

There are a lot of fairly dodgy ports in the tree which have bit-rotted
over time or suffered from lack of active maintainership.  There are a
pretty large number that haven't adopted what is considered the best
current practice for such things as eg. USES flags.

   4) Instead of having to have duplicate methods of doing post install
      actions -- eg. displaying a pkg-message -- between installing
      from a port vs. installing from a package, now you only need to
      write the actions for installing via a package.  This simplifies
      many port makefiles considerably.

Getting rid of this duplication of effort is going to improve port
quality a great deal.  Previously it was the case that code for doing
post-install actions when installing from a package was not tested
really at all.  Much of that code has been broken in the ports for quite
some time.

There are numerous other advantages that should accrue evenually.  For
instance, converting many port options into separate sub packages.  But
that's all in the future.

> I don't understand what you mean.
> Do you mean that an unprivileged user can
> somehow install software from ports not under
> /usr/local?

No.  It means you can create a package tarball foobar-9.9.99.txz as a
non-root user.  You cannot then take that package and install it into
${LOCALBASE} without root level privileges.

> I've read your mails and the wiki page,
> but still not sure what, if anything,
> I need/could do with my ports.

Basically:

If you have an instruction in you port to install a file from the build
area into the filesystem under ${PREFIX} = /usr/local then you need to
change it to install to ${STAGEDIR}${PREFIX}/whatever.  Note: this only
applies to the *install* parts: when building the package, you should
configure it for the eventual final install location under /usr/local.

(It's quite a lot like using DESTDIR to install the base system into a
jail.  Once you're in the jail, everything appears in it's proper place,
but from outside that's not the case.)

Where you don't have explicit install lines in you port, instead relying
on an install target from the package itself, usually that will be
handled automatically and you won't need to do anything.

If you have any post-install actions, where those are duplicated by eg.
pkg-install scripts, then you can just delete them from the port's
Makefile.  Otherwise you'll need to convert the post-install actions to
a pkg-install script, or otherwise enable them to happen at package
install time.

> Is the idea that all ports must/should
> support staging?

Yes.

> If a port doesn't support staging,
> will it fail portlint checks?

There's a 6 month target to convert the entire ports tree to staging.
Any ports not converted to use staging after that will be considered to
be broken.  If no one steps up to fix them, then after a suitable period
of deprecation they may well end up being removed.

No new ports should be added to the tree unless they work with staging.

portlint certainly should complain loudly about lack of staging support.
 I don't know if there are patches available yet.

	Cheers,

	Matthew

-- 
Dr Matthew J Seaman MA, D.Phil.

PGP: http://www.infracaninophile.co.uk/pgpkey
JID: matthew at infracaninophile.co.uk

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 398 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freebsd.org/pipermail/freebsd-ports/attachments/20131003/2d365d1d/attachment.sig>