Best Practices and Requirements for OpenSolaris development

Best Practices and Requirements

This chapter provides information on standards and procedures which must be followed by all developers. These rules are the same ones which Sun engineers have been required to follow when developing Solaris, and are the primary reason Solaris, and now OpenSolaris, is among the world's best available software. These standards generally apply to all consolidations.

7.1 Compatibility and Visibility Constraints

OpenSolaris has a comprehensive set of rules governing interfaces. An interface is any aspect of the system that a user or developer can observe or use. Examples include functions and variables in libraries, the location of a particular executable program, the output content, format, and argument semantics of an executable program, and the location in the filesystem of a header file. There are thousands of interfaces provided by OpenSolaris, and each of them has certain visibility, documentation, and compatibility constraints.

7.1.1 Interface Stability Taxonomy

One of the attributes included in many Solaris man pages is ``Interface Stability.'' The value of this attribute defines who may depend on the interface, and what expectations they may have for its future maintenance. The possible values and their explanations are described here; note that the Private levels will not appear in man pages shipped to customers.

In the absence of any evidence about an interface's stability level, certain assumptions must be made. Following the general rule ``be strict in what you produce, and liberal in what you accept'' would lead one to conclude that any documented interface is Stable, and undocumented interfaces are probably being used by others, but could be changed at any time without your knowledge (i.e. they are at once both Project Private and Unstable); as a consequence you should neither change the interface nor depend on its current implementation. If you need to depend on or change an undocumented interface whose stability level cannot be determined, you need to find that interface's owner, if any, and have the action approved by the relevant ARC. If the owner of the interface can be found, you will most likely want to promote the interface either to Open (public) status, or use one of the Contracted Private stability levels.

Following is a list of stability levels and their respective meanings. Additional information is available in the

attributes(5)

man page, including the precise public definitions of major, minor, and micro releases and additional information about Open interfaces.

Stability Level: Standard

----------------------------------------------------------------
 Specification          Open
 ----------------------------------------------------------------
 Incompatible Change    major release (X.0)
 ----------------------------------------------------------------
 Compatible Change      minor release (x.Y)
 ----------------------------------------------------------------
 ARC review of Specs    A precise reference is normally recorded
 ----------------------------------------------------------------
 Examples       POSIX, ANSI-C, ABI, SCD, SVID, XPG, X11, DKI, VMEbus,
                Ethernet, NFS protocol, DPS
 ----------------------------------------------------------------

Most of these interfaces are defined by a formal standard, and controlled by a standards organization. Incompatible changes to these interfaces are rare.

This stability classification can also apply to interfaces that have been adopted (without a formal standard) by an ``industry convention'' (X/Open, MIT X-Consortium, OMG), or even by a single-source (Adobe's Display PostScript, Novell's NetWare Protocols, Legato's network backup protocols, Berkeley's sendmail) if we expect that the de facto standard is unlikely to change incompatibly.

If possible, there should still be a reference to a standard specification or reference system, although there may be cases where no such citation is possible. Customers are normally pointed to the same specification.

Support is only provided for specific

version(s)

of a standard, and support for a particular version does not guarantee that support will be provided for other versions. Sometimes bugs are corrected or interpretation is clarified in a standard; we may make incompatible changes to react to these, but will evaluate the impact of doing so and will announce a compatibility and migration strategy. (PSARC/1995/224's Advisory Information section provides guidelines for implementing a preliminary draft of a new standard.)

Some standards lack bindings to a specific programming language; if the project team chose names, numbers, extensions, or other implementation-specific details, they should be called out for architectural review.

Stability Level: Stable

----------------------------------------------------------------
 Specification          Open
 ----------------------------------------------------------------
 Incompatible Change    major release (X.0)
 ----------------------------------------------------------------
 Compatible Change      minor release (x.Y)
 ----------------------------------------------------------------
 ARC review of Specs    Yes
 ----------------------------------------------------------------
 Examples               cc options, Sbus, XGL API; most bundled
                        commands
 ----------------------------------------------------------------

We publish the specification of these interfaces, typically as manual pages or other product documentation. We also tell customers we will remain compatible with them.

The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release), without having to change or recompile the applications. Even at a major release, incompatible changes are expected to be rare, and to have strong justifications. Stable interfaces are sometimes proposed to be industry Standards, as was the case with ToolTalk (now an X/Open standard).

