path: root/src/INSTALLpc.txt

INSTALLpc.txt - Installation of Vim on PC

This file contains instructions for compiling Vim. If you already have an
executable version of Vim, you don't need this.

You can find the latest here: https://github.com/vim/vim-win32-installer
This page also has links to install support for interfaces such as Perl,
Python, Lua, etc.

The file "feature.h" can be edited to match your preferences. You can skip
this, then you will get the default behavior as is documented, which should
be fine for most people.

This document assumes that you are building Vim for Win32 or later (Windows
XP/2003/Vista/7/8/10).  There are also instructions for pre-XP systems, but
they might no longer work.

The recommended way is to build a 32 bit Vim, also on 64 bit systems.  You can
build a 64 bit Vim if you like, the executable will be bigger and Vim won't be
any faster, but you can edit files larger than 2 Gbyte.


Contents:
1. Microsoft Visual C++
2. Using MSYS2 with MinGW
3. Using MinGW
4. Cygwin
5. Cross compiling for Win32 from a Linux machine
6. Building with Python support
7. Building with Python3 support
8. Building with Racket or MzScheme support
9. Building with Lua support
10. Building with Perl support
11. Building with Ruby support
12. Building with Tcl support
13. Building with DirectX (DirectWrite) support
14. Windows 3.1
15. MS-DOS

16. Installing after building from sources


The currently recommended way (that means it has been verified to work) is
using the "Visual Studio Community 2015" installation.  This includes the SDK
needed to target Windows XP.  But not older Windows versions (95, 98), see
"OLDER VERSIONS" below for that.


1. Microsoft Visual C++
=======================

