Provide support for vendored native code workflow.

This commit introduces generated overlay filesystem support for
${PATH}, ${LD_LIBRARY_PATH}, and ${PKG_CONFIG_PATH} as well as
includes a working example of how to take advantage of this support
when integrating with vendored code.

ChangeLog

@@ -12,7 +12,7 @@ Version: 0.0.8
 State: Stable
 
 CHANGES:
-  * Complete overhaul of the package system. Now uses 
+  * Complete overhaul of the package system. Now uses
     http://github.com/moovweb/gpkg
 
 Version: 0.0.7
@@ -66,7 +66,7 @@ Version: 0.0.3
 State: Beta
 
 CHANGES:
-  * Go versions are now identified by the full tag name. Fuzzy matches of Go 
+  * Go versions are now identified by the full tag name. Fuzzy matches of Go
     versions still works (ex. "60.3").
   * Fixed bug with ~/.gvm/gos folder not being created by Mercurial
   * Fixed error message in `gvm list` when no Go versions are installed

LICENSE

@@ -1,19 +1,19 @@
 Copyright (C) 2012 Moov Corp.
 
-Permission is hereby granted, free of charge, to any person obtaining 
-a copy of this software and associated documentation files (the "Software"), 
-to deal in the Software without restriction, including without limitation 
-the rights to use, copy, modify, merge, publish, distribute, sublicense, 
-and/or sell copies of the Software, and to permit persons to whom the 
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
 Software is furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included 
+The above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 
-OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
-THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.

Makefile.am

@@ -8,6 +8,6 @@ install-exec-hook:
 	(mkdir -p $(install_dir) ;	 \
 	cp -rf . $(install_dir))
 
-#install-data-hook: 
+#install-data-hook:
 #        (mkdir -p $(help_dir) ; \
-#        cp -f *_help.txt $(help_dir)) 
+#        cp -f *_help.txt $(help_dir))

README

@@ -55,7 +55,7 @@ If that doesn't work see the troubleshooting steps at the bottom of this page.
 
 Mac OS X Requirements
 ====================
-    Install mercurial from http://mercurial.berkwood.com/
+Install mercurial from http://mercurial.berkwood.com/
 
 Linux Requirements
 ==================
@@ -74,6 +74,53 @@ FreeBSD Requirements
     sudo pkg_add -r git
     sudo pkg_add -r mercurial
 
+Vendoring Native Code and Dependencies
+==================================================
+GVM supports vendoring package set-specific native code and related
+dependencies, which is useful if you need to qualify a new configuration
+or version of one of these dependencies against a last-known-good version
+in an isolated manner.  Such behavior is critical to maintaining good release
+engineering and production environment hygiene.
+
+As a convenience matter, GVM will furnish the following environment variables to
+aid in this manner if you want to decouple your work from what the operating
+system provides:
+
+1. ``${GVM_OVERLAY_PREFIX}`` functions in a manner akin to a root directory
+  hierarchy suitable for auto{conf,make,tools} where it could be passed in
+  to ``./configure --prefix=${GVM_OVERLAY_PREFIX}`` and not conflict with any
+  existing operating system artifacts and hermetically be used by your
+  workspace.  This is suitable to use with ``C{PP,XX}FLAGS and LDFLAGS``, but you will have
+  to manage these yourself, since each tool that uses them is different.
+
+2. ``${PATH}`` includes ``${GVM_OVERLAY_PREFIX}/bin`` so that any tools you
+  manually install will reside there, available for you.
+
+3. ``${LD_LIBRARY_PATH}`` includes ``${GVM_OVERLAY_PREFIX}/lib`` so that any
+  runtime library searching can be fulfilled there on FreeBSD and Linux.
+
+4. ``${DYLD_LIBRARY_PATH}`` includes ``${GVM_OVERLAY_PREFIX}/lib`` so that any
+  runtime library searching can be fulfilled there on Mac OS X.
+
+5. ``${PKG_CONFIG_PATH}`` includes ``${GVM_OVERLAY_PREFIX}/lib/pkgconfig`` so
+  that ``pkg-config`` can automatically resolve any vendored dependencies.
+
+Recipe for success:
+
+    gvm use go1.1
+    gvm pkgset use current-known-good
+    # Let's assume that this includes some C headers and native libraries, which
+    # Go's CGO facility wraps for us.  Let's assume that these native
+    # dependencies are at version V.
+    gvm pkgset create trial-next-version
+    # Let's assume that V+1 has come along and you want to safely trial it in
+    # your workspace.
+    gvm pkgset use trial-next-version
+    # Do your work here replicating current-known-good from above, but install
+    # V+1 into ${GVM_OVERLAY_PREFIX}.
+
+See examples/native for a working example.
+
 Troubleshooting
 ===============
 Sometimes especially during upgrades the state of gvm's files can get mixed up. This is mostly true for upgrade from older version than 0.0.8. Changes are slowing down and a LTR is imminent. But for now `rm -rf ~/.gvm` will always remove gvm. Stay tuned!

