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