Merge pull request #108 from Code-Hex/v3

v3

README.md

@@ -1,39 +1,46 @@
 vz - Go binding with Apple [Virtualization.framework](https://developer.apple.com/documentation/virtualization?language=objc)
 =======
 
-[![Build](https://github.com/Code-Hex/vz/actions/workflows/compile.yml/badge.svg)](https://github.com/Code-Hex/vz/actions/workflows/compile.yml)
+[![Build](https://github.com/Code-Hex/vz/actions/workflows/compile.yml/badge.svg)](https://github.com/Code-Hex/vz/actions/workflows/compile.yml) [![Go Reference](https://pkg.go.dev/badge/github.com/Code-Hex/vz/v3.svg)](https://pkg.go.dev/github.com/Code-Hex/vz/v3)
 
 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)](https://docs.oasis-open.org/virtio/virtio/v1.1/csprd01/virtio-v1.1-csprd01.html) specification, which defines standard interfaces for many device types, including network, socket, serial port, storage, entropy, and memory-balloon devices.
 
-## USAGE
+## Usage
 
-Please see the example directory.
+Please see the [example](https://github.com/Code-Hex/vz/tree/main/example) directory.
 
-## REQUIREMENTS
+## Requirements
 
-Higher or equal to Go 1.17.
+- Higher or equal to macOS Big Sur (11.0.0).
+- Latest version of vz supports last two Go major [releases](https://go.dev/doc/devel/release) and might work with older versions.
 
-### macOS Monterey (v12.x.x)
+## Installation
 
-[![Go Reference](https://pkg.go.dev/badge/github.com/Code-Hex/vz/v2.svg)](https://pkg.go.dev/github.com/Code-Hex/vz/v2)
+Initialize your project by creating a folder and then running `go mod init github.com/your/repo` ([learn more](https://go.dev/blog/using-go-modules)) inside the folder. Then install vz with the go get command:
 
-For the latest macOS version is developed on the [master](https://github.com/Code-Hex/vz) branch and released as `v2.x.x`.
-
-You can install by `go get github.com/Code-Hex/vz/v2`
-
-### macOS Big Sur (v11.x.x)
-
-[![Go Reference](https://pkg.go.dev/badge/github.com/Code-Hex/vz.svg)](https://pkg.go.dev/github.com/Code-Hex/vz)
+```
+$ go get github.com/Code-Hex/vz/v3
+```
 
-Some methods of this framework are available and some are not, depending on the version of macOS. Therefore, Go language side also needs to control which methods are available depending on the macOS version.
+Deprecated older versions (v1, v2).
 
-From now on, those available in Big Sur (11.0.0) will be developed on the [v1](https://github.com/Code-Hex/vz/tree/v1) branch and released as `v1.x.x`.
+## Feature Overview
 
-You can install by `go get github.com/Code-Hex/vz`
+- ✅ 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](https://github.com/Code-Hex/vz/wiki/Shared-Directories)
+- ✅ [Virtio Sockets](https://github.com/Code-Hex/vz/wiki/Sockets)
+- ✅ Less dependent (only under golang.org/x/*)
 
-## IMPORTANT
+## Important
 
 For binaries used in this package, you need to create an entitlements file like the one below and apply the following command.
 
@@ -61,6 +68,70 @@ $ codesign --entitlements vz.entitlements -s - <YOUR BINARY PATH>
 
 If you want to use [`VZBridgedNetworkDeviceAttachment`](https://developer.apple.com/documentation/virtualization/vzbridgednetworkdeviceattachment?language=objc), 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. Running this binary on a modern OS (macOS 12.3 or macOS 13) means that these APIs are not available. 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:
+
+```go
+bootLoader, err := vz.NewEFIBootLoader()
+if errors.Is(err, vz.ErrUnsupportedOSVersion) || errors.Is(err, 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](https://developer.apple.com/documentation/virtualization?language=objc). 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](https://github.com/Code-Hex/puipui-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

audio.go

@@ -8,7 +8,7 @@ package vz
 */
 import "C"
 import (
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // AudioDeviceConfiguration interface for an audio device configuration.

bootloader.go

@@ -11,7 +11,7 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // BootLoader is the interface of boot loader definitions.

bootloader_arm64.go

@@ -10,7 +10,7 @@ package vz
 */
 import "C"
 import (
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // MacOSBootLoader is a boot loader configuration for booting macOS on Apple Silicon.

cgoutil.go

@@ -64,7 +64,7 @@ import (
 	"fmt"
 	"unsafe"
 
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // pointer is a type alias which is able to use as embedded type and

clipboard.go

@@ -7,7 +7,7 @@ package vz
 */
 import "C"
 import (
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // SpiceAgentPortAttachment is an attachment point that enables

configuration.go

@@ -9,7 +9,7 @@ package vz
 */
 import "C"
 import (
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // VirtualMachineConfiguration defines the configuration of a VirtualMachine.

console.go

@@ -9,7 +9,7 @@ import "C"
 import (
 	"unsafe"
 
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // ConsoleDeviceConfiguration interface for an console device configuration.

debug.go

@@ -12,7 +12,7 @@ import "C"
 import (
 	"runtime"
 
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // DebugStubConfiguration is an interface to debug configuration.

entropy.go

@@ -7,7 +7,7 @@ package vz
 */
 import "C"
 import (
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // VirtioEntropyDeviceConfiguration is used to expose a source of entropy for the guest operating system’s random-number generator.

example/gui-linux/go.mod

@@ -2,10 +2,10 @@ module github.com/Code-Hex/vz/example/gui-linux
 
 go 1.19
 
-replace github.com/Code-Hex/vz/v2 => ../../
+replace github.com/Code-Hex/vz/v3 => ../../
 
 require (
-	github.com/Code-Hex/vz/v2 v2.0.0-00010101000000-000000000000
+	github.com/Code-Hex/vz/v3 v3.0.0-00010101000000-000000000000
 	github.com/Songmu/prompter v0.5.1
 )
 

example/gui-linux/main.go

@@ -10,7 +10,7 @@ import (
 	"runtime"
 	"time"
 
-	"github.com/Code-Hex/vz/v2"
+	"github.com/Code-Hex/vz/v3"
 )
 
 var install bool

example/gui-linux/rosseta_directory_share.go

@@ -3,7 +3,7 @@
 
 package main
 
-import "github.com/Code-Hex/vz/v2"
+import "github.com/Code-Hex/vz/v3"
 
 func createRosettaDirectoryShareConfiguration() (*vz.VirtioFileSystemDeviceConfiguration, error) {
 	return nil, errIgnoreInstall

example/gui-linux/rosseta_directory_share_arm64.go

@@ -7,7 +7,7 @@ import (
 	"fmt"
 	"log"
 
-	"github.com/Code-Hex/vz/v2"
+	"github.com/Code-Hex/vz/v3"
 	"github.com/Songmu/prompter"
 )
 

example/linux/go.mod

@@ -2,10 +2,10 @@ module github.com/Code-Hex/vz/example/linux
 
 go 1.19
 
-replace github.com/Code-Hex/vz/v2 => ../../
+replace github.com/Code-Hex/vz/v3 => ../../
 
 require (
-	github.com/Code-Hex/vz/v2 v2.0.0-00010101000000-000000000000
+	github.com/Code-Hex/vz/v3 v3.0.0-00010101000000-000000000000
 	github.com/pkg/term v1.1.0
 	golang.org/x/sys v0.1.0
 )

example/linux/main.go

@@ -7,7 +7,7 @@ import (
 	"strings"
 	"syscall"
 
-	"github.com/Code-Hex/vz/v2"
+	"github.com/Code-Hex/vz/v3"
 	"github.com/pkg/term/termios"
 	"golang.org/x/sys/unix"
 )

example/macOS/go.mod

@@ -2,8 +2,8 @@ module github.com/Code-Hex/vz/example/macOS
 
 go 1.19
 
-replace github.com/Code-Hex/vz/v2 => ../../
+replace github.com/Code-Hex/vz/v3 => ../../
 
-require github.com/Code-Hex/vz/v2 v2.0.0-00010101000000-000000000000
+require github.com/Code-Hex/vz/v3 v3.0.0-00010101000000-000000000000
 
 require golang.org/x/mod v0.6.0 // indirect

example/macOS/installer.go

@@ -6,7 +6,7 @@ import (
 	"os"
 	"time"
 
-	"github.com/Code-Hex/vz/v2"
+	"github.com/Code-Hex/vz/v3"
 )
 
 func installMacOS(ctx context.Context) error {

example/macOS/main.go

@@ -9,7 +9,7 @@ import (
 	"runtime"
 	"time"
 
-	"github.com/Code-Hex/vz/v2"
+	"github.com/Code-Hex/vz/v3"
 )
 
 var install bool

example_test.go

@@ -3,7 +3,7 @@ package vz_test
 import (
 	"errors"
 
-	"github.com/Code-Hex/vz/v2"
+	"github.com/Code-Hex/vz/v3"
 )
 
 func ExampleErrUnsupportedOSVersion() {

go.mod

@@ -1,4 +1,4 @@
-module github.com/Code-Hex/vz/v2
+module github.com/Code-Hex/vz/v3
 
 go 1.19
 

graphics.go

@@ -7,7 +7,7 @@ package vz
 */
 import "C"
 import (
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // GraphicsDeviceConfiguration is an interface for a graphics device configuration.

graphics_arm64.go

@@ -10,7 +10,7 @@ package vz
 */
 import "C"
 import (
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // MacGraphicsDeviceConfiguration is a configuration for a display attached to a Mac graphics device.

internal/progress/reader_test.go

@@ -7,7 +7,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/Code-Hex/vz/v2/internal/progress"
+	"github.com/Code-Hex/vz/v3/internal/progress"
 )
 
 func TestReader(t *testing.T) {

keyboard.go

@@ -8,7 +8,7 @@ package vz
 */
 import "C"
 import (
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // KeyboardConfiguration interface for a keyboard configuration.

memory_balloon.go

@@ -7,7 +7,7 @@ package vz
 */
 import "C"
 import (
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // MemoryBalloonDeviceConfiguration for a memory balloon device configuration.

network.go

@@ -14,7 +14,7 @@ import (
 	"syscall"
 	"unsafe"
 
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // BridgedNetwork defines a network interface that bridges a physical interface with a virtual machine.

network_test.go

@@ -4,7 +4,7 @@ import (
 	"net"
 	"testing"
 
-	"github.com/Code-Hex/vz/v2"
+	"github.com/Code-Hex/vz/v3"
 )
 
 func TestFileHandleNetworkDeviceAttachmentMTU(t *testing.T) {

platform.go

@@ -12,7 +12,7 @@ import (
 	"os"
 	"unsafe"
 
-	"github.com/Code-Hex/vz/v2/internal/objc"
+	"github.com/Code-Hex/vz/v3/internal/objc"
 )
 
 // PlatformConfiguration is an interface for a platform configuration.