View source for MacOSCompile

This is an '''howto''' to compile {{VLC}} on '''macOS''' ''(also known as Mac OS X)'', focused on '''VLC 3.0''' and later. 

= Pre-requisites  =

=== Apple Software ===

Those are the minimum build system requirements to compile VLC 4.0 (current development version). They are also highly recommended to compile VLC 3.0:
* At least '''macOS 10.13.4''', or any later version
* At least '''Xcode 9.3''' from [https://developer.apple.com/xcode/ developer.apple.com/xcode]. (Note: Installing the developer tools package is not needed, and building with that package is not supported officially)
* Use at least '''macOS SDK 10.13''' (this is included and the default in Xcode 9.3)

==== Compiler test  ====

Ensure the compiler is found correctly by running

 xcrun clang

in the Terminal, if this outputs anything else than <code>clang: error: no input files</code>, see the troubleshooting part of this document.

= [[GetTheSource|Get the source code]]  =

 git clone git://git.videolan.org/vlc.git

= Build VLC with a single command  =

Setup a build folder:
 cd vlc && mkdir build && cd build

And run the build:
 ../extras/package/macosx/build.sh

Wait and you have finished.

You can see more options for this build (change arch or sdk):
 ../extras/package/macosx/build.sh -h

In case this fails, please try the step-by-step build guide below using a
clean checkout.

= Build steps =
Now, if you prefer, you can read the following detailed information on how the build internally works:

== Additional development tools  ==

You need a number of tools, notably all the autotools, to build VLC correctly.
VLC has a way to build the specific versions of these tools required from source, here is how:
 
 cd extras/tools
 ./bootstrap && make
 cd ../..

'''Important''': Add the extras/tools build results to your PATH, before doing anything else:
 export PATH=$PWD/extras/tools/build/bin:$PATH

== Prepare [[Contrib Status|3rd party libraries]]  ==

To compile VLC, you need lots of other libraries, called 3rd party. VLC has the so-called “contribs” system to help building these libraries
from source. Alternatively you can use a pre-built package of these libraries provided by VideoLAN.

<!--
FIXME: Add guide how to use pre-built nightly contribs:

=== Using pre-built nightly contribs ===
Together with the nightly builds, the build bot does each night a new build of all of the 3rd party libraries required for VLC.
(Not all contribs are included in this pre-built package, as not all contribs are enabled on all OSes and required.)
-->

First, set the correct '''SDK''' version for the 3rd party libraries, usually your current OS X Version:

 export OSX_VERSION=10.11

Then, prepare the 3rd party library folder:

 mkdir -p contrib/contrib-osx &amp;&amp; cd contrib/contrib-osx
 ../bootstrap --build=x86_64-apple-darwin15

=== Prebuilt libraries (recommended) ===

If you want to download a prebuilt package of all the needed libraries. 

 make prebuilt

Now you can just skip to the [[OSXCompile#Update_PATH|Update PATH]] section.

=== Build your own libraries (not for the faint-hearted) ===
Note: In order to build the libraries you need to use an OS X SDK Version lower than 10.12, the 10.12 SDK causes problems
making it impossible to use the resulting libraries (and VLC build) on any macOS version lower than 10.12!
You can set the SDK Version (if it's installed) using <code>export OSX_VERSION=10.11</code>.

You need to install the [http://www.oracle.com/technetwork/pt/java/javase/downloads/index.html Java JDK].

If you want to build contribs from source, you first need to make gettext, which is needed for some other contrib libraries to build: 

 make -j4 .gettext

Now you need to update your path for the gettext tools to be usable later on, see the [[#Update_PATH|Update PATH]] section above.

Then fetch contrib sources: 

 make fetch

and build them with:

 make

If you had no errors, the 3rd party libraries (contrib) are built correctly and you can proceed to the next step.

=== Update PATH  ===

First we go back to the source directory:

 cd ../..

And now we still need to add the contribs to our path, so they can be found:

 export PATH=$PWD/contrib/x86_64-apple-darwin15/bin:$PATH

== Bootstrap VLC  ==

This will create the configure script: 

 ./bootstrap

Check that there are no obvious errors at this stage, like missing gettext or an error at exit.

== Configure the VLC build  ==

Create a build folder: 

 mkdir -p build &amp;&amp; cd build

To list the different options of configure: 

 ../extras/package/macosx/configure.sh --help

To build a binary with the previously installed x86_64-apple-darwin15 contrib: 

 ../extras/package/macosx/configure.sh --enable-debug --host=x86_64-apple-darwin15

By default it will not use the installed SDK, like Xcode does, but use System Root. This means that if you built contribs on your own, the configure script might behave unexpectedly, for example enabling functions which are not present in a given operating system version. To work around this and build against the latest installed SDK, you can use:

 --with-macosx-sdk=`xcrun --show-sdk-path`

If you want to use a different SDK, you can list all installed SDKs with <code>xcodebuild -showsdks</code> and to get the path for it, you can use the following command <code>xcodebuild -version <SDK Flag from before> Path</code>.<br />
For example: <code>xcodebuild -version -sdk macosx10.11 Path</code>

== Build VLC  ==

Just do:
 make -j4

and wait...

== Run VLC  ==
After <code>make</code>, you can just run VLC like so:

 ./bin/vlc-osx-static

If you want a VLC app bundle, just do
 
 make VLC.app

And use it like a normal .app bundle.

== Package VLC Application for Mac  ==

If you want a disk-image: 

 make package-macosx

Note: If you want a more fancy disk image, you need the [https://bitbucket.org/al45tair/dmgbuild dmgbuild] tool, which can be installed using <code>pip install dmgbuild</code> if you have
python installed using [https://brew.sh Homebrew].

== Sign VLC Application for Mac  ==

If you want to sign your application with a certificate, for example for Gatekeeper, you need to run:

 extras/package/macosx/codesign.sh -i "certificate name"

= Troubleshooting  =

== 3rd party packagers and PATH  ==

'''Pay careful attention to remove any reference to 3rd party package managers from your environment.''' This is important to avoid conflicts between your package manager (homebrew, fink, macports...) and the contrib package manager we use to build our contrib. 

It shouldn't be necessary, but it can happen. 

'''git must still be accessible though!''' 

 unset PKG_CONFIG_PATH
 unset PKG_CONFIG_LIBDIR
 export PATH=$PWD/build/bin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin

== Xcode 'No developer directory' error ==
When running <code>xcrun clang</code>, if you see

 Error: No developer directory...

then use xcode-select to select the developer directory within the Xcode package, to point to your xcode developer directory.

something like:

 sudo /usr/bin/xcode-select -switch /Applications/Xcode.app/Contents/Developer  

[[Category:Building]] [[Category:Mac OS X]]