Style guide

Work in progress This page is a work in progress.

Patches

When supplying patches to software in oi-build, please:

• One "purpose" per patch - try not to do giant megapatches
• Supply a comprehensive comment at the top of each patch explaining why it was necessary to provide a patch

Makefiles

GNU Makefile's syntax can be mind-bending, so the general purpose of this style guide is to provide suggestions for how to make files as readable as possible. There are three basic guidelines:

1. Maintain minimalism and readability. The Makefile should not have redundant settings or rules or preserve commented out lines that are no longer required. They should do the minimum necessary to provide a consistent build and do it in a way that a person can readily understand.
2. Write the file in the order of operations unless there are internal limitations that require variances. Where this is necessary, provide a comment unless the requirement is already established in developer documentation. 
   Thus a COMPONENT_PRE_CONFIGURE_ACTION should come before CONFIGURE_OPTIONS. 
   A COMPONENT_BUILD_ENV should come before the build target is defined.
3. The Makefile should produce a sample manifest that approximates what is actually packaged as closely as possible. It is acceptable for packaging to pull augments out of the component directory, but any other magic should be done using pre- and post-target actions in the Makefile rather than in the packaging manifest.

There are a number of conventions that should be respected, partly out of mechanics, partly for readability.

• The Makefile should start by providing an illumos CDDL declaration or preserve an OpenSolaris CDDL declaration if the Makefile was carried over from userland-gate. 
  Copyright should be asserted by illumos-userland contributors individually unless they are required to assign copyright to an employer.
• The first line of the Makefile should include shared-macros.mk using a relative directory. All subsequent includes should use $(WS_TOP).
• The component metadata for the packaging information and the definition of any additional archives should follow the initial include.
• These should be followed by:
  • prep.mk;
  • one of ant.mk, configure.mk, justmake.mk, makemaker.mk, or setup.py.mk;
  • and then ips.mk.
  The only variable definitions that should be mixed in with these are variables that need to be defined before immediate expansions in the includes (e.g. expansions performed with immediate shell interpolation).
• After this should follow definitions appropriate to the targets. The first variables should be build-time variables used to configure the build.
• Any patches that modify configure.in should have COMPONENT_PRE_CONFIGURE_ACTION setting that call autogen.sh.
• Any components that provide configure.in templates but do not come with pre-generated configure scripts should call autoconf.
• Any dependencies that are auto-discovered by a configure script should be listed as dependencies for the component or explicitly disabled.
• In order to manage dependencies properly, the final line in the Makefile should include depend.mk.

Legacy actions in .p5m files

Packages that have a pre-existing legacy action should have this left intact/unchanged, unless a package is being split up or the version bump is major, and it no longer makes sense to deliver the legacy action.

(The legacy action provides an SVR4 package entry in /var/sadm/pkg, so that the package shows up via pkginfo SUNWfoo - provided for backwards compatibility).

New packages that were not delivered via legacy SVR4 packages in previous versions of Solaris/OpenSolaris do not need a legacy action.