new repository

1 files changed, 23 insertions, 0 deletions

diff --git a/devdocs/vagrant/plugins%2Fguests.html b/devdocs/vagrant/plugins%2Fguests.html
new file mode 100644
index 00000000..2aef797e
--- /dev/null
+++ b/devdocs/vagrant/plugins%2Fguests.html
@@ -0,0 +1,23 @@
+<h1 id="plugin-development-guests">  Plugin Development: Guests </h1> <p>This page documents how to add new guest OS detection to Vagrant, allowing Vagrant to properly configure new operating systems. 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>
+<p>Vagrant has many features that requires doing guest OS-specific actions, such as mounting folders, configuring networks, etc. These tasks vary from operating system to operating system. If you find that one of these does not work for your operating system, then maybe the guest implementation is incomplete or incorrect.</p> <h2 id="definition-component">  Definition Component </h2> <p>Within the context of a plugin definition, new guests can be defined like so:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">guest "ubuntu" do
+  require_relative "guest"
+  Guest
+end
+</pre></div>
+<p>Guests are defined with the <code>guest</code> method. The first argument is the name of the guest. This name is not actually used anywhere, but may in the future, so choose something helpful. Then, the block argument returns a class that implements the <code>Vagrant.plugin(2, :guest)</code> interface.</p> <h2 id="implementation">  Implementation </h2> <p>Implementations of guests subclass <code>Vagrant.plugin("2", "guest")</code>. Within this implementation, only the <code>detect?</code> method needs to be implemented.</p> <p>The <code>detect?</code> method is called by Vagrant at some point after the machine is booted in order to determine what operating system the guest is running. If you detect that it is your operating system, return <code>true</code> from <code>detect?</code>. Otherwise, return <code>false</code>.</p> <p>Communication channels to the machine are guaranteed to be running at this point, so the most common way to detect the operating system is to do some basic testing:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">class MyGuest &lt; Vagrant.plugin("2", "guest")
+  def detect?(machine)
+    machine.communicate.test("cat /etc/myos-release")
+  end
+end
+</pre></div>
+<p>After detecting an OS, that OS is used for various <a href="guest-capabilities">guest capabilities</a> that may be required.</p> <h2 id="guest-inheritance">  Guest Inheritance </h2> <p>Vagrant also supports a form of inheritance for guests, since sometimes operating systems stem from a common root. A good example of this is Linux is the root of Debian, which further is the root of Ubuntu in many cases. Inheritance allows guests to share a lot of common behavior while allowing distro-specific overrides.</p> <p>Inheritance is not done via standard Ruby class inheritance because Vagrant uses a custom <a href="guest-capabilities">capability-based</a> system. Vagrant handles inheritance dispatch for you.</p> <p>To subclass another guest, specify that guest's name as a second parameter in the guest definition:</p> <div class="highlight"><pre class="highlight ruby" data-language="ruby">guest "ubuntu", "debian" do
+  require_relative "guest"
+  Guest
+end
+</pre></div>
+<p>With the above component, the "ubuntu" guest inherits from "debian." When a capability is looked up for "ubuntu", all capabilities from "debian" are also available, and any capabilities in "ubuntu" override parent capabilities.</p> <p>When detecting operating systems with <code>detect?</code>, Vagrant always does a depth-first search by searching the children operating systems before checking their parents. Therefore, it is guaranteed in the above example that the <code>detect?</code> method on "ubuntu" will be called before "debian."</p><div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2010&ndash;2018 Mitchell Hashimoto<br>Licensed under the MPL 2.0 License.<br>
+    <a href="https://www.vagrantup.com/docs/plugins/guests.html" class="_attribution-link">https://www.vagrantup.com/docs/plugins/guests.html</a>
+  </p>
+</div>