virtual_box 0.1.2 → 0.1.4

data/Gemfile.lock

@@ -12,7 +12,7 @@ GEM
       systemu (>= 2.4.0)
     metaclass (0.0.1)
     minitest (2.12.1)
-    mocha (0.11.3)
+    mocha (0.11.4)
       metaclass (~> 0.0.1)
     multi_json (1.3.4)
     net-ssh (2.3.0)

data/README.markdown

@@ -4,6 +4,36 @@ This gem is a Ruby API for VirtualBox, Sun's open-source virtualization software
 that supports Linux, Mac OS X, and Windows.
 
 
+## Usage
+
+virtual_box is mainly intended to help out with testing. The snippet below shows
+a complete setup / teardown scenario.
+
+```ruby
+setup do
+	vdi_file = '/tmp/disk.vdi'
+	@disk = VirtualBox::Vm::Disk.create :file => vdi_file,
+	                                    :size => 16 * 1024 * 1024
+  iso_file = 'test/fixtures/tinycore/remix.iso'
+  @net = VirtualBox::Net.new(:ip => '192.168.66.6', :netmask => '255.255.255.0',
+                             :dhcp => { :start_ip => '192.168.66.66' }).add
+
+  @vm = VirtualBox::Vm.new(
+      :board => { :ram => 256, :video_ram => 16, :os => :linux26 },
+      :io_buses => [{ :bus => :ide,
+                      :disks => [{ :file => iso_file, :port => 1 }] },
+                    { :bus => :sata, :disks => [@disk] }],
+      :nics => [{ :mode => :host, :chip => :virtual,
+                  :net_name => @net.name }]).register
+end
+  
+teardown do
+  @vm.unregister
+  @net.remove
+  @disk.drop
+end
+```
+
 ## Features
 
 Currently, the gem supports the following features:

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.4

data/lib/virtual_box/error.rb

@@ -16,7 +16,7 @@ class Error < StandardError
   #     VirtualBox.run call.
   def initialize(cli_result)
     @exit_code = cli_result[:status]
-    @output = output
+    @output = cli_result[:output]
     
     super "VirtualBox CLI exited with code #{@exit_code}:\n#{@output}\n"
   end

data/lib/virtual_box/net.rb

@@ -16,15 +16,17 @@ class Net
   # attribute is read-only, and it is automatically set when the network is
   # registered with VirtualBox.
   # @return [String]
-  attr_reader :if_name
+  attr_reader :name
 
   # The name of the VirtualBox internal network.
   #
+  # This is most likely not useful outside the VirtualBox API.
+  #
   # VirtualBox's CLI does not provide a way to set the internal network name.
   # Therefore, this attribute is read-only, and it is automatically set when the
   # network is registered with VirtualBox.
   # @return [String]
-  attr_reader :name
+  attr_reader :vbox_name
   
   # The MAC address of the host's virtual NIC that's connected to this network.
   #
@@ -69,8 +71,8 @@ class Net
   # True if this virtual network has been added to VirtualBox.
   # @return [Boolean] true if this network exists, false otherwise
   def live?
-    networks = self.class.all
-    network = networks.find { |net| net.if_name == if_name }
+    networks = self.class.all false
+    network = networks.find { |net| net.name == name }
     network ? true : false
   end
   
@@ -78,7 +80,7 @@ class Net
   #
   # @return [VirtualBox::Net] self, for easy call chaining
   def add
-    unless if_name.nil?
+    unless name.nil?
       raise "Virtual network already added to VirtualBox"
     end
     
@@ -88,17 +90,16 @@ class Net
     unless match = /^interface\s+'(.*)'\s+.*created/i.match(output)
       raise "VirtualBox output does not include interface name"
     end
-    @if_name = match[1]
+    @name = match[1]
     
