Skip to content

Latest commit

 

History

History
131 lines (88 loc) · 4.28 KB

README.md

File metadata and controls

131 lines (88 loc) · 4.28 KB
Raw

go-virtualbox

This is a wrapper package for Golang to interact with VirtualBox. The API is experimental at the moment and you should expect frequent changes. There is no compatibility guarantee between newer and older versions of Virtualbox.

Table of Contents

  1. Status
  2. Usage
    1. Library
    2. Commands
    3. Documentation
  3. Building
  4. Testing
    1. Preparation
    2. Run tests
    3. Re-generate mock
  5. Caveats

Status

Project Status Notes
Github Actions Continuous Integration
Go Report Card Go Report Card scan code with gofmt, go vet, gocyclo, golint, ineffassign, license and misspell.
GoDoc Go Doc
Release Release

Usage

Library

The part of the library that manages guest properties can run both from the Host and the Guest.

    err := virtualbox.SetGuestProperty("MyVM", "test_key", "test_val")
    val, err := GetGuestProperty(VM, "test_key")

See GoDoc for full details.

Commands

The vbhostd commands waits on the vbhostd/* guest-properties pattern.

  • When the guest writes a value on the vbhostd/open, it causes the host to open the given location:
    • Write http://www.hp.com will open the default browser as the given URL
    • Write mailto:[email protected][email protected] opens the default mailer pre-filling the recipient and carbon-copy recipient fields

Documentation

For the released version, see GoDoc:terra-farm/go-virtualbox. To see the local documentation, run godoc -http=:6060 & and then open http://localhost:6060/pkg/github.com/terra-farm/go-virtualbox/.

Building

First install dependencies

  • GoLang
  • GNU Make (Windows: via `choco install -y gnuwin32-make.portable)

Get Go dependencies: make deps or:

$ go get -v github.com/golang/dep/cmd/dep
$ dep ensure -v

Then build: make build or:

$ go build -v ./...
  • default run everything in order
  • deps install dependencies (dep and others)
  • build run go build ./...
  • test run go test ./...
  • lint only run gometalinter linter

Testing

Preparation

Tests run using mocked interfaces, unless the TEST_VM environment variable is set, in order to test against real VirtualBox. You either need to have a pre-provisioned VirtualBox VM and to set its name using the TEST_VM environment variable, or use Vagrant.

$ vagrant box add bento/ubuntu-16.04
# select virtualbox as provider

$ vagrant up

Then run the tests

$ export TEST_VM=go-virtualbox
$ go test

...or (on Windows):

> set TEST_VM=go-virtualbox
> go test

Once you are done with testing, run vagrant halt to same resources.

Run tests

As usual, run go test, or go test -v. To run one test in particular, run go test --run TestGuestProperty.

Re-generate mock

go generate ./...

Using local changes with your own project

If you have a project which depends on this library, you probably want to test your local changes of go-virtualbox in your project. See this article on how to set up your environment to do this.