An ARC should review and archive the specification, and adequate customer documentation must also exist.

These are interfaces whose specification is generally controlled within OpenSolaris, and does not rely on externally delivered projects.

Stability Level: Evolving

----------------------------------------------------------------
 Specification          Open
 ----------------------------------------------------------------
 Incompatible Change    minor release (x.Y), with impact
                        assessment
 ----------------------------------------------------------------
 Compatible Change      minor release (x.Y)
 ----------------------------------------------------------------
 ARC review of Specs    Yes
 ----------------------------------------------------------------
 Examples               core and .il file formats, Solaris DDI &
                        DGA; many GUIs, admin utils, config
                        files, daemons; most of PAM
 ----------------------------------------------------------------

An Evolving interface is subject to incompatible change at a major or minor release, but we should expect to change an Evolving interface only carefully, and probably slowly. As the interface evolves, we will make reasonable efforts to ensure that all changes are source and binary compatible.

An ARC should review the interface specification (especially with respect to ability to absorb expected evolution compatibly). Adequate customer documentation should also exist. The intention of an Evolving interface is to enable ISV's to exploit new technology, and it should be expected that they will ship products that depend on these interfaces. As a result, any incompatible change to an Evolving interface requires an assessment of potential customer impact, and a notification and migration plan. Elements of such a plan might include:

* clearly setting customer expectations about the circumstances under which the interfaces might change.

* ensuring that all such changes are described in the release notes for the affected release.

* providing migration aids for binary compatibility and/or continued source development.

A project's intention to accept the risk of depending on an Evolving interface must be evaluated and explicitly approved by an ARC.

NOTE: It will often be the case that interfaces declared to be Evolving will later be reclassified as Stable or Standard. Nonetheless, foreseen promotion is not a necessary attribute of the Evolving taxonomy level. An interface could be classified Evolving and remain as such indefinitely.

Stability Level: Unstable

----------------------------------------------------------------
 Specification          Open
 ----------------------------------------------------------------
 Incompatible Change    minor release (x.Y)
 ----------------------------------------------------------------
 Compatible Change      micro release (x.y.Z)
 ----------------------------------------------------------------
 ARC review of Specs    Yes
 ----------------------------------------------------------------
 Examples               SUNW* package abbreviations,
                        some config utils
 ----------------------------------------------------------------

Unstable interfaces are experimental or transitional. They are typically used to give developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated. No claims are made about either source or binary compatibility from one minor release to the next.

The intention of an Unstable interface is that they be imported only by prototypes and by products on the same CD (or whatever release medium) as the interface implementation. A project's intention to import an Unstable interface should be discussed with the ARC early. The stability classification of the interface -- or a replacement interface -- might be raised. The opinion allowing any project to import an Unstable interface should explain why it is acceptable.

Any documentation for an Unstable interface must contain warnings that these interfaces are subject to change without warning and should not be used in unbundled products. In some situations, it may be appropriate to document Unstable interfaces in White Papers rather than in standard product documentation.

Given such caveats, customer impact need not be a factor when considering incompatible changes to an Unstable interface in a major or minor release. Nonetheless, when such changes are introduced, the changes should still be mentioned in the release notes for the affected release.

An ARC should review and archive the specification. Any proposed change to the interface must be ARC approved.

NOTE: If we choose to offer a draft standard implementation but state our intention to track the standard (or the portions we find technically sound or likely to be standardized), we set customer expectations for incompatible changes by classifying the interface Unstable. The interface should be reclassified Standard when standard is final. Such an intention could be encoded ``Unstable->Standard''.)

Stability Level: External

----------------------------------------------------------------
 Specification          Open
 ----------------------------------------------------------------
 Incompatible Change    micro release (x.y.z)
 ----------------------------------------------------------------
 Compatible Change      micro release (x.y.z)
 ----------------------------------------------------------------
 Arc review of Specs    A precise reference is normally recorded
 ----------------------------------------------------------------
 Examples               OpenSSL
 ----------------------------------------------------------------

These interfaces are controlled by a body outside of OpenSolaris, but unlike Standard, it can not be asserted that an incompatible change to the interface would be exceedingly rare. In some cases it may not even be possible to clearly identify the controlling body. This classification is typically used for third-party open source components integrated wholesale into an OpenSolaris consolidation.

