Jump to content

[GUIDE] Updating OpenCore with Kext Updater and OCConfigCompare (plus config Tips and Tweaks)


5 posts in this topic

Recommended Posts

Preface: In this guide I will show you a reliable method of keeping your OpenCore bootloader up to date without any issues and provide some useful tips and tweaks along the way. Since there is no tool out yet to update the bootloader files and config automatically most of it has to be done manually (for now).

 

Last Update: July 19th, 2021

 

The issue: Unlike Clover, almost every aspect of OpenCore has to be defined in the config.plist. Apart from settings, this includes which SSDTs, Drivers and Kexts are loaded as well as the order they are loaded in. Since OpenCore is in on-going development, it is important to know that with each new build features can be added, removed, renamed or relocated to other categories of the config. These changes have to be reflected by the config.plist, to avoid "No schema for…" errors like these during boot:

 

NoSchema.jpg.4581c482522edc7ce66b65add466701b.jpgThe further apart two OpenCore builds are, the more time-consuming it is to update and the more has to be done. For example, the important "OpenRuntime.efi" was previously called  "FwRuntimeServices" prior to version 0.5.7. So when updating OpenCore, you not only have to replace old files with new ones, you may have to delete files and update the config by creating a new snapshot of the config using ProperTree to to include it in them in the config if you don't want to do it manually. So at some stage it is probably wiser to start building your EFI from a fresh clean slate using OC Gen X to generate a basic EFI and build from there rather than bringing an old build up to date.

 

DISCLAIMER: This is not a guide to create a working OpenCore configuration! For this please use the OpenCore Install Guide from Dortania or search the Forums.

 

TL;DR QUICK GUIDE (for experienced users):

  • Mount the EFI Partition and copy the EFI Folder to an USB stick in FAT32 format.
  • CAUTION: disable Bootstrap if enabled, reboot, reset NVRAM before updating to 0.6.6 and newer! More details here
  • Download and unpack the latest OpenCore Package or grab the latest nightly build from here
  • Replace Boot, OpenCore.efi, Drivers, Kexts and existing Tools in the EFI folder on the USB stick
  • Compare config.plist with Sample.plist (OCConfig Compare), include new/missing/changed/deleted/moved entries in config.plist
  • Validate config.plist with ocvalidate and correct errors if necessary
  • Boot from USB stick (NVRAM reset may be required)
  • if boot is successful, replace EFI folder on your hard disk with the one from USB stick
  • Have a look at  OpenCore Config Tipps & Tweaks En.pdf

 

 

STEP-BY-STEP GUIDE (for everybody else)

Since the order of operations is important to properly update the OpenCore and avoid boot errors, please don't skip or change the sequence of the steps unless you know what you are doing.

 

I. Preparation/Tools:

  • Disable System Integrity Protection (SIP). In order for Kext Updater to work properly you need to disable SIP. Instructions on how to do so can be found here:
  • Terminal: To find out the currently used version of OpenCore, enter: nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:opencore-version
  • MacDown (optional): free app to open and edit markdown files like the "changelog.md" included in every OpenCore packge under "Docs". Important keywords, to look out for when inspecting the changelog are: Added, Changed/Renamed, Removed/Deleted, Moved.
    Whenever any of these terms appear in the changelog followed by some highlighted text, you most likely have to edit the config.plist to reflect the updated/changed feature-set. If you don't want to install an extra App for that you can use the changelog online of course: https://github.com/acidanthera/OpenCorePkg/releases
  • Kext Updater One of the must-have tools for maintaining your system, imo. It can download OpenCore, Clover, Drivers and Kexts. It also has useful tools like validating the config, creating EFI Backups, updating the Kernel Cache, Kext of downloaded EFI Folders etc. It is a tremendous time saver for checking for kext updates and gathering files.
  • ProperTree and a plist Editor. I use a combination of ProperTree for creating snapshots of and PlistEditPro for editing the config.plist. There's also the free open-source, cross-platform PlistEDPlus
    CAUTION: Please don't use dedicated GUI-based Config Editors like OpenCore Configurator yet. Although convenient, they can ruin your config if they are not up to par with the latest feature-set of OpenCore which can change on a daily basis by features getting added, juggled around or removed. Dedicated Config Editors have to accommodate for these changes by an update to represent the changed feature-set. So they are always slightly behind in development. With a simple plist Editor you can avoid this problem altogether. From my experience, a simple plist editor is also much more practical when copying over multiple lines from one plist to another at once. Plist Editors are faster to operate, structured more logical and allow to comment-out lines with "#" if you want to test something but want to keep a "backup" of the original entry, like a framebuffer-patch for example. You cannot do this with dedicated GUI-based config editors.
  • OCConfigCompare A Python script to compare two OC config.plists. If Python is not present, Terminal will download and install it automatically for you. No longer necessary since it is integrated in Kext Updater's Tool Section since version 3.8.6

