From 82859ee286c1e75c6a0af00d0a259ded315cf2b1 Mon Sep 17 00:00:00 2001 From: Chris Roberts Date: Tue, 22 Nov 2016 16:45:37 -0800 Subject: [PATCH] Update plugin docs. Remove bundler instructions from source install instructions. --- website/source/docs/cli/plugin.html.md | 52 +++++++++++++++++-- .../source/docs/installation/source.html.md | 20 +++---- .../docs/plugins/development-basics.html.md | 6 --- 3 files changed, 53 insertions(+), 25 deletions(-) diff --git a/website/source/docs/cli/plugin.html.md b/website/source/docs/cli/plugin.html.md index 958faca2a..913367af0 100644 --- a/website/source/docs/cli/plugin.html.md +++ b/website/source/docs/cli/plugin.html.md @@ -16,11 +16,36 @@ This is the command used to manage [plugins](/docs/plugins/). The main functionality of this command is exposed via another level of subcommands: -* `install` -* `license` -* `list` -* `uninstall` -* `update` +* [`expunge`](#plugin-expunge) +* [`install`](#plugin-install) +* [`license`](#plugin-license) +* [`list`](#plugin-list) +* [`repair`](#plugin-repair) +* [`uninstall`](#plugin-uninstall) +* [`update`](#plugin-update) + +# Plugin Expunge + +**Command: `vagrant plugin expunge`** + +This removes all user installed plugin information. All plugin gems, their +dependencies, and the `plugins.json` file are removed. This command +provides a simple mechanism to fully remove all user installed custom plugins. + +When upgrading Vagrant it may be required to reinstall plugins due to +an internal incompatibility. The expunge command can help make that process +easier by attempting to automatically reinstall currently configured +plugins: + +```shell +# Delete all plugins and reinstall +$ vagrant plugin expunge --reinstall +``` + +This command accepts optional command-line flags: + +* `--force` - Do not prompt for confirmation prior to removal +* `--reinstall` - Attempt to reinstall plugins after removal # Plugin Install @@ -86,6 +111,16 @@ If a version constraint was specified for a plugin when installing it, the constraint will be listed as well. Other plugin-specific information may be shown, too. +# Plugin Repair + +Vagrant may fail to properly initialize user installed custom plugins. This can +be caused my improper plugin installation/removal, or by manual manipluation of +plugin related files like the `plugins.json` data file. Vagrant can attempt +to automatically repair the problem. + +If automatic repair is not successful, refer to the [expunge](#plugin-expunge) +command + # Plugin Uninstall **Command: `vagrant plugin uninstall [ ...]`** @@ -107,3 +142,10 @@ the plugin using `vagrant plugin install`. If a name is specified, only that single plugin will be updated. If a name is specified of a plugin that is not installed, this command will not install it. + +# Plugin Repair + +**Command: `vagrant plugin update []`** + +This updates the plugins that are installed within Vagrant. If you specified +version constraints when installing the plugin, this command will respect diff --git a/website/source/docs/installation/source.html.md b/website/source/docs/installation/source.html.md index 9065e6498..9c1fd76c9 100644 --- a/website/source/docs/installation/source.html.md +++ b/website/source/docs/installation/source.html.md @@ -15,23 +15,15 @@ when using the official installer is not an option. This page details the steps and prerequisites for installing Vagrant from source. ## Install Ruby -You must have a modern Ruby (>= 2.0) in order to develop and build Vagrant. The +You must have a modern Ruby (>= 2.2) in order to develop and build Vagrant. The specific Ruby version is documented in the Vagrant's `gemspec`. Please refer to the `vagrant.gemspec` in the repository on GitHub, as it will contain the most -up-to-date requirement. This guide will not discuss how to install and manage Ruby. However, beware of the following pitfalls: +up-to-date requirement. This guide will not discuss how to install and manage Ruby. +However, beware of the following pitfalls: - Do **NOT** use the system Ruby - use a Ruby version manager like rvm or chruby -- Ensure you have the latest version of Rubygems -- Ensure you have installed a version of [Bundler](https://bundler.io) that is - compatible with Vagrant. - - The bundler constraint is a floating requirement in Vagrant. You will need to inspect the `vagrant.gemspec` to determine the version when you are compiling from source. For example, if the gemspec specifies version 1.2.3, you will need to install a version of Bundler that satisfies that constraint. - - You can install a specific version of bundler with the following command: - - ```shell - gem install bundler -v '1.2.3' - ``` +- Vagrant plugins are configured based on current environment. If plugins are installed + using Vagrant from source, they will not work from the package based Vagrant installation. ## Clone Vagrant Clone Vagrant's repository from GitHub into the directory where you keep code on your machine: @@ -50,7 +42,7 @@ $ cd /path/to/your/vagrant/clone Run the `bundle` command with a required version* to install the requirements: ```shell -$ bundle _1.10.6_ install +$ bundle install ``` You can now run Vagrant by running `bundle exec vagrant` from inside that diff --git a/website/source/docs/plugins/development-basics.html.md b/website/source/docs/plugins/development-basics.html.md index 84e6313ef..bb47f4b27 100644 --- a/website/source/docs/plugins/development-basics.html.md +++ b/website/source/docs/plugins/development-basics.html.md @@ -65,12 +65,6 @@ load any gems listed in the "plugins" group. Note that this also allows you to add multiple plugins to Vagrant for development, if your plugin works with another plugin. -With this structure in place, your workflow should be like any other -Ruby project, with one exception. Because Vagrant uses the internal -APIs of Bundler, see [Installing Vagrant from Source](https://github.com/mitchellh/vagrant/wiki/Installing-Vagrant-from-Source) -for tips on using the correct version of Bundler to install -dependencies. - When you want to manually test your plugin, use `bundle exec vagrant` in order to run Vagrant with your plugin loaded (as we specified in the Gemfile).