Merge pull request geerlingguy#3 from MatthiasWinkelmann/master

Updates and improvements for macOS Sierra

README.md

@@ -1,24 +1,40 @@
 # macOS VirtualBox VM Instructions
 
-*Current macOS version*: Sierra (10.12)
+Current macOS version: *Sierra (10.12)*, tested with VirtualBox *5.1.6 r110634*
 
 To build a VM running macOS, follow the directions below:
 
   1. Download the installer from Mac App Store (it should be available in the 'Purchases' section if you've acquired it previously). The installer will be placed in your Applications folder.  (Should work for Yosemite, El Capitan and Sierra - 10.10-10.12.)
-  2. If you downloaded the Yosemite installer, run the included `prepare-iso.sh` script (make it executable first, with `chmod +x`, then run `./prepare-iso.sh` from the folder containing the script).  A new installer iso will eventually be saved to the Desktop.
+  2. Make the script executable and run it: `chmod +x prepare-iso.sh && ./prepare-iso.sh`.
+
+      If the script fails to find the installer you can specify its path as the first parameter. By default, the output is saved as <Yosemite|El Capitan|Sierra>.iso on the Desktop. You can change this using the second parameter.
+      Example:
+
+        ```./prepare-iso.sh /Applications/Install\ macOS Sierra\ 2.1\ Beta\ 2.app /Users/Steve/sierra-2.1-b2.iso```
+
   3. Open VirtualBox and create a new VM.
-  4. Set name, type, and version (set to Sierra for 'Version'). (This might not be necessary in the latest VirtualBox release.)
-  5. Follow the rest of the VM creation wizard and either leave the defaults or adjust to your liking. Be sure to at least increse video memory to 128 MB, otherwise the VM might not boot.
+  4. Set:
+      - name: your choice
+      - type: `OS X`
+      - version: `Mac OS X 10.11 El Capitan (64-bit)` or `macOS Sierra`, if your version of VirtualBox has been updated to include it.
+  5. Follow the rest of the VM creation wizard and either leave the defaults or adjust to your liking. You may want to increase the video memory from the VirtualBox default of 16MB to 64MB or 128MB. While the current release of macOS Sierra does boot with just 16MB, interace performance is severly constraint.
   6. In Terminal, run the command `VBoxManage modifyvm "{vmname}" --cpuidset 00000001 000306a9 00020800 80000201 178bfbff` (where `"{vmname}"` is the exact name of the VM set in step 4) so the VM has the right CPU settings for macOS.
   7. To prevent choppiness in the VM, go into settings and uncheck the 'Enable Audio' option under 'Audio'.
   8. Click 'Start' to boot the new VM.
   9. Select the iso created in step 2 when VirtualBox asks for it.
-  10. Once the installer appears, instead of clicking 'Continue', first go to Utilities > Disk Utility and partition/format the VirtualBox disk as a "Mac OS Extended (Journaled)" drive.
-  11. Quit Disk Utility, and then continue with installation as normal.
+  10. In the installer, select your preferred language.
+  11. Go to `Utilities > Disk Utility`. Select the VirtualBox disk and choose `Erase` to format it as a `Mac OS Extended (Journaled)` drive.
+  12. Quit Disk Utility, and then continue with installation as normal.
+
 
-When the installation is complete, and you have a fresh new macOS VM, you can shut it down and create a snapshot so you can go back to the initial state in the future. I use this technique to test the [`mac-dev-playbook`](https://github.com/geerlingguy/mac-dev-playbook), which I use to set up and configure my own Mac workstation for web and app development.
+## Troubleshooting & Improvements
 
-I've noticed that sometimes I need to go in and explicitly mark the iso as a Live CD in the VM settings, in order to get the VM to boot from the image.
+- I've noticed that sometimes I need to go in and explicitly mark the iso as a Live CD in the VM settings in order to get the VM to boot from the image.
+- Conversly, VirtualBox sometimes does not eject the virtual installer DVD after installation. If your VM boots into the installer again, remove the ISO in `Settings -> Storage`.
+- VirtualBox uses the left command key as the "host key" by default. If you want to use it for shortcuts like `command+c` or `command-v` (copy&paste), you need to remap or unset the "Host Key Combination" in `Preferences -> Input -> Virtual Machine`.
+- The default Video Memory of 16MB is far below Apple's official requirement of 128MB. Increasing this value may help if you run into problems and is also the most effective performance tuning.
+- Depending on your hardware, you may also want to increase RAM and the share of CPU power the VM is allowed to use.
+- When the installation is complete, and you have a fresh new macOS VM, you can shut it down and create a snapshot. This way, you can go back to the initial state in the future. I use this technique to test the [`mac-dev-playbook`](https://github.com/geerlingguy/mac-dev-playbook), which I use to set up and configure my own Mac workstation for web and app development.
 
 ## Notes