bbrowning-virtualbox 0.7.6.dev

data/.gitignore

@@ -0,0 +1,8 @@
+doc/*
+.yardoc/*
+pkg/*
+test/coverage/*
+.bundle/*
+Gemfile.lock
+test.rb
+*.rbc

data/.yardopts

@@ -0,0 +1,3 @@
+-
+docs/GettingStarted.md
+docs/WhatsNew.md

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+gemspec
+
+# Gems required for development only.
+group :development do
+  # Docs
+  gem "yard"
+
+  # Unit tests
+  gem "rcov"
+
+  # Integration tests
+  gem "cucumber", "~> 0.8.0"
+  gem "rspec"
+end

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Mitchell Hashimoto.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,33 @@
+require "rubygems"
+require "bundler/setup"
+require "rake/testtask"
+require "rcov/rcovtask"
+require "cucumber"
+require "cucumber/rake/task"
+require "yard"
+Bundler::GemHelper.install_tasks
+
+task :default => "test:units"
+
+namespace :test do
+  Rake::TestTask.new(:units) do |t|
+    t.libs << "test"
+    t.pattern = 'test/**/*_test.rb'
+  end
+
+  Cucumber::Rake::Task.new(:integration) do |t|
+    t.cucumber_opts = "features --format pretty"
+  end
+
+  Rcov::RcovTask.new do |t|
+    t.libs << "test"
+    t.test_files = FileList["test/**/*_test.rb"]
+    t.output_dir = "test/coverage"
+    t.verbose = true
+  end
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.options = ['--main', 'Readme.md', '--markup', 'markdown']
+  t.options += ['--title', 'VirtualBox Ruby Library Documentation']
+end

data/Readme.md

