Cyril Plisko writes:
> On Tue, Jul 22, 2008 at 4:11 PM, James Carlson <[EMAIL PROTECTED]> wrote:
> > Peter Memishian writes:
> >>
> >> > > (The comments field on that CR should mostly be moved to
> >> > > "description," but you'll need meem's and Darren's permission.)
> >> >
> >> > Permission granted for my comments in that CR.
> >>
> >> Likewise.
> >
> > OK; done.
>
> So, in 24 hours we should see it ?
I'm no expert in the way external bug system works, nor do I have
ready access to such an expert right now, but I'd think so. In the
meantime (note that all of this was written years ago; and the
terminology in several areas has changed since then, though the ideas
are still viable):
Private, undocumented interfaces installed by default in Solaris
represent both unnecessary clutter, and an attractive nuisance for the
unwary. With some 14 megabytes in 2054 header files under
/usr/include, there's quite a bit of both in s10.
While undocumented and unsupported access to these interfaces should
be kept available for customers who don't mind living on the bleeding
edge, it should also be hidden by default for users who don't care and
who might be hurt.
Some suggestions on how to begin doing this are below.
*** (#1 of 2): 2004-06-11 01:50:40 EDT [EMAIL PROTECTED]
*** Last Edit: 2008-07-22 09:10:49 EDT [EMAIL PROTECTED]
Hiding Private Parts
INTRODUCTION
This case presents a new policy for the inclusion of header files,
library links, and lint libraries in ON, and eases the transition
for the eventual removal of old, unused interfaces.
In the past, header files and occasionally libraries as well have
been shipped in a somewhat haphazard fashion. Some are clearly
required for standards compliance or are parts of publicly
documented proprietary interfaces. Many, however, represent
internal implementation artifacts and have no supported and
customer-usable content.
Worse still, customers are often generally unaware of our
distinctions among interfaces, and thus use 'grep' as a means to
locate usable symbols in /usr/include or 'nm' in /usr/lib. Because
we expose Project Private details in these files, and these details
can change in patches, unwary customers are at unnecessary risk of
breakage from Solaris patches. In some cases, where structures and
definitions are included and used within an application without
reference to external symbols, appcert(1) doesn't catch the problem.
More significantly, customers who stumble into the private
interfaces are generally unable to use these interfaces properly
without direct access to the system source code.
Besides being unusable, these private definitions represent wasted
disk storage on every Solaris system, as well as unnecessary bloat
in patches.
On the other hand, some customers either enjoy using unstable
interfaces or have business reasons to do so, and are able to accept
the fact that their code will be broken from patch to patch on
Solaris. For these customers, we should continue to deliver
undocumented details (to the extent that legal issues may allow).
DESCRIPTION
This proposal creates a new package cluster, SUNWCprivate, as well
as several packages for that cluster. The new cluster is not
installed by default and must be installed deliberately by the
customer. The case materials (TBD) describe a proposed list of
contents for each of those packages, as well as a set of tools to
keep the gate 'clean.' (That is, to avoid having references from
any normally installed object to anything in SUNWCprivate.)
Two new packages containing header files are created in
SUNWCprivate:
Package name Stability Description
------------ --------- -----------
SUNWheai Unstable internal, non-public interfaces
SUNWlibi Unstable internal library linkage
SUNWlibix Unstable internal library linkage (64 bit)
SUNWheau Obsolete unused interfaces
The SUNWheai package will contain headers for private ON interfaces
in active use. SUNWlibi will contain internal static libraries,
library build links (libfoo.so => libfoo.so.1), and lint libraries
for private ON libraries in active use. SUNWlibix will contain the
64 bit versions of these.
The SUNWheau package will contain ancient headers that are unused in
Solaris and have no known usable implementation, but which are old
enough that it is likely that customers may have included them by
mistake. For example, sys/jioctl.h falls in this category. Not all
unused include files will necessarily be put into this package.
Some private include files that we believe are never used by
customers may be removed instead.
Note that no SUNWlibu is necessary by definition.
The intent is to ship SUNWheau as Obsolete with the next minor
release of Solaris (currently Solaris 10) along with an appropriate
notice, and then remove it from a future minor release. Users are
thus given the benefit of a reduced and more usable /usr/include in
S10, while retaining the ability to install any header files
manually that are needed by deficient applications.
The installation of these packages will print a warning message to
let the user know that he will be getting unstable material that
cannot be relied upon from patch to patch, and that is not
documented for use by customers.
NEW POLICY
Careful consideration should be given for each case, but some
guidelines can be established for inclusion into each one of these
groups based on the stability level of the interface.
Published header files (SUNWhea) and libraries (SUNWlib*):
Standard
Stable (formerly "Public")
Evolving
Unstable *
External +
Contracted External +
Obsolete *
* - warning notes required
+ - appropriate notes encouraged
Not typically published (SUNWheai and SUNWlibi):
Committed Private
Contracted Committed Private
Partner Private
Sun Private
Contracted Sun Private
Contracted Consolidation Private
Contract Private
Contracted Project Private
Consolidation Private
Project Private
Internal
Note that new projects should not add new files to SUNWheau.
Instead, private interfaces in SUNWheai that become unused can be
removed without warning in a patch, and interfaces described via
SUNWhea must go through the normal EOF announcement process.
ISSUES
Many include files have an unfortunate mixture of public and private
interfaces. Such files will be left in SUNWhea, with RFEs filed to
extract the private components.
Note that project teams writing new code are encouraged to write
separate header files for public and non-public portions of their
interfaces.
Some include files are private but are so widely used (e.g.,
sys/vnode.h) that moving them to a separate package would likely
represent an unnecessary risk of breakage in third party
applications. As an aside, the existence of these files likely
indicates that an interface with a public stability level is needed
in some of these cases.
[EMAIL PROTECTED] 2002-06-13
Another angle of this problem that should be considered is whether we
can also ease issues for some of ON's *internal* customers. For instance,
the Solaris Test Collection (/ws/onXX-test) is currently dependent on a
number of unpackaged internal header files, which causes them no end of
grief.
On another note: one concern I have regarding this proposal (as it stands)
is that it couples installation with configuration. I would rather somehow
see these broken into two steps so that administrators don't have to go
digging for packages if it turns out they require some private interface.
Furthermore, having a separate configuration mechanism allows us to
potentially provide fine-grained configuration (e.g., only allowing a
certain set of applications to access private header files).
[EMAIL PROTECTED] 2003-01-21
Since the goal is to reduce the risk that developers discover and use
private interfaces I agree with Meem. This can't be done just at install
time since it is unlikely that the developer and the person doing the
os install are the same person.
It might be possible to use some pragma or other CPP construct in the
header files so that any attempt to compile with them causes a message
to be displayed. Ideally this should be done in such a way as to
ensure that it works regardless of the compiler the developer uses.
Off the top of my head this would probably work:
#ifndef SUNW_ALLOW_PRIVATE_INTERFACES
#error "You have included a header file which contains private interfaces
of Sun Microsystems Inc (or technology it has licensed)."
#endif
The places in the ON (and other Solaris consolidations) where private
interfaces are allowed would define this.
Looking forward we could probably use a technique that would allow us to
"enforce" the different private interfaces and the contracted variants.
*** (#1 of 1): 2004-06-12 03:22:57 EDT [EMAIL PROTECTED]
*** (#2 of 2): 2008-07-22 09:10:49 EDT [EMAIL PROTECTED]
--
James Carlson, Solaris Networking <[EMAIL PROTECTED]>
Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084
MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677
_______________________________________________
opensolaris-code mailing list
opensolaris-code@opensolaris.org
http://mail.opensolaris.org/mailman/listinfo/opensolaris-code
