granicus.if.org Git - libjpeg-turbo/blob - BUILDING.md

   1 Building libjpeg-turbo
   2 ======================
   3
   4
   5 Build Requirements
   6 ------------------
   7
   8
   9 ### All Systems
  10
  11 - [CMake](http://www.cmake.org) v2.8.12 or later
  12
  13 - [NASM](http://www.nasm.us) or [YASM](http://yasm.tortall.net)
  14   (if building x86 or x86-64 SIMD extensions)
  15   * If using NASM, 2.10 or later is required.
  16   * If using NASM, 2.10 or later (except 2.11.08) is required for an x86-64 Mac
  17     build (2.11.08 does not work properly with libjpeg-turbo's x86-64 SIMD code
  18     when building macho64 objects.)  NASM or YASM can be obtained from
  19     [MacPorts](http://www.macports.org/) or [Homebrew](http://brew.sh/).
  20   * If using YASM, 1.2.0 or later is required.
  21      - NOTE: Currently, if it is desirable to hide the SIMD function symbols in
  22        Mac executables or shared libraries that statically link with
  23        libjpeg-turbo, then YASM must be used when building libjpeg-turbo.
  24   * If building on Windows, **nasm.exe**/**yasm.exe** should be in your `PATH`.
  25
  26   The binary RPMs released by the NASM project do not work on older Linux
  27   systems, such as Red Hat Enterprise Linux 5.  On such systems, you can easily
  28   build and install NASM from a source RPM by downloading one of the SRPMs from
  29
  30   <http://www.nasm.us/pub/nasm/releasebuilds>
  31
  32   and executing the following as root:
  33
  34         ARCH=`uname -m`
  35         rpmbuild --rebuild nasm-{version}.src.rpm
  36         rpm -Uvh /usr/src/redhat/RPMS/$ARCH/nasm-{version}.$ARCH.rpm
  37
  38   NOTE: the NASM build will fail if texinfo is not installed.
  39
  40
  41 ### Un*x Platforms (including Linux, Mac, FreeBSD, Solaris, and Cygwin)
  42
  43 - GCC v4.1 (or later) or Clang recommended for best performance
  44
  45 - If building the TurboJPEG Java wrapper, JDK or OpenJDK 1.5 or later is
  46   required.  Most modern Linux distributions, as well as Solaris 10 and later,
  47   include JDK or OpenJDK.  On OS X 10.5 and 10.6, it will be necessary to
  48   install the Java Developer Package, which can be downloaded from
  49   <http://developer.apple.com/downloads> (Apple ID required.)  For other
  50   systems, you can obtain the Oracle Java Development Kit from
  51   <http://www.java.com>.
  52
  53
  54 ### Windows
  55
  56 - Microsoft Visual C++ 2005 or later
  57
  58   If you don't already have Visual C++, then the easiest way to get it is by
  59   installing the
  60   [Windows SDK](http://msdn.microsoft.com/en-us/windows/bb980924.aspx).
  61   The Windows SDK includes both 32-bit and 64-bit Visual C++ compilers and
  62   everything necessary to build libjpeg-turbo.
  63
  64   * You can also use Microsoft Visual Studio Express/Community Edition, which
  65     is a free download.  (NOTE: versions prior to 2012 can only be used to
  66     build 32-bit code.)
  67   * If you intend to build libjpeg-turbo from the command line, then add the
  68     appropriate compiler and SDK directories to the `INCLUDE`, `LIB`, and
  69     `PATH` environment variables.  This is generally accomplished by
  70     executing `vcvars32.bat` or `vcvars64.bat` and `SetEnv.cmd`.
  71     `vcvars32.bat` and `vcvars64.bat` are part of Visual C++ and are located in
  72     the same directory as the compiler.  `SetEnv.cmd` is part of the Windows
  73     SDK.  You can pass optional arguments to `SetEnv.cmd` to specify a 32-bit
  74     or 64-bit build environment.
  75
  76    ... OR ...
  77
  78 - MinGW
  79
  80   [MSYS2](http://msys2.github.io/) or [tdm-gcc](http://tdm-gcc.tdragon.net/)
  81   recommended if building on a Windows machine.  Both distributions install a
  82   Start Menu link that can be used to launch a command prompt with the
  83   appropriate compiler paths automatically set.
  84
  85 - If building the TurboJPEG Java wrapper, JDK 1.5 or later is required.  This
  86   can be downloaded from <http://www.java.com>.
  87
  88
  89 Out-of-Tree Builds
  90 ------------------
  91
  92 Binary objects, libraries, and executables are generated in the directory from
  93 which CMake is executed (the "binary directory"), and this directory need not
  94 necessarily be the same as the libjpeg-turbo source directory.  You can create
  95 multiple independent binary directories, in which different versions of
  96 libjpeg-turbo can be built from the same source tree using different compilers
  97 or settings.  In the sections below, *{build_directory}* refers to the binary
  98 directory, whereas *{source_directory}* refers to the libjpeg-turbo source
  99 directory.  For in-tree builds, these directories are the same.
 100
 101
 102 Build Procedure
 103 ---------------
 104
 105 NOTE: The build procedures below assume that CMake is invoked from the command
 106 line, but all of these procedures can be adapted to the CMake GUI as
 107 well.
 108
 109
 110 ### Un*x
 111
 112 The following procedure will build libjpeg-turbo on Unix and Unix-like systems.
 113 (On Solaris, this generates a 32-bit build.  See "Build Recipes" below for
 114 64-bit build instructions.)
 115
 116     cd {build_directory}
 117     cmake -G"Unix Makefiles" [additional CMake flags] {source_directory}
 118     make
 119
 120 This will generate the following files under *{build_directory}*:
 121
 122 **libjpeg.a**<br>
 123 Static link library for the libjpeg API
 124
 125 **libjpeg.so.{version}** (Linux, Unix)<br>
 126 **libjpeg.{version}.dylib** (Mac)<br>
 127 **cygjpeg-{version}.dll** (Cygwin)<br>
 128 Shared library for the libjpeg API
 129
 130 By default, *{version}* is 62.2.0, 7.2.0, or 8.1.2, depending on whether
 131 libjpeg v6b (default), v7, or v8 emulation is enabled.  If using Cygwin,
 132 *{version}* is 62, 7, or 8.
 133
 134 **libjpeg.so** (Linux, Unix)<br>
 135 **libjpeg.dylib** (Mac)<br>
 136 Development symlink for the libjpeg API
 137
 138 **libjpeg.dll.a** (Cygwin)<br>
 139 Import library for the libjpeg API
 140
 141 **libturbojpeg.a**<br>
 142 Static link library for the TurboJPEG API
 143
 144 **libturbojpeg.so.0.2.0** (Linux, Unix)<br>
 145 **libturbojpeg.0.2.0.dylib** (Mac)<br>
 146 **cygturbojpeg-0.dll** (Cygwin)<br>
 147 Shared library for the TurboJPEG API
 148
 149 **libturbojpeg.so** (Linux, Unix)<br>
 150 **libturbojpeg.dylib** (Mac)<br>
 151 Development symlink for the TurboJPEG API
 152
 153 **libturbojpeg.dll.a** (Cygwin)<br>
 154 Import library for the TurboJPEG API
 155
 156
 157 ### Visual C++ (Command Line)
 158
 159     cd {build_directory}
 160     cmake -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=Release [additional CMake flags] {source_directory}
 161     nmake
 162
 163 This will build either a 32-bit or a 64-bit version of libjpeg-turbo, depending
 164 on which version of **cl.exe** is in the `PATH`.
 165
 166 The following files will be generated under *{build_directory}*:
 167
 168 **jpeg-static.lib**<br>
 169 Static link library for the libjpeg API
 170
 171 **jpeg{version}.dll**<br>
 172 DLL for the libjpeg API
 173
 174 **jpeg.lib**<br>
 175 Import library for the libjpeg API
 176
 177 **turbojpeg-static.lib**<br>
 178 Static link library for the TurboJPEG API
 179
 180 **turbojpeg.dll**<br>
 181 DLL for the TurboJPEG API
 182
 183 **turbojpeg.lib**<br>
 184 Import library for the TurboJPEG API
 185
 186 *{version}* is 62, 7, or 8, depending on whether libjpeg v6b (default), v7, or
 187 v8 emulation is enabled.
 188
 189
 190 ### Visual C++ (IDE)
 191
 192 Choose the appropriate CMake generator option for your version of Visual Studio
 193 (run `cmake` with no arguments for a list of available generators.)  For
 194 instance:
 195
 196     cd {build_directory}
 197     cmake -G"Visual Studio 10" [additional CMake flags] {source_directory}
 198
 199 NOTE: Add "Win64" to the generator name (for example, "Visual Studio 10 Win64")
 200 to build a 64-bit version of libjpeg-turbo.  A separate build directory must be
 201 used for 32-bit and 64-bit builds.
 202
 203 You can then open **ALL_BUILD.vcproj** in Visual Studio and build one of the
 204 configurations in that project ("Debug", "Release", etc.) to generate a full
 205 build of libjpeg-turbo.
 206
 207 This will generate the following files under *{build_directory}*:
 208
 209 **{configuration}/jpeg-static.lib**<br>
 210 Static link library for the libjpeg API
 211
 212 **{configuration}/jpeg{version}.dll**<br>
 213 DLL for the libjpeg API
 214
 215 **{configuration}/jpeg.lib**<br>
 216 Import library for the libjpeg API
 217
 218 **{configuration}/turbojpeg-static.lib**<br>
 219 Static link library for the TurboJPEG API
 220
 221 **{configuration}/turbojpeg.dll**<br>
 222 DLL for the TurboJPEG API
 223
 224 **{configuration}/turbojpeg.lib**<br>
 225 Import library for the TurboJPEG API
 226
 227 *{configuration}* is Debug, Release, RelWithDebInfo, or MinSizeRel, depending
 228 on the configuration you built in the IDE, and *{version}* is 62, 7, or 8,
 229 depending on whether libjpeg v6b (default), v7, or v8 emulation is enabled.
 230
 231
 232 ### MinGW
 233
 234 NOTE: This assumes that you are building on a Windows machine using the MSYS
 235 environment.  If you are cross-compiling on a Un*x platform (including Mac and
 236 Cygwin), then see "Build Recipes" below.
 237
 238     cd {build_directory}
 239     cmake -G"MSYS Makefiles" [additional CMake flags] {source_directory}
 240     make
 241
 242 This will generate the following files under *{build_directory}*:
 243
 244 **libjpeg.a**<br>
 245 Static link library for the libjpeg API
 246
 247 **libjpeg-{version}.dll**<br>
 248 DLL for the libjpeg API
 249
 250 **libjpeg.dll.a**<br>
 251 Import library for the libjpeg API
 252
 253 **libturbojpeg.a**<br>
 254 Static link library for the TurboJPEG API
 255
 256 **libturbojpeg.dll**<br>
 257 DLL for the TurboJPEG API
 258
 259 **libturbojpeg.dll.a**<br>
 260 Import library for the TurboJPEG API
 261
 262 *{version}* is 62, 7, or 8, depending on whether libjpeg v6b (default), v7, or
 263 v8 emulation is enabled.
 264
 265
 266 ### Debug Build
 267
 268 Add `-DCMAKE_BUILD_TYPE=Debug` to the CMake command line.  Or, if building
 269 with NMake, remove `-DCMAKE_BUILD_TYPE=Release` (Debug builds are the default
 270 with NMake.)
 271
 272
 273 ### libjpeg v7 or v8 API/ABI Emulation
 274
 275 Add `-DWITH_JPEG7=1` to the CMake command line to build a version of
 276 libjpeg-turbo that is API/ABI-compatible with libjpeg v7.  Add `-DWITH_JPEG8=1`
 277 to the CMake command line to build a version of libjpeg-turbo that is
 278 API/ABI-compatible with libjpeg v8.  See [README.md](README.md) for more
 279 information about libjpeg v7 and v8 emulation.
 280
 281
 282 ### In-Memory Source/Destination Managers
 283
 284 When using libjpeg v6b or v7 API/ABI emulation, add `-DWITH_MEM_SRCDST=0` to
 285 the CMake command line to build a version of libjpeg-turbo that lacks the
 286 `jpeg_mem_src()` and `jpeg_mem_dest()` functions.  These functions were not
 287 part of the original libjpeg v6b and v7 APIs, so removing them ensures strict
 288 conformance with those APIs.  See [README.md](README.md) for more information.
 289
 290
 291 ### Arithmetic Coding Support
 292
 293 Since the patent on arithmetic coding has expired, this functionality has been
 294 included in this release of libjpeg-turbo.  libjpeg-turbo's implementation is
 295 based on the implementation in libjpeg v8, but it works when emulating libjpeg
 296 v7 or v6b as well.  The default is to enable both arithmetic encoding and
 297 decoding, but those who have philosophical objections to arithmetic coding can
 298 add `-DWITH_ARITH_ENC=0` or `-DWITH_ARITH_DEC=0` to the CMake command line to
 299 disable encoding or decoding (respectively.)
 300
 301
 302 ### TurboJPEG Java Wrapper
 303
 304 Add `-DWITH_JAVA=1` to the CMake command line to incorporate an optional Java
 305 Native Interface (JNI) wrapper into the TurboJPEG shared library and build the
 306 Java front-end classes to support it.  This allows the TurboJPEG shared library
 307 to be used directly from Java applications.  See [java/README](java/README) for
 308 more details.
 309
 310 If Java is not in your `PATH`, or if you wish to use an alternate JDK to
 311 build/test libjpeg-turbo, then (prior to running CMake) set the `JAVA_HOME`
 312 environment variable to the location of the JDK that you wish to use.  The
 313 `Java_JAVAC_EXECUTABLE`, `Java_JAVA_EXECUTABLE`, and `Java_JAR_EXECUTABLE`
 314 CMake variables can also be used to specify alternate commands or locations for
 315 javac, jar, and java (respectively.)  You can also set the
 316 `CMAKE_JAVA_COMPILE_FLAGS` CMake variable or the `JAVAFLAGS` environment
 317 variable to specify arguments that should be passed to the Java compiler when
 318 building the TurboJPEG classes, and the `JAVAARGS` CMake variable to specify
 319 arguments that should be passed to the JRE when running the TurboJPEG Java unit
 320 tests.
 321
 322
 323 Build Recipes
 324 -------------
 325
 326
 327 ### 32-bit Build on 64-bit Linux/Unix/Mac
 328
 329 Use export/setenv to set the following environment variables before running
 330 CMake:
 331
 332     CFLAGS=-m32
 333     LDFLAGS=-m32
 334
 335
 336 ### 64-bit Build on Solaris
 337
 338 Use export/setenv to set the following environment variables before running
 339 CMake:
 340
 341     CFLAGS=-m64
 342     LDFLAGS=-m64
 343
 344
 345 ### Other Compilers
 346
 347 On Un*x systems, prior to running CMake, you can set the `CC` environment
 348 variable to the command used to invoke the C compiler.
 349
 350
 351 ### 32-bit MinGW Build on Un*x (including Mac and Cygwin)
 352
 353 Create a file called **toolchain.cmake** under *{build_directory}*, with the
 354 following contents:
 355
 356     set(CMAKE_SYSTEM_NAME Windows)
 357     set(CMAKE_SYSTEM_PROCESSOR X86)
 358     set(CMAKE_C_COMPILER {mingw_binary_path}/i686-w64-mingw32-gcc)
 359     set(CMAKE_RC_COMPILER {mingw_binary_path}/i686-w64-mingw32-windres)
 360
 361 *{mingw\_binary\_path}* is the directory under which the MinGW binaries are
 362 located (usually **/usr/bin**.)  Next, execute the following commands:
 363
 364     cd {build_directory}
 365     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 366       [additional CMake flags] {source_directory}
 367     make
 368
 369
 370 ### 64-bit MinGW Build on Un*x (including Mac and Cygwin)
 371
 372 Create a file called **toolchain.cmake** under *{build_directory}*, with the
 373 following contents:
 374
 375     set(CMAKE_SYSTEM_NAME Windows)
 376     set(CMAKE_SYSTEM_PROCESSOR AMD64)
 377     set(CMAKE_C_COMPILER {mingw_binary_path}/x86_64-w64-mingw32-gcc)
 378     set(CMAKE_RC_COMPILER {mingw_binary_path}/x86_64-w64-mingw32-windres)
 379
 380 *{mingw\_binary\_path}* is the directory under which the MinGW binaries are
 381 located (usually **/usr/bin**.)  Next, execute the following commands:
 382
 383     cd {build_directory}
 384     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 385       [additional CMake flags] {source_directory}
 386     make
 387
 388
 389 Building libjpeg-turbo for iOS
 390 ------------------------------
 391
 392 iOS platforms, such as the iPhone and iPad, use ARM processors, and all
 393 currently supported models include NEON instructions.  Thus, they can take
 394 advantage of libjpeg-turbo's SIMD extensions to significantly accelerate JPEG
 395 compression/decompression.  This section describes how to build libjpeg-turbo
 396 for these platforms.
 397
 398
 399 ### Additional build requirements
 400
 401 - For configurations that require [gas-preprocessor.pl]
 402   (https://raw.githubusercontent.com/libjpeg-turbo/gas-preprocessor/master/gas-preprocessor.pl),
 403   it should be installed in your `PATH`.
 404
 405
 406 ### ARMv7 (32-bit)
 407
 408 **gas-preprocessor.pl required**
 409
 410 The following scripts demonstrate how to build libjpeg-turbo to run on the
 411 iPhone 3GS-4S/iPad 1st-3rd Generation and newer:
 412
 413 #### Xcode 4.2 and earlier (LLVM-GCC)
 414
 415     IOS_PLATFORMDIR=/Developer/Platforms/iPhoneOS.platform
 416     IOS_SYSROOT=($IOS_PLATFORMDIR/Developer/SDKs/iPhoneOS*.sdk)
 417     export CFLAGS="-mfloat-abi=softfp -march=armv7 -mcpu=cortex-a8 -mtune=cortex-a8 -mfpu=neon -miphoneos-version-min=3.0"
 418
 419     cd {build_directory}
 420
 421     cat <<EOF >toolchain.cmake
 422     set(CMAKE_SYSTEM_NAME Darwin)
 423     set(CMAKE_SYSTEM_PROCESSOR arm)
 424     set(CMAKE_C_COMPILER ${IOS_PLATFORMDIR}/Developer/usr/bin/arm-apple-darwin10-llvm-gcc-4.2)
 425     EOF
 426
 427     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 428       -DCMAKE_OSX_SYSROOT=${IOS_SYSROOT[0]} \
 429       [additional CMake flags] {source_directory}
 430     make
 431
 432 #### Xcode 4.3-4.6 (LLVM-GCC)
 433
 434 Same as above, but replace the first line with:
 435
 436     IOS_PLATFORMDIR=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform
 437
 438 #### Xcode 5 and later (Clang)
 439
 440     IOS_PLATFORMDIR=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform
 441     IOS_SYSROOT=($IOS_PLATFORMDIR/Developer/SDKs/iPhoneOS*.sdk)
 442     export CFLAGS="-mfloat-abi=softfp -arch armv7 -miphoneos-version-min=3.0"
 443     export ASMFLAGS="-no-integrated-as"
 444
 445     cd {build_directory}
 446
 447     cat <<EOF >toolchain.cmake
 448     set(CMAKE_SYSTEM_NAME Darwin)
 449     set(CMAKE_SYSTEM_PROCESSOR arm)
 450     set(CMAKE_C_COMPILER /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang)
 451     EOF
 452
 453     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 454       -DCMAKE_OSX_SYSROOT=${IOS_SYSROOT[0]} \
 455       [additional CMake flags] {source_directory}
 456     make
 457
 458
 459 ### ARMv7s (32-bit)
 460
 461 **gas-preprocessor.pl required**
 462
 463 The following scripts demonstrate how to build libjpeg-turbo to run on the
 464 iPhone 5/iPad 4th Generation and newer:
 465
 466 #### Xcode 4.5-4.6 (LLVM-GCC)
 467
 468     IOS_PLATFORMDIR=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform
 469     IOS_SYSROOT=($IOS_PLATFORMDIR/Developer/SDKs/iPhoneOS*.sdk)
 470     export CFLAGS="-Wall -mfloat-abi=softfp -march=armv7s -mcpu=swift -mtune=swift -mfpu=neon -miphoneos-version-min=6.0"
 471
 472     cd {build_directory}
 473
 474     cat <<EOF >toolchain.cmake
 475     set(CMAKE_SYSTEM_NAME Darwin)
 476     set(CMAKE_SYSTEM_PROCESSOR arm)
 477     set(CMAKE_C_COMPILER ${IOS_PLATFORMDIR}/Developer/usr/bin/arm-apple-darwin10-llvm-gcc-4.2)
 478     EOF
 479
 480     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 481       -DCMAKE_OSX_SYSROOT=${IOS_SYSROOT[0]} \
 482       [additional CMake flags] {source_directory}
 483     make
 484
 485 #### Xcode 5 and later (Clang)
 486
 487 Same as the ARMv7 build procedure for Xcode 5 and later, except replace the
 488 compiler flags as follows:
 489
 490     export CFLAGS="-Wall -mfloat-abi=softfp -arch armv7s -miphoneos-version-min=6.0"
 491
 492
 493 ### ARMv8 (64-bit)
 494
 495 **gas-preprocessor.pl required if using Xcode < 6**
 496
 497 The following script demonstrates how to build libjpeg-turbo to run on the
 498 iPhone 5S/iPad Mini 2/iPad Air and newer.
 499
 500     IOS_PLATFORMDIR=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform
 501     IOS_SYSROOT=($IOS_PLATFORMDIR/Developer/SDKs/iPhoneOS*.sdk)
 502     export CFLAGS="-Wall -arch arm64 -miphoneos-version-min=7.0 -funwind-tables"
 503
 504     cd {build_directory}
 505
 506     cat <<EOF >toolchain.cmake
 507     set(CMAKE_SYSTEM_NAME Darwin)
 508     set(CMAKE_SYSTEM_PROCESSOR aarch64)
 509     set(CMAKE_C_COMPILER /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang)
 510     EOF
 511
 512     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 513       -DCMAKE_OSX_SYSROOT=${IOS_SYSROOT[0]} \
 514       [additional CMake flags] {source_directory}
 515     make
 516
 517 Once built, lipo can be used to combine the ARMv7, v7s, and/or v8 variants into
 518 a universal library.
 519
 520
 521 Building libjpeg-turbo for Android
 522 ----------------------------------
 523
 524 Building libjpeg-turbo for Android platforms requires the
 525 [Android NDK](https://developer.android.com/tools/sdk/ndk).
 526
 527
 528 ### ARMv7 (32-bit)
 529
 530 The following is a general recipe script that can be modified for your specific
 531 needs.
 532
 533     # Set these variables to suit your needs
 534     NDK_PATH={full path to the "ndk" directory-- for example, /opt/android/sdk/ndk-bundle}
 535     BUILD_PLATFORM={the platform name for the NDK package you installed--
 536       for example, "windows-x86" or "linux-x86_64" or "darwin-x86_64"}
 537     TOOLCHAIN_VERSION={"4.8", "4.9", "clang3.5", etc.  This corresponds to a
 538       toolchain directory under ${NDK_PATH}/toolchains/.}
 539     ANDROID_VERSION={The minimum version of Android to support-- for example,
 540       "16", "19", etc.}
 541
 542     # It should not be necessary to modify the rest
 543     HOST=arm-linux-androideabi
 544     SYSROOT=${NDK_PATH}/platforms/android-${ANDROID_VERSION}/arch-arm
 545     export CFLAGS="-march=armv7-a -mfloat-abi=softfp -fprefetch-loop-arrays \
 546       -D__ANDROID_API__=${ANDROID_VERSION} --sysroot=${SYSROOT} \
 547       -isystem ${NDK_PATH}/sysroot/usr/include \
 548       -isystem ${NDK_PATH}/sysroot/usr/include/${HOST}"
 549     export LDFLAGS=-pie
 550     TOOLCHAIN=${NDK_PATH}/toolchains/${HOST}-${TOOLCHAIN_VERSION}/prebuilt/${BUILD_PLATFORM}
 551
 552     cd {build_directory}
 553
 554     cat <<EOF >toolchain.cmake
 555     set(CMAKE_SYSTEM_NAME Linux)
 556     set(CMAKE_SYSTEM_PROCESSOR arm)
 557     set(CMAKE_C_COMPILER ${TOOLCHAIN}/bin/${HOST}-gcc)
 558     set(CMAKE_FIND_ROOT_PATH ${TOOLCHAIN}/${HOST})
 559     EOF
 560
 561     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 562       -DCMAKE_POSITION_INDEPENDENT_CODE=1 \
 563       [additional CMake flags] {source_directory}
 564     make
 565
 566
 567 ### ARMv8 (64-bit)
 568
 569 The following is a general recipe script that can be modified for your specific
 570 needs.
 571
 572     # Set these variables to suit your needs
 573     NDK_PATH={full path to the "ndk" directory-- for example, /opt/android/sdk/ndk-bundle}
 574     BUILD_PLATFORM={the platform name for the NDK package you installed--
 575       for example, "windows-x86" or "linux-x86_64" or "darwin-x86_64"}
 576     TOOLCHAIN_VERSION={"4.8", "4.9", "clang3.5", etc.  This corresponds to a
 577       toolchain directory under ${NDK_PATH}/toolchains/.}
 578     ANDROID_VERSION={The minimum version of Android to support.  "21" or later
 579       is required for a 64-bit build.}
 580
 581     # It should not be necessary to modify the rest
 582     HOST=aarch64-linux-android
 583     SYSROOT=${NDK_PATH}/platforms/android-${ANDROID_VERSION}/arch-arm64
 584     export CFLAGS="-D__ANDROID_API__=${ANDROID_VERSION} --sysroot=${SYSROOT} \
 585       -isystem ${NDK_PATH}/sysroot/usr/include \
 586       -isystem ${NDK_PATH}/sysroot/usr/include/${HOST}"
 587     export LDFLAGS=-pie
 588     TOOLCHAIN=${NDK_PATH}/toolchains/${HOST}-${TOOLCHAIN_VERSION}/prebuilt/${BUILD_PLATFORM}
 589
 590     cd {build_directory}
 591
 592     cat <<EOF >toolchain.cmake
 593     set(CMAKE_SYSTEM_NAME Linux)
 594     set(CMAKE_SYSTEM_PROCESSOR aarch64)
 595     set(CMAKE_C_COMPILER ${TOOLCHAIN}/bin/${HOST}-gcc)
 596     set(CMAKE_FIND_ROOT_PATH ${TOOLCHAIN}/${HOST})
 597     EOF
 598
 599     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 600       -DCMAKE_POSITION_INDEPENDENT_CODE=1 \
 601       [additional CMake flags] {source_directory}
 602     make
 603
 604
 605 ### x86 (32-bit)
 606
 607 The following is a general recipe script that can be modified for your specific
 608 needs.
 609
 610     # Set these variables to suit your needs
 611     NDK_PATH={full path to the "ndk" directory-- for example, /opt/android/sdk/ndk-bundle}
 612     BUILD_PLATFORM={the platform name for the NDK package you installed--
 613       for example, "windows-x86" or "linux-x86_64" or "darwin-x86_64"}
 614     TOOLCHAIN_VERSION={"4.8", "4.9", "clang3.5", etc.  This corresponds to a
 615       toolchain directory under ${NDK_PATH}/toolchains/.}
 616     ANDROID_VERSION={The minimum version of Android to support-- for example,
 617       "16", "19", etc.}
 618
 619     # It should not be necessary to modify the rest
 620     HOST=i686-linux-android
 621     SYSROOT=${NDK_PATH}/platforms/android-${ANDROID_VERSION}/arch-x86
 622     export CFLAGS="-D__ANDROID_API__=${ANDROID_VERSION} --sysroot=${SYSROOT} \
 623       -isystem ${NDK_PATH}/sysroot/usr/include \
 624       -isystem ${NDK_PATH}/sysroot/usr/include/${HOST}"
 625     export LDFLAGS=-pie
 626     TOOLCHAIN=${NDK_PATH}/toolchains/x86-${TOOLCHAIN_VERSION}/prebuilt/${BUILD_PLATFORM}
 627
 628     cd {build_directory}
 629
 630     cat <<EOF >toolchain.cmake
 631     set(CMAKE_SYSTEM_NAME Linux)
 632     set(CMAKE_SYSTEM_PROCESSOR i386)
 633     set(CMAKE_C_COMPILER ${TOOLCHAIN}/bin/${HOST}-gcc)
 634     set(CMAKE_FIND_ROOT_PATH ${TOOLCHAIN}/${HOST})
 635     EOF
 636
 637     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 638       -DCMAKE_POSITION_INDEPENDENT_CODE=1 \
 639       [additional CMake flags] {source_directory}
 640     make
 641
 642
 643 ### x86-64 (64-bit)
 644
 645 The following is a general recipe script that can be modified for your specific
 646 needs.
 647
 648     # Set these variables to suit your needs
 649     NDK_PATH={full path to the "ndk" directory-- for example, /opt/android/sdk/ndk-bundle}
 650     BUILD_PLATFORM={the platform name for the NDK package you installed--
 651       for example, "windows-x86" or "linux-x86_64" or "darwin-x86_64"}
 652     TOOLCHAIN_VERSION={"4.8", "4.9", "clang3.5", etc.  This corresponds to a
 653       toolchain directory under ${NDK_PATH}/toolchains/.}
 654     ANDROID_VERSION={The minimum version of Android to support.  "21" or later
 655       is required for a 64-bit build.}
 656
 657     # It should not be necessary to modify the rest
 658     HOST=x86_64-linux-android
 659     SYSROOT=${NDK_PATH}/platforms/android-${ANDROID_VERSION}/arch-x86_64
 660     export CFLAGS="-D__ANDROID_API__=${ANDROID_VERSION} --sysroot=${SYSROOT} \
 661       -isystem ${NDK_PATH}/sysroot/usr/include \
 662       -isystem ${NDK_PATH}/sysroot/usr/include/${HOST}"
 663     export LDFLAGS=-pie
 664     TOOLCHAIN=${NDK_PATH}/toolchains/x86_64-${TOOLCHAIN_VERSION}/prebuilt/${BUILD_PLATFORM}
 665
 666     cd {build_directory}
 667
 668     cat <<EOF >toolchain.cmake
 669     set(CMAKE_SYSTEM_NAME Linux)
 670     set(CMAKE_SYSTEM_PROCESSOR x86_64)
 671     set(CMAKE_C_COMPILER ${TOOLCHAIN}/bin/${HOST}-gcc)
 672     set(CMAKE_FIND_ROOT_PATH ${TOOLCHAIN}/${HOST})
 673     EOF
 674
 675     cmake -G"Unix Makefiles" -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake \
 676       -DCMAKE_POSITION_INDEPENDENT_CODE=1 \
 677       [additional CMake flags] {source_directory}
 678     make
 679
 680
 681 If building for Android 4.0.x (API level < 16) or earlier, remove
 682 `-DCMAKE_POSITION_INDEPENDENT_CODE=1` from the CMake arguments and `-pie` from
 683 `LDFLAGS`.
 684
 685 If building on Windows, add `.exe` to the end of `CMAKE_C_COMPILER`.
 686
 687
 688 Advanced CMake Options
 689 ----------------------
 690
 691 To list and configure other CMake options not specifically mentioned in this
 692 guide, run
 693
 694     ccmake {source_directory}
 695
 696 or
 697
 698     cmake-gui {source_directory}
 699
 700 from the build directory after initially configuring the build.  CCMake is a
 701 text-based interactive version of CMake, and CMake-GUI is a GUI version.  Both
 702 will display all variables that are relevant to the libjpeg-turbo build, their
 703 current values, and a help string describing what they do.
 704
 705
 706 Installing libjpeg-turbo
 707 ========================
 708
 709 You can use the build system to install libjpeg-turbo (as opposed to creating
 710 an installer package.)  To do this, run `make install` or `nmake install`
 711 (or build the "install" target in the Visual Studio IDE.)  Running
 712 `make uninstall` or `nmake uninstall` (or building the "uninstall" target in
 713 the Visual Studio IDE) will uninstall libjpeg-turbo.
 714
 715 The `CMAKE_INSTALL_PREFIX` CMake variable can be modified in order to install
 716 libjpeg-turbo into a directory of your choosing.  If you don't specify
 717 `CMAKE_INSTALL_PREFIX`, then the default is:
 718
 719 **c:\libjpeg-turbo**<br>
 720 Visual Studio 32-bit build
 721
 722 **c:\libjpeg-turbo64**<br>
 723 Visual Studio 64-bit build
 724
 725 **c:\libjpeg-turbo-gcc**<br>
 726 MinGW 32-bit build
 727
 728 **c:\libjpeg-turbo-gcc64**<br>
 729 MinGW 64-bit build
 730
 731 **/opt/libjpeg-turbo**<br>
 732 Un*x
 733
 734 The default value of `CMAKE_INSTALL_PREFIX` causes the libjpeg-turbo files to
 735 be installed with a directory structure resembling that of the official
 736 libjpeg-turbo binary packages.  Changing the value of `CMAKE_INSTALL_PREFIX`
 737 (for instance, to **/usr/local**) causes the libjpeg-turbo files to be
 738 installed with a directory structure that conforms to GNU standards.
 739
 740 The `CMAKE_INSTALL_BINDIR`, `CMAKE_INSTALL_DATAROOTDIR`,
 741 `CMAKE_INSTALL_DOCDIR`, `CMAKE_INSTALL_INCLUDEDIR`, `CMAKE_INSTALL_JAVADIR`,
 742 `CMAKE_INSTALL_LIBDIR`, and `CMAKE_INSTALL_MANDIR` CMake variables allow a
 743 finer degree of control over where specific files in the libjpeg-turbo
 744 distribution should be installed.  These directory variables can either be
 745 specified as absolute paths or as paths relative to `CMAKE_INSTALL_PREFIX` (for
 746 instance, setting `CMAKE_INSTALL_DOCDIR` to **doc** would cause the
 747 documentation to be installed in **${CMAKE\_INSTALL\_PREFIX}/doc**.)  If a
 748 directory variable contains the name of another directory variable in angle
 749 brackets, then its final value will depend on the final value of that other
 750 variable.  For instance, the default value of `CMAKE_INSTALL_MANDIR` is
 751 **\<CMAKE\_INSTALL\_DATAROOTDIR\>/man**.
 752
 753 NOTE: If setting one of these directory variables to a relative path using the
 754 CMake command line, you must specify that the variable is of type `PATH`.
 755 For example:
 756
 757     cmake -G"{generator type}" -DCMAKE_INSTALL_LIBDIR:PATH=lib {source_directory}
 758
 759 Otherwise, CMake will assume that the path is relative to the build directory
 760 rather than the install directory.
 761
 762
 763 Creating Distribution Packages
 764 ==============================
 765
 766 The following commands can be used to create various types of distribution
 767 packages:
 768
 769
 770 Linux
 771 -----
 772
 773     make rpm
 774
 775 Create Red Hat-style binary RPM package.  Requires RPM v4 or later.
 776
 777     make srpm
 778
 779 This runs `make dist` to create a pristine source tarball, then creates a
 780 Red Hat-style source RPM package from the tarball.  Requires RPM v4 or later.
 781
 782     make deb
 783
 784 Create Debian-style binary package.  Requires dpkg.
 785
 786
 787 Mac
 788 ---
 789
 790     make dmg
 791
 792 Create Mac package/disk image.  This requires pkgbuild and productbuild, which
 793 are installed by default on OS X 10.7 and later and which can be obtained by
 794 installing Xcode 3.2.6 (with the "Unix Development" option) on OS X 10.6.
 795 Packages built in this manner can be installed on OS X 10.5 and later, but they
 796 must be built on OS X 10.6 or later.
 797
 798     make udmg
 799
 800 This creates a Mac package/disk image that contains universal x86-64/i386/ARM
 801 binaries.  The following CMake variables control which architectures are
 802 included in the universal binaries.  Setting any of these variables to an empty
 803 string excludes that architecture from the package.
 804
 805 * `OSX_32BIT_BUILD`: Directory containing an i386 (32-bit) Mac build of
 806   libjpeg-turbo (default: *{source_directory}*/osxx86)
 807 * `IOS_ARMV7_BUILD`: Directory containing an ARMv7 (32-bit) iOS build of
 808   libjpeg-turbo (default: *{source_directory}*/iosarmv7)
 809 * `IOS_ARMV7S_BUILD`: Directory containing an ARMv7s (32-bit) iOS build of
 810   libjpeg-turbo (default: *{source_directory}*/iosarmv7s)
 811 * `IOS_ARMV8_BUILD`: Directory containing an ARMv8 (64-bit) iOS build of
 812   libjpeg-turbo (default: *{source_directory}*/iosarmv8)
 813
 814 You should first use CMake to configure i386, ARMv7, ARMv7s, and/or ARMv8
 815 sub-builds of libjpeg-turbo (see "Build Recipes" and "Building libjpeg-turbo
 816 for iOS" above) in build directories that match those specified in the
 817 aforementioned CMake variables.  Next, configure the primary build of
 818 libjpeg-turbo as an out-of-tree build, and build it.  Once the primary build
 819 has been built, run `make udmg` from the build directory.  The packaging system
 820 will build the sub-builds, use lipo to combine them into a single set of
 821 universal binaries, then package the universal binaries in the same manner as
 822 `make dmg`.
 823
 824
 825 Cygwin
 826 ------
 827
 828     make cygwinpkg
 829
 830 Build a Cygwin binary package.
 831
 832
 833 Windows
 834 -------
 835
 836 If using NMake:
 837
 838     cd {build_directory}
 839     nmake installer
 840
 841 If using MinGW:
 842
 843     cd {build_directory}
 844     make installer
 845
 846 If using the Visual Studio IDE, build the "installer" target.
 847
 848 The installer package (libjpeg-turbo-*{version}*[-gcc|-vc][64].exe) will be
 849 located under *{build_directory}*.  If building using the Visual Studio IDE,
 850 then the installer package will be located in a subdirectory with the same name
 851 as the configuration you built (such as *{build_directory}*\Debug\ or
 852 *{build_directory}*\Release\).
 853
 854 Building a Windows installer requires the
 855 [Nullsoft Install System](http://nsis.sourceforge.net/).  makensis.exe should
 856 be in your `PATH`.
 857
 858
 859 Regression testing
 860 ==================
 861
 862 The most common way to test libjpeg-turbo is by invoking `make test` (Un*x) or
 863 `nmake test` (Windows command line) or by building the "RUN_TESTS" target
 864 (Visual Studio IDE), once the build has completed.  This runs a series of tests
 865 to ensure that mathematical compatibility has been maintained between
 866 libjpeg-turbo and libjpeg v6b.  This also invokes the TurboJPEG unit tests,
 867 which ensure that the colorspace extensions, YUV encoding, decompression
 868 scaling, and other features of the TurboJPEG C and Java APIs are working
 869 properly (and, by extension, that the equivalent features of the underlying
 870 libjpeg API are also working.)
 871
 872 Invoking `make testclean` (Un*x) or `nmake testclean` (Windows command line) or
 873 building the "testclean" target (Visual Studio IDE) will clean up the output
 874 images generated by the tests.
 875
 876 On Un*x platforms, more extensive tests of the TurboJPEG C and Java wrappers
 877 can be run by invoking `make tjtest`.  These extended TurboJPEG tests
 878 essentially iterate through all of the available features of the TurboJPEG APIs
 879 that are not covered by the TurboJPEG unit tests (including the lossless
 880 transform options) and compare the images generated by each feature to images
 881 generated using the equivalent feature in the libjpeg API.  The extended
 882 TurboJPEG tests are meant to test for regressions in the TurboJPEG wrappers,
 883 not in the underlying libjpeg API library.