II. Update Example 1: Updating a downloaded OpenCore EFI Folder

We all know this scenario: you want to try OpenCore but you don't know how to configure it and don't want to go through the install guide. So you look for an EFI on the net but it's outdated and produces a bunch or errors is you try it or won't boot at all. For this example, I am using an older version of an EFI folder for my previous Boards from this thread to demonstrate how to update it correctly. It's for version 0.6.0 so there's probably a lot to do to update it.

 

1. Gathering latest versions of OpenCore, Kexts, Drivers and Resources using Kext Updater

  1. Extract the downloaded zip of the EFI Folder you downloaded from the Internet
  2. Disable SIP and reboot so Kext Updater fully works. Instructions:
  3. Open Kext Updater and click on "Bootloader"
  4. Select "OpenCore" in both drop-down menus and hit "Download". This will download the latest release version of OpenCore to your Desktop > Kext-Updates by default
  5. Click on "Bootloader" again but this time select "OcBinaryData" from the right drop-down menu and click "Download"
  6. Back in the Main of Kext Updater, click on "Tools"
  7. Click on "Choose Folder", navigate to the downloaded EFI Folder and click "Open"
  8. Finally, click the highlighted "Check for Updates" button. Kext Updater will downloads the latest Kexts for the specified EFI to the Kext-Updates folder on your Desktop (your Kext-Updates Folder will included files for your system so it will look different):

gathererdfiles.png.6fcac1980ce1810c3a5eb35c2aa29f0d.png

Now that we have gathered all necessary files we can start updating OpenCore…

 

2. Updating OpenCore Files, Drivers, Kexts and Resources

Next, we will Update the OpenCore Files of the downloaded EFI Folder. To do so, drag and replace the following files from Kext-Updates to your downloaded EFI Folder. These files have to be replaced every time you update OpenCore:

  • EFI > BOOT > BOOTx64.efi
  • EFI > Bootstrap > Bootstrap.efi CAUTION: Bootstrap is included in OpenCore.efi since version 0.6.6. To safely disable and delete bootstrap.efi, please follow this guide
  • EFI > OC > OpenCore.efi
  • EFI > OC > Drivers > Only Replace existing .efi drivers, not the whole folder!.
    NOTE: Proprietary File System Drivers like HfsPlus.efi etc. are located in the OcBinaryData Package.
    CAUTION: If you are updating from OpenCore 0.5.6 or earlier, delete FwRuntimeServices.efi and replace it with OpenRuntime.efi!
  • Kexts: copy and replace all the downloaded .kext files. Any by .kext files I mean .kext ONLY. No Sub folders, no additional content like .dsls etc. – just .kext fIles.

If you use OpenCanopy for the GUI-based Boot Picker, copy over the "Resources" Folder from OcBinaryData as well. You only need to update the Resources if the Boot Picker doesn't work as expected after the release of a new OC build. Congratulations, you've successfully updated your OpenCore EFI Folder! Now on to the strenuous part: updating the config.plist…

 

3. Updating the config.plist using OCConfigCompare

  • Double-click OCConfigCompare.command to start the tool. Open the "Tools" Section in Kext Updater and click the "OCConfigCompare" Button
  • Press "5" and hit "Enter" to hide certain entries to be displayed from the results of the config comparison.
  • Press "2" to "Hide comments (#), PciRoot, and most OC NVRAM samples". Press "M" and hit "Enter" to return to the Main Menu
  • Press '1"' to download the latest Release Sample or '2' to download the latest Commit Sample (for nightly builds only)
  • Press "4", drag in your config.plist and hit "Enter"
  • Back in the Main Menu, Press '7' and hit Enter to begin the config comparison

The resulting output will contain 2 Sections: "Values missing from User plist" and "Values missing from Sample plist" and may look like this:

943164700_MissingfromUserConfig.thumb.png.00841d3d60b45a423312d3d9a7587d57.png

3.1 Interpreting the Results