Use of the External interface stability level allows freeware interfaces provided by Sun to quickly track the fluid, external specification. In many cases, this is preferred to providing additional stability to the interface, as it tends to track the expectations of the community. However, External interfaces should adhere to OpenSolaris standards in at least the following areas:

* Security, Authentication * Manual Page Section Numbering * File System Semantics (/usr may be read-only, /var is where all significant run-time growth occurs, ...)

All External interfaces should be labeled as such in all associated documentation and the consequence of using such interfaces should be explained either as part of that documentation or by reference. Default search paths should not lead to External interfaces - the user should be required to take some simple, explicit action to access them.

Shipping incompatible change in a patch should be strongly avoided. It is not strictly prohibited for the following two reasons:

* Since we are not in explicit control of the changes, we can not guarantee with reasonable assurance that an unidentified incompatibility isn't present.

* A strong business case may exist for shipping a newer version as a patch if that newer version closes significant escalations.

In general, the intent of allowing change in a patch is to allow for change in Update Releases.

It should be noted that in some cases it will be preferable to apply a less fluid interface classification to an interface even if the controlling body is external to OpenSolaris. Use of the Unstable classification extends the stability commitment over micro/patch releases, allowing use of additional support models for software that depends upon these interfaces, at the potential cost of less frequent updates. However, care should be exercised because it will be difficult to differentiate External and Unstable as a classification for seemingly identical software. It is suggested to use External and behave (through contracts) as Unstable. Use of the Evolving classification promotes these interfaces to first class OpenSolaris interfaces, at the potential cost of diverging from the external specification. By using Evolving, we are essentially taking control of the interface, although it may liberally import from the external reference. Use of the Stable classification is not recommended.

Stability Level: Contracted External

This stability level is the same as External, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to place restrictions on how and when an interface may change if the normal rules for External do not satisfy the requirements of the consumer.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Stability Level: Obsolete

----------------------------------------------------------------
 Specification          Open, along with warning of obsolescence
 ----------------------------------------------------------------
 Incompatible Change    minor release (x.Y)
 ----------------------------------------------------------------
 Compatible Change      By former classification, but unlikely
 ----------------------------------------------------------------
 ARC review of Specs    Normally downgraded from a higher
                        stability; ARC approval of interface or
                        feature removal is also required.
 ----------------------------------------------------------------
 Examples               RFS, System-V LP protocol
 ----------------------------------------------------------------

An interface that is ``deprecated'' and/or no longer in general use. An existing interface may be downgraded from some other status (such as Stable or Standard) to Obsolete to encourage customers to migrate from that interface before it will be removed (or incompatibly changed).

In addition to reclassifying the interface Obsolete and documenting the new classification in customer documentation, a pro-active program to communicate to customers the change in commitment must precede the incompatible change or removal in a minor release. For some interfaces, the ARC may find such a communication program appropriate before removing an interface, even at a major release.

The standard program to communicate a change in commitment requires:

1. Demonstration of support by the Steering Committee responsible for the

deliverable(s)

containing the interface. Such support can be demonstrated by a change to strategy document or resolutions taken in meetings and documented in the minutes.

2. One year's notice to the customer base and the Sun product development community of the intended obsolescence of the interface. This requirement ensures that no further commitments against the interface are created and gives those affected by future removal of the facility a chance to make alternative arrangements.

The year must elapse after the notice and prior to the delivery of a product that contains a change incompatible with the present status of the interface.

Acceptable means of customer notice includes letters to customers on support contracts, release notes or product documentation, or announcements to customer forums appropriate for the interface in question.

The notice of obsolescence is considered to be ``public'' information in that it is available freely to the customers. It is not intended that this require specific actions to ``publish'' the information, such as press releases or similar forms of publicity.

3. Where technically feasible, inclusion in the release where the interface is declared Obsolete of a warning mechanism if the interface is used. The mechanism should produce a message of the form ``The application uses interface which has been declared obsolete and may not be present in versions of released after [event]. Please notify your support person. See in [reference] for more information.'' One suggested method is to use syslog(3), with a level of ``LOG_WARNING''. A method for turning off the warning message should also be provided. Common sense should apply in determining how often the warning should appear.

4. Information in the User Documentation that contains the following:

* An explanation of the meaning of Obsolete.

* An indication of the kinds of warning messages that may appear.

* A suggesting that the customer ask their support person to contact the vendor of any application that causes such a warning to appear.

* General instructions for turning off the warning messages.

