"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/nt/INSTALL" (14 Apr 2017, 36458 Bytes) of package /linux/misc/emacs-25.3.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "INSTALL": 25.1_vs_25.2.

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