| 1 | Building and Installing Emacs on MS-Windows |
| 2 | using the MSYS and MinGW tools |
| 3 | |
| 4 | Copyright (C) 2013-2014 Free Software Foundation, Inc. |
| 5 | See the end of the file for license conditions. |
| 6 | |
| 7 | The MSYS/MinGW build described here is supported on versions of |
| 8 | Windows starting with Windows 2000 and newer. Windows 9X are not |
| 9 | supported (but the Emacs binary produced by this build will run on |
| 10 | Windows 9X as well). |
| 11 | |
| 12 | Do not use this recipe with Cygwin. For building on Cygwin, use the |
| 13 | normal installation instructions, ../INSTALL. |
| 14 | |
| 15 | * For the brave (a.k.a. "impatient"): |
| 16 | |
| 17 | For those who have a working MSYS/MinGW development environment and |
| 18 | are comfortable with running Posix configure scripts, here are the |
| 19 | concise instructions for configuring and building the native Windows |
| 20 | binary of Emacs with these tools: |
| 21 | |
| 22 | 0. Start the MSYS Bash window. Everything else below is done from |
| 23 | that window's Bash prompt. |
| 24 | |
| 25 | 0a. If you are building from the development trunk (as opposed to a |
| 26 | release tarball), produce the configure script, by typing from |
| 27 | the top-level Emacs source directory: |
| 28 | |
| 29 | ./autogen.sh |
| 30 | |
| 31 | 1. If you want to build Emacs outside of the source tree |
| 32 | (recommended), create the build directory and chdir there. |
| 33 | |
| 34 | 2. Invoke the configure script: |
| 35 | |
| 36 | - If you are building outside the source tree: |
| 37 | |
| 38 | /PATH/TO/EMACS/SOURCE/TREE/configure --prefix=PREFIX ... |
| 39 | |
| 40 | - If you are building in-place, i.e. inside the source tree: |
| 41 | |
| 42 | ./configure --prefix=PREFIX ... |
| 43 | |
| 44 | It is always preferable to use --prefix to configure Emacs for |
| 45 | some specific location of its installed tree; the default |
| 46 | /usr/local is not suitable for Windows (see the detailed |
| 47 | instructions for the reasons). The prefix must be absolute. |
| 48 | |
| 49 | You can pass other options to the configure script. Here's a |
| 50 | typical example (for an in-place debug build): |
| 51 | |
| 52 | CFLAGS='-O0 -g3' ./configure --prefix=/d/usr/emacs --enable-checking='yes,glyphs' |
| 53 | |
| 54 | 3. After the configure script finishes, it should display the |
| 55 | resulting configuration. After that, type |
| 56 | |
| 57 | make |
| 58 | |
| 59 | Use "make -j N" if your MSYS Make supports parallel execution; |
| 60 | the build will take significantly less time in that case. Here N |
| 61 | is the number of simultaneous parallel jobs; use the number of |
| 62 | the cores on your system. |
| 63 | |
| 64 | 4. Install the produced binaries: |
| 65 | |
| 66 | make install |
| 67 | |
| 68 | If you want the installation tree to go to a place that is |
| 69 | different from the one specified by --prefix, say |
| 70 | |
| 71 | make install prefix=/where/ever/you/want |
| 72 | |
| 73 | That's it! |
| 74 | |
| 75 | If these short instructions somehow fail, read the rest of this |
| 76 | file. |
| 77 | |
| 78 | * Installing MinGW and MSYS |
| 79 | |
| 80 | Make sure you carefully read the following two sections in their |
| 81 | entirety and install/configure the various packages as instructed. |
| 82 | A correct installation makes all the rest almost trivial; a botched |
| 83 | installation will likely make you miserable for quite some time. |
| 84 | |
| 85 | There are two alternatives to installing MinGW + MSYS: using the GUI |
| 86 | installer, called mingw-get, provided by the MinGW project, or |
| 87 | manual installation. The next two sections describe each one of |
| 88 | these. |
| 89 | |
| 90 | ** Installing MinGW and MSYS using mingw-get |
| 91 | |
| 92 | A nice installer, called mingw-get, is available for those who don't |
| 93 | like to mess with manual installations. You can download it from |
| 94 | here: |
| 95 | |
| 96 | https://sourceforge.net/projects/mingw/files/Installer/mingw-get/ |
| 97 | |
| 98 | (This installer only supports packages downloaded from the MinGW |
| 99 | site; for the rest you will still need the manual method.) |
| 100 | |
| 101 | After installing mingw-get, invoke it to install the packages that |
| 102 | are already selected by default on the "Select Components" screen of |
| 103 | its wizard. |
| 104 | |
| 105 | After that, use "mingw-get install PACKAGE" to install the following |
| 106 | additional packages: |
| 107 | |
| 108 | . msys-base |
| 109 | . mingw-developer-toolkit |
| 110 | |
| 111 | (We recommend that you refrain from installing the MSYS Texinfo |
| 112 | package, which is part of msys-base, because it might produce mixed |
| 113 | EOL format when installing Info files. Instead, install the MinGW |
| 114 | port of Texinfo, see the ezwinports URL below. To uninstall the |
| 115 | MSYS Texinfo, after installing it as part of msys-base, invoke the |
| 116 | command "mingw-get remove msys-texinfo".) |
| 117 | |
| 118 | In addition, building Emacs from the development repository requires |
| 119 | pkg-config to be installed. As the MinGW project does not offer it, |
| 120 | you will have to install it from elsewhere; see below (search for |
| 121 | "pkg-config"). |
| 122 | |
| 123 | At this point, you should be ready to configure and build Emacs in |
| 124 | its basic configuration. Skip to the "Generating the configure |
| 125 | script" section for the build instructions. If you want to build it |
| 126 | with image support and other optional libraries, read about the |
| 127 | optional libraries near the end of this document, before you start |
| 128 | the build. Also, consider installing additional MinGW packages that |
| 129 | are required/recommended, especially if you are building from the |
| 130 | repository, as described in the next section. |
| 131 | |
| 132 | ** Installing MinGW and MSYS manually |
| 133 | |
| 134 | *** MinGW |
| 135 | |
| 136 | You will need to install the MinGW port of GCC and Binutils, and the |
| 137 | MinGW runtime and Windows API distributions, to compile Emacs. You |
| 138 | can find these on the MinGW download/Base page: |
| 139 | |
| 140 | https://sourceforge.net/projects/mingw/files/MinGW/Base/ |
| 141 | |
| 142 | In general, install the latest stable versions of the following |
| 143 | MinGW packages from that page: gcc, binutils, mingw-rt, w32api. You |
| 144 | only need the 'bin' and the 'dll' tarballs of each of the above. |
| 145 | |
| 146 | MinGW packages are distributed as .tar.lzma compressed archives. To |
| 147 | install the packages manually, we recommend to use the Windows port |
| 148 | of the 'bsdtar' program to unpack the tarballs. 'bsdtar' is |
| 149 | available as part of the 'libarchive' package from here: |
| 150 | |
| 151 | http://sourceforge.net/projects/ezwinports/files/ |
| 152 | |
| 153 | The recommended place to install these packages is a single tree |
| 154 | starting from some directory on a drive other than the system drive |
| 155 | C:. A typical example would be D:\usr, with D:\usr\bin holding the |
| 156 | binaries and DLLs (should be added to your Path environment |
| 157 | variable), D:\usr\include holding the include files, D:\usr\lib |
| 158 | holding the static and import libraries, D:\usr\share holding docs, |
| 159 | message catalogs, and package-specific subdirectories, etc. |
| 160 | |
| 161 | Having all the headers and libraries in a single place will greatly |
| 162 | reduce the number of -I and -L flags you will have to pass to the |
| 163 | configure script (see below), as these files will be right where the |
| 164 | compiler expects them. |
| 165 | |
| 166 | We specifically do NOT recommend installing packages below |
| 167 | "C:\Program Files" or "C:\Program Files (x86)". These directories |
| 168 | are protected on versions of Windows from Vista and on, and you will |
| 169 | have difficulties updating and maintaining your installation later, |
| 170 | due to UAC elevation prompts, file virtualization, etc. You *have* |
| 171 | been warned! |
| 172 | |
| 173 | Additional MinGW packages are required/recommended, especially if |
| 174 | you are building from the repository: |
| 175 | |
| 176 | . Texinfo (needed to produce the Info manuals when building from |
| 177 | bzr/git, and for "make install") |
| 178 | |
| 179 | Available from http://sourceforge.net/projects/ezwinports/files/. |
| 180 | |
| 181 | . pkg-config (invoked by the configure script to look for optional |
| 182 | packages; _required_ for building from the development |
| 183 | repository, as some components of pkg-config are needed to run |
| 184 | the autoconf and aclocal scripts) |
| 185 | |
| 186 | Available from http://www.gtk.org/download/win32.php |
| 187 | |
| 188 | . gzip (needed to compress files during "make install") |
| 189 | |
| 190 | Available from http://gnuwin32.sourceforge.net/packages/gzip.htm. |
| 191 | |
| 192 | Each package might list other packages as prerequisites on its |
| 193 | download page (under "Runtime requirements"); download those as |
| 194 | well. (Using the mingw-get installer will fetch those prerequisites |
| 195 | automatically for you.) A missing prerequisite will manifest itself |
| 196 | by the program failing to run and presenting a pop-up dialog that |
| 197 | states the missing or incompatible DLL; be sure to find and install |
| 198 | these missing DLLs. |
| 199 | |
| 200 | Once you think you have MinGW installed, test the installation by |
| 201 | building a trivial "hello, world!" program, and make sure that it |
| 202 | builds without any error messages and the binary works when run. |
| 203 | |
| 204 | *** MSYS |
| 205 | |
| 206 | You will need a reasonably full MSYS installation. MSYS is an |
| 207 | environment needed to run the Posix configure scripts and the |
| 208 | resulting Makefile's, in order to produce native Windows binaries |
| 209 | using the MinGW compiler and runtime libraries. Here's the list of |
| 210 | MSYS packages that are required: |
| 211 | |
| 212 | . All the packages from the MSYS Base distribution, listed here: |
| 213 | |
| 214 | https://sourceforge.net/projects/mingw/files/MSYS/Base/ |
| 215 | |
| 216 | . Additional packages listed below, from the MSYS Extension |
| 217 | distribution here: |
| 218 | |
| 219 | https://sourceforge.net/projects/mingw/files/MSYS/Extension/ |
| 220 | |
| 221 | - flex |
| 222 | - bison |
| 223 | - m4 |
| 224 | - perl |
| 225 | - mktemp |
| 226 | |
| 227 | These should only be needed if you intend to build development |
| 228 | versions of Emacs from the repository. |
| 229 | |
| 230 | . Additional packages (needed only if building from the |
| 231 | repository): Automake and Autoconf. They are available from |
| 232 | here: |
| 233 | |
| 234 | http://sourceforge.net/projects/ezwinports/files/automake-1.11.6-msys-bin.zip/download |
| 235 | http://sourceforge.net/projects/ezwinports/files/autoconf-2.65-msys-bin.zip/download |
| 236 | |
| 237 | MSYS packages are distributed as .tar.lzma compressed archives. To |
| 238 | install the packages manually, we recommend to use the Windows port |
| 239 | of the 'bsdtar' program, already mentioned above. |
| 240 | |
| 241 | If/when you are confident in your MinGW/MSYS installation, and want |
| 242 | to speed up the builds, we recommend installing a pre-release |
| 243 | version of Make from here: |
| 244 | |
| 245 | https://sourceforge.net/projects/mingwbuilds/files/external-binary-packages/ |
| 246 | |
| 247 | These are snapshot builds of many packages, but you only need |
| 248 | make.exe from there. The advantage of this make.exe is that it |
| 249 | supports parallel builds, so you can use "make -j N" to considerably |
| 250 | speed up your builds. |
| 251 | |
| 252 | Several users reported that MSYS 1.0.18 causes Make to hang in |
| 253 | parallel builds. If you bump into this, we suggest to downgrade to |
| 254 | MSYS 1.0.17, which doesn't have that problem. |
| 255 | |
| 256 | For each of these packages, install the 'bin' and 'dll' tarballs of |
| 257 | their latest stable releases. If there's an 'ext' tarball (e.g., |
| 258 | msysCORE and Coreutils have it), download and install those as well. |
| 259 | |
| 260 | Each package might list other packages as prerequisites on its |
| 261 | download page (under "Runtime requirements"); download those as |
| 262 | well. (Using the mingw-get installer will fetch those prerequisites |
| 263 | automatically for you.) A missing prerequisite will manifest itself |
| 264 | by the program failing to run and presenting a pop-up dialog that |
| 265 | states the missing or incompatible DLL; be sure to find and install |
| 266 | these missing DLLs. |
| 267 | |
| 268 | MSYS packages should be installed in a separate tree from MinGW. |
| 269 | For example, use D:\MSYS or D:\usr\MSYS as the top-level directory |
| 270 | from which you unpack all of the MSYS packages. |
| 271 | |
| 272 | Do NOT add the MSYS bin directory to your Windows Path! Only the |
| 273 | MinGW bin directory should be on Path. When you install MSYS, it |
| 274 | creates a shortcut on your desktop that invokes the MSYS Bash shell |
| 275 | in a Command Prompt window; that shell is already set up so that the |
| 276 | MSYS bin directory is on PATH ahead of any other directory. Thus, |
| 277 | Bash will find MSYS executables first, which is exactly what you |
| 278 | need. |
| 279 | |
| 280 | At this point, you are ready to build Emacs in its basic |
| 281 | configuration. If you want to build it with image support and other |
| 282 | optional libraries, read about that near the end of this document. |
| 283 | |
| 284 | * Generating the configure script |
| 285 | |
| 286 | If you are building a release or pretest tarball, skip this section, |
| 287 | because the configure script is already present in the tarball. |
| 288 | |
| 289 | To build a development snapshot from the Emacs repository, |
| 290 | you will first need to generate the configure script and a few other |
| 291 | auto-generated files. |
| 292 | |
| 293 | To generate the configure script, type this at the MSYS Bash prompt |
| 294 | from the top-level directory of the Emacs tree: |
| 295 | |
| 296 | ./autogen.sh |
| 297 | |
| 298 | If successful, this command should produce the following output: |
| 299 | |
| 300 | $ ./autogen.sh |
| 301 | Checking whether you have the necessary tools... |
| 302 | (Read INSTALL.REPO for more details on building Emacs) |
| 303 | |
| 304 | Checking for autoconf (need at least version 2.65)... |
| 305 | ok |
| 306 | Checking for automake (need at least version 1.11)... |
| 307 | ok |
| 308 | Your system has the required tools, running autoreconf... |
| 309 | You can now run `./configure'. |
| 310 | |
| 311 | * Configuring Emacs for MinGW: |
| 312 | |
| 313 | Now it's time to run the configure script. You can do that either |
| 314 | from a separate build directory that is outside of the Emacs source |
| 315 | tree (recommended), or from inside the source tree. The former is |
| 316 | recommended because it allows you to have several different builds, |
| 317 | e.g., an optimized build and an unoptimized one, of the same |
| 318 | revision of the source tree; the source tree will be left in its |
| 319 | pristine state, without any build products. |
| 320 | |
| 321 | You invoke the configure script like this: |
| 322 | |
| 323 | /PATH/TO/EMACS/SOURCE/TREE/configure --prefix=PREFIX ... |
| 324 | |
| 325 | or, if you are building in-place, i.e. inside the source tree: |
| 326 | |
| 327 | ./configure --prefix=PREFIX ... |
| 328 | |
| 329 | Here PREFIX is the place where you eventually want to install Emacs |
| 330 | once built, e.g. /d/usr. We recommend to always use --prefix when |
| 331 | building Emacs on Windows, because the default '/usr/local' is not |
| 332 | appropriate for Windows: it will be mapped by MSYS to something like |
| 333 | C:\MSYS\local, and it will defeat the purpose of PREFIX, which is to |
| 334 | install programs in a single coherent tree resembling Posix systems. |
| 335 | Such a single-tree installation makes sure all the other programs |
| 336 | and packages ported from GNU or Unix systems will work seamlessly |
| 337 | together. Where exactly is the root of that tree on your system is |
| 338 | something only you, the user who builds Emacs, can know, and the |
| 339 | Emacs build process cannot guess, because usually there's no |
| 340 | '/usr/local' directory on any drive on Windows systems. |
| 341 | |
| 342 | Do NOT use Windows-style x:/foo/bar file names on the configure |
| 343 | script command line; use the MSYS-style /x/foo/bar instead. Using |
| 344 | Windows-style file names was reported to cause subtle and hard to |
| 345 | figure out problems during the build. This applies both to the |
| 346 | command switches, such as --prefix=, and to the absolute file name |
| 347 | of 'configure', if you are building outside of the source tree. |
| 348 | |
| 349 | You can pass additional options to the configure script, for the |
| 350 | full list type |
| 351 | |
| 352 | ./configure --help |
| 353 | |
| 354 | As explained in the help text, you may need to tell the script what |
| 355 | are the optional flags to invoke the compiler. This is needed if |
| 356 | some of your headers and libraries, e.g., those belonging to |
| 357 | optional image libraries, are installed in places where the compiler |
| 358 | normally doesn't look for them. (Remember that advice above to |
| 359 | avoid such situations? here's is where you will start paying for |
| 360 | disregarding that recommendation.) For example, if you have libpng |
| 361 | headers in C:\emacs\libs\libpng-1.2.37-lib\include and jpeg library |
| 362 | headers in C:\emacs\libs\jpeg-6b-4-lib\include, you will need to say |
| 363 | something like this: |
| 364 | |
| 365 | CPPFLAGS='-I/c/emacs/libs/libpng-1.2.37-lib/include -I/c/emacs/libs/jpeg-6b-4-lib/include' ./configure --prefix=PREFIX |
| 366 | |
| 367 | which is quite a mouth-full, especially if you have more directories |
| 368 | to specify... Perhaps you may wish to revisit your installation |
| 369 | decisions now. |
| 370 | |
| 371 | If you have a global site-lisp directory from previous Emacs |
| 372 | installation, and you want Emacs to continue using it, specify it |
| 373 | via the --enable-locallisppath switch to 'configure', like this: |
| 374 | |
| 375 | ./configure --prefix=PREFIX --enable-locallisppath="/d/usr/share/emacs/VERSION/site-lisp:/d/wherever/site-lisp" |
| 376 | |
| 377 | Use the normal MSYS /d/foo/bar style to specify directories by their |
| 378 | absolute file names. |
| 379 | |
| 380 | A few frequently used options are needed when you want to produce an |
| 381 | unoptimized binary with runtime checks enabled: |
| 382 | |
| 383 | CFLAGS='-O0 -g3' ./configure --prefix=PREFIX --enable-checking='yes,glyphs' |
| 384 | |
| 385 | Once invoked, the configure script will run for some time, and, if |
| 386 | successful, will eventually produce a summary of the configuration |
| 387 | similar to this: |
| 388 | |
| 389 | Configured for `i686-pc-mingw32'. |
| 390 | |
| 391 | Where should the build process find the source code? /path/to/emacs/sources |
| 392 | What compiler should emacs be built with? gcc -std=gnu99 -O0 -g3 |
| 393 | Should Emacs use the GNU version of malloc? yes |
| 394 | Should Emacs use a relocating allocator for buffers? yes |
| 395 | Should Emacs use mmap(2) for buffer allocation? no |
| 396 | What window system should Emacs use? w32 |
| 397 | What toolkit should Emacs use? none |
| 398 | Where do we find X Windows header files? NONE |
| 399 | Where do we find X Windows libraries? NONE |
| 400 | Does Emacs use -lXaw3d? no |
| 401 | Does Emacs use -lXpm? yes |
| 402 | Does Emacs use -ljpeg? yes |
| 403 | Does Emacs use -ltiff? yes |
| 404 | Does Emacs use a gif library? yes |
| 405 | Does Emacs use -lpng? yes |
| 406 | Does Emacs use -lrsvg-2? no |
| 407 | Does Emacs use imagemagick? no |
| 408 | Does Emacs use -lgpm? no |
| 409 | Does Emacs use -ldbus? no |
| 410 | Does Emacs use -lgconf? no |
| 411 | Does Emacs use GSettings? no |
| 412 | Does Emacs use -lselinux? no |
| 413 | Does Emacs use -lgnutls? yes |
| 414 | Does Emacs use -lxml2? yes |
| 415 | Does Emacs use -lfreetype? no |
| 416 | Does Emacs use -lm17n-flt? no |
| 417 | Does Emacs use -lotf? no |
| 418 | Does Emacs use -lxft? no |
| 419 | Does Emacs use toolkit scroll bars? yes |
| 420 | |
| 421 | You are almost there, hang on. |
| 422 | |
| 423 | If the output is significantly different, or if configure finishes |
| 424 | prematurely and displays some error message, you should examine the |
| 425 | configuration log in config.log and find the reason for the failure. |
| 426 | |
| 427 | Once you succeeded in configuring Emacs, and just want to rebuild it |
| 428 | after updating your local repository from the main repository, you |
| 429 | don't need to re-run the configure script manually, unless you want |
| 430 | to change the configure-time options. Just typing "make" will |
| 431 | re-run configure if necessary with the exact same options you |
| 432 | specified originally, and then go on to invoking Make, described |
| 433 | below. |
| 434 | |
| 435 | * Running Make. |
| 436 | |
| 437 | This is simple: just type "make" and sit back, watching the fun. |
| 438 | |
| 439 | If you installed a snapshot build of Make, the build will be much |
| 440 | faster if you type "make -j N" instead, where N is the number of |
| 441 | independent processing units on your machine. E.g., on a core i7 |
| 442 | system try using N of 6 or even 8. (If this hangs, see the notes |
| 443 | above about downgrading to MSYS 1.0.17.) |
| 444 | |
| 445 | When Make finishes, you can install the produced binaries: |
| 446 | |
| 447 | make install |
| 448 | |
| 449 | or, if you want the installed tree to go in a place different from |
| 450 | the configured one, type |
| 451 | |
| 452 | make install prefix=WHEREVER |
| 453 | |
| 454 | Congrats! You have built and installed your own Emacs! |
| 455 | |
| 456 | * Make targets |
| 457 | |
| 458 | The following make targets may be used by users building the source |
| 459 | distribution, or users who have checked out of the repository after |
| 460 | an initial bootstrapping. |
| 461 | |
| 462 | make |
| 463 | Builds Emacs from the available sources and pre-compiled lisp files. |
| 464 | |
| 465 | make install |
| 466 | Installs the built programs and the auxiliary files. |
| 467 | |
| 468 | make clean |
| 469 | Removes object and executable files produced by the build process in |
| 470 | the current configuration. After "make clean", you can rebuild with |
| 471 | the same configuration using make. useful when you want to be sure |
| 472 | that all of the products are built from coherent sources. |
| 473 | |
| 474 | make distclean |
| 475 | In addition to the files removed by make clean, this also removes |
| 476 | Makefiles and other generated files to get back to the state of a |
| 477 | freshly unpacked source distribution. After make distclean, it is |
| 478 | necessary to run the configure script followed by "make", in order |
| 479 | to rebuild. |
| 480 | |
| 481 | The following targets are intended only for use with the repository |
| 482 | sources. |
| 483 | |
| 484 | make bootstrap |
| 485 | Removes all the auto-generated files and all the *.elc byte-compiled |
| 486 | files, and builds Emacs from scratch. Useful when some change in |
| 487 | basic Emacs functionality makes byte compilation of updated files |
| 488 | fail. |
| 489 | |
| 490 | make maintainer-clean |
| 491 | Removes everything that can be recreated, including compiled Lisp |
| 492 | files, to get back to the state of a fresh repository tree. After make |
| 493 | maintainer-clean, it is necessary to run configure and "make" or |
| 494 | "make bootstrap" to rebuild. Occasionally it may be necessary to |
| 495 | run this target after an update. |
| 496 | |
| 497 | * Optional image library support |
| 498 | |
| 499 | In addition to its "native" image formats (pbm and xbm), Emacs can |
| 500 | handle other image types: xpm, tiff, gif, png, jpeg and experimental |
| 501 | support for svg. |
| 502 | |
| 503 | To build Emacs with support for them, the corresponding headers must |
| 504 | be in the include path and libraries should be where the linker |
| 505 | looks for them, when the configure script is run. If needed, this |
| 506 | can be set up using the CPPFLAGS and CFLAGS variable specified on |
| 507 | the configure command line. The configure script will report |
| 508 | whether it was able to detect the headers and libraries. If the |
| 509 | results of this testing appear to be incorrect, please look for |
| 510 | details in the file config.log: it will show the failed test |
| 511 | programs and compiler error messages that should explain what is |
| 512 | wrong. (Usually, any such failures happen because some headers are |
| 513 | missing due to bad packaging of the image support libraries.) |
| 514 | |
| 515 | Note that any file path passed to the compiler or linker must use |
| 516 | forward slashes, or double each backslash, as that is how Bash |
| 517 | works. |
| 518 | |
| 519 | If the configure script finds the necessary headers and libraries, |
| 520 | but they are for some reason incompatible, or if you want to omit |
| 521 | support for some image library that is installed on your system for |
| 522 | some other reason, use the --without-PACKAGE option to configure, |
| 523 | such as --without-gif to omit GIF, --without-tiff to omit TIFF, etc. |
| 524 | Passing the --help option to the configure script displays all of |
| 525 | the supported --without-PACKAGE options. |
| 526 | |
| 527 | To use the external image support, the DLLs implementing the |
| 528 | functionality must be found when Emacs first needs them, either on the |
| 529 | PATH, or in the same directory as emacs.exe. Failure to find a |
| 530 | library is not an error; the associated image format will simply be |
| 531 | unavailable. Note that once Emacs has determined that a library can |
| 532 | not be found, there's no way to force it to try again, other than |
| 533 | restarting. See the variable `dynamic-library-alist' to configure the |
| 534 | expected names of the libraries. |
| 535 | |
| 536 | Some image libraries have dependencies on one another, or on zlib. |
| 537 | For example, tiff support depends on the jpeg library. If you did not |
| 538 | compile the libraries yourself, you must make sure that any dependency |
| 539 | is in the PATH or otherwise accessible and that the binaries are |
| 540 | compatible (for example, that they were built with the same compiler). |
| 541 | |
| 542 | For PNG images, we recommend to use versions 1.4.x and later of |
| 543 | libpng, because previous versions had security issues. You can find |
| 544 | precompiled libraries and headers on the GTK download page for |
| 545 | Windows (http://www.gtk.org/download/win32.php for 32-bit builds and |
| 546 | http://www.gtk.org/download/win64.php for 64-bit builds). The |
| 547 | ezwinports site, http://sourceforge.net/projects/ezwinports/files/ |
| 548 | also offers PNG (as well as other image libraries), which are |
| 549 | usually newer. |
| 550 | |
| 551 | Versions 1.4.0 and later of libpng are binary incompatible with |
| 552 | earlier versions, so Emacs will only look for libpng libraries which |
| 553 | are compatible with the version it was compiled against. That |
| 554 | version is given by the value of the Lisp variable `libpng-version'; |
| 555 | e.g., 10403 means version 1.4.3. The variable `dynamic-library-alist' |
| 556 | is automatically set to name only those DLL names that are known to |
| 557 | be compatible with the version given by `libpng-version'. If PNG |
| 558 | support does not work for you even though you have the support DLL |
| 559 | installed, check the name of the installed DLL against |
| 560 | `dynamic-library-alist' and the value of `libpng-version', and |
| 561 | download compatible DLLs if needed. |
| 562 | |
| 563 | For GIF images, we recommend to use versions 5.0.0 or later of |
| 564 | giflib, as it is much enhanced wrt previous versions. You can find |
| 565 | precompiled binaries and headers for giflib on the ezwinports site, |
| 566 | http://sourceforge.net/projects/ezwinports/files/. |
| 567 | |
| 568 | Version 5.0.0 and later of giflib are binary incompatible with |
| 569 | previous versions (the signatures of several functions have |
| 570 | changed), so Emacs will only look for giflib libraries that are |
| 571 | compatible with the version it was compiled against. Similar to |
| 572 | libpng, that version is given by the value of the Lisp variable |
| 573 | `libgif-version'; e.g., 50005 means version 5.0.5. The variable |
| 574 | `dynamic-library-alist' is automatically set to name only those DLL |
| 575 | libraries that are known to be compatible with the version given by |
| 576 | `libgif-version'. |
| 577 | |
| 578 | For JPEG images, you will need libjpeg 6b or later, which will be |
| 579 | called libjpeg-N.dll, jpeg62.dll, libjpeg.dll, or jpeg.dll. You can |
| 580 | find these on the ezwinports site. |
| 581 | |
| 582 | TIFF images require libTIFF 3.0 or later, which will be called |
| 583 | libtiffN.dll or libtiff-N.dll or libtiff.dll. These can be found on |
| 584 | the ezwinports site. |
| 585 | |
| 586 | Pre-built versions of librsvg and its dependencies can be found in |
| 587 | one of these places: |
| 588 | |
| 589 | 1. http://sourceforge.net/projects/ezwinports/files/ |
| 590 | |
| 591 | This site includes a minimal (as much as possible for librsvg) |
| 592 | build of the library and its dependencies; it is also more |
| 593 | up-to-date with the latest upstream versions. However, it |
| 594 | currently only offers 32-bit builds. For building Emacs, you |
| 595 | need to download from this site all of the following *-bin.zip |
| 596 | archives: |
| 597 | |
| 598 | librsvg, gdk-pixbuf, cairo, glib |
| 599 | |
| 600 | The 'bin' archives on this site include both header files and the |
| 601 | libraries needed for building with librsvg and for running Emacs. |
| 602 | The librsvg archive includes all the shared libraries needed to |
| 603 | run Emacs with SVG support; the other 3 packages are required |
| 604 | because the compiler needs to see their header files when |
| 605 | building Emacs. |
| 606 | |
| 607 | 2. GTK project download site for Windows (see above for 2 URLs, |
| 608 | either for 32-bit builds or 64-bit builds) |
| 609 | |
| 610 | This is the official Windows download site of the GTK project. |
| 611 | Its builds of librsvg are fatter, but are currently the only |
| 612 | alternative for 64-bit builds. The easiest way to obtain the |
| 613 | dependencies required for building from this site is to download |
| 614 | a pre-bundled GTK+ development environment for Windows. If you |
| 615 | would nevertheless like to download only the packages that are |
| 616 | strictly required, then, as of the time of this writing, here's |
| 617 | the list of GTK+ packages you will need: |
| 618 | |
| 619 | librsvg, pango, freetype-2.4.11, freetype-2.4.2, croco, cairo, |
| 620 | glib, gdk-pixbuf, fontconfig, libpng-1.4.x, libpng-1.5.x, |
| 621 | libffi, libxml2, zlib |
| 622 | |
| 623 | The GTK download page provides 2 separate archives for each |
| 624 | package: a 'bin' (binary) archive with programs and DLLs, and a |
| 625 | 'dev' (development) archive with header files, import libraries, |
| 626 | and pkg-config files; download and install both archives for each |
| 627 | package you need. (Sources of each package are available in a |
| 628 | separate, 3rd archive.) |
| 629 | |
| 630 | As you see, some libraries for using this site's librsvg are |
| 631 | needed in more than one version -- this is because librsvg and |
| 632 | some of its dependencies were linked against different versions |
| 633 | of those libraries, and will look only for those DLLs when you |
| 634 | invoke SVG function. So there's a bit of "DLL hell" involved |
| 635 | here, but at least in theory this should work, as each library |
| 636 | will dynamically link only against its dependencies, even if |
| 637 | another version of the same library is already loaded. In |
| 638 | particular, at least 2 different versions of libpng will have to |
| 639 | be installed on your machine. When you install these libpng |
| 640 | versions, be sure to keep the header files and the pkg-config |
| 641 | files in sync, i.e. install both the 'bin' and 'dev' archives of |
| 642 | the same libpng version together. |
| 643 | |
| 644 | To use librsvg at runtime, ensure that librsvg and its dependencies |
| 645 | are on your PATH, or in the same directory as the emacs.exe binary. |
| 646 | If you are downloading from the ezwinports site, you only need to |
| 647 | install a single archive, librsvg-X.Y.Z-w32-bin.zip, which includes |
| 648 | all the dependency DLLs. For the GTK project site, download the |
| 649 | 'bin' archives for each of the libraries mentioned above. |
| 650 | |
| 651 | If you think you've got all the dependencies and SVG support is |
| 652 | still not working, check your PATH for other libraries that shadow |
| 653 | the ones you downloaded. Libraries of the same name from different |
| 654 | sources may not be compatible, this problem was encountered in the |
| 655 | past, e.g., with libcroco from gnome.org. |
| 656 | |
| 657 | If you can see etc/images/splash.svg, then you have managed to get |
| 658 | SVG support working. Congratulations for making it through DLL hell |
| 659 | to this point. For some SVG images, you'll probably see error |
| 660 | messages from Glib about failed assertions, or warnings from Pango |
| 661 | about failure to load fonts (installing the missing fonts should fix |
| 662 | the latter kind of problems). Problems have been observed in some |
| 663 | images that contain text, they seem to be a problem in the Windows |
| 664 | port of Pango, or maybe a problem with the way Cairo or librsvg is |
| 665 | using it that doesn't show up on other platforms. However, Emacs |
| 666 | should not crash due to these issues. If you eventually find the |
| 667 | SVG support too unstable to your taste, you can rebuild Emacs |
| 668 | without it by specifying the --without-rsvg switch to the configure |
| 669 | script. |
| 670 | |
| 671 | Binaries for the other image libraries can be found on the |
| 672 | ezwinports site or at the GnuWin32 project (the latter are generally |
| 673 | very old, so not recommended). Note specifically that, due to some |
| 674 | packaging snafus in the GnuWin32-supplied image libraries, you will |
| 675 | need to download _source_ packages for some of the libraries in |
| 676 | order to get the header files necessary for building Emacs with |
| 677 | image support. |
| 678 | |
| 679 | * Optional GnuTLS support |
| 680 | |
| 681 | To compile with GnuTLS, you will need pkg-config to be installed, as |
| 682 | the configure script invokes pkg-config to find out which compiler |
| 683 | switches to use for GnuTLS. See above for the URL where you can |
| 684 | find pkg-config for Windows. |
| 685 | |
| 686 | You will also need to install the p11-kit package, which is a |
| 687 | dependency of GnuTLS, and its header files are needed for |
| 688 | compilation of programs that use GnuTLS. You can find p11-kit on |
| 689 | the same site as GnuTLS, see the URL below. |
| 690 | |
| 691 | If the configure script finds the GnuTLS header files and libraries |
| 692 | on your system, Emacs is built with GnuTLS support by default; to |
| 693 | avoid that you can pass the argument --without-gnutls. |
| 694 | |
| 695 | In order to support GnuTLS at runtime, a GnuTLS-enabled Emacs must |
| 696 | be able to find the relevant DLLs during startup; failure to do so |
| 697 | is not an error, but GnuTLS won't be available to the running |
| 698 | session. |
| 699 | |
| 700 | You can get pre-built binaries (including any required DLL and the |
| 701 | header files) at http://sourceforge.net/projects/ezwinports/files/. |
| 702 | |
| 703 | * Optional libxml2 support |
| 704 | |
| 705 | To compile with libxml2, you will need pkg-config to be installed, |
| 706 | as the configure script invokes pkg-config to find out which |
| 707 | compiler switches to use for libxml2. See above for the URL where |
| 708 | you can find pkg-config for Windows. |
| 709 | |
| 710 | If the configure script finds the libxml2 header files and libraries |
| 711 | on your system, Emacs is built with libxml2 support by default; to |
| 712 | avoid that you can pass the argument --without-libxml2. |
| 713 | |
| 714 | In order to support libxml2 at runtime, a libxml2-enabled Emacs must |
| 715 | be able to find the relevant DLLs during startup; failure to do so |
| 716 | is not an error, but libxml2 features won't be available to the |
| 717 | running session. |
| 718 | |
| 719 | One place where you can get pre-built Windows binaries of libxml2 |
| 720 | (including any required DLL and the header files) is here: |
| 721 | |
| 722 | http://sourceforge.net/projects/ezwinports/files/ |
| 723 | |
| 724 | For runtime support of libxml2, you will also need to install the |
| 725 | libiconv "development" tarball, because the libiconv headers need to |
| 726 | be available to the compiler when you compile with libxml2 support. |
| 727 | A MinGW port of libiconv can be found on the MinGW site: |
| 728 | |
| 729 | http://sourceforge.net/projects/mingw/files/MinGW/Base/libiconv/ |
| 730 | |
| 731 | You need the libiconv-X.Y.Z-N-mingw32-dev.tar.lzma tarball from that |
| 732 | site. |
| 733 | |
| 734 | \f |
| 735 | This file is part of GNU Emacs. |
| 736 | |
| 737 | GNU Emacs is free software: you can redistribute it and/or modify |
| 738 | it under the terms of the GNU General Public License as published by |
| 739 | the Free Software Foundation, either version 3 of the License, or |
| 740 | (at your option) any later version. |
| 741 | |
| 742 | GNU Emacs is distributed in the hope that it will be useful, |
| 743 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 744 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 745 | GNU General Public License for more details. |
| 746 | |
| 747 | You should have received a copy of the GNU General Public License |
| 748 | along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |