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

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