• Stars
    star
    569
  • Rank 78,369 (Top 2 %)
  • Language
    Go
  • License
    MIT License
  • Created almost 4 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Create virtual machines and run Linux-based operating systems in Go using Apple Virtualization.framework.

vz - Go binding with Apple Virtualization.framework

Build Go Reference

vz provides the power of the Apple Virtualization.framework in Go. Put here is block quote of overreview which is written what is Virtualization.framework from the document.

The Virtualization framework provides high-level APIs for creating and managing virtual machines (VM) on Apple silicon and Intel-based Mac computers. Use this framework to boot and run macOS or Linux-based operating systems in custom environments that you define. The framework supports the Virtual I/O Device (VIRTIO) specification, which defines standard interfaces for many device types, including network, socket, serial port, storage, entropy, and memory-balloon devices.

Usage

Please see the example directory.

Requirements

  • Higher or equal to macOS Big Sur (11.0.0).
  • Latest version of vz supports last two Go major releases and might work with older versions.

Installation

Initialize your project by creating a folder and then running go mod init github.com/your/repo (learn more) inside the folder. Then install vz with the go get command:

$ go get github.com/Code-Hex/vz/v3

Deprecated older versions (v1, v2).

Feature Overview

  • โœ… Virtualize Linux on a Mac (x86_64, arm64)
    • GUI Support
    • Boot Extensible Firmware Interface (EFI) ROM
    • Clipboard sharing through the SPICE agent
  • โœ… Virtualize macOS on Apple Silicon Macs (arm64)
    • Fetches the latest restore image supported by this host from the network
    • Start in recovery mode
  • โœ… Running Intel Binaries in Linux VMs with Rosetta (arm64)
  • โœ… Shared Directories
  • โœ… Virtio Sockets
  • โœ… Less dependent (only under golang.org/x/*)

Important

For binaries used in this package, you need to create an entitlements file like the one below and apply the following command.

vz.entitlements
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.security.virtualization</key>
	<true/>
</dict>
</plist>
$ codesign --entitlements vz.entitlements -s - <YOUR BINARY PATH>

A process must have the com.apple.security.virtualization entitlement to use the Virtualization APIs.

If you want to use VZBridgedNetworkDeviceAttachment, you need to add also com.apple.vm.networking entitlement.

Known compile-time warnings

If you compile using an older Xcode SDK, you will get the following warnings.

This example warns that macOS 12.3 API and macOS 13 API are not available in the binary build. This means these APIs are not available even if you are running this binary on a modern OS (macOS 12.3 or macOS 13).

$ go build .
# github.com/Code-Hex/vz/v3
In file included from _cgo_export.c:4:
In file included from socket.go:6:
In file included from ./virtualization_11.h:9:
./virtualization_helper.h:25:9: warning: macOS 12.3 API has been disabled [-W#pragma-messages]
./virtualization_helper.h:32:9: warning: macOS 13 API has been disabled [-W#pragma-messages]

If you want to build a binary that can use the API on all operating systems, make sure the Xcode SDK is up-to-date.

You can check the version of the Xcode SDK available for each macOS on this site.

https://xcodereleases.com/

Version compatibility check

The package provides a mechanism for checking the availability of the respective API through error handling:

bootLoader, err := vz.NewEFIBootLoader()
if errors.Is(err, vz.ErrUnsupportedOSVersion) || errors.Is(err, vz.ErrBuildTargetOSVersion) {
  return fallbackBootLoader()
}
if err != nil {
  return nil, err
}
return bootLoader, nil

There are two items to check.

  1. API is compatible with the version of macOS
  2. The binary was built with the API enabled

Knowledge for the Apple Virtualization.framework

There is a lot of knowledge required to use this Apple Virtualization.framework, but the information is too scattered and very difficult to understand. In most cases, this can be found in the official documentation. However, the Linux kernel knowledge required to use the feature provided by this framework is not documented. Therefore, I have compiled the knowledge I have gathered so far into this wiki.

https://github.com/Code-Hex/vz/wiki

Anyone is free to edit this wiki. It would help someone if you could add information not listed here. Let's make a good wiki together!

Testing

If you want to contribute some code, you will need to add tests.

PUI PUI Linux is used to test this library. This Linux is designed to provide only the minimum functionality required for the Apple Virtualization.framework (Virtio), so the kernel file size is very small.

The test code uses the Makefile in the project root.

$ # Download PUI PUI Linux, Only required the first time.
$ make download_kernel
$ make test

LICENSE

MIT License

More Repositories

1

pget

The fastest, resumable file download client
Go
1,047
star
2

go-generics-cache

A key:value store/cache library written in Go generics. LRU, LFU, FIFO, MRU, Clock support.
Go
458
star
3

graphql-codegen-typescript-validation-schema

GraphQL Code Generator plugin to generate form validation schema from your GraphQL schema
TypeScript
313
star
4

synchro

๐Ÿ•ฐ๏ธ Synchro: Timezone-typesafe date and time framework for Go. ๐ŸŒŸ Star to support our work!
Go
260
star
5

Neo-cowsay

๐Ÿฎ cowsay is reborn. Neo Cowsay has written in Go.
Go
246
star
6

gqldoc

The easiest way to make API documents for GraphQL
Go
192
star
7

dd

Data Dumper library dumps any data as valid syntax in Go
Go
185
star
8

firebase-auth-cloudflare-workers

TypeScript
131
star
9

battery

Display your battery status on terminal (or tmux) written by Go
Go
70
star
10

golet

*.go file as a mini supervisor
Go
60
star
11

funcy-mock

funcy-mock generates mock file from interface go file
Go
52
star
12

shibafu

Shibafu Programming Language wwwwwwwwwww
Go
41
star
13

container-registry

container-registry
Go
29
star
14

puipui-linux

So tiny linux for testing virtualization (Virtual I/O aka VIRTIO) purpose
Shell
24
star
15

fast-service

fast-service is opensource speedtest service written in Go
Go
24
star
16

testing-grpc

go-grpc server, client for onboarding
Go
23
star
17

go-install-tools

Install All go-tools at one time!!
Go
22
star
18

sqlx-transactionmanager

Transaction manager for github.com/jmoiron/sqlx
Go
22
star
19

White-MobileTerminal

Supports ios versions from 7.0 to 8.1 !!
C++
20
star
20

go-version-update

Update the version string of your go project.
Go
20
star
21

echo-static

Static middleware for echo web framework(golang)
Go
19
star
22

sigctx

context with signal in golang
Go
19
star
23

retrygroup

Package retrygroup provides synchronization, Context cancelation for groups of retry goroutines working on subtasks of a common task.
Go
17
star
24

sqb

โšกBlazing fast, Flexible, SQL Query Builder for Go
Go
17
star
25

gvisor-vmnet

vmnet based gvisor tcpip stack
Go
11
star
26

auto-milestone-binder

An action for binding milestone to some PR or some issues
TypeScript
8
star
27

dotfiles

ๅคงไบ‹ใชdotใ‚’็ฎก็†ใ—ใฆใพใ™๐Ÿ‘
Shell
8
star
28

grpc-edge-gateway

gRPC Gateway on the edge functions
TypeScript
7
star
29

deno-context

๐Ÿฆ•ใ€Denoใ€‘Propagate deadlines, a cancellation and other request-scoped values to multiple promise.
TypeScript
6
star
30

neo-cowsay-action

๐Ÿฎ GitHub action for cowsay lovers
Shell
5
star
31

takopi

ใฃใƒ”๏ผ
Go
5
star
32

socks5

socks5 server implemented by Go
Go
5
star
33

go-emojipacks

https://github.com/lambtron/emojipacks has been stopped. A new emojipacks has been implemented by Go
Go
5
star
34

saltissimo

Easy generate, easy compare hash using pbdkf2
Go
5
star
35

exit

Error makes exit code meaningful
Go
5
star
36

gqldoc-actions

JavaScript
5
star
37

code-hex.github.io

My homepage
TypeScript
5
star
38

Text-Shirasu

Wrapped Text::MeCab in Perl
Perl
5
star
39

go-async

More Easy, more readable sync.WaitGroup
Go
5
star
40

twippai

Perlใ€Pythonใ€RubyใงTwitterใ‹ใ‚‰ใŸใใ•ใ‚“ใฎใŠใฃใฑใ„ใ‚’ใƒ€ใ‚ฆใƒณใƒญใƒผใƒ‰ใ™ใ‚‹
Go
4
star
41

go-infinity-channel

Provides an infinitely queueing channel.
Go
4
star
42

go-github-token

Very easy to get github access token library written in Go
Go
3
star
43

arm64-docker-mysql

Shell
3
star
44

uploader

uploader by grpc go
Go
3
star
45

HotKeyCapture

This is a sandboxed of custom global hotkeys in Swift using HotKeyCapture
Swift
3
star
46

ssh-gpt

Fictitious SSH Server - Powered by OpenAI ChatGPT
Go
3
star
47

chair

isucon tool
Go
2
star
48

Text-CaboCha

Alternate Text-CaboCha Binding
Perl
2
star
49

gpl

Update multiple local repositories with parallel
Go
2
star
50

p5-App-Format

Format for perl code. It's like a gofmt.
Perl
2
star
51

Card

ใƒ†ใ‚นใƒˆใ‚’ไน—ใ‚Šๅˆ‡ใ‚‹ใŸใ‚ใซ้–‹็™บใ•ใ‚ŒใŸใ‚ขใƒ—ใƒช
Swift
2
star
52

m1-docker

Please following this URL
Go
2
star
53

network

Asynchronous Networking Patterns
Go
2
star
54

vegeta

Project to collect large amounts of vegetable data using IoT
Go
2
star
55

Algorithm-NaiveBayes-RandomForest

RandomForest with Algorithm::NaiveBayes in perl
Perl
1
star
56

go-groff

groff parser
Go
1
star
57

go-elisp

elisp implement by Go
Go
1
star
58

MyApplication

Implement NSApplication main-event-loop
Objective-C
1
star
59

first-label-interaction

Labeling actions for new comer
JavaScript
1
star
60

fmm

Friendly memory monitoring tool
C
1
star
61

touchbar-emoji

emoji on control strip
Objective-C
1
star
62

godzilla

Management tool for go
Go
1
star
63

alpine-chrome

Chrome Headless docker images built upon alpine
Dockerfile
1
star
64

ghp

Create a new project on the ghq root
Go
1
star
65

IF

Ternary operator package for Go
Go
1
star
66

Color-Capture

Color Capture is PopClip Extension
Objective-C
1
star
67

go-riscv

Go
1
star
68

p5-Shell-Tiny

Very tiny shell written in Perl5
Perl
1
star
69

august

gRPC to RESTful or Protobuf on HTTP proxy for microservices
1
star
70

tenpuzzle

Tenpuzzle - Find the solution of the 10 puzzles in Genetic Algorithm
Go
1
star
71

p5-XS-Closure-Example

Example for how to make a closure on XS
C
1
star
72

p5-List-Flatten-XS

Fast flatten
Perl
1
star