|Work in progress|
This page is a work in progress.
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
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:
- Maintain minimalism and readability. The
Makefileshould 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.
- 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.
COMPONENT_PRE_CONFIGURE_ACTIONshould come before
COMPONENT_BUILD_ENVshould come before the build target is defined.
Makefileshould 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
Makefilerather than in the packaging manifest.
There are a number of conventions that should be respected, partly out of mechanics, partly for readability.
Makefileshould start by providing an illumos CDDL declaration or preserve an OpenSolaris CDDL declaration if the
Makefilewas carried over from
Copyright should be asserted by
illumos-userlandcontributors individually unless they are required to assign copyright to an employer.
- The first line of the
shared-macros.mkusing a relative directory. All subsequent includes should use
- The component metadata for the packaging information and the definition of any additional archives should follow the initial include.
- These should be followed by:
- one of
- and then
- 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
COMPONENT_PRE_CONFIGURE_ACTIONsetting that call
- Any components that provide
configure.intemplates but do not come with pre-generated
configurescripts should call
- Any dependencies that are auto-discovered by a
configurescript should be listed as dependencies for the component or explicitly disabled.
- In order to manage dependencies properly, the final line in the
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.