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