We do not provide download links, since Microsoft keeps changing them.  You
can search for "Visual Studio Community 2015", for example.  You will need to
create a Microsoft account (it's free).

When installing "Visual Studio Community 2015 with Update 3" make sure to
select "custom" and check "Windows XP Support for C++" and all checkboxes
under "Universal Windows App Development Tools"


Visual Studio
-------------

Building with Visual Studio (VS2010, VS2012, VS2013, VS2015, VS2017 and VS2019)
is straightforward.

To build Vim from the command line with MSVC, use Make_mvc.mak.
Visual Studio installed a batch file called vcvars32.bat, which you must
run to set up paths for nmake and MSVC.

nmake -f Make_mvc.mak		console   Win32 SDK or Microsoft Visual C++
nmake -f Make_mvc.mak GUI=yes	GUI	  Microsoft Visual C++
nmake -f Make_mvc.mak OLE=yes	OLE	  Microsoft Visual C++
nmake -f Make_mvc.mak PERL=C:\Perl PYTHON=C:\Python etc.
				Perl, Python, etc.

Make_mvc.mak allows a Vim to be built with various different features and
debug support.

For compiling gVim with IME support on far-east Windows, add IME=yes
to the parameters you pass to Make_mvc.mak.

See the specific files for comments and options.

These files have been supplied by George V. Reilly, Ben Singer, Ken Scott and
Ron Aaron; they have been tested.


Visual C++ 2010 Express Edition       *msvc-2010-express*
-------------------------------

Visual C++ 2010 Express Edition can be downloaded for free from:
    http://www.microsoft.com/express/vc/Default.aspx
This includes the IDE and the debugger.

To set the environment execute the msvc2010.bat script.  You can then build
Vim with Make_mvc.mak.


Targeting Windows XP with MSVC 2012 and later      *new-msvc-windows-xp*
---------------------------------------------

Beginning with Visual C++ 2012, Microsoft changed the behavior of LINK.EXE
so that it targets Windows 6.0 (Vista) by default.  In order to override
this, the target Windows version number needs to be passed to LINK like
follows:
    LINK ... /subsystem:console,5.01

Make_mvc.mak now supports a macro SUBSYSTEM_VER to pass the Windows version.
Use lines like follows to target Windows XP x86 (assuming using Visual C++
2012 under 64-bit Windows):
    set WinSdk71=%ProgramFiles(x86)%\Microsoft SDKs\Windows\v7.1A
    set INCLUDE=%WinSdk71%\Include;%INCLUDE%
    set LIB=%WinSdk71%\Lib;%LIB%
    set CL=/D_USING_V110_SDK71_
    nmake -f Make_mvc.mak ... WINVER=0x0501 SUBSYSTEM_VER=5.01

To target Windows XP x64 instead of x86, you need to change the settings of
LIB and SUBSYSTEM_VER:
    ...
    set LIB=%WinSdk71%\Lib\x64;%LIB%
    ...
    nmake -f Make_mvc.mak ... WINVER=0x0501 SUBSYSTEM_VER=5.02

If you use Visual C++ 2015 (either Express or Community Edition), executing
msvc2015.bat will set them automatically.  For x86 builds run this without
options:
  msvc2015
For x64 builds run this with the "x86_amd64" option:
  msvc2015 x86_amd64
This enables x86_x64 cross compiler. This works on any editions including
Express edition.
If you use Community (or Professional) edition, you can enable the x64 native
compiler by using the "x64" option:
  msvc2015 x64

The following Visual C++ team blog can serve as a reference page:
    http://blogs.msdn.com/b/vcblog/archive/2012/10/08/windows-xp-targeting-with-c-in-visual-studio-2012.aspx

VC 2019 dropped support for targeting Windows XP.  If you want a binary that
targeting Windows XP, use VC 2017 or earlier.


Cross compile support for Windows on ARM64
------------------------------------------

This depends on VS2017 with the optional ARM64 compiler and SDK
installed. Use "vcvarsall.bat x64_arm64" as the build environment.

The ARM64 support was provided by Leendert van Doorn.


OLDER VERSIONS

The minimal supported version is Windows XP. Building with older compilers
might still work, but these instructions might be outdated.

If you need the executable to run on Windows 98 or ME, use the 2003 one
|msvc-2003-toolkit| or |msvc-2005-express|, and use the source code before
8.0.0029.

Visual C++ Toolkit 2003				*msvc-2003-toolkit*
-----------------------

NOTE: this most likely does not work

You could download the Microsoft Visual C++ Toolkit 2003 from
    http://msdn.microsoft.com/visualc/vctoolkit2003/
Unfortunately this URL is no longer valid.  Unofficial downloads appear to be
available from links mentioned on these pages (use at your own risk):
   http://www.filewatcher.com/m/VCToolkitSetup.exe.32952488.0.0.html
   http://feargame.net/wiki/index.php?title=Building_Source_with_the_VC2003_Toolkit

This contains the command-line tools (compiler, linker, CRT headers,
and libraries) for Visual Studio .NET 2003, but not the Visual Studio IDE.
To compile and debug Vim with the VC2003 Toolkit, you will also need
|ms-platform-sdk|, |dotnet-1.1-redist|, |dotnet-1.1-sdk|,
and |windbg-download|.

It's easier to download Visual C++ 2008 Express Edition, |msvc-2008-express|,
which is freely available in perpetuity.

The free Code::Blocks IDE works with the VC2003 Toolkit, as described at
    http://wiki.codeblocks.org/index.php?title=Integrating_Microsoft_Visual_Toolkit_2003_with_Code::Blocks_IDE
(This site also takes you through configuring a number of other
free C compilers for Win32.)

To compile Vim using the VC2003 Toolkit and Make_mvc.mak, you must first
execute the following commands in a cmd.exe window (the msvcsetup.bat batch
file can be used):

    set PATH=%SystemRoot%\Microsoft.NET\Framework\v1.1.4322;%PATH%
    call "%VCToolkitInstallDir%vcvars32.bat"
    set MSVCVer=7.1
    call "%ProgramFiles%\Microsoft Platform SDK\SetEnv.Cmd"
    set LIB=%ProgramFiles%\Microsoft Visual Studio .NET 2003\Vc7\lib;%LIB%

Now you can build Vim with Make_mvc.mak.


Getting the Windows Platform SDK	    *ms-platform-sdk*

You will also need a copy of the Windows Platform SDK.  Specifically, you need
the Windows Core SDK subset of the Platform SDK, which contains the Windows
headers and libraries.  You need to search for it, Microsoft keeps changing
the URL.


Getting the .NET Framework 1.1 Runtime      *dotnet-1.1-redist*

You need the .NET Framework 1.1 Redistributable Package from
    http://www.microsoft.com/downloads/details.aspx?familyid=262d25e3-f589-4842-8157-034d1e7cf3a3
or from Windows Update:
    http://windowsupdate.microsoft.com/
This is needed to install |dotnet-1.1-sdk|. It also contains cvtres.exe,
which is needed to link Vim.


Getting the .NET Framework 1.1 SDK	    *dotnet-1.1-sdk*

You need the .NET Framework 1.1 SDK from
    http://www.microsoft.com/downloads/details.aspx?familyid=9b3a2ca6-3647-4070-9f41-a333c6b9181d
This contains some additional libraries needed to compile Vim,
such as msvcrt.lib. You must install |dotnet-1.1-redist| before
installing the .NET 1.1 SDK.


Getting the WinDbg debugger		    *windbg-download*

The Debugging Tools for Windows can be downloaded from
    http://www.microsoft.com/whdc/devtools/debugging/default.mspx
This includes the WinDbg debugger, which you will want if you ever need
to debug Vim itself. An earlier version of the Debugging Tools
is also available through the Platform SDK, |ms-platform-sdk|.


Visual C++ 2005 Express Edition       *msvc-2005-express*
-------------------------------

NOTE: this most likely does not work

Visual C++ 2005 Express Edition can be downloaded for free from:
    http://msdn.microsoft.com/vstudio/express/visualC/default.aspx
This includes the IDE and the debugger. You will also need
|ms-platform-sdk|. You can build Vim with Make_mvc.mak.

Instructions for integrating the Platform SDK into VC Express:
    http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/default.aspx


Visual C++ 2008 Express Edition       *msvc-2008-express*
-------------------------------

NOTE: this most likely does not work

Visual C++ 2008 Express Edition can be downloaded for free from:
    http://www.microsoft.com/express/downloads/
This includes the IDE and the debugger.

To set the environment execute the msvc2008.bat script.  You can then build
Vim with Make_mvc.mak.

For building 64 bit binaries you also need to install the SDK:
"Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 SP1"
You don't need the examples and documentation.


2. MSYS2 with MinGW
===================

2.1. Setup the basic msys2 environment

Go to the official page of MSYS2: https://www.msys2.org
Download an installer:

* msys2-x86_64-YYYYMMDD.exe for 64-bit Windows
  (Even if you want to build 32-bit Vim)
* msys2-i686-YYYYMMDD.exe for 32-bit Windows

Execute the installer and follow the instructions to update basic packages.
At the end keep the checkbox checked to run msys2 now.  If needed, you can
open the window from the start menu, MSYS2 64 bit / MSYS2 MSYS.

Execute:
    $ pacman -Syu

And restart MSYS2 console (select "MSYS2 MSYS 32-Bit" icon from the Start
Menu for building 32 bit Vim, otherwise select "MSYS2 MinGW 64-Bit").
Then execute:
    $ pacman -Su

If pacman complains that `catgets` and `libcatgets` conflict with another
package, select `y` to remove them.


2.2. Install additional packages for building Vim

The following package groups are required for building Vim:

* base-devel
* mingw-w64-i686-toolchain (for building 32-bit Vim)
* mingw-w64-x86_64-toolchain (for building 64-bit Vim)

(These groups also include some useful packages which are not used by Vim.)
Use the following command to install them:

    $ pacman -S base-devel mingw-w64-i686-toolchain mingw-w64-x86_64-toolchain

Or you can use the `pacboy` command to avoid long package names:

    $ pacboy -S base-devel: toolchain:m

The suffix ":" means that it disables the package name translation.
The suffix ":m" means both i686 and x86_64.  You can also use the ":i" suffix
to install only i686, and the ":x" suffix to install only x86_64.
(See `pacboy help` for the help.)

See also the pacman page in ArchWiki for the general usage of pacman:
    https://wiki.archlinux.org/index.php/pacman

MSYS2 has its own git package, and you can also install it via pacman:

    $ pacman -S git

For enabling libsodium support, you also need to install the package

    $ pacman -S mingw-w64-x86_64-libsodium

2.3. Keep the build environment up-to-date

After you have installed the build environment, you may want to keep it
up-to-date (E.g. always use the latest GCC).
In that case, you just need to execute the command:
    $ pacman -Syu


2.4. Build Vim

Select one of the following icon from the Start Menu:

* MSYS2 MinGW 32-bit (To build 32-bit versions of Vim)
* MSYS2 MinGW 64-bit (To build 64-bit versions of Vim)

Go to the source directory of Vim, then execute the make command.  E.g.:

    make -f Make_ming.mak
    make -f Make_ming.mak GUI=no
    make -f Make_ming.mak GUI=no DEBUG=yes

NOTE: you can't execute vim.exe in the MSYS2 console, open a normal Windows
console for that.  You need to set $PATH to be able to build there, e.g.:

    set PATH=c:\msys64\mingw32\bin;c:\msys64\usr\bin;%PATH%

This command is in msys32.bat.  Or for the 64 bit compiler use msys64.bat:

    set PATH=c:\msys64\mingw64\bin;c:\msys64\usr\bin;%PATH%

If you have msys64 in another location you will need to adjust the paths for
that.


3. MinGW
========

(written by Ron Aaron: <ronaharon@yahoo.com>, updated by Ken Takata, et al.)

This is about how to produce a Win32 binary of gvim with MinGW from the normal
Command Prompt window.  (To use MSYS2 console, see above.)

First, you need to get the 'MinGW-w64' compiler, which is free for the
download at:

    http://mingw-w64.sourceforge.net/

Or a compiler provided on msys2:

    https://www.msys2.org/

The original 'mingw32' compiler is outdated, and may no longer work:

    http://www.mingw.org/

Once you have downloaded the compiler binaries, unpack them on your hard disk
somewhere, and put them on your PATH.  Go to the Control Panel, (Performance
and Maintenance), System, Advanced, and edit the environment from there.  If
you use the standalone MinGW-w64 compiler, the path may depend on your
installation.  If you use msys2 compilers, set your installed paths (normally
one of the following):

    C:\msys32\mingw32\bin   (32-bit msys2, targeting 32-bit builds)
    C:\msys64\mingw32\bin   (64-bit msys2, targeting 32-bit builds)
    C:\msys64\mingw64\bin   (64-bit msys2, targeting 64-bit builds)

Test if gcc is on your path.  From a Command Prompt window:

    C:\> gcc --version
    gcc (GCC) 4.8.1

    C:\> mingw32-make --version
    GNU Make 3.82.90 (...etc...)

Now you are ready to rock 'n' roll.  Unpack the vim sources (look on
www.vim.org for exactly which version of the vim files you need).

Change directory to 'vim\src':

    C:\> cd vim\src
    C:\VIM\SRC>

and you type:

    mingw32-make -f Make_ming.mak gvim.exe

After churning for a while, you will end up with 'gvim.exe' in the 'vim\src'
directory.

You should not need to do *any* editing of any files to get vim compiled this
way.  If, for some reason, you want the console-mode-only version of vim (this
is NOT recommended on Win32, especially on '95/'98!!!), you can use:

    mingw32-make -f Make_ming.mak GUI=no vim.exe

If you are dismayed by how big the EXE is, I strongly recommend you get 'UPX'
(also free!) and compress the file (typical compression is 50%). UPX can be
found at
    http://www.upx.org/

As of 2011, UPX still does not support compressing 64-bit EXE's; if you have
built a 64-bit vim then an alternative to UPX is 'MPRESS'. MPRESS can be found
at:
    http://www.matcode.com/mpress.htm


ADDITION: NLS support with MinGW

(by Eduardo F. Amatria <eferna1@platea.pntic.mec.es>)

If you want National Language Support, read the file src/po/README_mingw.txt.
You need to uncomment lines in Make_ming.mak to have NLS defined.


4. Cygwin
=========

Use Make_cyg.mak with Cygwin's GCC. See
    http://users.skynet.be/antoine.mechelynck/vim/compile.htm

With Cygnus gcc you should use the Unix Makefile instead (you need to get the
Unix archive then).  Then you get a Cygwin application (feels like Vim is
running on Unix), while with Make_cyg.mak you get a Windows application (like
with the other makefiles).


5. Cross compiling for Win32 from a Linux machine
=================================================

[Update of 1) needs to be verified]