* A list of the Obsolete interfaces contained in this release, the earliest that they may disappear, the kind of warning that might appear, and the method for disabling the warning.

Proposals to downgrade an interface through this mechanism must be approved by an ARC before ``core'' documentation may be altered to identify the interface as Obsolete. Release notes may warn of the possibility of removal with either ARC or Steering Committee approval. A warning that the interface *may* be removed in a future release could be included without ARC approval, but the ARC may not deem such notice alone as sufficient notification to customers to ``start the 1-year clock''.

A follow-on project to perform the actual feature removal in a forthcoming minor or major release after the timeout period expires, requires architectural approval to ensure that the requirements of the obsolescence policy have been met. Provided they have been met, approval will be straightforward.

Stability Level: Committed Private

----------------------------------------------------------------
 Specification          Closed
 ----------------------------------------------------------------
 Incompatible Change    major release (X.0)
 ----------------------------------------------------------------
 Compatible Change      micro release (x.y.Z)
 ----------------------------------------------------------------
 ARC review of Specs    Yes
 ----------------------------------------------------------------
 Example                        UFS media format,
                        Calendar Manager RPC protocol
 ----------------------------------------------------------------

For some otherwise-private interfaces, we must maintain compatibility from release to release, in order to meet the customer's expectations for compatibility of the programs using these interfaces. However, we don't want customers to depend on these interfaces directly, and we don't want to directly expose these interfaces to customers. These interfaces are classified as Committed Private.

Our commitment is that a customer's ``normal'' use of system facilities should not allow them to see any incompatible changes to these interfaces. Since these interfaces typically span machines by being embodied in media or protocols (and since customers cannot upgrade all their machines simultaneously), these interfaces can't be changed with the freedom of a private interface. Yet, changes to the details of the interface can be dramatic, provided the commitment to the customer is maintained. In general, Committed Private interfaces should be versioned.

An ARC should review and archive the specification, and will at least assure that the interface can satisfy its purpose and support the evolution described in the previous paragraph. Any proposed change to or new dependency on the interface must be ARC approved.

Stability Level: Contracted Committed Private

This stability level is the same as Committed Private, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to allow exposure of the interface to a Sun Partner.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Stability Level: Sun Private

----------------------------------------------------------------
 Specification          Closed
 ----------------------------------------------------------------
 Incompatible Change    minor release (x.Y)
 ----------------------------------------------------------------
 Compatible Change      micro release (x.y.Z)
 ----------------------------------------------------------------
 ARC review of Specs    Yes
 ----------------------------------------------------------------
 Example                trap 40 (gethrtime)
 ----------------------------------------------------------------

These are interfaces which one consolidation depends on and another consolidation provides. Changes to these interfaces must be coordinated among all providers and users of the interface. Some internal kernel interfaces are Sun Private interfaces.

Interfaces are occasionally made Sun Private in order to gain some experience with them before opening them up to wider use as Unstable or Stable interfaces. Making such interfaces Consolidation Private would be preferable, however, as evolution is then far easier.

Sun Private interfaces are strongly discouraged. Coordinating changes to these interfaces within a consolidation is usually feasible, but coordinating changes among different consolidations released asynchronously is extremely difficult. Interface versioning is advised for Sun Private interfaces.

An ARC will review and archive these interfaces, with special attention to how the interface could evolve, if necessary. Any proposed change to the interface must be ARC approved.

Stability Level: Contracted Sun Private

This stability level is the same as Sun Private, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to allow exposure of the interface to a partner.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Stability Level: Consolidation Private

----------------------------------------------------------------
 Specification          Closed
 ----------------------------------------------------------------
 Incompatible Change    micro release (x.y.Z) or "jumbo patch"
 ----------------------------------------------------------------
 Compatible Change      micro release (x.y.Z) or "jumbo patch"
 ----------------------------------------------------------------
 ARC review of Specs    Not necessary
 ----------------------------------------------------------------
 Examples               libdeskset, kernel nameslists
 ----------------------------------------------------------------

These are interfaces internal to the consolidation that one piece of a consolidation depends on and another piece of the same consolidation provides. Changes to these interfaces must be coordinated among all providers and users of the interface. Many internal kernel interfaces are Consolidation Private interfaces.

