"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/nt/INSTALL" (25 May 2018, 36708 Bytes) of package /linux/misc/emacs-26.1.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 latest Fossies "Diffs" side-by-side code changes report for "INSTALL": 25.3_vs_26.1.

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