If you like, you can compile the 'mingw' Win32 version from the comfort of
your Linux (or other unix) box.  To do this, you need to follow a few steps:
    1) Install the mingw32 cross-compiler. See
	http://www.mingw.org/wiki/LinuxCrossMinGW
	http://www.libsdl.org/extras/win32/cross/README.txt
    2) Get and unpack both the Unix sources and the extra archive
    3) in 'Make_cyg_ming.mak', set 'CROSS' to 'yes' instead of 'no'.
       Make further changes to 'Make_cyg_ming.mak' and 'Make_ming.mak' as you
       wish.  If your cross-compiler prefix differs from the predefined value,
       set 'CROSS_COMPILE' corresponding.
    4) make -f Make_ming.mak gvim.exe

Now you have created the Windows binary from your Linux box!  Have fun...


6. Building with Python support
===============================

For building with MSVC the "Windows Installer" from www.python.org works fine.

When building, you need to set the following variables at least:

    PYTHON:         Where Python is installed. E.g. C:\Python27
    DYNAMIC_PYTHON: Whether dynamic linking is used. Usually, set to yes.
    PYTHON_VER:     Python version. E.g. 27 for Python 2.7.X.

E.g. When using MSVC (as one line):

    nmake -f Make_mvc.mak
        PYTHON=C:\Python27 DYNAMIC_PYTHON=yes PYTHON_VER=27

