From 2cc6f45c3ba4acf007948acd58b9f870fe884904 Mon Sep 17 00:00:00 2001 From: Daniel Pittman Date: Thu, 13 Jan 2011 10:49:06 -0800 Subject: [PATCH] Bug #5284 -- improve module autoloading documentation. Import a relatively clear example from the mailing list, and generally try to improve the module autoloading documentation. That means I restructure the text to put the emphasis on the things we want to happen rather than the things that are undesirable but possible. Those get left for a tiny little tip so they look less important to folks. --- source/guides/modules.markdown | 80 +++++++++++++++++++++++++++------------ 1 files changed, 55 insertions(+), 25 deletions(-) diff --git a/source/guides/modules.markdown b/source/guides/modules.markdown index 1531adf..6590125 100644 --- a/source/guides/modules.markdown +++ b/source/guides/modules.markdown @@ -219,31 +219,61 @@ more-specific files under the module path (see the discussion under [Feature 1012](http://projects.puppetlabs.com/issues/1012) for the history here). -From version Puppet 0.23.1 onwards, everything under the -modulepath is automatically imported into Puppet and is available -to be used. This is called module autoloading. Puppet will attempt to -auto-load classes and definitions from modules, so you don't have to explicitly import -them. You can just include the module class or start using the -definition. Note that the init.pp file will always be loaded first, -so you can put all of your classes and definitions in there if you -prefer. - -With namespaces, some additional magic is also available. Let's say your -autofs module has a class defined in init.pp but you -want an additional class called craziness. If you define that class -as autofs::craziness and store it in file craziness.pp under the -manifests directory, then simply using something like include -autofs::craziness will trigger puppet to search for a class called -craziness in a file named craziness.pp in a module named autofs in -the specified module paths. Hooray! - -If you prefer to keep class autofs in a file named autofs.pp, -create an init.pp file containing simply: - - import "*" - -And you will then be able to reference the class by using include -autofs just as if it were defined in init.pp. +From version Puppet 0.23.1 onwards, everything under the modulepath is +automatically imported into Puppet and is available to be used, through the +magic of "module autoloading". Puppet will attempt to auto-load classes and +definitions from modules, so you don't have to explicitly import them. You can +just include the module class or start using the definition. + +The rules that puppet uses to find the appropriate manifest are pretty easy to +understand, and break down like this: + + include puppet + => modules/puppet/manifests/init.pp + # class puppet { ... + + include puppet::master + => modules/puppet/manifests/master.pp + # class puppet::master { ... + + puppet::params { "example": value => 'meow' } + => modules/puppet/manifests/params.pp + # define puppet::params ($value) { ... + + class { "puppet::master::awesome": } + => modules/puppet/manifests/master/awesome.pp + # class puppet::master::awesome { ... + +So, the break-down is pretty simple: split up your `include` or `define` name +on the `::` marks. The first word is the name of the module - in the examples +above, that is always in the module "puppet". + +If that was the only word (eg: `include puppet`, which doesn't have a `::` in +it) then we look for `manifests/init.pp` in the module directory. + +If you had any words left, though, we transform them into another file in that +directory by treating the last one as the filename and the middle all as +directories. + + For the example puppet::master::awesome ... + + puppet is the *module* name. + master is a *directory* under the module manifests directory. + awesome is the manifest name; we stick '.pp' on the end. + +One big tip: make *sure* that the name of your `class` or `define` matches the +name of the file. If you rename one of them, rename the other one at the same +time and all... + +That makes it pretty easy to locate the file for any definition: if it is +named after the module, look in `init.pp`, otherwise look for the files +matching those rules. + + +Pro tip: we actually always load the `init.pp` manifest, so sometimes you can +cheat and just write your classes in there. It makes it harder for people to +find where your class or define lives, though, so we don't recommend it. + ## Generated Module Documentation -- 1.7.3.5