Contributing to vftool

Contributions to vftool are welcome. As a minimalist project, the focus is on maintaining simplicity and stability.

Development Setup

To get started with development, you'll need to set up a build environment, which is the same as the command-line installation process.

  1. Prerequisites: Ensure you have Xcode or the Xcode Command Line Tools installed.

    xcode-select --install

  2. Clone the repository:

    git clone https://github.com/evansm7/vftool.git
    cd vftool

  3. Build the project:

    make
    The compiled binary will be located at build/vftool. You can run make clean to remove build artifacts.

Code Overview

The entire logic of vftool is contained within a single file: vftool/main.m.

  • main() function: This is the entry point. It handles parsing command-line arguments using getopt and sets up default values.
  • getVMConfig(...) function: This is the core of the application. It takes the parsed arguments and constructs a VZVirtualMachineConfiguration object by setting up the bootloader, CPU, memory, and all necessary virtio devices.
  • createPty(...) function: A helper function for creating and managing the pseudo-terminal for the console.

Code Signing and Entitlements

To interact with Virtualization.framework, the compiled binary must be signed and include a specific entitlement.

  • Entitlements: The required entitlement, com.apple.security.virtualization, is defined in vftool/vftool.entitlements.
  • Signing: The Makefile automatically handles signing during the build process using the codesign command:
    sign:   build/vftool
        codesign --entitlements vftool/vftool.entitlements --force -s - $<
    The -s - argument creates an ad-hoc signature, which is sufficient for local development and running the tool on your own machine.

Submitting Changes

  1. Fork the repository on GitHub.
  2. Create a new branch for your feature or bug fix.
  3. Make your changes in the vftool/main.m file.
  4. Build and test your changes locally.
  5. Commit your changes and push them to your fork.
  6. Open a pull request against the main branch of the original repository.