When using MinGW and link with the official Python (as one line):

    mingw32-make -f Make_ming.mak
        PYTHON=C:/Python27 DYNAMIC_PYTHON=yes PYTHON_VER=27

When using msys2 and link with Python2 bundled with msys2 (as one line):

    mingw32-make -f Make_ming.mak PYTHON=c:/msys64/mingw64
        PYTHON_HOME=c:/msys64/mingw64
        PYTHONINC=-Ic:/msys64/mingw64/include/python2.7
        DYNAMIC_PYTHON=yes
        PYTHON_VER=27
        DYNAMIC_PYTHON_DLL=libpython2.7.dll
        STATIC_STDCPLUS=yes

(This is for 64-bit builds.  For 32-bit builds, replace mingw64 with mingw32.)
(STATIC_STDCPLUS is optional.  Set to yes if you don't want to require
libstdc++-6.dll.)


(rest written by Ron Aaron: <ronaharon@yahoo.com>)

Building with the mingw32 compiler, and the ActiveState ActivePython:
    http://www.ActiveState.com/Products/ActivePython/

After installing the ActivePython, you will have to create a 'mingw32'
'libpython20.a' to link with:
    cd $PYTHON/libs
    pexports python20.dll > python20.def
    dlltool -d python20.def -l libpython20.a

