diff options
Diffstat (limited to 'devdocs/vagrant/plugins%2Fcommands.html')
| -rw-r--r-- | devdocs/vagrant/plugins%2Fcommands.html | 43 |
1 files changed, 43 insertions, 0 deletions
diff --git a/devdocs/vagrant/plugins%2Fcommands.html b/devdocs/vagrant/plugins%2Fcommands.html new file mode 100644 index 00000000..cb46319a --- /dev/null +++ b/devdocs/vagrant/plugins%2Fcommands.html @@ -0,0 +1,43 @@ +<h1 id="plugin-development-commands"> Plugin Development: Commands </h1> <p>This page documents how to add new commands to Vagrant, invocable via <code>vagrant YOUR-COMMAND</code>. 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 commands can be defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">command "foo" do + require_relative "command" + Command +end +</pre></div> +<p>Commands are defined with the <code>command</code> method, which takes as an argument the name of the command, in this case "foo." This means the command will be invocable via <code>vagrant foo</code>. Then the block argument returns a class that implements the <code>Vagrant.plugin(2, "command")</code> interface.</p> <p>You can also define <em>non-primary commands</em>. These commands do not show up in the <code>vagrant -h</code> output. They only show up if the user explicitly does a <code>vagrant list-commands</code> which shows the full listing of available commands. This is useful for highly specific commands or plugins that a beginner to Vagrant would not be using anyways. Vagrant itself uses non-primary commands to expose some internal functions, as well.</p> <p>To define a non-primary command:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">command("foo", primary: false) do + require_relative "command" + Command +end +</pre></div> +<h2 id="implementation"> Implementation </h2> <p>Implementations of commands should subclass <code>Vagrant.plugin(2, :command)</code>, which is a Vagrant method that will return the proper superclass for a version 2 command. The implementation itself is quite simple, since the class needs to only implement a single method: <code>execute</code>. Example:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">class Command < Vagrant.plugin(2, :command) + def execute + puts "Hello!" + 0 + end +end +</pre></div> +<p>The <code>execute</code> method is called when the command is invoked, and it should return the exit status (0 for success, anything else for error).</p> <p>This is a command at its simplest form. Of course, the command superclass gives you access to the Vagrant environment and provides some helpers to do common tasks such as command line parsing.</p> <h2 id="parsing-command-line-options"> Parsing Command-Line Options </h2> <p>The <code>parse_options</code> method is available which will parse the command line for you. It takes an <a href="http://ruby-doc.org/stdlib-1.9.3/libdoc/optparse/rdoc/OptionParser.html">OptionParser</a> as an argument, and adds some common elements to it such as the <code>--help</code> flag, automatically showing help if requested. View the API docs directly for more information.</p> <p>This is recommended over raw parsing/manipulation of command line flags. The following is an example of parsing command line flags pulled directly from the built-in Vagrant <code>destroy</code> command:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">options = {} +options[:force] = false + +opts = OptionParser.new do |o| + o.banner = "Usage: vagrant destroy [vm-name]" + o.separator "" + + o.on("-f", "--force", "Destroy without confirmation.") do |f| + options[:force] = f + end +end + +# Parse the options +argv = parse_options(opts) +</pre></div> +<h2 id="using-vagrant-machines"> Using Vagrant Machines </h2> <p>The <code>with_target_vms</code> method is a helper that helps you interact with the machines that Vagrant manages in a standard Vagrant way. This method automatically does the right thing in the case of multi-machine environments, handling target machines on the command line (<code>vagrant foo my-vm</code>), etc. If you need to do any manipulation of a Vagrant machine, including SSH access, this helper should be used.</p> <p>An example of using the helper, again pulled directly from the built-in <code>destroy</code> command:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">with_target_vms(argv, reverse: true) do |machine| + machine.action(:destroy) +end +</pre></div> +<p>In this case, it asks for the machines in reverse order and calls the destroy action on each of them. If a user says <code>vagrant destroy foo</code>, then the helper automatically only yields the <code>foo</code> machine. If no parameter is given and it is a multi-machine environment, every machine in the environment is yielded, and so on. It just does the right thing.</p> <h2 id="using-the-raw-vagrant-environment"> Using the Raw Vagrant Environment </h2> <p>The raw loaded <code>Vagrant::Environment</code> object is available with the '@env' instance variable.</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/commands.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/commands.html</a> + </p> +</div> |