Documentation · Using OSX-REIMS
Reims vGPU version
Tested or latest version: how to choose, update and go back.
This documentation covers OSX-REIMS 0.6.0, alpha software. Commands and options may change between versions; when in doubt, check osx-reims --help on the installed version.
OSX-REIMS uses Reims vGPU (opens in a new tab), downloaded from its original repository into /opt/reims-vgpu and built on your computer. Each OSX-REIMS version is tested with a specific Reims vGPU commit, but you can choose which version to follow.
Note
OSX-REIMS and Reims vGPU are independent projects, by different authors. OSX-REIMS uses Reims vGPU as third-party software, under its authors' license, and takes no part in its development.
Tested or latest
| Version | What it is |
|---|---|
| Tested | The commit tested with your OSX-REIMS version. It is the default and the recommended choice |
| Latest | The newest commit of the Reims vGPU master branch, not yet tested with OSX-REIMS |
In OSX-REIMS 0.6.0, the tested version is commit c099dd5a, already on the rewritten Reims vGPU (see below). Up to 0.4.1, it was commit 69a57dd6.
The choice is made on the first run of osx-reims setup and is saved. osx-reims doctor shows which version the computer follows.
Warning
The latest version may bring fixes and new features, but it may also fail to build or keep the VMs from starting. If that happens, go back to the tested one.
Changing version or updating
With all VMs shut down, run:
osx-reims update-reimsOr, in the console, choose Maintenance › Update Reims vGPU. The command:
- asks which version to follow, offering your current choice;
- shows the current commit, the new one, how many commits change and the version followed;
- asks for confirmation; for an untested version, the default answer is no;
- checks out the new commit and builds Reims vGPU: first its library, then QEMU on it. The build takes a few minutes, and the VMs cannot start until it finishes.
If Reims vGPU is already at the chosen commit, nothing is built. To build it again anyway, use osx-reims setup --rebuild.
Following the latest version does not bring in new commits by itself: run osx-reims update-reims again to fetch the newest commit of master. setup keeps the commit that is already built.
Rebuilding the same version from scratch
A build that used to work can stop working after a system update, which moves libraries under a build already made, or after a build interrupted half way. With every VM shut down:
osx-reims rebuild-reimsIn the console the same thing is Maintenance › Rebuild Reims vGPU. It builds QEMU-Reims again, from scratch, at the same commit: nothing is downloaded and the version followed does not change. It is not the same as setup --rebuild, which builds over the folder that is there — which does not help when the folder itself is the problem.
The current build is not deleted first: it is moved aside and removed only once the new one passes the same checks setup makes. If the build or the checks fail, or you interrupt it with Ctrl+C, the previous one goes back in place and the VMs start as before. The command stops before changing anything when the QEMU source is missing or at another commit, when the build folder holds files owned by another user, or when there is less than 3 GB free next to Reims vGPU.
If the new version fails
If the new commit fails to build or to pass the checks, update-reims goes back to the commit that worked and builds it again, so the VMs start as before. The log shows what failed.
If the new version builds but the VMs do not start with it, go back to the tested one:
osx-reims update-reims --testedOSX-REIMS' fixes to Reims vGPU
OSX-REIMS applies fixes of its own to Reims vGPU during the build and takes them back right after it, so the /opt/reims-vgpu folder stays as its commit has it. They were made for the tested commit:
- one fixes the black window of a VM on an NVIDIA GPU under compositors without explicit sync, such as vGPU OS's;
- another has OpenCore's picker, the Apple logo and macOS Recovery drawn at about 60 frames a second, instead of 10.
On another commit (the latest version or a chosen commit), a fix that no longer applies is left out, with a warning in setup's log (building without it). To go back to the tested commit and its fixes, use osx-reims update-reims --tested.
The rewritten Reims vGPU
OSX-REIMS 0.6.0 is tested with a commit after Reims vGPU's rewrite, which replaced the whole project: macOS now sees QEMU's apple-gfx-pci graphics device, which uses Apple's own driver, and the Reims vGPU library is linked into QEMU. The VM window is new too: click into it to give macOS the keyboard, and use Ctrl+Alt+Super to give it back to Ubuntu.
When 0.6.0 is installed over an earlier version, the Reims vGPU on the computer is still the one from before the rewrite, and start says so: This version of OSX-REIMS needs the new Reims vGPU. With all VMs shut down, run:
osx-reims update-reims --testedIt moves Reims vGPU to the new commit, cleans up what is left of the old build and builds it again (about 3 minutes, plus the download). Existing VMs keep their own disks, identity and settings. The old build, in /opt/reims-vgpu/vendor/qemu/build, is not deleted: it can be removed afterwards to get its space back.
When installing a new OSX-REIMS version
A new OSX-REIMS version may be tested with a different Reims vGPU commit. If the computer follows the tested version and it changed, the package installation tells you to run osx-reims update-reims, with the VMs shut down. If it follows the latest version or a chosen commit, the installation reminds you that updating is up to you.
A specific commit (advanced)
The --reims-ref <ref> option of setup and update-reims accepts a Reims vGPU commit, tag or branch. That choice is not tested and stays saved until you choose --tested or --latest.
Note
Local changes in /opt/reims-vgpu stop setup and update-reims: nothing is cleaned or reset automatically.