Once that is done, edit the 'Make_ming.mak' so the PYTHON variable points to
the root of the Python installation (C:\Python20, for example).  If you are
cross-compiling on Linux with the mingw32 setup, you need to also convert all
the 'Include' files to *unix* line-endings.  This bash command will do it
easily:
    for fil in *.h ; do vim -e -c 'set ff=unix|w|q' $fil

Now just do:
    make -f Make_ming.mak gvim.exe

You will end up with a Python-enabled, Win32 version. Enjoy!


7. Building with Python3 support
================================

For building with MSVC the "Windows Installer" from www.python.org works fine.
Python 3.6 is recommended.

When building, you need to set the following variables at least:

    PYTHON3:         Where Python3 is installed. E.g. C:\Python36
    DYNAMIC_PYTHON3: Whether dynamic linking is used. Usually, set to yes.
    PYTHON3_VER:     Python3 version. E.g. 36 for Python 3.6.X.

E.g. When using MSVC (as one line):

    nmake -f Make_mvc.mak
        PYTHON3=C:\Python36 DYNAMIC_PYTHON3=yes PYTHON3_VER=36

When using MinGW and link with the official Python3 (as one line):

    mingw32-make -f Make_ming.mak
        PYTHON3=C:/Python36 DYNAMIC_PYTHON3=yes PYTHON3_VER=36

