// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\page qtmultimedia-building-ffmpeg-macos.html
\title Building FFmpeg from source on macOS
\brief This document describes how to build FFmpeg from source code.

This page explains how to configure and build \l{FFmpeg} on macOS.
This involves:

\list
\li Get the FFmpeg source code.
\li Install the required dependencies.
\li Configure FFmpeg from the command line.
\li Build the development libraries.
\endlist

\section1 Get the FFmpeg source code

You can get the FFmpeg source code in these ways:

\list
    \li Download from the
        \l{https://ffmpeg.org/download.html#get-sources}{FFmpeg download page}.
    \li Clone from git. For example, this command clones the version 7.1 of the
        FFmpeg sources to \c{~/ffmpeg}.

        \badcode
        % git clone --branch n7.1 https://git.ffmpeg.org/ffmpeg.git ffmpeg
        \endcode
\endlist

It is recommended to use the same FFmpeg version as documented in the
\l{Qt Multimedia}{Qt Multimedia main page}.

The following paragraphs assumes that you store the FFmpeg source code under
\c{~/ffmpeg}.

\section1 Prerequisites

To build FFmpeg, these tools and packages are required:

\list
    \li \l{https://brew.sh/}{Homebrew}
    \li Homebrew packages (yasm).
\endlist

\section2 Installing Homebrew

To install Homebrew, run:

\badcode
% /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
\endcode

\section2 Installing Homebrew packages

To install Homebrew package Yasm, run:

\badcode
% brew install yasm
\endcode

\section1 Configuring and building FFmpeg

Create a \c build directory inside the \c{~/ffmpeg} directory and navigate into it:

\badcode
% mkdir ~/ffmpeg/build
% cd ~/ffmpeg/build
\endcode

To configure FFmpeg, run:

\badcode
% ../configure --prefix=/usr/local/ffmpeg --disable-doc --enable-network --enable-shared
\endcode

The \c{--prefix} argument specifies a path where the FFmpeg development
libraries are installed after building. The documentation is not needed, but
network features should be enabled. To build FFmpeg as static libraries, omit
the \c{--enable-shared} option.

In the previous code snippet, an absolute path was used for \c{--prefix} argument intentionally.
If you specify a relative path (for example, \c{../install}), the dependencies will be referenced
using this relative path and not the correct one using \c{@rpath}. Using absolute paths makes
an FFmpeg build non-portable.
To use relative paths and make FFmpeg build portable, you need to manually fix
dependencies
using \l{https://www.unix.com/man-page/osx/1/otool/}{otool}.

Once the \c configure command finishes, build and install FFmpeg using the
\c make command.

\badcode
% make -j install
\endcode

If the build completes without errors, FFmpeg development libraries are
installed in the \c{/usr/local/ffmpeg} directory. If you build Qt Multimedia,
this path is stored in the \c FFMPEG_DIR variable used when configuring Qt
Multimedia.

\section2 Configuring and Building FFmpeg Universal Binaries

To create universal binaries on macOS (for example, for both x86_64 and arm64 architectures),
follow these steps:

\list
    \li Configure and build FFmpeg for arm64 architecture:
        \badcode
        % ../configure --prefix=/usr/local/ffmpeg/arm64 --disable-doc --enable-network \
            --enable-shared --enable-cross-compile --arch=arm64 --cc="clang -arch arm64"
        % make -j install
        \endcode
    \li Configure and build FFmpeg for x86_64 architecture:
        \badcode
        % ../configure --prefix=/usr/local/ffmpeg/x86_64 --disable-doc --enable-network \
            --enable-shared --enable-cross-compile --arch=x86_64 --cc="clang -arch x86_64"
        % make -j install
        \endcode
    \li Combine the builds into a universal binary
        using \l{https://www.unix.com/man-page/osx/1/lipo/}{lipo}.
\endlist

*/
