X-Git-Url: https://git.donarmstrong.com/?p=dsa-puppet.git;a=blobdiff_plain;f=3rdparty%2Fmodules%2Fstdlib%2FREADME_DEVELOPER.markdown;fp=3rdparty%2Fmodules%2Fstdlib%2FREADME_DEVELOPER.markdown;h=04349ed79b41504d8ae80e94876d7537f8729549;hp=0000000000000000000000000000000000000000;hb=ad88f67c13ae0f1a08936dad643f1e3509ab5f40;hpb=23d29143ac40015ce61cf83a4067466f8f7d66dc

diff --git a/3rdparty/modules/stdlib/README_DEVELOPER.markdown b/3rdparty/modules/stdlib/README_DEVELOPER.markdown
new file mode 100644
index 00000000..04349ed7
--- /dev/null
+++ b/3rdparty/modules/stdlib/README_DEVELOPER.markdown
@@ -0,0 +1,35 @@
+Puppet Specific Facts
+=====================
+
+Facter is meant to stand alone and apart from Puppet.  However, Facter often
+runs inside Puppet and all custom facts included in the stdlib module will
+almost always be evaluated in the context of Puppet and Facter working
+together.
+
+Still, we don't want to write custom facts that blow up in the users face if
+Puppet is not loaded in memory.  This is often the case if the user runs
+`facter` without also supplying the `--puppet` flag.
+
+Ah! But Jeff, the custom fact won't be in the `$LOAD_PATH` unless the user
+supplies `--facter`! You might say...
+
+Not (always) true I say!  If the user happens to have a CWD of
+`<modulepath>/stdlib/lib` then the facts will automatically be evaluated and
+blow up.
+
+In any event, it's pretty easy to write a fact that has no value if Puppet is
+not loaded.  Simply do it like this:
+
+    Facter.add(:node_vardir) do
+      setcode do
+        # This will be nil if Puppet is not available.
+        Facter::Util::PuppetSettings.with_puppet do
+          Puppet[:vardir]
+        end
+      end
+    end
+
+The `Facter::Util::PuppetSettings.with_puppet` method accepts a block and
+yields to it only if the Puppet library is loaded.  If the Puppet library is
+not loaded, then the method silently returns `nil` which Facter interprets as
+an undefined fact value.  The net effect is that the fact won't be set.