README.md

@@ -53,7 +53,7 @@ To completely remove gvm and all installed Go versions and packages:
 
 Mac OS X Requirements
 ====================
-    Install mercurial from http://mercurial.berkwood.com/
+Install mercurial from http://mercurial.berkwood.com/
 
 Linux Requirements
 ==================
@@ -72,3 +72,53 @@ FreeBSD Requirements
     sudo pkg_add -r git
     sudo pkg_add -r mercurial
 
+Vendoring Native Code and Dependencies
+==================================================
+GVM supports vendoring package set-specific native code and related
+dependencies, which is useful if you need to qualify a new configuration
+or version of one of these dependencies against a last-known-good version
+in an isolated manner.  Such behavior is critical to maintaining good release
+engineering and production environment hygiene.
+
+As a convenience matter, GVM will furnish the following environment variables to
+aid in this manner if you want to decouple your work from what the operating
+system provides:
+
+1. ``${GVM_OVERLAY_PREFIX}`` functions in a manner akin to a root directory
+  hierarchy suitable for auto{conf,make,tools} where it could be passed in
+  to ``./configure --prefix=${GVM_OVERLAY_PREFIX}`` and not conflict with any
+  existing operating system artifacts and hermetically be used by your
+  workspace.  This is suitable to use with ``C{PP,XX}FLAGS and LDFLAGS``, but you will have
+  to manage these yourself, since each tool that uses them is different.
+
+2. ``${PATH}`` includes ``${GVM_OVERLAY_PREFIX}/bin`` so that any tools you
+  manually install will reside there, available for you.
+
+3. ``${LD_LIBRARY_PATH}`` includes ``${GVM_OVERLAY_PREFIX}/lib`` so that any
+  runtime library searching can be fulfilled there on FreeBSD and Linux.
+
+4. ``${DYLD_LIBRARY_PATH}`` includes ``${GVM_OVERLAY_PREFIX}/lib`` so that any
+  runtime library searching can be fulfilled there on Mac OS X.
+
+5. ``${PKG_CONFIG_PATH}`` includes ``${GVM_OVERLAY_PREFIX}/lib/pkgconfig`` so
+  that ``pkg-config`` can automatically resolve any vendored dependencies.
+
+Recipe for success:
+
+    gvm use go1.1
+    gvm pkgset use current-known-good
+    # Let's assume that this includes some C headers and native libraries, which
+    # Go's CGO facility wraps for us.  Let's assume that these native
+    # dependencies are at version V.
+    gvm pkgset create trial-next-version
+    # Let's assume that V+1 has come along and you want to safely trial it in
+    # your workspace.
+    gvm pkgset use trial-next-version
+    # Do your work here replicating current-known-good from above, but install
+    # V+1 into ${GVM_OVERLAY_PREFIX}.
+
+See examples/native for a working example.
+
+Troubleshooting
+===============
+Sometimes especially during upgrades the state of gvm's files can get mixed up. This is mostly true for upgrade from older version than 0.0.8. Changes are slowing down and a LTR is imminent. But for now `rm -rf ~/.gvm` will always remove gvm. Stay tuned!

VERSION

@@ -1 +1 @@
-1.0.16
+1.0.17