Generally these are interfaces that have proven convenient for building the consolidation, but which change often enough that we're not willing to document them for external use nor to commit to their stability. libdeskset is an example of such an interface. Though the libkvm API is Public, the undocumented names that can be accessed through that interface are Consolidation or Project Private.

An ARC may review and archive these interfaces, or may leave the consolidation to monitor their own internal commitments. If a Consolidation Private interface is reviewed by the ARC, ask that ARC if they want to review later changes to that interface.

Importing the interface by any project outside the Consolidation would require negotiating a ``contract'' with the interface providers. An ARC must review and approve the classification change to Contracted Consolidation Private and the terms of the contract.

Stability Level: Contracted Consolidation Private

This stability level is the same as Consolidation Private, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to allow exposure of the interface to a specific consumer in a different consolidation.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Stability Level: Project Private

----------------------------------------------------------------
 Specification          Closed
 ----------------------------------------------------------------
 Incompatible Change    micro release (x.y.Z)
 ----------------------------------------------------------------
 Compatible Change      micro release (x.y.Z) or patch
 ----------------------------------------------------------------
 ARC review of Specs    No
 ----------------------------------------------------------------
 Examples               Metamucil ioctls, nfssys system call,
                        uadmin cpu control functions
 ----------------------------------------------------------------

Project Private interfaces usually occur when a project must communicate between its components across a boundary in the system. For instance, Metamucil includes several new ioctls to perform operations on UFS filesystems. The Metamucil ufsdump program uses these ioctls. The ioctls are private interfaces since they are intended to be used only by the Metamucil product. If the Metamucil product needs to change these ioctls in the future, they can do so without coordinating with any other projects, since no other projects may use these ioctls. Likewise, the nfssys system call is used to communicate between the kernel- and user-level portions of NFS.

Project Private interfaces also occur in libraries where one module needs to call a private routine in another module in the same library.

Also, Project Private interfaces may be provisional or in transition. The uadmin cpu control functions are Project Private because they will change form before appearing as Standard interfaces, and in the meantime we don't want anyone depending on them.

Sadly, many kernel procedures are Project Private interfaces (instead of Internal interfaces) because they are visible to dynamically loaded kernel modules.

Once an interface is classified Project Private by an ARC, changes to that interface need not be ARC approved.

Any use of the interface from outside the project would involve negotiating a ``contract'' with the interface providers; an ARC must review and approve the classification change to Contracted Project Private and the terms of the contract.

Stability Level: Contracted Project Private

This stability level is the same as Project Private, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to allow exposure of the interface to a specific consumer in a different consolidation.

An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

7.1.2 Library Considerations

Libraries delivered by ON contain symbol versioning information that limits the exposure of private interfaces and provides tracking of changes to public interfaces. This versioning information is embodied in the specfiles and mapfiles found under

usr/src/lib/*/spec

.

7.2 Style Guide

Like many engineering efforts, OpenSolaris enforces a coding style on contributed code, regardless of its source. This coding style is very similar to that used by the Linux kernel, BSD systems, and many other non-GNU projects (the GNU project uses its own unique coding style). This style is described in detail at http://opensolaris.org/os/community/onnv/, although some elements in the style guide are rather dated, especially as they relate to K&R C versus ANSI (now ISO) C. You also should examine the files in

usr/src/prototypes

; these provide examples of the correct general layout and style for most types of source files.

7.2.1 Automated Style Tools

Two tools for checking many elements of the coding style are available as part of the ON tools. These tools are

cstyle(1)

for verifying compliance of C code with most style guidelines, and

hdrchk(1)

for checking the style of C and C++ headers. Note that these tools are not perfect; there are style mistakes that cannot be caught by any reasonable tool, and others that cannot be caught by the particular implementations. Improving the accuracy and completeness of these tools is an ongoing task and enhancements of all kinds are welcome.

All headers are expected to pass 'hdrchk'. All C files and headers are expected to pass 'cstyle -P -p'. These tools produce no output and exit with status code 0 if the

file(s)

checked meet the style requirements.

7.2.2 =head3 Style Examples

A few common examples of bad style which are not currently caught by the tools include:

* Mixing declaration of initialized and uninitialized variables on the same line; for example:

int a, b = 16, c = -4, d;

Instead, uninitialized variables may be declared one or more per line, and each initialized variable should be declared on its own line:

int a, d;
        int b = 16;
        int c = -4;

or

int a;
        int b = 16;
        int c = -4;
        int d;

* Inconsistent use of acceptable styles. In the above example, two acceptable ways to declare variables are presented. Good style dictates that whichever is used by used everywhere within a file; however, the tools do not check for such consistency.

* Incorrect placement and use of braces around if/else constructs. The heuristic test for this is not run by default, and is not completely reliable. For simplicity's sake, here is the correct format for if/else in which both alternatives are compound statements:

if (x != SOME_CONSTANT) {
                do_stuff();
                return (x);
        } else {
                do_other_stuff();
                x = OTHER_CONSTANT;
        }

If neither alternative is a compound statement, use:

if (x != SOME_CONSTANT)
                do_stuff();
        else
                do_other_stuff();

Finally, if only one alternative is a compound statement, both alternatives should have braces, formatted as shown:

if (x != SOME_CONSTANT) {
                do_stuff();
                return (x);
        } else {
                do_other_stuff();
        }

Note the placement of braces; they should surround an ``else'' and only the closing brace should be on a line by itself.

* Use of comments associated with conditional compilation directives. It is good style to include trailing comments after #else and #endif directives describing the condition it references; for example:

#ifdef __FOO
        ...
        #else   /* !__FOO */
        ...
        #endif  /* !__FOO */

