Repository files navigation

A minimal framework for fast, secure, and reliable build and dependency management forOpenCore EFIs.

OCE-Build is designed to help enable projects to be highly composable and easilymaintainable, prioritizing a small git-friendly footprint. It is designed to beflexible and extensible for existing projects, while also providing a simpleconfiguration and interface for new projects to get started quickly.

• Declarative Configuration
  • Minimal project configuration.
  • Flexible support for any project structure.
  • Shared/Template config.plist configurations.
  • Automated config.plist schema conflict resolution.
• Version Management
  • Versioning for OpenCore binaries and resources (Kexts, SSDTs, etc).
  • Automatic version resolution for dependencies.
  • Lockfile creation for intelligent registry management.
• Build Support
  • Incremental builds and cache management from lockfile.
  • Advanced ACPI language support, including compiler and patchfile options.
  • Dependency sorting for proper prelink injection (i.e. SSDTs, Kexts).
  • CI support for managing and building Kexts with XCode.

This section is for users looking to integrate this tool with their own project.For information on contributing to this project, refer to theDeveloper Docs

This project is distributed as both a standalone CLI and a Python library onPyPI. The CLI is intended to be used for simple projects or for CI/CD, while thelibrary is intended to be used for supporting Python library development orcomplex build pipelines. The library also comes bundled with the CLI and it'ssource code is available under theocebuild.cli module.

The recommended way to install the CLI is fromGitHub releases. This will provide you with a standalone executable that can be used without installing Python or any other dependencies. The CLI is available for Windows, macOS, and Linux.

To install the CLI / library from PyPI, you will need to have Python 3.8 orlater installed. You can install Python frompython.orgor from your package manager. For more information on installing Python, referto thePython documentation.

To install the library directly from PyPI usingpip, simply run the followingcommand in your terminal:

pip install ocebuild

Or when using thepoetry package manager, run:

poetry add ocebuild

Depending on your system, you may need to usepip3 instead ofpip wheninstalling the library. You may also need to usesudo orpip install --userto install the library globally or locally, respectively.

After installing the library, the CLI will also be available in your PATH, whichyou can invoke by simply runningocebuild in your terminal (orpoetry run ocebuild).

To get started, you will need to create abuild.yml file in the root of yourproject. This file will contain all of the information needed to build your EFI.You can follow along with the below example or reference one of theexample projects included in this repository.

The following is a minimal example of abuild.yml file located under asrc/directory:

# src/build.yml---build:DEBUGversion:latest---ACPI:Drivers:  -AudioDxe  -HfsPlus  -OpenRuntime  -ResetNvramEntryKexts:Lilu:latestVirtualSMC:latestResources:Tools:  -OpenShell

Once you have created yourbuild.yml file, you can run the build command tobuild your EFI:

ocebuild build --cwd src/build.yml

This will create a newdist/ directory in your project containing your EFI.You can also specify a custom output directory by using the-o /--outputoption. To view all available commands and options, runocebuild --help or runocebuild <command> --help for more information on a specific command.

Refer todocs/configuration.md for more information on how to setup your buildconfiguration.

Note that this does not output a config.plist file. To generate a config.plistfile, you will need to create aconfig.yml file in the same directory as yourbuild.yml file. Theconfig.yml file contains only the changes you wish tomake to the default Sample.plist file (located underdist/Docs/Sample.plist).Refer todocs/configuration.md for more information.

This section is for developers looking to contribute to this project. This isonly meant to be a brief overview of the project structure and developmentguidelines. For more information, refer to thecontributingdocumentation.

The general philosophy for this project is to keep things as simple as possible.This means that the project should be easy to understand, easy to maintain, andeasy to contribute to.

A summary of the contributing guidelines for this project are as follows:

• Create anissue for any majorchanges and enhancements that you wish to make.
  • If you find a security vulnerability, do NOT open an issue. Please refer to ourSecurity Policy for reporting security vulnerabilities.
  • For questions or discussions related to this project, please open a new GitHubdiscussion instead ofopening an issue.
• Create apull request for yourchanges and coordinate with the project maintainers to get it merged to main.
  • Include unit tests when you contribute new features or fix a bug. This:
    • Proves that your code works correctly and prevents regressions from goingunnoticed.
    • Guards against breaking changes to the public API and ensures that theproject can remain backwards compatible.
    • Lowers the maintenance cost of the project by making it easier totroubleshoot and debug issues.
  • Keep compatibility and cohesiveness mind when contributing a change thatwill impact the public API. This helps limit the scope of changes to onlywhat is required to implement the new feature or fix the bug.

BSD 3-Clause License.