What "Missing from user plist" means is pretty obvious. "Missing from Sample plist" on the other hand is not. It means that these entries/parameters are no longer being used in the current build of OpenCore and have to be deleted from the config.plist. So in other words, "Missing from Config plist" means adding entries to the config while "Missing from Sample plist" means deleting them. In this case, the list of missing entries is so long, that the "Missing from Sample plist" Section doesn't even fit in the visible screen space… oh boy…

 

3.2 Window Arrangement
Next, we need to arrange our workspace a bit to be able see both configs and the results from OCConfigCompare at the same time. I usually arrange my windows like this: config.plist on the left, sample.plist on the right and OCConfigCompare on the bottom. With the three windows in front of you, use OCConfigCompare as an aid to navigate through the sample config to find parameters to copy over to the config.plist:

1598073699_Arrangeworkspace.thumb.png.a63e1482b99b4127f87f4bad4f2dcc83.png

 

3.3 Adding version Info to the config.plist (optional but recommended)

Since you can only find out which build of OpenCore you are actually using is while it's running, it's good practice to include some basic information about the Build and System in your config – especially if plan on sharing it. In this case I added "#OC Version", #Date" and #Board/Chipset as Strings in PlistEditPro at the beginning of the config.plist. It's important to hash out ("#") the added lines, otherwise OpenCore thinks it's an instruction. Things like this you cannot do with GUI-based config editors.

 

3.4 Config Editing workflow

Now that we have all the windows arranged in a useful way, we can finally start to update the config line for line. This is how I do it:

  1. Check a) which Section of the config OCConfigCompare is referring to and b) which Parameter is missing from User Plist
  2. Navigate to said section in the Sample.plist, look for the parameter in question and either copy and paste it to the same location in the config.plist or drag and drop it
  3. Repeat from step 1 until nothing is missing from User Plist any longer.
    TIP:
    Save the config in between steps to shrink the list and update the results list. In OCConfigCompare, hit "Enter" to return to the main menu and then hit "5" and "Enter" again to compare the two configs again and continue working.
  4. Once you reached "Missing from Sample plist" section, the workflow changes. Now instead of adding things to the config.plist we delete entries from the config.plist
  5. Repeat step 4 until you reach the end of the list
  6. Save the config
  7. Update OCConfigCompare list.

NOTE: You can ignore the following results form OCConfigCompare: "DeviceProperties" and "Type Differences" if the selected parameter supports more then one Type of value  (like Integer, Data or Number). Here's a video of how this particular config.plist was updated:

 

 

4. Create a new Snapshot of the config.plist using ProperTree

In order to reflect any changes made to the file and folder structure of the updated EFI folder, it is a good idea to create a new snapshot of your config.plist using ProperTree. ProperTree also detects possible conflicts in the config.plist and can fix them automatically.

  1. Download and extract ProperTree
  2. In Finder, navigate to the ProperTree-master > Scripts Folder
  3. Double-click "buildapp.command". In Big Sur this may not work - use "buildapp-python3.command" instead
  4. This will compile the ProperTree App
  5. Run ProperTree
  6. Open the updated .plist (CMD+O)
  7. Click on File > OC Snapshot (CMD+R)
  8. Navigate to the updated EFI Folder > EFI > OC and click "Open"
  9. Save the config and quit ProperTree

5. Checking the config.plist for validity

Although ProperTree is great for synchronizing the config.plist with the contents of its EFI folder, it does not detect configuration issues or syntax errors in 'DeviceProperties' for example. To validate your config, you can either use Kext Updater or ocvalidate located in the downloaded OpenCore Package under "Utilities". In this example, we use Kext Updater since it is more user friendly foe novices. You'd be surprised how many configuration issues this will reveal you didn't know your config had… Happens all the time.

  1. In Kext Updater, click on "Tools"
  2. On the right click on "Choose .plist", navigate to the config.plist you want to validate (in this case the one from the downloaded EFI folder) and click "Open"
  3. Next, click "Check for validity". The remaining issues will be display in the main window.
  4. Use a combination of sample.plist, Dortania Installation Guide and/or Configuration.pdf located in the OpenCore Package under "Docs" to resolve the issues
  5. Validate the config again
  6. Repeat Steps 2 to 5 until all issues are fixed (ideally).

6. Copy updated EFI Folder to FAT32 formatted USB Stick

7. Reboot from USB Stick to test if the updated EFI works

8. Perform NVRAM Reset

9. Boot macOS

10. If the boot is successful, replace the system EFI with the one from the USB Stick

 

DONE! Congratulations you successfully updated OpenCore to the latest version!


II. Update Example 2: Updating/Maintaining the system's EFI Folder

