PIC

OpenCore

Reference Manual (0.6.2.3)

[2020.11.24]

Copyright ©2018-2020 vit9696


 12.4 Debugging
 12.5 Tips and Tricks

1 Introduction

This document provides information on OpenCore user configuration file format used to set up the correct functioning of the macOS operating system. It is to be read as the official clarification of expected OpenCore behaviour. All deviations, if found in published OpenCore releases, shall be considered to be documentation or implementation bugs which should be reported via the Acidanthera Bugtracker. An errata sheet is available in OpenCorePkg repository.

This document is structured as a specification and is not meant to provide a step-by-step guide to configuring an end-user Board Support Package (BSP). The intended audience of the document is anticipated to be programmers and engineers with a basic understanding of macOS internals and UEFI functionality. For these reasons, this document is available exclusively in English, and all other sources or translations of this document are unofficial and may contain errors.

Third-party articles, utilities, books, and alikesimilar, may be more useful for a wider audience as they could provide guide-like material. However, they are subject to their authors’ preferences, tastes, misinterpretations of this document, and unavoidable obsolescence. In cases of using such sources, such as Dortania’s OpenCore Install Guide and related material, please refer back to this document on every decision made and re-evaluate potential consequences.

Please note that regardless of the sources used, users are required to fully understand every OpenCore configuration option, and the principles behind them, before posting issues to the Acidanthera Bugtracker.

Note: Creating this document would not have been possible without the invaluable contributions from other people: Andrey1970, Goldfish64, dakanji, PMheart, and several others, with the full list available in OpenCorePkg history.

1.1 Generic Terms

Note: It is not guaranteed that paths longer than OC_STORAGE_SAFE_PATH_MAX (128 characters including
0-terminator) will be accessible within OpenCore.

3.2 Installation and Upgrade

To install OpenCore reflect the ?? described in the previous section on a EFI volume of a GPT partition. While corresponding sections of this document do provide some information in regards to external resources like regarding external resources such as ACPI tables, UEFI drivers, or kernel extensions (kexts), completeness of the matter is out of the scope of this document. Information about kernel extensions may be found in a separate Kext List document available in OpenCore repository. Vaulting information is provided in ?? section of this document.

OC config, just like any property lists can be edited with any stock textual editor (e.g. nano, vim), but specialised software may provide better experience. On macOS the preferred GUI application is Xcode. For a lightweight cross-platform and open-source alternative ProperTree editor can be utilised.

For BIOS booting a third-party UEFI environment provider will have to be used. OpenDuetPkg is one of the known UEFI environment providers for legacy systems. To run OpenCore on such a legacy system, OpenDuetPkg can be installed with a dedicated tool — BootInstall (bundled with OpenCore). Third-party utilities can be used to perform this on systems other than macOS.

For upgrade purposes refer to Differences.pdf document, providing the information about the changes affecting the configuration compared to the previous release, and Changelog.md document, containing the list of modifications across all published updates.

3.3 Contribution

OpenCore can be compiled as an ordinary EDK II package. Since UDK development was abandoned by TianoCore, OpenCore requires the use of EDK II Stable. Currently supported EDK II release is hosted in acidanthera/audk. The required patches for the package are present in Patches directory.

The only officially supported toolchain is XCODE5. Other toolchains might work, but are neither supported, nor recommended. Contribution of clean patches is welcome. Please do follow EDK II C Codestyle.

To compile with XCODE5, besides Xcode, one should also install NASM and MTOC. The latest Xcode version is recommended for use despite the toolchain name. Example command sequence may look as follows:

git clone --depth=1 https://github.com/acidanthera/audk UDK 
cd UDK 
git submodule update --init --recommend-shallow 
git clone --depth=1 https://github.com/acidanthera/OpenCorePkg 
source edksetup.sh 
make -C BaseTools 
build -a X64 -b RELEASE -t XCODE5 -p OpenCorePkg/OpenCorePkg.dsc
Listing 1:Compilation Commands

For IDE usage Xcode projects are available in the root of the repositories. Another approach could be Sublime Text with EasyClangComplete plugin. Add .clang_complete file with similar content to the UDK root:

-I/UefiPackages/MdePkg 
-I/UefiPackages/MdePkg/Include 
-I/UefiPackages/MdePkg/Include/X64 
-I/UefiPackages/MdeModulePkg 
-I/UefiPackages/MdeModulePkg/Include 
-I/UefiPackages/MdeModulePkg/Include/X64 
-I/UefiPackages/OpenCorePkg/Include/AMI 
-I/UefiPackages/OpenCorePkg/Include/Acidanthera 
-I/UefiPackages/OpenCorePkg/Include/Apple 
-I/UefiPackages/OpenCorePkg/Include/Apple/X64 
-I/UefiPackages/OpenCorePkg/Include/Duet 
-I/UefiPackages/OpenCorePkg/Include/Generic 
-I/UefiPackages/OpenCorePkg/Include/Intel 
-I/UefiPackages/OpenCorePkg/Include/Microsoft 
-I/UefiPackages/OpenCorePkg/Include/VMware 
-I/UefiPackages/OvmfPkg/Include 
-I/UefiPackages/UefiCpuPkg/Include 
-IInclude 
-include 
/UefiPackages/MdePkg/Include/Uefi.h 
-fshort-wchar 
-Wall 
-Wextra 
-Wno-unused-parameter 
-Wno-missing-braces 
-Wno-missing-field-initializers 
-Wno-tautological-compare 
-Wno-sign-compare 
-Wno-varargs 
-Wno-unused-const-variable 
-DOC_TARGET_NOOPT=1 
-DNO_MSABI_VA_FUNCS=1
Listing 2:ECC Configuration

Warning: Tool developers modifying config.plist or any other OpenCore files must ensure that their tool checks for opencore-version NVRAM variable (see Debug Properties section below) and warn the user if the version listed is unsupported or prerelease. OpenCore configuration may change across the releases and the tool shall ensure that it carefully follows this document. Failure to do so may result in this tool to be considered as malware and blocked with all possible means.

3.4 Coding conventions

Just like As with any other project, we have conventions that we follow during the development. All third-party contributors are highly recommended to read and follow advised to adhere to the conventions listed below before submitting their patches. In general it is also recommended to firstly discuss the issue in patches. To minimise abortive work and the potential rejection of submissions, third-party contributors should initially raise issues to the Acidanthera Bugtracker before sending the patch to ensure no double work and to avoid the patch being rejectedfor feedback before submitting patches.

Organisation. The codebase is contained in the OpenCorePkg repository, which is the primary EDK II package.

Design. The codebase is written in a subset of freestanding C11 (C17) supported by most modern toolchains used by EDK II. Applying common software development practices or requesting clarification is recommended if any particular case is not discussed below.

Codestyle. The codebase follows EDK II codestyle with few changes and clarifications.

3.5 Debugging

The codebase incorporates EDK II debugging and few custom features to improve the experience.

When trying to find the problematic change it is useful to rely on git-bisect functionality. There also are some unofficial resources that provide per-commit binary builds of OpenCore, like such as Dortania.