The style tools do not check for the presence, usefulness, or correctness of these trailing comments, but you should normally include them, especially if the intervening code blocks are lengthy or the tests are part of a complicated set of nested preprocessor conditionals.

* Incorrect guards in header files. Guard names should be derived from the header name, but hdrchk does not check this. For example, a header installed in <sys/scsi/foo_impl.h> should have a guard as follows:

#ifndef _SYS_SCSI_FOO_IMPL_H
        #define _SYS_SCSI_FOO_IMPL_H
        ...
        #endif /* _SYS_SCSI_FOO_IMPL_H */

However, hdrchk verifies neither the actual guard token name nor the comment following #endif.

* Comment style is only partially checked. For example, the correct style for block comments is:

/*
         * Some comment here.
         * More here.
         */

cstyle(1)

can detect some common errors, such as enclosing the entire block comment in a box of asterisks or other characters. However, it cannot detect all such errors; for example:

/*
           Some comment here.
           We conserve asterisks even though it's harder to read.
           Our comment is nonconforming.
         */

Correct indentation of comments is also unchecked; block and single-line comments within functions should be indented at the same level as the code they document. Trailing comments should be aligned with other trailing comments in related code. None of these style guidelines is checked by the tools.

It probably goes without saying that the contents of comments aren't checked in any way. Please, be sure to follow the comment content guidelines in the style guide.

7.2.3 Non-Formatting Considerations

cstyle(1)

and

hdrchk(1)

will, in addition to several code-formatting guidelines, verify compliance with SCCS keyword and copyright requirements. All files must be under SCCS control, and each must have a set of keywords near the top (see the prototypes for the exact order of file contents). In general, the keywords should have the following format in C files and headers:

#pragma ident	"%Z%%M%	%I%	%E% SMI	/* optional comment */

Note that this string actually contains several embedded tabs; showing these tabs as /t, the keywords look like:

#pragma ident/t"%Z%%M%/t%I%/t%E% SMI/t/* optional comment */

Files which are not C (or C++) implementations or headers should dispense with the ``pragma'' portion and just use #ident as follows:

# ident/t"%Z%%M%/t%I%/t%E% SMI/t/* optional comment */

In addition, each file must contain a statement of copyright at the very top. The acceptable text and formats for these copyrights are shown in the example files in usr/src/prototypes. When a source file is significantly updated, the year or range of years in the copyright should be replaced with just the current year at the time of modification. Significant updates do not include formatting changes. However, if you prefer not to think about whether your change constitutes a significant update or if you don't trust your judgment, erring on the side of always updating the year is acceptable. Since the prototypes assume that Sun is always the sole copyright holder, you will need to change the copyright statement slightly; for example, if a file initially contains:

/*
         * Copyright (c) 1992-1998 by Sun Microsystems, Inc.
         * All rights reserved.
         */

you should replace this notice with:

/*
         * Copyright 2005 Sun Microsystems, Inc.
         * All rights reserved.  Use is subject to license terms.
         */

and, if you are a contributor not employed by Sun, you should also add:

/*
         * Copyright 2005 J. Random Hacker
         * All rights reserved.  Use is subject to license terms.
         */

