Subject: Package Paths Proposal
To: None <tech-pkg@netbsd.org>
From: Curt Sampson <cjs@cynic.net>
List: tech-pkg
Date: 12/11/1998 13:42:02
Ok; here's my proposal for how to set up the paths for packages.
The most important thing about it is that it acommodates both the
integrationists (everything in the main tree) and the full separatists
(everythig stays out of the main tree) with a single symlink change,
and it works with binary packages. Keep this in mind when you
propose changes.

Also, I'd prefer constructive criticism; saying `I don't like it;
don't do it' is not helpful because that option doesn't solve the
problem of those who want to see the packages integrated into the
main tree. When you comment, explain what it is you can't do that
you want to if your change is not made. Given that, I'm open to
pretty radical changes to this, if that's necessary. I've only put
in a couple of hours of work on this document, so I'ms sure that
a lot of people can think of a lot of ways to improve it.

cjs
--
Curt Sampson  <cjs@cynic.net>   604 801 5335   De gustibus, aut bene aut nihil.
The most widely ported operating system in the world: http://www.netbsd.org



Principles:

1. /usr is designed to be shared amongst multiple machines of a
single architecture. Therefore, in the default configuration, files
that are not exactly the same for all machines of a single archtecture
should not go here, and files that are written other than at package
installation should not go here.

2. /var and /etc are local to the current machine. As per the
hier(8) manpage, /etc has configuration files and /var has log,
temporary, transient and spool files.

3. For debugging and development purposes, it must be possible to
have the package system install files in a separate area, where
they are not mixed in with the standard system binaries.

Locations:

1. The package tools will install things in /pkg. This will normally
be a symlink to /, causing the package stuff to be intermixed with
the operating system files themselves. This has several advantages:

    a) Paths don't have to be changed; users just use their usual
    paths to find the installed packages. (In my personal experience,
    this would make it easier to convert Linux users.)

    b) New package binaries (such as sendmail or named) replace
    the current system binaries, thus avoiding the problems caused
    when two different versions of a program are installed in
    different places on the same system. 

    c) Package binaries that replace the current system binaries
    will still start as normal from /etc/rc.conf, etc.

    d) System binaries, package binaries and locally compiled
    binaries all use the same configuration files, thus getting
    rid of some config file versioning problems, and making upgrades
    easier.

(This fixes the nasty case that I've had the most trouble with:
when an admin installs a new daemon, starts it, but doesn't remove
the old one or update /etc/rc.local. This makes the daemon
mysteriously switch back to the old version--possibly with old
configuration files!--on the next reboot, which is usually months
down the road after everyone's forgotten what has been done.)

However, should the owner of the system want the packages to be
separated (for development purposes, or on a separate disk for
space reasons, or whatever) /pkg may be redirected elsewhere.

NetBSD, by default, will be distributed with /pkg symlinked to /.
(This is a statement I'll back down on if there's an uproar about
it, but I think that /pkg -> / is the best option for new an naive
users, who are the least likely to know to change it.)

2. Files will be installed under /pkg in usr/bin, usr/sbin, usr/lib,
usr/libexec, usr/libdata, usr/share, as per hier(8).

3. Configuration files: Programs use configuration files from
/pkg/etc as the compiled-in default. Generally, subdirectories
(/pkg/etc/<pkgname>) should be created for packages that have more
than one or two config files. Sample configuration files should be
placed in /pkg/usr/share/examples/<pkgname>. The general algorithm
for installation is:

    a) See if example config files exist. If they do, rename them
    with a .old extension. (This facilitates a later diff(1) or
    merge(1) to see and deal with configuration options that are
    new or changed when a package is upgraded.)

    b) Install sample config files in usr/share/examples/<pkgname>.

    c) See if `real' configuration files exist in etc. If not,
    copy the sample config set over to etc.

    d) As an alternative to c), if the configuration files are
    the sort that are unlikely to be changed from system to system
    (examples, anyone?), a symlink to the example file could be
    put in etc. If the local user needs to edit it, the symlink
    can be removed, the file copied over, and it can be edited.
    This does pose the danger that the naive user just edits the
    file directly, without realising that it's a symlink.

Note that things that are currently in /usr/pkg/etc but that should
be shared (such as application startup scripts) no longer go in
etc. See below.

4. /pkg/var: as per hier(8). var/run for files rebuilt after each
reboot, var/db for automatically-generated system-specific files,
var/games for high scores and whatnot, etc.

If any of the files in var must pre-exist, copies that can be copied
to var should be put in usr/share/examples/<pkgname>/var (?elsewhere?)
so that given a shared /usr arrangement, a sysadmin can run the
package on machines other than the one the pkg_add was done on.

(Maybe we need an optional per-package setup script under usr/share
for this sort of thing?)

5. /pkg/usr/X11R6: if the user elects to symlink /pkg to some place
other than root, there should be a strong suggestion that he symlink
/pkg/usr/X11R6 to /usr/X11R6, due to the problems that crop up when
you try to put X11 elsewhere. (Unless, of course, you're doing
PLIST development or some such, in which case you probably don't
want to be dumping crud in your /usr/X11R6.)

6. Startup scripts: daemons that start at boot time should have a
start/stop script available. This should be placed in
/pkg/usr/share/rc.d/<pkgname>. It should accept the following
arguments:

    start:	start the daemon
    stop:	stop the daemon
    reload:	reload configuration files

The `stop' item is so that the script can clean up things that the
daemon doesn't (such as /var/run/xntpd.pid, for xntpd) and the
reload is so that the script can do whatever is appropriate to make
the server reread its config files (send a sighup, stop and start
for dhcpd, mysqladmin reload for MySQL, etc.)

These should return a status code, but should not produce output
except in the case of an error. These scripts are likely to be
called from another program, though they may also be run directly
by the user.

7. Package metadata: the files describing a package install (PLIST,
etc.) go in /pkg/usr/pkgdb. That way if a package is installed on
a one system sharing /usr with others, it `appears' on the other
systems (minus config files and var files).


Notes:

1. Notice that, unlike the current situation, things are set up
for shared systems by default, and it is a single step to turn that
off. (Right now it's several steps to put in symlinks to turn on
sharing.) Keep this in mind when suggesting changes.

2. We need to document the various levels of sharing that people
might want to use, and how to set them up. The ones I see right
off are:

    a) Everything shared, fully integrated: /pkg -> /

    b) Nothing shared, completely separate: /pkg -> /usr/pkg,
       seprate filesystem, whatever.

    c) Nothing shared but X11: as b) but with
       /pkg/usr/X11R6 -> /usr/X11R6.

    c) Shared, but packages are seprate: as c) but /pkg/var ->
       /var, /pkg/etc -> /etc.