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