or a similar statement of your copyright. Do not combine copyright notices, and do not remove the existing copyright notices unless specifically instructed to do so.

7.2.4 Integration Requirements

Before submitting any changes for code review prior to inclusion in OpenSolaris, you should self-review your code for stylistic correctness (as well as semantic correctness!). Running the

cstyle(1)

and/or

hdrchk(1)

tools is part of this process, but you should also be familiar with the entire style guide so that you will be able to use correct style even in elements that the tools do not check. All new code must be cstyle- and, if applicable, hdrchk-clean. If you are modifying existing code which does not conform to the style guide, your changes should be conformant, and at worst your changes should not increase the number of cstyle or hdrchk warnings.

7.3 Testing Guidelines

Changes must be adequately tested. Because of the complexity of testing some changes and the lack of test suite availability, sponsors will provide guidance on appropriate testing.

7.4 Using Lint

The entire Solaris kernel and many libraries and commands are completely lint clean, both pass1 and pass2. It is important that we maintain this cleanliness as yet another tool to insure a high quality release. Although not all non-kernel code is lint-clean, new code should be, and all new commands and libraries should be entirely lint-clean. Lint-clean code should indicate to the build system that it should be linted. For an example of code in transition to lint-cleanliness, see usr/src/cmd/cmd-inet/usr.sbin/Makefile and the associated code.

Before checking in your changes use the following steps (on both SPARC and x86!) to check for any new errors:

% cd $SRC/uts
        % ( make && make lint ) > ERRS 2>&1
        % grep "warning:" ERRS

*ANY* warning messages must be fixed!

Note that you can also use

nightly(1)

to generate lint output. If you instruct

nightly(1)

to run lint, which you should always do by adding 'l' to your NIGHTLY_OPTIONS or explicitly using the '-l' command line option, it will produce a listing of any ``lint noise'' as part of its final output if your changes have introduced lint warnings; it should be empty. This can be much easier than looking through a log file as described above, and includes any lint warnings from both kernel and non-kernel code which is intended to be lint-clean.

In the build system, linting is fairly similar to a ``normal'' build, but it has an additional complication. In order to get meaningful output from lint pass2, all the modules must be linted together. This is accomplished by each module being responsible to produce its own pass1 output (file.ln, one per .c/.s file). It is also responsible for placing the lint-library (llib-lMODULE) in the uts/MACHINE/lint-libs directory. The final full lint is accomplished by the makefile in the uts/MACHINE directory by linting all the lint-libraries against each other.

Note that, to keep lint happy about functions defined in assembly only, there are also C prototypes in the .s files. For example:

#if defined(lint)
        int
        blort(int, int)
        { return 0 }
        #else   /* lint */

ENTRY(blort)
                ld      [%i0],....
                ....
                SET_SIZE(blort)

#endif  /* lint */

Here are some additional rules for keeping code lint-clean and avoiding lint problems:

* *NEVER* *EVER* use /* LINTLIBRARY */ in OpenSolaris kernel source!

* Modification of header files, either directly or as a result of a merge, does not always cause the lint libraries to be rebuilt. This may result in seemingly impossible errors of a function having two different declarations. Be sure to run ``make clean.lint'' after any merge or modification of a header file.

* When calling a function with a return value but not using it, place a (void) cast in front. Common functions are sprintf and strcpy. Many times ignoring a function return value can hide error conditions. Functions that always have the values ignored might need to consider having their specification redeclared void, although of course this normally does not apply to public interfaces.

* Format strings for long integers use one of ``%ld'', %lx``, or ''%lu``

* Format strings for unsigned integers use one of ``%u'' or ``%x''

* Format strings for long long integers use ``%lld'' or ``%llx''

* Format strings for pointers should use ``%p'', with the pointer cast to (void *). Using %d or %x and casting to an (int) will break in a 64-bit kernel.

* For code that is supposed to work for either ILP32 or LP64, there are some macros that you can use in the format string, so that you don't need to #ifdef longs versus ints. See <sys/int_fmtio.h>.

* Use full ANSI/ISO prototypes in function declarations, as the kernel is always compiled with __STDC__ defined. New code should not use K&R-style declarations.

* Make sure machine dependent function declarations are consistent across platforms.

* Be sure you are linting against the headers in your proto area and not the installed headers on your build machine.

7.5 Tips and Suggestions

Contribute your feedback and suggestions!