Updating your system's EFI folder basically works the same as updating a downloaded EFI folder. The only difference is that we store a backup to a USB stick and perform the actual update directly on the mounted ESP. There are less steps to perform overall and the workflow in Kext Updater differs slightly.

1. Gathering latest versions of OpenCore, Kexts, Drivers and Resources using Kext Updater

  1. Disable SIP if you haven't already and reboot so Kext Updater fully works.
  2. Open Kext Updater, grand it admin privileges and hit the red "EFI" button to mount it. If it turns green the EFI is mounted
  3. IMPORTANT Backup your working EFI Folder to a FAT32 formatted USB Stick as a fallback to boot from if the system won't boot after updating OpenCore
  4. Back in Kext Updater, click on "Check" to download the latest kexts for your EFI. They will be stored in Desktop > Kext-Updates by default
  5. Click on "Bootloader"
  6. Select "OpenCore" in both drop-down menus and hit "Download". This will download the latest release version of OpenCore
  7. Click on "Bootloader" again but this time select "OcBinaryData" from the right drop-down menu and click "Download"

Steps 2 to 5 follow the same procedure as in Example 1 except that you are now working on your system EFI and config located on the ESP.

6. Reboot System

7. Perform NVRAM Reset

8. Start macOS. If the boot fails, start your Hackintosh from the backup on your USB Stick, fix the issue(s) and try again.

 

DONE! Congratulations you successfully updated OpenCore to the latest version!

 

II. Update Example 3: Migrating data from an outdated config.plist into the latest OpenCore build

As seen in example 1, updating an old config.plist can be tedious and time consuming task. Depending on the results of OCConfigCompare you may reach a junction where you have to decide: "do I update this config or should build it fresh from the current sample?". Well, if the difference in versions of two OpenCore builds is greater than 0.0.3 you should consider building the config fresh from scratch using OC Gen-X. Here's why: OpenCore builds are released on a monthly basis and with each release their version increases in 0.0.1 increments which is equivalent to one month of development time. So although a version difference of 0.0.7 (as in example 1) might seem pretty small, in reality it's a big deal because it resembles seven months of development time, which is an eon! So at this stage it's probably a good idea to generate a fresh EFI Folder using OC Gen-X and implement ACPI Patches and Settings from the existing config – especially if it is a Desktop PC. Here's how you do it:

  1. Download, unpack and run OC Gen-X
  2. Click through the different Tabs of the App and select everything you need for your config. It's pretty straight forward and self-explanatory
  3. Hit "Generate". An EFI Folder will be created on the Desktop
  4. From the old EFI folder copy over the ACPI Folder
  5. Copy over the Following sections from your old config into the current:
    • ACPI > Add
    • ACPI > Delete
    • ACPI > Patch
    • DeviceProperties
    • Kernel > Patch
    • Platforminfo > Generic
  6. Run Kext Updater check the EFI Folder on the Desktop for Kext Updates
  7. Hit "Kext Manager" and check all additional Kexts you may need for your System which are not included in OC Gen-X and hit "Download".
  8. Add the necessary Kexts to the EFI Folder
  9. Generate a snapshot of your config using ProperTree
  10. Check your config for errors using the OCValidate Utility or OpenCore config.plist Sanity Checker (out of date)
  11. Fix any errors that may occur (like Booter and Kernel Quirks) with the OpenCore Installation Guide for your platform
  12. Re-Check the config again
  13. Put the EFI Folder on a FAT32 formatted USB Stick and try booting from it
  14. If it works, congratulations. If it doesn't start over from Step 11.
  15. Once everything is working, copy the EFI Folder to your system ESP

 

DONE!

Edited by 5T33Z0
  • Like 3
  • Thanks 3

 

58 minutes ago, 5T33Z0 said:

Since there is no tool out yet to update the bootloader files and config automatically most of it has to be done manually (for now).

@5T33Z0

Nice guide thanks; I think you forgot (or haven't used) a very useful tool by @Pavo called OC-Gen-X which helps to build and configure latest version of OpenCore and the kexts for various systems.

I just thought you might wanna add it to your guide.

  • Like 1
Posted (edited)

@Cyberdevs I haven't forgot. It's just another scnenario I will add later. Btw, is there an advanced mode in the editor to see the pure text? I think there are some hidden elements in the text I copied over form Typora which mess up the formatting.

Edited by 5T33Z0
  • 5T33Z0 changed the title to [GUIDE] Updating OpenCore with Kext Updater and OCConfigCompare (plus config Tips and Tweaks)
  • 1 month later...
×
×
  • Create New...