--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/makefile-targets.txt	Thu Mar 19 20:44:31 2015 -0700
@@ -0,0 +1,105 @@
+
+This is a guide to explain various useful targets in Userland component
+Makefiles.  There is a set of targets that all Makefiles must include, plus
+some addtional targets that are there for convenience.
+
+component-environment-check::
+  This target is an optional target that will be included in most Makefiles
+  automatically.  It is defined in $(WS_MAKE_RULES)/environment.mk which is
+  included by $(WS_MAKE_RULES)/shares-macros.mk.  It reports on some interesting
+  information about the current environment and whether or not it is suitable
+  to build, publish, or test the component.
+
+component-environment-prep::
+  This target is an optional target that will be included in most Makefiles
+  automatically.  It is defined in $(WS_MAKE_RULES)/environment.mk which is
+  included by $(WS_MAKE_RULES)/shares-macros.mk.  It uses the REQUIRE_PACKAGES
+  macro contents to attempt to install any required packages in the current
+  environment.  It should never by used by developers to update any public
+  build machines as those are managed by dedicated staff.
+
+download::
+  This target must be present in all Makefiles.  It can be used at the top level
+  to act across all components, or on an individual component basis.  It is
+  typically defined by including $(WS_MAKE_RULES)/prep.mk in your component
+  Makefile.  This target depends on your component Makefile, so changes to your
+  component Makefile will automatically trigger a re-download and subsequent
+  build steps that depend on it.  You can use the MAKEFILE_PREREQ macro to
+  override this behaviour and avoid rebuilding with each Makefile change.  This
+  macro should only be used in the calling environment via something like:
+    $ gmake MAKEFILE_PREREQ= install
+
+prep::
+  This target must be present in all Makefiles.  It can be used at the top level
+  to act across all components, or on an individual component basis.  It is 
+  typically defined by including $(WS_MAKE_RULES)/prep.mk in your component
+  Makefile.  It depends on the previously described "download" target, as well
+  as internal interum targets to unpack source archives and apply patches to
+  the unpacked source.
+
+configure:
+  This target is an optional target that can be included in component Makefiles
+  to run the community source configuration phase of a component build.  It is
+  typically defined in component Makefiles that make use of the
+  $(WS_MAKE_RULES)/configure.mk Makefile fragment, but could be defined in
+  others that include a source code configuration step.  It is not explicitly
+  called during the build, but provides a convenient means of downloading,
+  unpacking, patching, and "configuring" component source for building without
+  actually compiling the bits.
+
+build::
+  This target must be present in all Makefiles.  It can be used at the top level
+  to act across all components, or on an individual component basis.  It is
+  defined in the individual component Makefiles, but most Makefile fragments
+  under $(WS_MAKE_RULES) include targets that allow the definitions to depend
+  on one of several convenience macros $(BUILD_32), $(BUILD_64),
+  $(BUILD_32_and_64), and $(BUILD_NO_ARCH) to build 32-bit support, 64-bit
+  support, both 32 and 64 bit support, or architecture neutral support.  The
+  macro used will depend on the component.
+
+install::
+  This target must be present in all Makefiles.  It can be used at the top level
+  to act across all components, or on an individual component basis.  It is
+  defined in the individual component Makefiles, but most Makefile fragments
+  under $(WS_MAKE_RULES) include targets that allow the definitions to depend
+  on one of several convenience macros $(INSTALL_32), $(INSTALL_64),
+  $(INSTALL_32_and_64), and $(INSTALL_NO_ARCH) to install 32-bit support, 64-bit
+  support, both 32 and 64 bit support, or architecture neutral support.  The
+  macro used will depend on the component and corresponds to the build target
+  macro used.
+
+pkglint::
+  This target is an optional target is automatically defined in each Makefile
+  by the inclusion of $(WS_MAKE_RULES)/prep.mk.  It will run the build steps
+  necessary to pkglint the manifests for a component.
+
+publish::
+  This target must be present in all Makefiles.  It can be used at the top level
+  to act across all components, or on an individual component basis.  It is
+  often automatically defined by including $(WS_MAKE_RULES)/prep.mk.  It depends
+  on the previously described 'install' target and will perform a series of
+  internal, intermediate steps to use the component package manifests to
+  generate and publish packages for that component.
+
+clean::
+  This target must be present in all Makefiles.  It can be used at the top level
+  to act across all components, or on an individual component basis.  It is
+  often automatically defined by including one of the $(WS_MAKE_RULES)
+  Makefile fragments.  It cleans up any files created by building the component
+  with the exception of any downloaded files.
+
+clobber::
+  This target must be present in all Makefiles.  It can be used at the top level
+  to act across all components, or on an individual component basis.  It is
+  often automatically defined by including one of the $(WS_MAKE_RULES)
+  Makefile fragments.  It depends on the previously described 'clean' target
+  and additionally cleans up any downloaded source archives.
+
+REQUIRED_PACKAGES::
+  This target is present in all component Makefiles.  It is automatically
+  defined by including $(WS_MAKE_RULES)/ips.mk.  It is a convenience that can
+  be used to generate the set of REQUIRED_PACKAGES that is needed by the
+  'pkgdepend resolve' portion of package generation and publication (publish
+  target).  It automatically appends to the component Makefile, but the results
+  should be
+  manually verified.