-    # Now list all the networks to pull the rest of the information.
-    networks = self.class.all
-    network = networks.find { |net| net.if_name == if_name }
-    @name = network.name
+    # Query VirtualBox to pull the rest of the information.
+    network = self.class.named name
+    @vbox_name = network.vbox_name
     @mac = network.mac
     
     if (ip && ip != network.ip) || (netmask && netmask != network.netmask)
       VirtualBox.run_command! ['VBoxManage', '--nologo', 'hostonlyif',
-          'ipconfig', if_name, '--ip', ip, '--netmask', netmask]
+          'ipconfig', name, '--ip', ip, '--netmask', netmask]
     else
       self.ip = network.ip
       self.netmask = network.netmask
@@ -114,28 +115,44 @@ class Net
   #
   # @return [VirtualBox::Net] self, for easy call chaining
   def remove
-    unless if_name.nil?
+    unless name.nil?
       dhcp.remove self if dhcp
-      VirtualBox.run_command ['VBoxManage', 'hostonlyif', 'remove', if_name]
+      VirtualBox.run_command ['VBoxManage', 'hostonlyif', 'remove', name]
     end
     self
   end
   
   # The virtual networks added to VirtualBox.
   #
+  # @param [Boolean] with_dhcp if false, the returned VirtualBox::Net instances
+  #     will have their dhcp property set to nil, even if they have DHCP
+  #     servers; this saves a CLI call when DHCP information is not needed
   # @return [Array<VirtualBox::Net>] all the DHCP servers added to VirtualBox
-  def self.all
-    dhcps = VirtualBox::Net::Dhcp.all
+  def self.all(with_dhcp = true)
+    dhcps = with_dhcp ? VirtualBox::Net::Dhcp.all : {}
     
     output = VirtualBox.run_command! ['VBoxManage', '--nologo', 'list',
                                       '--long', 'hostonlyifs']
     output.split("\n\n").map do |net_info|
-      net = new.from_net_info(net_info)
-      net.dhcp = dhcps[net.name]
+      net = new.from_net_info net_info
+      net.dhcp = dhcps[net.vbox_name]
       net
     end
   end
   
+  # The virtual network added to VirtualBox with a given name.
+  #
+  # This is a convenience for calling find on Net.all, so it's just as
+  # inefficient.
+  # @param [String] name the name to look for
+  # @param [Boolean] with_dhcp if false, the returned VirtualBox::Net instance
+  #     will have its dhcp property set to nil, even if it has a DHCP
+  #     server; this saves a CLI call when DHCP information is not needed
+  def self.named(name, with_dhcp = true)
+    networks = all with_dhcp
+    networks.find { |net| net.name == name }
+  end
+  
   # Parses information about a DHCP server returned by VirtualBox.
   #
   # The parsed information is used to replace this network's specification.
@@ -147,8 +164,8 @@ class Net
       line.split(':', 2).map(&:strip)
     }]
     
-    @if_name = info['Name']
-    @name = info['VBoxNetworkName']
+    @name = info['Name']
+    @vbox_name = info['VBoxNetworkName']
     @mac = info['HardwareAddress'].upcase.gsub(/[^0-9A-F]/, '')
     self.ip = info['IPAddress']
     self.netmask = info['NetworkMask']

data/lib/virtual_box/net/dhcp.rb

@@ -71,7 +71,7 @@ class Dhcp
         '--netmask', netmask, '--lowerip', start_ip, '--upperip', end_ip,
         '--enable']
     if net_or_name.kind_of? VirtualBox::Net
-      command.push '--ifname', net_or_name.if_name
+      command.push '--ifname', net_or_name.name
     else
       command.push '--netname', net_or_name
     end
@@ -88,7 +88,7 @@ class Dhcp
   def remove(net_or_name)
     command = ['VBoxManage', 'dhcpserver', 'remove']
     if net_or_name.kind_of? VirtualBox::Net
-      command.push '--ifname', net_or_name.if_name
+      command.push '--ifname', net_or_name.name
     else
       command.push '--netname', net_or_name
     end

data/lib/virtual_box/vm.rb

@@ -167,20 +167,44 @@ class Vm
   #   :nmi:: NMI (non-maskable interrupt)
   # @return [VirtualBox::Vm] self, for easy call chaining
   def control(action)