@@ -0,0 +1,70 @@
+# VirtualBox Ruby Gem
+
+The VirtualBox ruby gem is a library which allows anyone to control VirtualBox
+from ruby code! Create, destroy, start, stop, suspend, and resume virtual machines.
+Also list virtual machines, list hard drives, network devices, etc.
+
+## Installation and Requirements
+
+First you need to install [VirtualBox](http://www.virtualbox.org/) which is available for
+Windows, Linux, and OS X. After installation, install the gem:
+
+    sudo gem install virtualbox
+
+The gem uses the native COM interface with VirtualBox provides to communicate with
+VirtualBox. On Windows, this is globally available. On Linux-based machines, the gem
+uses Ruby-FFI to talk to a dynamic library. No configuration should be necessary.
+
+## Basic Usage
+
+The virtualbox gem is modeled after ActiveRecord. If you've used ActiveRecord, you'll
+feel very comfortable using the virtualbox gem.
+
+There is a [quick getting started guide](http://mitchellh.github.com/virtualbox/file.GettingStarted.html) to
+get you acquainted with the conventions of the virtualbox gem.
+
+Complete documentation can be found at [http://mitchellh.github.com/virtualbox](http://mitchellh.github.com/virtualbox).
+
+Below are some examples:
+
+    require 'virtualbox'
+
+    vm = VirtualBox::VM.find("my-vm")
+
+    # Let's first print out some basic info about the VM
+    puts "Memory: #{vm.memory_size}"
+
+    # Let's modify the memory and name...
+    vm.memory_size = 360
+    vm.name = "my-renamed-vm"
+
+    # Save it!
+    vm.save
+
+## Known Issues or Uncompleted Features
+
+VirtualBox has a _ton_ of features! As such, this gem is still not totally complete.
+You can see the features that are still left to do in the TODO file.
+
+## Reporting Bugs or Feature Requests
+
+Please use the [issue tracker](https://github.com/mitchellh/virtualbox/issues).
+
+## Contributing
+
+If you'd like to contribute to VirtualBox, the first step to developing is to
+clone this repo, get [bundler](http://github.com/carlhuda/bundler) if you
+don't have it already, and do the following:
+
+    bundle install --relock
+    rake
+
+This will run the test suite, which should come back all green! Then you're good to go!
+
+## Special Thanks
+
+These folks went above and beyond with contributions to the virtualbox gem, and
+for that, I have to say "thanks!"
+
+* [Kieran Pilkington](http://github.com/KieranP)
+* [Aleksey Palazhchenko](http://github.com/AlekSi)

data/docs/GettingStarted.md

@@ -0,0 +1,196 @@
+# Getting Started with the VirtualBox Gem
+
+* [Basic Conventions](#basic-conventions)
+    * [Finding Models](#bc-finding-models)
+    * [Accessing Models](#bc-accessing-models)
+    * [Modifying Models](#bc-modifying-models)
+    * [Saving Models](#bc-saving-models)
+
+<a name="basic-conventions"></a>
+# Basic Conventions
+
+The entire virtualbox library follows a few conventions to make sure
+things work uniformly across the entire codebase, and so that nothing
+should surprise any developers once they understand these conventions.
+
+When browsing the documentation, you'll probably notice that a lot of the
+classes inherit from {VirtualBox::AbstractModel}. This just means that all
+these classes act the same way! Every {VirtualBox::AbstractModel AbstractModel}
+shares the following behaviors:
+
+* Finding
+* Accessing
+* Modifying
+* Saving
+
+These behaviors should be similar if not the exact same across all
+virtualbox models. Each of these behaviors is covered below.
+
+<a name="bc-finding-models"></a>
+## Finding Models
+
+All data models have a `find` or `all` method (or sometimes both!) These
+methods do what you expect them to: `all` will return an array of all instances
+of that model which is typically unordered. `find` will allow you to find a
+specific instance of that model, typically by name or UUID. Below are a couple
+examples of this.
+
+### All
+
+This example uses {VirtualBox::HardDrive}. As you can see, its just an
+unmodified ruby `Array` which is returned by `all`. This can be used find,
+sort, enumerate, etc.
+
+    drives = VirtualBox::HardDrive.all
+    puts "You have #{drives.length} hard drives!"
+
+    drives.each do |drive|
+      puts "Drive: #{drive.uuid}"
+    end
+
+In the case that `all` returns an empty array, this simply means that none
+of that model exist.
+
+### Find
+
+This example uses {VirtualBox::VM}, which will probably be the most common
+model you search for.
+
+    vm = VirtualBox::VM.find("MyVM")
+    puts "This VM has #{vm.memory} MB of RAM allocated to it."
+
+Find can also be used with UUIDs:
+
+    vm = VirtualBox::VM.find("3d0f87b4-50f7-4fc5-ad89-93375b1b32a3")
+    puts "This VM's name is: #{vm.name}"
+
+When a find fails, it will return `nil`.
+
+<a name="bc-accessing-models"></a>
+## Accessing Models
+
+Every model has an _attribute list_ associated with it. These attributes are
+what can be accessed on the model via the typical ruby attribute accessing
+syntax with the `.` (dot) operator. Because these methods are generated
+dynamically, they don't show up as methods in the documentation. Because of this,
+attributes are listed for every model in their overviews. For examples, see the
+overviews of {VirtualBox::VM}, {VirtualBox::HardDrive}, etc.
+
+In addition to an attribute list, many models also have _relationships_.
+Relationships are, for our purposes, similar enough to attributes that they
+can be treated the same. Relationship accessing methods are also dynamically
+generated, so they are listed within the overviews of the models as well (if they
+have any). Relationships allow two models to show that they are connected in some
+way, and can therefore be accessed through each other.
+
+### Attributes
+
+Reading attributes is simple. Let's use a {VirtualBox::VM} as an example:
+
+    vm = VirtualBox::VM.find("FooVM")
+
+    # Accessing attributes:
+    vm.memory
+    vm.name
+    vm.boot1
+    vm.ioapic
+
+### Relationships
+
+Relationships are read the exact same way as attributes. Again using a
+{VirtualBox::VM} as an example:
+
+    vm = VirtualBox::VM.find("FooVM")
+
+    # storage_controllers is a relationship containing an array of all the
+    # storage controllers on this VM
+    vm.storage_controllers.each do |sc|
+      puts "Storage Controller: #{sc.uuid}"
+    end
+
+The difference from an attribute is that while attributes are typically ruby
+primitives such as `String` or `Boolean`, relationship objects are always other
+virtualbox models such as {VirtualBox::StorageController}.
+
+<a name="bc-modifying-models"></a>
+## Modifying Models
+
+In addition to simply reading attributes and relationships, most can be modified
+as well. I say "most" because some attributes are `readonly` and some relationships
+simply don't support being directly modified (though their objects may, I'll get to
+this in a moment). By looking at the attribute list it is easy to spot a readonly
+attribute, which will have the `:readonly` option set to `true`. Below is an example
+of what you might see in the overview of some model:
+
+    attribute :uuid, :readonly => true
+
+In the above case, you could read the `uuid` attribute as normal, but it wouldn't support
+modification (and you'll simply get a `NoMethodError` if you try to set it).
+
+Relationships are a little bit trickier, since when discussing modifying a relationship,
+it could either be taken to mean the items _in_ the relationship, or the relationship
+itself. A good rule of thumb, assuming there exists a relationship `foos`,is if you ever
+want to do `object.foos =` something, then you're _modifying the relationship_ and _not_
+the objects. But if you ever do `object.foos[0].destroy`, then you're _modifying the
+relationship objects_ and _not_ the relationship itself.
+
+### Attributes
+
+Attributes which support modification are modified like standard ruby attributes. The
+following example uses {VirtualBox::HardDrive}:
+
+    hd = VirtualBox::HardDrive.new
+    hd.size = 2000 # megabytes
+    hd.format = "VMDK"
+
+As you can see, there is nothing sneaky going on here, and does what you expect.
+
+### Relationships
+
+Modifying relationships, on the other hand, is a little different. If the model supports
+modifying the relationship (which it'll note in its respective documentation), then
+you can set it just like an attribute. Below, we use {VirtualBox::AttachedDevice} as
+an example:
+
+    ad = VirtualBox::AttachedDevice.new
+
+    # Attached devices have an image relationship
+    ad.image = VirtualBox::DVD.empty_drive
+
+If a relationship doesn't support setting it, it will raise a {VirtualBox::Exceptions::NonSettableRelationshipException}.
+
+**Note**: Below is an example of modifying a relationship object, rather than a
+relationship itself. The example below uses {VirtualBox::VM}.
+
+    vm = VirtualBox::VM.find("FooVM")
+    vm.storage_controllers[0].name = "Foo Controller"
+
+<a name="bc-saving-models"></a>
+## Saving Models
+
+Saving models is _really_ easy: you simply call `save`. That's all! Well, there are
+some subtleties, but that's the basic idea. `save` will typically **also save relationships**
+so if you modify a relationship object or relationship itself, calling `save` on the
+parent object will typically save the relationships as well. `save` always returns
+`true` or `false` depending on whether the operation was a success or not. If you'd like
+instead to know why a `save` failed, you can call the method with a `true` parameter
+which sets `raise_errors` to `true` and will raise a {VirtualBox::Exceptions::CommandFailedException}
+if there is a failure. The message on this object contains the reason.
+
+Below is an example of saving a simple {VirtualBox::VM} object:
+
+    vm = VirtualBox::VM.find("FooVM")
+
+    # Double the memory
+    vm.memory = vm.memory.to_i * 2
+
+    # This will return true/false depending on success
+    vm.save
+
+Below is an example where an exception will be raised if an error occurs:
+
+    vm = VirtualBox::VM.find("FooVM")
+    vm.memory = "INVALID"
+
+    # This will raise an exception, since the memory is invalid
+    vm.save(true)

data/docs/WhatsNew.md

@@ -0,0 +1,12 @@
+# What's New in 0.6.x?
+
+## Native Interface
+
+The VirtualBox gem no longer piggy-backs on top of `VBoxManage` or XML configuration files.
+The gem now uses the native interface provided by VirtualBox to communicate. The result of
+this is a _huge_ speed increase which simply would not have been possible otherwise, and
+stability across versions. In addition to that, the entire VirtualBox API is now at your
+disposal. While the gem itself doesn't yet support creating VMs and so on, the API is available
+for you to do it manually (if you really wanted to!).
+
+Future versions will support more and more of the API.

data/features/README.md

@@ -0,0 +1,33 @@
+# VirtualBox Gem Feature Tests
+
+**Warning: These tests actually hit the real VirtualBox software!**
+
+The tests in this directory are _not_ meant as a replacement
+for the unit tests in the `test/` directory. Instead, these
+features are meant to test the actual integration of the
+virtualbox gem with an actual VirtualBox installation.
+
+Whereas the unit tests try to test every branch of the code in a
+very prescribed, isolated environment, the feature tests do not
+test specific branches of code, but test behavior of the gem.
+The reasoning for both tests is that the unit tests test proper
+behavior _within the library itself_ whereas these feature tests
+test proper behavior _with the outside world_.
+
+## Running Feature Tests
+
+The easiest way to run these feature tests is via `rake` or the
+`cucumber` binary. `rake` shown below:
+
+    rake test:integration
+
+## Feature Coverage
+
+The test coverage of the features are purposefully not trying to
+reach 100% branch coverage. They test the basic functionality (and
+as much as the functionality as possible) to verify the library is
+functional. If a bug is found, then a feature should be added to
+reproduce and verify the bug no longer exists, but I'm not concerned
+with getting 100% branch coverage right away.
+
+For 100% branch coverage, see the unit tests, which do this.

data/features/global.feature

@@ -0,0 +1,19 @@
+Feature: Global Data
+  As a virtualbox library user
+  I want to access information about the global state of VirtualBox
+  In order to get information about my environment
+
+  Scenario: Reading the VMs
+    Given the global object
+    When I read the "vms"
+    Then I should get a matching length for "vms"
+
+  Scenario: Reading the hard drives
+    Given the global object
+    When I read the media "hard drives"
+    Then I should get a matching length of media items
+
+  Scenario: Reading the dvds
+    Given the global object
+    When I read the media "dvds"
+    Then I should get a matching length of media items

data/features/global_extra_data.feature

@@ -0,0 +1,27 @@
+Feature: Global Extra Data
+  As a virtualbox library user
+  I want to access and update global extra data
+
+  Background:
+    Given the global object
+    And I delete the "global" extra data "VirtualBoxGemTest/Key"
+    And the "extra_data" relationship
+
+  Scenario: Reading extra data
+    When I get the extra data of "global"
+    Then all the extra data should match
+
+  @unsafe
+  Scenario: Writing extra data
+    When I set the extra data "VirtualBoxGemTest/Key" to "Value"
+    And I save the relationship
+    And I get the extra data of "global"
+    Then the extra data should include "VirtualBoxGemTest/Key" as "Value"
+
+  @unsafe
+  Scenario: Deleting extra data
+    When I set the extra data "VirtualBoxGemTest/Key" to "Value"
+    And I save the relationship
+    And I delete the extra data "VirtualBoxGemTest/Key"
+    And I get the extra data of "global"
+    Then the extra data should not include "VirtualBoxGemTest/Key"