From 98324a5d35c14f5f5f29a298e6475a77dbf4e46e Mon Sep 17 00:00:00 2001 From: Fabio Rehm Date: Wed, 5 Feb 2014 20:48:28 -0200 Subject: [PATCH] http://tom.preston-werner.com/2010/08/23/readme-driven-development.html --- CHANGELOG.md | 9 ++++ README.md | 8 ++-- docs/index.md | 9 ++-- docs/usage.md | 102 +++++++++++++++++++++++----------------- vagrant-cachier.gemspec | 12 ++++- 5 files changed, 86 insertions(+), 54 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 86e7e64..f88a3a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ BACKWARDS INCOMPATIBILITY: + - Plugin activation is now triggered by the `cache.scope` config and that config + is now required. Previous versions of the plugin had it set to `:box` but + there is no consensus whether `:box` and `:machine` is better. This is to + highlight that you need to think about the caching strategy you are going + to use. For more information and to discuss this move please check [GH-17](https://github.com/fgrehm/vagrant-cachier/issues/17). + - Because `cache.scope` is now a requirement and in order to reduce the amount of + configuration required by the plugin, we enabled automatic bucket detection by + default. To revert to the old behavior you can disable it globally from your + `~/.vagrant.d/Vagrantfile`. - Support for Vagrant < 1.4 is gone, please use a previous plugin version if you are running Vagrant 1.2 / 1.3 - Automatic handling of multiple machine scoped cache dirs from versions diff --git a/README.md b/README.md index fefe1e8..9a205c8 100644 --- a/README.md +++ b/README.md @@ -17,15 +17,13 @@ vagrant plugin install vagrant-cachier ## Quick start -The easiest way to set things up is just to enable [cache buckets auto detection](http://fgrehm.viewdocs.io/vagrant-cachier/usage) -from within your `Vagrantfile`: - ```ruby Vagrant.configure("2") do |config| config.vm.box = 'your-box' if Vagrant.has_plugin?("vagrant-cachier") - # Enable cache buckets auto detection - config.cache.auto_detect = true + # Configure cached packages to be shared between instances of the same base box. + # More info on http://fgrehm.viewdocs.io/vagrant-cachier/usage + config.cache.scope = :box # If you are using VirtualBox, you might want to use that to enable NFS for # shared folders. This is also very useful for vagrant-libvirt if you want diff --git a/docs/index.md b/docs/index.md index 316bae4..c3d0507 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,12 +24,9 @@ from within your `Vagrantfile`: Vagrant.configure("2") do |config| config.vm.box = 'your-box' if Vagrant.has_plugin?("vagrant-cachier") - # Enable cache buckets auto detection - config.cache.auto_detect = true - - # You can pass in extra mount options for your cache buckets - # from http://docs.vagrantup.com/v2/synced-folders/basic_usage.html - config.cache.synced_folder_opts = { create: true } + # Configure cached packages to be shared between instances of the same base box. + # More info on the "Usage" link above + config.cache.scope = :box # If you are using VirtualBox, you might want to use that to enable NFS for # shared folders. This is also very useful for vagrant-libvirt if you want diff --git a/docs/usage.md b/docs/usage.md index 93e9a0b..e3d71dd 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,24 +1,76 @@ # Usage -## Auto detect supported cache buckets +## Being nice to others -This is the easiest way to get started with plugin. By adding the code below to -your `Vagrantfile` you can enable automatic detection of supported cache _buckets_. It is a good practice to wrap plugin specific configuration with `has_plugin?` checks -so the user's Vagrantfiles do not break if vagrant-cachier is uninstalled or -the Vagrantfile is shared with people that don't have the plugin installed. +so the user's Vagrantfiles do not break if `vagrant-cachier` is uninstalled or +the Vagrantfile is shared with people that don't have the plugin installed: ```ruby Vagrant.configure("2") do |config| # ... if Vagrant.has_plugin?("vagrant-cachier") - config.cache.auto_detect = true + # ... vagrant-cachier configs ... end end ``` -This will make `vagrant-cachier` do its best to find out what is supported on the -guest machine and will set buckets accordingly. +## Cache scope + +This is the only required configuration for the plugin to work and should be present +on your project's specific `Vagrantfile` or on your `~/.vagrant.d/Vagrantfile` in +order to enable it. + +### `:box` scope + +By setting `cache.scope` to `:box`, downloaded packages will get stored on a folder +scoped to base boxes under your `~/.vagrant.d/cache`. The idea is to leverage the +cache by allowing downloaded packages to be reused across projects. So, if your +`Vagrantfile` has something like: + +```ruby +Vagrant.configure("2") do |config| + config.vm.box = 'some-box' + if Vagrant.has_plugin?("vagrant-cachier") + config.cache.scope = :box + end +end +``` + +The cached files will be stored under `$HOME/.vagrant.d/cache/some-box`. + +### `:machine` scope + +If you are on a [multi VM environment](http://docs.vagrantup.com/v2/multi-machine/index.html), +there is a huge chance that you'll end up having issues by sharing the same bucket +across different machines. For example, if you `apt-get install` from two machines +at "almost the same time" you are probably going to hit a _"SystemError: Failed to +lock /var/cache/apt/archives/lock"_. To work around that, you can set the scope +to be based on machines: + +```ruby +Vagrant.configure("2") do |config| + config.vm.box = 'some-box' + if Vagrant.has_plugin?("vagrant-cachier") + config.cache.scope = :machine + end +end +``` + +This will tell vagrant-cachier to download packages to `.vagrant/machines//cache` +on your current project directory. + +## Cache buckets automatic detection + +This is the easiest way to get started with plugin and is enabled by default. +Under the hood, `vagrant-cachier` does its best to find out what is supported on the +guest machine and will set buckets accordingly + + +By adding the code below to +your `Vagrantfile` you can enable automatic detection of supported cache _buckets_. + +This will make . ## Enable buckets as needed @@ -57,40 +109,6 @@ end Please referer to http://docs.vagrantup.com/v2/synced-folders/basic_usage.html for more information about the supported parameters. -## Cache scope - -By default downloaded packages will get stored on a folder scoped to base boxes -under your `$HOME/.vagrant.d/cache`. The idea is to leverage the cache by allowing -downloaded packages to be reused across projects. So, if your `Vagrantfile` has -something like: - -```ruby -Vagrant.configure("2") do |config| - config.vm.box = 'some-box' - config.cache.auto_detect = true -end -``` - -The cached files will be stored under `$HOME/.vagrant.d/cache/some-box`. - -If you are on a [multi VM environment](http://docs.vagrantup.com/v2/multi-machine/index.html), -there is a huge chance that you'll end up having issues by sharing the same bucket -across different machines. For example, if you `apt-get install` from two machines -at "almost the same time" you are probably going to hit a _"SystemError: Failed to -lock /var/cache/apt/archives/lock"_. To work around that, you can set the scope -to be based on machines: - -```ruby -Vagrant.configure("2") do |config| - config.vm.box = 'some-box' - config.cache.scope = :machine -end -``` - -This will tell vagrant-cachier to download packages to `.vagrant/machines//cache` -on your current project directory. - - ## Finding out disk space used by buckets At some point we might implement a `vagrant cache stats` command that will give you that diff --git a/vagrant-cachier.gemspec b/vagrant-cachier.gemspec index 1b14ea9..243ce2c 100644 --- a/vagrant-cachier.gemspec +++ b/vagrant-cachier.gemspec @@ -8,7 +8,7 @@ Gem::Specification.new do |spec| spec.version = VagrantPlugins::Cachier::VERSION spec.authors = ["Fabio Rehm"] spec.email = ["fgrehm@gmail.com"] - spec.description = %q{Speed up vagrant boxes provisioning} + spec.description = %q{Caffeine reducer} spec.summary = spec.description spec.homepage = "https://github.com/fgrehm/vagrant-cachier" spec.license = "MIT" @@ -17,4 +17,14 @@ Gem::Specification.new do |spec| spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) } spec.test_files = spec.files.grep(%r{^(test|spec|features)/}) spec.require_paths = ["lib"] + + spec.post_install_message = %q{ + If you are new to vagrant-cachier just follow along with the docs available + at http://fgrehm.viewdocs.io/vagrant-cachier. + + If you are a long time user, please note that plugin has gone through many + backwards incompatible changes since 0.6.0 so checkout + https://github.com/fgrehm/vagrant-cachier/blob/master/CHANGELOG.md + before continuing and caching all the things :) + } end