docs/README.macOS.md

   1 ![Kodi Logo](resources/banner_slim.png)
   2
   3 # macOS build guide
   4 This guide has been tested using Xcode 11.3.1 running on MacOS 10.14.4 (Mojave). Please note this combination is the only version our CI system builds. The minimum OS requirement for this version of Xcode is MacOS 10.14.4. Other combinations may work but we provide no assurances that other combinations will build correctly and run identically to Team Kodi releases. It is meant to build Kodi for macOS using **[Kodi's unified depends build system](../tools/depends/README.md)**. Please read it in full before you proceed to familiarize yourself with the build procedure.
   5
   6 ## Table of Contents
   7 1. **[Document conventions](#1-document-conventions)**
   8 2. **[Prerequisites](#2-prerequisites)**
   9 3. **[Get the source code](#3-get-the-source-code)**
  10 4. **[Configure and build tools and dependencies](#4-configure-and-build-tools-and-dependencies)**
  11   4.1. **[Advanced Configure Options](#41-advanced-configure-options)**
  12 5. **[Build binary add-ons](#5-build-binary-add-ons)**
  13 6. **[Build Kodi](#6-build-kodi)**
  14   6.1. **[Build with Xcode](#61-build-with-xcode)**
  15   6.2. **[Build with xcodebuild](#62-build-with-xcodebuild)**
  16   6.3. **[Build with make](#63-build-with-make)**
  17 7. **[Run Kodi](#7-run-kodi)**
  18   7.1. **[Built with Xcode or xcodebuild](#71-built-with-xcode-or-xcodebuild)**
  19   7.2. **[Built with make](#72-built-with-make)**
  20 8. **[Package](#8-package)**
  21 9. **[Install](#9-install)**
  22
  23 ## 1. Document conventions
  24 This guide assumes you are using `terminal`, also known as `console`, `command-line` or simply `cli`. Commands need to be run at the terminal, one at a time and in the provided order.
  25
  26 This is a comment that provides context:
  27 ```
  28 this is a command
  29 this is another command
  30 and yet another one
  31 ```
  32
  33 **Example:** Clone Kodi's current master branch:
  34 ```
  35 git clone https://github.com/xbmc/xbmc kodi
  36 ```
  37
  38 Commands that contain strings enclosed in angle brackets denote something you need to change to suit your needs.
  39 ```
  40 git clone -b <branch-name> https://github.com/xbmc/xbmc kodi
  41 ```
  42
  43 **Example:** Clone Kodi's current Krypton branch:
  44 ```
  45 git clone -b Krypton https://github.com/xbmc/xbmc kodi
  46 ```
  47
  48 Several different strategies are used to draw your attention to certain pieces of information. In order of how critical the information is, these items are marked as a note, tip, or warning. For example:
  49
  50 > [!NOTE]
  51 > Linux is user friendly... It's just very particular about who its friends are.
  52
  53 > [!TIP]
  54 > Algorithm is what developers call code they do not want to explain.
  55
  56 > [!WARNING]
  57 > Developers don't change light bulbs. It's a hardware problem.
  58
  59 **[back to top](#table-of-contents)** | **[back to section top](#1-document-conventions)**
  60
  61 ## 2. Prerequisites
  62 * **[Java Development Kit (JDK)](http://www.oracle.com/technetwork/java/javase/downloads/index.html)**
  63 * **[Xcode](https://developer.apple.com/xcode/)**. Install it from the AppStore or from the **[Apple Developer Homepage](https://developer.apple.com/)**.
  64 * Device with **OSX 10.14 or newer** to run Kodi after build.
  65
  66 Building for OSX/macOS should work with the following constellations of Xcode and OSX/macOS versions:
  67   * Xcode 12.4 against MacOSX SDK 11.1 on 10.15.7 (Catalina)(recommended)(CI)
  68   * Xcode 13.x against MacOSX SDK 12.3 on 12.x (Monterey)(recommended)
  69
  70 Team Kodi CI infrastructure is limited, and therefore we only have the single combination tested. Newer xcode/macos combinations generally should work, however the team does not actively test/use pre-release versions, so use with caution. Earlier versions may work, however we dont actively support them, so use with caution.
  71 > [!WARNING]
  72 > Start Xcode after installation finishes. You need to accept the licenses and install missing components.
  73
  74 **[back to top](#table-of-contents)**
  75
  76 ## 3. Get the source code
  77 Change to your `home` directory:
  78 ```
  79 cd $HOME
  80 ```
  81
  82 Clone Kodi's current master branch:
  83 ```
  84 git clone https://github.com/xbmc/xbmc kodi
  85 ```
  86
  87 **[back to top](#table-of-contents)**
  88
  89 ## 4. Configure and build tools and dependencies
  90 Kodi can be built as either a 32bit or 64bit program. The dependencies are built in `$HOME/kodi/tools/depends` and installed into `/Users/Shared/xbmc-depends`.
  91
  92 > [!TIP]
  93 > Look for comments starting with `Or ...` and only execute the command(s) you need.
  94
  95 > [!NOTE]
  96 > `--with-platform` is mandatory for all Apple platforms
  97
  98 Configure build (x86 intel):
  99 ```
 100 cd $HOME/kodi/tools/depends
 101 ./bootstrap
 102 ./configure --host=x86_64-apple-darwin --with-platform=macos
 103 ```
 104
 105 Configure build (apple silicon):
 106 ```
 107 cd $HOME/kodi/tools/depends
 108 ./bootstrap
 109 ./configure --host=aarch64-apple-darwin --with-platform=macos
 110 ```
 111
 112 Build tools and dependencies:
 113 ```
 114 make -j$(getconf _NPROCESSORS_ONLN)
 115 ```
 116
 117 > [!TIP]
 118 > By adding `-j<number>` to the make command, you can choose how many concurrent jobs will be used and expedite the build process. It is recommended to use `-j$(getconf _NPROCESSORS_ONLN)` to compile on all available processor cores. The build machine can also be configured to do this automatically by adding `export MAKEFLAGS="-j$(getconf _NPROCESSORS_ONLN)"` to your shell config (e.g. `~/.bashrc`).
 119
 120 > [!WARNING]
 121 > Look for the `Dependencies built successfully.` success message. If in doubt run a single threaded `make` command until the message appears. If the single make fails, clean the specific library by issuing `make -C target/<name_of_failed_lib> distclean` and run `make`again.
 122
 123 > [!NOTE]
 124 > **Advanced developers** may want to specify an SDK version (if multiple versions are installed) in the configure line(s) shown above. The example below would use SDK 10.14:
 125
 126 ```
 127 ./configure --host=x86_64-apple-darwin --with-platform=macos --with-sdk=10.14
 128 ```
 129
 130 ### 4.1. Advanced Configure Options
 131
 132
 133 **All platforms:**
 134
 135 ```
 136 --with-toolchain=<path>
 137 ```
 138   specify path to toolchain. Auto set for android. Defaults to xcode root for darwin, /usr for linux
 139
 140 ```
 141 --enable-debug=<yes:no>
 142 ```
 143   enable debugging information (default is yes)
 144
 145 ```
 146 --disable-ccache
 147 ```
 148   disable ccache
 149
 150 ```
 151 --with-tarballs=<path>
 152 ```
 153   path where tarballs will be saved [prefix/xbmc-tarballs]
 154
 155 ```
 156 --with-cpu=<cpu>
 157 ```
 158   optional. specify target cpu. guessed if not specified
 159
 160 ```
 161 --with-linker=<linker>
 162 ```
 163   specify linker to use. (default is ld)
 164
 165 ```
 166 --with-platform=<platform>
 167 ```
 168   target platform
 169
 170 ```
 171 --enable-gplv3=<yes:no>
 172 ```
 173   enable gplv3 components. (default is yes)
 174
 175 ```
 176 --with-target-cflags=<cflags>
 177 ```
 178   C compiler flags (target)
 179
 180 ```
 181 --with-target-cxxflags=<cxxflags>
 182 ```
 183   C++ compiler flags (target)
 184
 185 ```
 186 --with-target-ldflags=<ldflags>
 187 ```
 188   linker flags. Use e.g. for -l<lib> (target)
 189
 190 ```
 191 --with-ffmpeg-options
 192 ```
 193   FFmpeg configure options, e.g. --enable-vaapi (target)
 194
 195 **Apple Specific:**
 196
 197 ```
 198 --with-sdk=<sdknumber>
 199 ```
 200   specify sdk platform version.
 201
 202 **[back to top](#table-of-contents)** | **[back to section top](#4-configure-and-build-tools-and-dependencies)**
 203
 204 ## 5. Build binary add-ons
 205 You can find a complete list of available binary add-ons **[here](https://github.com/xbmc/repo-binary-addons)**.
 206
 207 Change to Kodi's source code directory:
 208 ```
 209 cd $HOME/kodi
 210 ```
 211
 212 There are multiple possibilities to choose which addons are built. The following 3 examples will give an idea.
 213
 214 (1) Build all add-ons:
 215 ```
 216 make -j$(getconf _NPROCESSORS_ONLN) -C tools/depends/target/binary-addons
 217 ```
 218 OR
 219
 220 (2) Build specific add-ons:
 221 ```
 222 make -j$(getconf _NPROCESSORS_ONLN) -C tools/depends/target/binary-addons ADDONS="audioencoder.flac pvr.vdr.vnsi audiodecoder.snesapu"
 223 ```
 224 OR
 225
 226 (3) Build a specific group of add-ons:
 227 ```
 228 make -j$(getconf _NPROCESSORS_ONLN) -C tools/depends/target/binary-addons ADDONS="pvr.*"
 229 ```
 230 For additional information on regular expression usage for ADDONS_TO_BUILD, view ADDONS_TO_BUILD section located at [Kodi add-ons CMake based buildsystem](../cmake/addons/README.md)
 231
 232 **[back to top](#table-of-contents)**
 233
 234 ## 6. Build Kodi
 235 Before you can use Xcode to build Kodi, the Xcode project has to be generated with CMake. CMake is built as part of the dependencies and doesn't have to be installed separately. A toolchain file is also generated and is used to configure CMake.
 236
 237 ### 6.1. Build with Xcode
 238 Create an out-of-source build directory:
 239 ```
 240 mkdir $HOME/kodi-build
 241 ```
 242 Generate Xcode project as per configure command in **[Configure and build tools and dependencies](#4-configure-and-build-tools-and-dependencies)**:
 243 ```
 244 make -C tools/depends/target/cmakebuildsys BUILD_DIR=$HOME/kodi-build GEN=Xcode
 245 ```
 246
 247 > [!TIP]
 248 > BUILD_DIR can be omitted, and project will be created in $HOME/kodi/build
 249 Change all relevant paths onwards if omitted.
 250
 251 Additional cmake arguments can be supplied via the CMAKE_EXTRA_ARGUMENTS command line variable
 252
 253 **Alternatively**
 254
 255 Change to build directory:
 256 ```
 257 cd $HOME/kodi-build
 258 ```
 259
 260 Generate Xcode project (x86_64 intel):
 261 ```
 262 /Users/Shared/xbmc-depends/x86_64-darwin17.5.0-native/bin/cmake -G Xcode -DCMAKE_TOOLCHAIN_FILE=/Users/Shared/xbmc-depends/macosx10.14_x86_64-target-debug/share/Toolchain.cmake ../kodi
 263 ```
 264
 265 > [!WARNING]
 266 > The toolchain file location differs depending on SDK version. You have to replace `x86_64-darwin17.5.0-native` and `macosx10.14_x86_64-target-debug` in the paths above with the correct ones on your system.
 267
 268 You can check `Users/Shared/xbmc-depends` directory content with:
 269 ```
 270 ls -l /Users/Shared/xbmc-depends
 271 ```
 272
 273 **Start Xcode, open the Kodi project file** (`kodi.xcodeproj`) located in `$HOME/kodi-build` and hit `Build`.
 274
 275 > [!WARNING]
 276 > If you have selected a specific SDK version in **[step 4](#4-configure-and-build-tools-and-dependencies)** then you might need to adapt the active target to use the same SDK version, otherwise build will fail. Be sure to select a device configuration. Building for simulator is **not** supported.
 277
 278 ### 6.2. Build with xcodebuild
 279 Alternatively, you can also build via Xcode from the command-line with `xcodebuild`, triggered by CMake:
 280
 281 Build Kodi:
 282 ```
 283 cd $HOME/kodi-build
 284 xcodebuild -config "Debug" -jobs $(getconf _NPROCESSORS_ONLN)
 285 ```
 286
 287 > [!TIP]
 288 > You can specify Release instead of Debug as -config parameter.
 289
 290 **Alternatively**
 291
 292 Build Kodi:
 293 ```
 294 /Users/Shared/xbmc-depends/x86_64-darwin17.5.0-native/bin/cmake --build . --config "Debug" -- -verbose -jobs $(getconf _NPROCESSORS_ONLN)
 295 ```
 296
 297 > [!TIP]
 298 > You can specify `Release` instead of `Debug` as `--config` parameter.
 299
 300 ### 6.3. Build with make
 301 CMake is also able to generate makefiles that can be used to build with make.
 302
 303 Change to Kodi's source code directory:
 304 ```
 305 cd $HOME/kodi
 306 ```
 307
 308 Generate makefiles:
 309 ```
 310 make -C tools/depends/target/cmakebuildsys
 311 ```
 312
 313 > [!TIP]
 314 > BUILD_DIR can be provided as an argument to cmakebuildsys. This allows you to provide an alternate build location. Change all paths onwards as required if BUILD_DIR option used.
 315 ```
 316 mkdir $HOME/kodi-build
 317 make -C tools/depends/target/cmakebuildsys BUILD_DIR=$HOME/kodi-build
 318 ```
 319
 320 Build Kodi:
 321 ```
 322 make -j$(getconf _NPROCESSORS_ONLN) -C build
 323 ```
 324
 325 **[back to top](#table-of-contents)** | **[back to section top](#6-build-kodi)**
 326
 327 ## 7. Run Kodi
 328 ### 7.1. Built with Xcode or xcodebuild
 329 After build finishes, you can run Kodi from Xcode or from terminal.
 330
 331 Run `Debug` config from terminal:
 332 ```
 333 $HOME/kodi-build/Debug/kodi.bin
 334 ```
 335
 336 Run `Release` config from terminal:
 337 ```
 338 $HOME/kodi-build/Release/kodi.bin
 339 ```
 340
 341 ### 7.2. Built with make
 342 After build finishes, you can run Kodi from terminal:
 343 ```
 344 $HOME/kodi/build/kodi.bin
 345 ```
 346
 347 **[back to top](#table-of-contents)**
 348
 349 ## 8. Package
 350 CMake generates a target called `dmg` which will package Kodi ready for distribution. After Kodi has been built, the target can be triggered by selecting it in Xcode active scheme or manually running
 351
 352 ```
 353 cd $HOME/kodi-build
 354 xcodebuild -target dmg
 355 ````
 356 **OR**
 357 ```
 358 cd $HOME/kodi-build
 359 /Users/Shared/xbmc-depends/x86_64-darwin17.5.0-native/bin/cmake --build . --target "dmg" --config "Debug"
 360 ```
 361
 362 Generated `dmg` file will be inside `$HOME/kodi-build/tools/darwin/packaging/osx/`.
 363
 364 Alternatively, if you built using make:
 365 ```
 366 cd $HOME/kodi-build
 367 make dmg
 368 ```
 369
 370 Generated `dmg` file will be inside `$HOME/kodi-build/tools/darwin/packaging/osx/`.
 371
 372 **[back to top](#table-of-contents)**
 373
 374 ## 9. Install
 375 Kodi can be installed like any other app.
 376
 377 **[back to top](#table-of-contents)**
 378