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

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