Class: Vagrant::Box

Inherits:
Actions::Runner show all
Defined in:
lib/vagrant/box.rb

Overview

Represents a “box,” which is simply a packaged vagrant environment. Boxes are simply ‘tar` files which contain an exported VirtualBox virtual machine, at the least. They are created with `vagrant package` and may contain additional files if specified by the creator. This class serves to help manage these boxes, although most of the logic is kicked out to actions.

What can the Box class do?

  • Find boxes

  • Add existing boxes (from some URI)

  • Delete existing boxes

# Finding Boxes

Using the Box.find method, you can search for existing boxes. This method will return ‘nil` if none is found or an instance of Box otherwise.

box = Vagrant::Box.find("base")
if box.nil?
  puts "Box not found!"
else
  puts "Box exists at #{box.directory}"
end

# Adding a Box

Boxes can be added from any URI. Some schemas aren’t supported; if this is the case, the error will output to the logger.

Vagrant::Box.add("foo", "http://myfiles.com/foo.box")

# Destroying a box

Boxes can be deleted as well. This method is final and there is no way to undo this action once it is completed.

box = Vagrant::Box.find("foo")
box.destroy

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Actions::Runner

#actions, #add_action, execute!, #execute!, #find_action, #invoke_around_callback, #invoke_callback

Methods included from Util

#error_and_exit, included, #logger, #wrap_output

Constructor Details

#initialize(env = nil, name = nil) ⇒ Box

Creates a new box instance. Given an optional ‘name` parameter, newly created instance will have that name, otherwise it defaults to `nil`.

Note: This method does not actually create the box, but merely returns a new, abstract representation of it. To add a box, see #add.



118
119
120
121
 
# File 'lib/vagrant/box.rb', line 118

def initialize(env=nil, name=nil)
  @name = name
  @env = env
end

Instance Attribute Details

#env ⇒ Object

The environment which this box belongs to. Although this could actually be many environments, this points to the environment of a specific instance.



57
58
59
 
# File 'lib/vagrant/box.rb', line 57

def env
  @env
end

#name ⇒ Object

The name of the box.



45
46
47
 
# File 'lib/vagrant/box.rb', line 45

def name
  @name
end

#temp_path ⇒ Object

The temporary path to the downloaded or copied box. This should only be used internally.



52
53
54
 
# File 'lib/vagrant/box.rb', line 52

def temp_path
  @temp_path
end

#uri ⇒ Object

The URI for a new box. This is not available for existing boxes.



48
49
50
 
# File 'lib/vagrant/box.rb', line 48

def uri
  @uri
end

Class Method Details

.add(env, name, uri) ⇒ Object

Adds a new box with given name from the given URI. This method begins the process of adding a box from a given URI by setting up the Vagrant::Box instance and calling #add.

Parameters:

  • name (String) —

    The name of the box

  • uri (String) —

    URI to the box file



93
94
95
96
97
98
99
 
# File 'lib/vagrant/box.rb', line 93

def add(env, name, uri)
  box = new
  box.name = name
  box.uri = uri
  box.env = env
  box.add
end

.all(env) ⇒ Array<String>

Returns an array of all created boxes, as strings.

Returns:

  • (Array<String>) 


63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/vagrant/box.rb', line 63

def all(env)
  results = []

  Dir.open(env.boxes_path) do |dir|
    dir.each do |d|
      next if d == "." || d == ".." || !File.directory?(File.join(env.boxes_path, d))
      results << d.to_s
    end
  end

  results
end

.directory(env, name) ⇒ String

Returns the directory to a box of the given name. The name given as a parameter is not checked for existence; this method simply returns the directory which would be used if the box did exist.

Parameters:

  • name (String) —

    Name of the box whose directory you’re interested in.

Returns:

  • (String) —

    Full path to the box directory.



107
108
109
 
# File 'lib/vagrant/box.rb', line 107

def directory(env, name)
  File.join(env.boxes_path, name)
end

.find(env, name) ⇒ Box

Finds a box with the given name. This method searches for a box with the given name, returning ‘nil` if none is found or returning a Vagrant::Box instance otherwise.

Parameters:

  • name (String) —

    The name of the box

Returns:



82
83
84
85
 
# File 'lib/vagrant/box.rb', line 82

def find(env, name)
  return nil unless File.directory?(directory(env, name))
  new(env, name)
end

Instance Method Details

#add ⇒ Object

Begins the process of adding a box to the vagrant installation. This method requires that ‘name` and `uri` be set. The logic of this method is kicked out to the add box action.



135
136
137
 
# File 'lib/vagrant/box.rb', line 135

def add
  execute!(Actions::Box::Add)
end

#destroy ⇒ Object

Beings the process of destroying this box.



140
141
142
 
# File 'lib/vagrant/box.rb', line 140

def destroy
  execute!(Actions::Box::Destroy)
end

#directory ⇒ String

Returns the directory to the location of this boxes content in the local filesystem.

Returns:

  • (String) 


148
149
150
 
# File 'lib/vagrant/box.rb', line 148

def directory
  self.class.directory(env, self.name)
end

#ovf_file ⇒ String

Returns path to the OVF file of the box. The OVF file is an open virtual machine file which contains specifications of the exported virtual machine this box contains.

Returns:

  • (String) 


128
129
130
 
# File 'lib/vagrant/box.rb', line 128

def ovf_file
  File.join(directory, Vagrant.config.vm.box_ovf)
end