diff options
Diffstat (limited to 'devdocs/vagrant/plugins%2Fconfiguration.html')
| -rw-r--r-- | devdocs/vagrant/plugins%2Fconfiguration.html | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/devdocs/vagrant/plugins%2Fconfiguration.html b/devdocs/vagrant/plugins%2Fconfiguration.html new file mode 100644 index 00000000..b0e751f8 --- /dev/null +++ b/devdocs/vagrant/plugins%2Fconfiguration.html @@ -0,0 +1,85 @@ +<h1 id="plugin-development-configuration"> Plugin Development: Configuration </h1> <p>This page documents how to add new configuration options to Vagrant, settable with <code>config.YOURKEY</code> in Vagrantfiles. Prior to reading this, you should be familiar with the <a href="development-basics">plugin development basics</a>.</p> <blockquote class="alert alert-warning"> <p><strong>Warning: Advanced Topic!</strong> Developing plugins is an advanced topic that only experienced Vagrant users who are reasonably comfortable with Ruby should approach.</p> </blockquote> +<h2 id="definition-component"> Definition Component </h2> <p>Within the context of a plugin definition, new configuration keys can be defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">config "foo" do + require_relative "config" + Config +end +</pre></div> +<p>Configuration keys are defined with the <code>config</code> method, which takes as an argument the name of the configuration variable as the argument. This means that the configuration object will be accessible via <code>config.foo</code> in Vagrantfiles. Then, the block argument returns a class that implements the <code>Vagrant.plugin(2, :config)</code> interface.</p> <h2 id="implementation"> Implementation </h2> <p>Implementations of configuration keys should subclass <code>Vagrant.plugin(2, :config)</code>, which is a Vagrant method that will return the proper subclass for a version 2 configuration section. The implementation is very simple, and acts mostly as a plain Ruby object. Here is an example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">class Config < Vagrant.plugin(2, :config) + attr_accessor :widgets + + def initialize + @widgets = UNSET_VALUE + end + + def finalize! + @widgets = 0 if @widgets == UNSET_VALUE + end +end +</pre></div> +<p>When using this configuration class, it looks like the following:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + # ... + + config.foo.widgets = 12 +end +</pre></div> +<p>Easy. The only odd thing is the <code>UNSET_VALUE</code> bits above. This is actually so that Vagrant can properly automatically merge multiple configurations. Merging is covered in the next section, and <code>UNSET_VALUE</code> will be explained there.</p> <h2 id="merging"> Merging </h2> <p>Vagrant works by loading <a href="../vagrantfile/index#load-order">multiple Vagrantfiles and merging them</a>. This merge logic is built-in to configuration classes. When merging two configuration objects, we will call them "old" and "new", it'll by default take all the instance variables defined on "new" that are not <code>UNSET_VALUE</code> and set them onto the merged result.</p> <p>The reason <code>UNSET_VALUE</code> is used instead of Ruby's <code>nil</code> is because it is possible that you want the default to be some value, and the user actually wants to set the value to <code>nil</code>, and it is impossible for Vagrant to automatically determine whether the user set the instance variable, or if it was defaulted as nil.</p> <p>This merge logic is what you want almost every time. Hence, in the example above, <code>@widgets</code> is set to <code>UNSET_VALUE</code>. If we had two Vagrant configuration objects in the same file, then Vagrant would properly merge the follows. The example below shows this:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">Vagrant.configure("2") do |config| + config.widgets = 1 +end + +Vagrant.configure("2") do |config| + # ... other stuff +end + +Vagrant.configure("2") do |config| + config.widgets = 2 +end +</pre></div> +<p>If this were placed in a Vagrantfile, after merging, the value of widgets would be "2".</p> <p>The <code>finalize!</code> method is called only once ever on the final configuration object in order to set defaults. If <code>finalize!</code> is called, that configuration will never be merged again, it is final. This lets you detect any <code>UNSET_VALUE</code> and set the proper default, as we do in the above example.</p> <p>Of course, sometimes you want custom merge logic. Let us say we wanted our widgets to be additive. We can override the <code>merge</code> method to do this:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">class Config < Vagrant.config("2", :config) + attr_accessor :widgets + + def initialize + @widgets = 0 + end + + def merge(other) + super.tap do |result| + result.widgets = @widgets + other.widgets + end + end +end +</pre></div> +<p>In this case, we did not use <code>UNSET_VALUE</code> for widgets because we did not need that behavior. We default to 0 and always merge by summing the two widgets. Now, if we ran the example above that had the 3 configuration blocks, the final value of widgets would be "3".</p> <h2 id="validation"> Validation </h2> <p>Configuration classes are also responsible for validating their own values. Vagrant will call the <code>validate</code> method to do this. An example validation method is shown below:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">class Config < Vagrant.plugin("2", :config) + # ... + + def validate(machine) + errors = _detected_errors + if @widgets <= 5 + errors << "widgets must be greater than 5" + end + + { "foo" => errors } + end +end +</pre></div> +<p>The validation method is given a <code>machine</code> object, since validation is done for each machine that Vagrant is managing. This allows you to conditionally validate some keys based on the state of the machine and so on.</p> <p>The <code>_detected_errors</code> method returns any errors already detected by Vagrant, such as unknown configuration keys. This returns an array of error messages, so be sure to turn it into the proper Hash object to return later.</p> <p>The return value is a Ruby Hash object, where the key is a section name, and the value is a list of error messages. These will be displayed by Vagrant. The hash must not contain any values if there are no errors.</p> <h2 id="accessing"> Accessing </h2> <p>After all the configuration options are merged and finalized, you will likely want to access the finalized value in your plugin. The initializer function varies with each type of plugin, but <em>most</em> plugins expose an initializer like this:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">def initialize(machine, config) + @machine = machine + @config = config +end +</pre></div> +<p>When authoring a plugin, simply call <code>super</code> in your initialize function to setup these instance variables:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">def initialize(*) + super + + @config.is_now_available + # ...existing code +end + +def my_helper + @config.is_here_too +end +</pre></div> +<p>For examples, take a look at Vagrant's own internal plugins in the <code>plugins</code> folder in Vagrant's source on GitHub.</p><div class="_attribution"> + <p class="_attribution-p"> + © 2010–2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br> + <a href="https://www.vagrantup.com/docs/plugins/configuration.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/configuration.html</a> + </p> +</div> |