-    action = case action
-    when :kill
-      'poweroff'
-    when :power_button
-      'acpipowerbutton'
-    when :nmi
-      'injectnmi'
-    end
+    result = nil
+    
+    3.times do
+      action_arg = case action
+      when :kill
+        'poweroff'
+      when :power_button
+        'acpipowerbutton'
+      when :nmi
+        'injectnmi'
+      else
+        action
+      end
 
-    VirtualBox.run_command! ['VBoxManage', '--nologo', 'controlvm', uid,
-                             action]
+      result =  VirtualBox.run_command ['VBoxManage', '--nologo', 'controlvm',
+                                        uid, action_arg]
+      return self if result[:status] == 0
+      
+      # Perhaps the VM is already powered off?
+      if action == :kill || action == :power_button
+        return self unless live?
+        sleep 0.1
+      else
+        break
+      end
+    end
+    raise VirtualBox::Error, result
+    
     self
   end
   
+  # True if this virtual machine is running inside VirtualBox.
+  #
+  # @return [Boolean] true if this VM is being simulated by VirtualBox
+  def live?
+    (uid && self.class.started_uids.include?(uid)) ? true : false
+  end
+  
   # The UUIDs of all VMs that are registered with VirtualBox.
   #
   # @return [Array<String>] UUIDs for VMs that VirtualBox is aware of

data/lib/virtual_box/vm/disk.rb

@@ -93,6 +93,16 @@ class Disk
     new :file => path, :format => format, :media => :disk
   end
   
+  # Removes the image file backing this disk.
+  #
+  # The method name is drop, as in "DROP TABLE". It doesn't remove the disk from
+  # any VM, it just removes the file.
+  # @return [VirtualBox::Vm::Disk] self, for easy call chaining
+  def drop
+    File.unlink @file if File.exist?(@file)
+    self
+  end
+  
   # Disk image format based on the extension in the file name.
   def self.guess_image_format(image_file)
     parts = File.basename(image_file).split('.')

data/test/helper.rb

@@ -11,6 +11,9 @@ require 'minitest/unit'
 require 'minitest/spec'
 require 'mocha'
 
+require 'simplecov'
+SimpleCov.start
+
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'virtual_box'

data/test/virtual_box/integration_test.rb

@@ -15,7 +15,7 @@ describe 'VirtualBox' do
         :io_buses => [{ :bus => :ide,
                         :disks => [{ :file => iso_file, :port => 1 }] }],
         :nics => [{ :mode => :host, :chip => :virtual,
-                    :net_name => @net.if_name }]).register
+                    :net_name => @net.name }]).register
   end
   
   after do
@@ -31,11 +31,7 @@ describe 'VirtualBox' do
     end
     
     after do
-      unless @vm.nil?
-        @vm.stop
-        # Let VirtualBox stop the VM, so that it can be unregistered.
-        Kernel.sleep 0.5
-      end
+      @vm.stop unless @vm.nil?
     end
     
     it 'responds to a SSH connection' do

data/test/virtual_box/net_test.rb

@@ -20,7 +20,9 @@ describe VirtualBox::Net do
       end
       
       it 'has its device name show up in ifconfig' do
-        `ifconfig -a`.must_include card[:name]
+        # NOTE: on OSX, recent VirtualBox builds return user-friendly NIC names,
+        #       such as "en0: Ethernet" instead of "en0"
+        `ifconfig -a`.must_include card[:name].split(':', 2).first
       end
     end
   end
@@ -49,12 +51,12 @@ describe VirtualBox::Net do
       end
       
       it 'has an interface name that shows up in the ifconfig output' do
-        @net.if_name.wont_be_nil
-        `ifconfig -a`.must_include @net.if_name
+        @net.name.wont_be_nil
+        `ifconfig -a`.must_include @net.name
       end
       
-      it 'has a name' do
-        @net.name.wont_be_nil
+      it 'has a VirtualBox network name' do
+        @net.vbox_name.wont_be_nil
       end
       
       it 'has a MAC address' do
