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:** Linux is user friendly... It's just very particular about who its friends are.
  51 **TIP:** Algorithm is what developers call code they do not want to explain.
  52 **WARNING:** Developers don't change light bulbs. It's a hardware problem.
  53
  54 **[back to top](#table-of-contents)** | **[back to section top](#1-document-conventions)**
  55
  56 ## 2. Prerequisites
  57 * **[Java Development Kit (JDK)](http://www.oracle.com/technetwork/java/javase/downloads/index.html)**
  58 * **[Xcode](https://developer.apple.com/xcode/)**. Install it from the AppStore or from the **[Apple Developer Homepage](https://developer.apple.com/)**.
  59 * Device with **OSX 10.13 or newer** to run Kodi after build.
  60
  61 Building for OSX/macOS should work with the following constellations of Xcode and OSX/macOS versions:
  62   * Xcode 12.4 against MacOSX SDK 11.1 on 10.15.7 (Catalina)(recommended)(CI)
  63   * Xcode 13.x against MacOSX SDK 12.3 on 12.x (Monterey)(recommended)
  64
  65 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.
  66 **WARNING:** Start Xcode after installation finishes. You need to accept the licenses and install missing components.
  67
  68 **[back to top](#table-of-contents)**
  69
  70 ## 3. Get the source code
  71 Change to your `home` directory:
  72 ```
  73 cd $HOME
  74 ```
  75
  76 Clone Kodi's current master branch:
  77 ```
  78 git clone https://github.com/xbmc/xbmc kodi
  79 ```
  80
  81 **[back to top](#table-of-contents)**
  82
  83 ## 4. Configure and build tools and dependencies
  84 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`.
  85
  86 **TIP:** Look for comments starting with `Or ...` and only execute the command(s) you need.
  87 **NOTE:** `--with-platform` is mandatory for all Apple platforms
  88
  89 Configure build (x86 intel):
  90 ```
  91 cd $HOME/kodi/tools/depends
  92 ./bootstrap
  93 ./configure --host=x86_64-apple-darwin --with-platform=macos
  94 ```
  95
  96 Configure build (apple silicon):
  97 ```
  98 cd $HOME/kodi/tools/depends
  99 ./bootstrap
 100 ./configure --host=aarch64-apple-darwin --with-platform=macos
 101 ```
 102
 103 Build tools and dependencies:
 104 ```
 105 make -j$(getconf _NPROCESSORS_ONLN)
 106 ```
 107
 108 **TIP:** 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`).
 109
 110 **WARNING:** 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.
 111
 112 **NOTE:** **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.13:
 113 ```
 114 ./configure --host=x86_64-apple-darwin --with-platform=macos --with-sdk=10.13
 115 ```
 116
 117 Developers can also select native windowing/input handling with the following
 118 ```
 119 ./configure --host=x86_64-apple-darwin --with-platform=macos --with-windowsystem=native
 120 ```
 121
 122 ### 4.1. Advanced Configure Options
 123
 124
 125 **All platforms:**
 126
 127 ```
 128 --with-toolchain=<path>
 129 ```
 130   specify path to toolchain. Auto set for android. Defaults to xcode root for darwin, /usr for linux
 131
 132 ```
 133 --enable-debug=<yes:no>
 134 ```
 135   enable debugging information (default is yes)
 136
 137 ```
 138 --disable-ccache
 139 ```
 140   disable ccache
 141
 142 ```
 143 --with-tarballs=<path>
 144 ```
 145   path where tarballs will be saved [prefix/xbmc-tarballs]
 146
 147 ```
 148 --with-cpu=<cpu>
 149 ```
 150   optional. specify target cpu. guessed if not specified
 151
 152 ```
 153 --with-linker=<linker>
 154 ```
 155   specify linker to use. (default is ld)
 156
 157 ```
 158 --with-platform=<platform>
 159 ```
 160   target platform
 161
 162 ```
 163 --enable-gplv3=<yes:no>
 164 ```
 165   enable gplv3 components. (default is yes)
 166
 167 ```
 168 --with-target-cflags=<cflags>
 169 ```
 170   C compiler flags (target)
 171
 172 ```
 173 --with-target-cxxflags=<cxxflags>
 174 ```
 175   C++ compiler flags (target)
 176
 177 ```
 178 --with-target-ldflags=<ldflags>
 179 ```
 180   linker flags. Use e.g. for -l<lib> (target)
 181
 182 ```
 183 --with-ffmpeg-options
 184 ```
 185   FFmpeg configure options, e.g. --enable-vaapi (target)
 186
 187 **Apple Specific:**
 188
 189 ```
 190 --with-windowsystem=<native:sdl>
 191 ```
 192   Windowing system to use (default is sdl when not provided). arm64 MacOS requires native
 193
 194 ```
 195 --with-sdk=<sdknumber>
 196 ```
 197   specify sdk platform version.
 198
 199 **[back to top](#table-of-contents)** | **[back to section top](#4-configure-and-build-tools-and-dependencies)**
 200
 201 ## 5. Build binary add-ons
 202 You can find a complete list of available binary add-ons **[here](https://github.com/xbmc/repo-binary-addons)**.
 203
 204 Change to Kodi's source code directory:
 205 ```
 206 cd $HOME/kodi
 207 ```
 208
 209 There are multiple possibilities to choose which addons are built. The following 3 examples will give an idea.
 210
 211 (1) Build all add-ons:
 212 ```
 213 make -j$(getconf _NPROCESSORS_ONLN) -C tools/depends/target/binary-addons
 214 ```
 215 OR
 216
 217 (2) Build specific add-ons:
 218 ```
 219 make -j$(getconf _NPROCESSORS_ONLN) -C tools/depends/target/binary-addons ADDONS="audioencoder.flac pvr.vdr.vnsi audiodecoder.snesapu"
 220 ```
 221 OR
 222
 223 (3) Build a specific group of add-ons:
 224 ```
 225 make -j$(getconf _NPROCESSORS_ONLN) -C tools/depends/target/binary-addons ADDONS="pvr.*"
 226 ```
 227 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)
 228
 229 **[back to top](#table-of-contents)**
 230
 231 ## 6. Build Kodi
 232 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.
 233
 234 ### 6.1. Build with Xcode
 235 Create an out-of-source build directory:
 236 ```
 237 mkdir $HOME/kodi-build
 238 ```
 239 Generate Xcode project as per configure command in **[Configure and build tools and dependencies](#4-configure-and-build-tools-and-dependencies)**:
 240 ```
 241 make -C tools/depends/target/cmakebuildsys BUILD_DIR=$HOME/kodi-build GEN=Xcode
 242 ```
 243
 244 To explicitly select the windowing/input system to use do the following (default is to use SDL if not provided)
 245 ```
 246 make -C tools/depends/target/cmakebuildsys BUILD_DIR=$HOME/kodi-build GEN=Xcode APP_WINDOW_SYSTEM=native
 247 ```
 248
 249 **TIP:** BUILD_DIR can be omitted, and project will be created in $HOME/kodi/build
 250 Change all relevant paths onwards if omitted.
 251
 252 Additional cmake arguments can be supplied via the CMAKE_EXTRA_ARGUMENTS command line variable
 253
 254 **Alternatively**
 255
 256 Change to build directory:
 257 ```
 258 cd $HOME/kodi-build
 259 ```
 260
 261 Generate Xcode project (x86_64 intel):
 262 ```
 263 /Users/Shared/xbmc-depends/x86_64-darwin17.5.0-native/bin/cmake -G Xcode -DCMAKE_TOOLCHAIN_FILE=/Users/Shared/xbmc-depends/macosx10.13_x86_64-target-debug/share/Toolchain.cmake ../kodi
 264 ```
 265
 266 **WARNING:** The toolchain file location differs depending on SDK version. You have to replace `x86_64-darwin17.5.0-native` and `macosx10.13_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:** 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.
 276
 277 ### 6.2. Build with xcodebuild
 278 Alternatively, you can also build via Xcode from the command-line with `xcodebuild`, triggered by CMake:
 279
 280 Build Kodi:
 281 ```
 282 cd $HOME/kodi-build
 283 xcodebuild -config "Debug" -jobs $(getconf _NPROCESSORS_ONLN)
 284 ```
 285
 286 **TIP:** You can specify Release instead of Debug as -config parameter.
 287
 288 **Alternatively**
 289
 290 Build Kodi:
 291 ```
 292 /Users/Shared/xbmc-depends/x86_64-darwin17.5.0-native/bin/cmake --build . --config "Debug" -- -verbose -jobs $(getconf _NPROCESSORS_ONLN)
 293 ```
 294
 295 **TIP:** You can specify `Release` instead of `Debug` as `--config` parameter.
 296
 297 ### 6.3. Build with make
 298 CMake is also able to generate makefiles that can be used to build with make.
 299
 300 Change to Kodi's source code directory:
 301 ```
 302 cd $HOME/kodi
 303 ```
 304
 305 Generate makefiles:
 306 ```
 307 make -C tools/depends/target/cmakebuildsys
 308 ```
 309
 310 **TIP:** 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.
 311 ```
 312 mkdir $HOME/kodi-build
 313 make -C tools/depends/target/cmakebuildsys BUILD_DIR=$HOME/kodi-build
 314 ```
 315
 316 Build Kodi:
 317 ```
 318 make -j$(getconf _NPROCESSORS_ONLN) -C build
 319 ```
 320
 321 **[back to top](#table-of-contents)** | **[back to section top](#6-build-kodi)**
 322
 323 ## 7. Run Kodi
 324 ### 7.1. Built with Xcode or xcodebuild
 325 After build finishes, you can run Kodi from Xcode or from terminal.
 326
 327 Run `Debug` config from terminal:
 328 ```
 329 $HOME/kodi-build/Debug/kodi.bin
 330 ```
 331
 332 Run `Release` config from terminal:
 333 ```
 334 $HOME/kodi-build/Release/kodi.bin
 335 ```
 336
 337 ### 7.2. Built with make
 338 After build finishes, you can run Kodi from terminal:
 339 ```
 340 $HOME/kodi/build/kodi.bin
 341 ```
 342
 343 **[back to top](#table-of-contents)**
 344
 345 ## 8. Package
 346 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
 347
 348 ```
 349 cd $HOME/kodi-build
 350 xcodebuild -target dmg
 351 ````
 352 **OR**
 353 ```
 354 cd $HOME/kodi-build
 355 /Users/Shared/xbmc-depends/x86_64-darwin17.5.0-native/bin/cmake --build . --target "dmg" --config "Debug"
 356 ```
 357
 358 Generated `dmg` file will be inside `$HOME/kodi-build/tools/darwin/packaging/osx/`.
 359
 360 Alternatively, if you built using make:
 361 ```
 362 cd $HOME/kodi-build
 363 make dmg
 364 ```
 365
 366 Generated `dmg` file will be inside `$HOME/kodi-build/tools/darwin/packaging/osx/`.
 367
 368 **[back to top](#table-of-contents)**
 369
 370 ## 9. Install
 371 Kodi can be installed like any other app.
 372
 373 **[back to top](#table-of-contents)**
 374