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