@@ -90,13 +92,13 @@ describe VirtualBox::Net do
       end
       
       it 'has an interface name that shows up in the ifconfig output' do
-        @net.if_name.wont_be_nil
-        `ifconfig -a`.must_include @net.if_name
+        @net.name.wont_be_nil
+        `ifconfig -a`.must_include @net.name
       end
       
       it 'shows up on the list of live networks' do
         networks = VirtualBox::Net.all
-        network = networks.find { |n| n.if_name == @net.if_name }
+        network = networks.find { |n| n.name == @net.name }
         network.to_hash.must_equal @net.to_hash
       end      
     end
@@ -124,14 +126,12 @@ describe VirtualBox::Net do
       end
       
       it 'has an interface name that shows up in the ifconfig output' do
-        @net.if_name.wont_be_nil
-        `ifconfig -a`.must_include @net.if_name
+        @net.name.wont_be_nil
+        `ifconfig -a`.must_include @net.name
       end
       
       it 'shows up on the list of live networks' do
-        networks = VirtualBox::Net.all
-        network = networks.find { |n| n.if_name == @net.if_name }
-        network.to_hash.must_equal @net.to_hash
+        VirtualBox::Net.named(@net.name).to_hash.must_equal @net.to_hash
       end      
     end
   end

data/test/virtual_box/vm/disk_test.rb

@@ -15,7 +15,7 @@ describe VirtualBox::Vm::Disk do
     end
   end
   
-  describe 'create' do
+  describe '#create' do
     describe '16-megabyte VMDK flexible' do
       let(:vmdk_path) { '/tmp/disk.vmdk' }
     
@@ -44,6 +44,13 @@ describe VirtualBox::Vm::Disk do
       it 'returns a VMDK Disk' do
         @disk.format.must_equal :vmdk
       end
+      
+      describe '#drop' do
+        before { @disk.drop }
+        it 'removes the file' do
+          File.exist?(vmdk_path).must_equal false
+        end
+      end
     end
     
     describe '16-megabyte preallocated' do

data/test/virtual_box/vm_test.rb

@@ -18,7 +18,7 @@ describe VirtualBox::Vm do
       @vm.wont_be :registered?
     end
     
-    describe 'registered' do
+    describe '#register' do
       before do
         @vm.register
       end
@@ -36,19 +36,43 @@ describe VirtualBox::Vm do
         uids.must_include @vm.uid
       end
       
-      describe 'started' do
+      it 'is not live' do
+        @vm.live?.must_equal false
+      end
+      
+      describe '#stop' do
+        it "doesn't crash" do
+          @vm.stop
+          @vm.live?.must_equal false
+        end
+      end
+      
+      describe '#start' do
         before do
           @vm.start
         end        
         after do
           @vm.stop
-          sleep 0.5  # VirtualBox will barf if we unregister the VM right away.
         end
         
         it 'shows up on the list of started VM UIDs' do
           uids = VirtualBox::Vm.started_uids
           uids.must_include @vm.uid
         end
+
+        it 'is live' do
+          @vm.live?.must_equal true
+        end
+        
+        describe '#stop' do
+          before do
+            @vm.stop
+          end
+          
+          it 'is no longer live' do
+            @vm.live?.must_equal false
+          end
+        end
       end
     end
   end

data/virtual_box.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "virtual_box"
-  s.version = "0.1.2"
+  s.version = "0.1.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Victor Costan"]
-  s.date = "2012-05-06"
+  s.date = "2012-05-07"
   s.description = "Drives the VirtualBox command-line to manage VMs"
   s.email = "victor@costan.us"
   s.extra_rdoc_files = [
@@ -55,7 +55,7 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/csail/police"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.24"
+  s.rubygems_version = "1.8.23"
   s.summary = "VirtualBox driver"
 
   if s.respond_to? :specification_version then

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: virtual_box
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-06 00:00:00.000000000 Z
+date: 2012-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: posix-spawn
@@ -228,7 +228,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3995801418779294892
+      hash: 1577724543477993918
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -237,7 +237,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: VirtualBox driver