Rewrite doc/INSTALL-MAC.md with a working recipe for Apple Silicon and Intel Macs#1058
Open
geekrebel wants to merge 2 commits intoOpenShot:developfrom
Open
Rewrite doc/INSTALL-MAC.md with a working recipe for Apple Silicon and Intel Macs#1058geekrebel wants to merge 2 commits intoOpenShot:developfrom
geekrebel wants to merge 2 commits intoOpenShot:developfrom
Conversation
libopenshot on both Apple Silicon (arm64) and Intel Macs. The previous version still referenced Homebrew formulae and tools that have been gone for a decade (gcc48, Python 3.3, Qt 5.4.2), used Intel-only /usr/local/Cellar paths, suggested the non-existent "cmake -d" flag, and had no Apple Silicon coverage at all. As a result, every current-day macOS contributor who followed the file was landing on stale CMake errors, typically the "Could not find a package configuration file provided by OpenShotAudio" message (see libopenshot#1030). The new document walks through the steps that were actually verified end-to-end on macOS 15 / Apple Silicon with AppleClang 17 and CMake 4.0.3: installing Command Line Tools, installing the Homebrew dependencies (qt@5, ffmpeg@7, libomp, cppzmq, swig, zeromq, etc.), building libopenshot-audio, and then building libopenshot with the OpenMP hint flags that AppleClang requires. All prefixes use "$(brew --prefix ...)" so the same commands work on Intel Macs against /usr/local and on Apple Silicon against /opt/homebrew. A troubleshooting section documents the current set of macOS-specific gotchas that contributors will still hit even with this recipe: * AGL framework removal (recently fixed in libopenshot-audio 0.6.x). * cppzmq marked optional in CMake but required by ZmqLogger.h. * AppleClang OpenMP via libomp. * Apple system Ruby headers using the C++17-removed 'register' keyword, which forces -DENABLE_RUBY=0 on all modern macOS builds. * Homebrew default ffmpeg formula already being at FFmpeg 8, which the develop branch does not yet target (see libopenshot#1018). This is a docs-only change. No CMake, source, or build system behaviour is modified. Running the recipe in this file successfully produces libopenshot.dylib, _openshot.so, and a working "import openshot" from Python 3 on Apple Silicon. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
|
Merge conflicts have been detected on this PR, please resolve. |
…Shot#1027) and updating the INSTALL-MAC.md recipe to document both Qt 5 and Qt 6 as supported options on macOS. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
doc/INSTALL-MAC.mdhas drifted badly from reality. It still tellscontributors to run commands like:
brew install gcc48 --enable-all-languages(thegcc48formula wasremoved from Homebrew years ago; GCC 4.8 is from 2013),
brew install unittest-cpp --cc=gcc-4.8,brew install qt5(the current formula isqt@5),/usr/local/Cellar/qt5/5.4.2/and/usr/local/Cellar/python3/3.3.2/...(Intel-only paths, Python 3.3 hasbeen EOL since 2017),
cmake -d -G ...(there is no-dflag; that is what thereporter of #1030
was doing, straight from this file).
As a result, anyone following the existing doc on a current Mac, and
especially any contributor on Apple Silicon, lands on opaque CMake
errors. The most common one, and the subject of #1030, is the follow-on
"Could not find a package configuration file provided by OpenShotAudio",
which hides the actual problem that
libopenshot-audioitself no longerbuilds with the commands the doc suggests.
What this PR changes
A full rewrite of
doc/INSTALL-MAC.mdwith a recipe that wasverified end-to-end on:
arm64)/opt/homebrewEvery prefix is derived via
$(brew --prefix ...), so the same commandswork on Intel Macs against
/usr/localwithout modification.The new document covers:
cmake,swig,qt@5,ffmpeg@7,libomp,zeromq,cppzmq,pkgconf), plus optionalones.
libopenshot-audioandlibopenshotas siblings.libopenshot-audiowith the default out-of-source CMakeworkflow.
libopenshotwith the exact flags AppleClang needs, inparticular the five
-DOpenMP_*hints that work around AppleClang notshipping an OpenMP runtime.
python3 -c "import openshot; ...".cmake --install buildstep and how to point it at Homebrew'sprefix.
gotchas that a contributor will hit even with this recipe.
What is documented in Troubleshooting
These are genuine current issues, surfaced while walking the build on
Apple Silicon. Each has a sensible workaround captured in the doc, and
each is worth its own small follow-up PR:
fixed by Remove dead "-framework AGL" link directive (macOS 10.14+ and all Apple Silicon) libopenshot-audio#169 (my own PR). Once that merges,
the troubleshooting note can be tightened.
cppzmqis marked optional in CMake but required in source:src/ZmqLogger.hunconditionally#includes<zmq.hpp>, so the"optional" classification in
src/CMakeLists.txtis misleading. Wortha follow-up PR to make it actually required (or guarded by a compile
flag).
find_package(OpenMP REQUIRED)failsout of the box on macOS because AppleClang does not ship OpenMP.
Worth a follow-up PR to add a small macOS fallback path to the CMake
module (or at least to
cmake/'s helper set).register: Apple's/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks/Ruby.framework/Headers/ruby/ruby/intern.hdeclares functions using the
registerspecifier, which C++17 hasremoved. This blocks the Ruby bindings on every modern macOS SDK.
Worth a follow-up PR to default
ENABLE_RUBYtoOFFon macOS.ffmpegformula is already atFFmpeg 8, which is not yet supported on
develop; until#1018 lands, the
doc tells users to install
ffmpeg@7.Scope
Docs-only.
CMakeLists.txt, source, and every build target areunchanged. The recipe in this file was used to build
libopenshot.dyliband
_openshot.sofrom a clean clone on an Apple Silicon Mac; runningpython3 -c "import openshot; print(openshot.OPENSHOT_VERSION_FULL)"prints
0.7.0.Fixes
Fixes #1030.
Context
This is my first PR to
libopenshotproper. It is the documentationhalf of a small series of Apple Silicon contributor fixes I have been
working on. On the packaging side, the corresponding
openshot-qtPRsare #6003,
#6004,
#6005, and
#6006; on the
audio-library side, the corresponding fix is
OpenShot/libopenshot-audio#169. The follow-up CMake fixes enumerated in
Troubleshooting above will land as separate small PRs.