When using msys2 and link with Python3 bundled with msys2 (as one line):

    mingw32-make -f Make_ming.mak PYTHON3=c:/msys64/mingw64
        PYTHON3_HOME=c:/msys64/mingw64
        PYTHON3INC=-Ic:/msys64/mingw64/include/python3.6m
        DYNAMIC_PYTHON3=yes
        PYTHON3_VER=36
        DYNAMIC_PYTHON3_DLL=libpython3.6m.dll
        STATIC_STDCPLUS=yes

(This is for 64-bit builds.  For 32-bit builds, replace mingw64 with mingw32.)
(STATIC_STDCPLUS is optional.  Set to yes if you don't want to require
libstdc++-6.dll.)


8. Building with Racket or MzScheme support
===========================================

1) Building with Racket support (newest)

MzScheme and PLT Scheme names have been rebranded as Racket.  Vim with Racket
support can be built with either MSVC or MinGW (or Cygwin).
Get it from https://download.racket-lang.org/

Copy lib/libracket{version}.dll to your Windows system directory. The system
directory depends on your Windows bitness and Vim bitness:
  32-bit Vim on 32-bit Windows: C:\Windows\System32
  32-bit Vim on 64-bit Windows: C:\Windows\SysWOW64
  64-bit Vim on 64-bit Windows: C:\Windows\System32

For building you need to set the following variables:

    MZSCHEME:          Where Racket is installed.
                       E.g. C:\Program Files (x86)\Racket
    DYNAMIC_MZSCHEME:  Whether dynamic linking is used. Usually, set to yes.
    MZSCHEME_VER:      Racket DLL version which is used for the file name.
                       See below for a list of MZSCHEME_VER.
                       The DLL can be found under the lib directory. E.g.
                       C:\Program Files (x86)\Racket\lib\libracket3m_XXXXXX.dll
    MZSCHEME_COLLECTS: (Optional) Path of the collects directory used at
                       runtime. Default: $(MZSCHEME)\collects
                       User can override this with the PLTCOLLECTS environment
                       variable.

List of MZSCHEME_VER (incomplete):

    Racket ver. | MZSCHEME_VER
    ==========================
    6.3         | 3m_9z0ds0
    6.6         | 3m_a0solc
    6.8         | 3m_a1zjsw
    6.10        | 3m_a36fs8


E.g. When using MSVC (as one line):

    nmake -f Make_mvc.mak
        MZSCHEME="C:\Program Files (x86)\Racket&