doc/windows.md

   1 # Windows
   2
   3 Ruby supports a few native build platforms for Windows.
   4
   5 * mswin: Build using Microsoft Visual C++ compiler with vcruntimeXXX.dll
   6 * mingw-msvcrt: Build using compiler for Mingw with msvcrtXX.dll
   7 * mingw-ucrt: Build using compiler for Mingw with Windows Universal CRT
   8
   9 ## Building Ruby using Mingw with UCRT
  10
  11 The easiest build environment is just a standard [RubyInstaller-Devkit]
  12 installation and [git-for-windows]. You might like to use [VSCode] as an
  13 editor.
  14
  15 ### Build examples
  16
  17 Ruby core development can be done either in Windows `cmd` like:
  18
  19 ```
  20 ridk enable ucrt64
  21
  22 pacman -S --needed %MINGW_PACKAGE_PREFIX%-openssl %MINGW_PACKAGE_PREFIX%-libyaml %MINGW_PACKAGE_PREFIX%-libffi
  23
  24 cd c:\
  25 mkdir work
  26 cd work
  27 git clone https://github.com/ruby/ruby
  28
  29 cd c:\work\ruby
  30 sh autogen.sh
  31 sh configure  -C --disable-install-doc
  32 make
  33 ```
  34
  35 or in MSYS2 `bash` like:
  36
  37 ```
  38 ridk enable ucrt64
  39 bash
  40
  41 pacman -S --needed $MINGW_PACKAGE_PREFIX-openssl $MINGW_PACKAGE_PREFIX-libyaml $MINGW_PACKAGE_PREFIX-libffi
  42
  43 cd /c/
  44 mkdir work
  45 cd work
  46 git clone https://github.com/ruby/ruby
  47 cd ruby
  48
  49 ./autogen.sh
  50 ./configure -C --disable-install-doc
  51 make
  52 ```
  53
  54 [RubyInstaller-Devkit]: https://rubyinstaller.org/
  55 [git-for-windows]: https://gitforwindows.org/
  56 [VSCode]: https://code.visualstudio.com/
  57
  58 ## Building Ruby using Visual C++
  59
  60 ### Requirement
  61
  62 1.  Windows 10/Windows Server 2016 or later.
  63
  64 2.  Visual C++ 14.0 (2015) or later.
  65
  66     **Note** if you want to build x64 version, use native compiler for
  67     x64.
  68
  69 3.  Please set environment variable `INCLUDE`, `LIB`, `PATH`
  70     to run required commands properly from the command line.
  71
  72     **Note** building ruby requires following commands.
  73
  74     * nmake
  75     * cl
  76     * ml
  77     * lib
  78     * dumpbin
  79
  80 4.  If you want to build from GIT source, following commands are required.
  81     * git
  82     * patch
  83     * sed
  84     * ruby 3.0 or later
  85
  86     You can use [scoop](https://scoop.sh/) to install them like:
  87
  88     ```
  89     scoop install git patch sed ruby
  90     ```
  91
  92 5.  You need to install required libraries using [vcpkg](https://vcpkg.io/) on
  93     directory of ruby repository like:
  94
  95     ```
  96     vcpkg --triplet x64-windows install
  97     ```
  98
  99 6.  Enable Command Extension of your command line.  It's the default behavior
 100     of `cmd.exe`.  If you want to enable it explicitly, run `cmd.exe` with
 101     `/E:ON` option.
 102
 103 ### How to compile and install
 104
 105 1.  Execute `win32\configure.bat` on your build directory.
 106     You can specify the target platform as an argument.
 107     For example, run `configure --target=i686-mswin32`
 108     You can also specify the install directory.
 109     For example, run `configure --prefix=<install_directory>`
 110     Default of the install directory is `/usr` .
 111     The default _PLATFORM_ is `i386-mswin32_`_MSRTVERSION_ on 32-bit
 112     platforms, or `x64-mswin64_`_MSRTVERSION_ on x64 platforms.
 113     _MSRTVERSION_ is the 2- or 3-digits version of the Microsoft
 114     Runtime Library.
 115
 116 2.  Change _RUBY_INSTALL_NAME_ and _RUBY_SO_NAME_ in `Makefile`
 117     if you want to change the name of the executable files.
 118     And add _RUBYW_INSTALL_NAME_ to change the name of the
 119     executable without console window if also you want.
 120
 121 3.  You need specify vcpkg directory to use `--with-opt-dir`
 122     option like `win32\configure.bat --with-opt-dir=vcpkg_installed\x64-windows`
 123
 124 4.  Run `nmake up` if you are building from GIT source.
 125
 126 5.  Run `nmake`
 127
 128 6.  Run `nmake prepare-vcpkg` if you need to copy
 129     vcpkg installed libraries like `libssl-3-x64.dll` to the build directory.
 130
 131 7.  Run `nmake check`
 132
 133 8.  Run `nmake install`
 134
 135 ### Build examples
 136
 137 * Build on the ruby source directory.
 138
 139     ```
 140     ruby source directory:  C:\ruby
 141     build directory:        C:\ruby
 142     install directory:      C:\usr\local
 143     ```
 144
 145     ```
 146     C:
 147     cd \ruby
 148     win32\configure --prefix=/usr/local
 149     nmake
 150     nmake check
 151     nmake install
 152     ```
 153
 154 * Build on the relative directory from the ruby source directory.
 155
 156     ```
 157     ruby source directory:  C:\ruby
 158     build directory:        C:\ruby\mswin32
 159     install directory:      C:\usr\local
 160     ```
 161
 162     ```
 163     C:
 164     cd \ruby
 165     mkdir mswin32
 166     cd mswin32
 167     ..\win32\configure --prefix=/usr/local
 168     nmake
 169     nmake check
 170     nmake install
 171     ```
 172
 173 * Build on the different drive.
 174
 175     ```
 176     ruby source directory:  C:\src\ruby
 177     build directory:        D:\build\ruby
 178     install directory:      C:\usr\local
 179     ```
 180
 181     ```
 182     D:
 183     cd D:\build\ruby
 184     C:\src\ruby\win32\configure --prefix=/usr/local
 185     nmake
 186     nmake check
 187     nmake install DESTDIR=C:
 188     ```
 189
 190 * Build x64 version (requires native x64 VC++ compiler)
 191
 192     ```
 193     ruby source directory:  C:\ruby
 194     build directory:        C:\ruby
 195     install directory:      C:\usr\local
 196     ```
 197
 198     ```
 199     C:
 200     cd \ruby
 201     win32\configure --prefix=/usr/local --target=x64-mswin64
 202     nmake
 203     nmake check
 204     nmake install
 205     ```
 206
 207 ### Bugs
 208
 209 You can **NOT** use a path name that contains any white space characters
 210 as the ruby source directory, this restriction comes from the behavior
 211 of `!INCLUDE` directives of `NMAKE`.
 212
 213 You can build ruby in any directory including the source directory,
 214 except `win32` directory in the source directory.
 215 This is restriction originating in the path search method of `NMAKE`.
 216
 217 ### Dependency management
 218
 219 Ruby uses [vcpkg](https://vcpkg.io/) to manage dependencies on mswin platform.
 220
 221 You can update and install it under the build directory like:
 222
 223 ```
 224 nmake update-vcpkg # Update baseline version of vcpkg
 225 nmake install-vcpkg # Install vcpkg from build directory
 226 ```
 227
 228
 229 ## Icons
 230
 231 Any icon files(`*.ico`) in the build directory, directories specified with
 232 _icondirs_ make variable and `win32` directory under the ruby
 233 source directory will be included in DLL or executable files, according
 234 to their base names.
 235     $(RUBY_INSTALL_NAME).ico or ruby.ico   --> $(RUBY_INSTALL_NAME).exe
 236     $(RUBYW_INSTALL_NAME).ico or rubyw.ico --> $(RUBYW_INSTALL_NAME).exe
 237     the others                             --> $(RUBY_SO_NAME).dll
 238
 239 Although no icons are distributed with the ruby source, you can use
 240 anything you like. You will be able to find many images by search engines.
 241 For example, followings are made from [Ruby logo kit]:
 242
 243 * Small [favicon] in the official site
 244
 245 * [vit-ruby.ico] or [icon itself]
 246
 247 [Ruby logo kit]: https://cache.ruby-lang.org/pub/misc/logo/ruby-logo-kit.zip
 248 [favicon]: https://www.ruby-lang.org/favicon.ico
 249 [vit-ruby.ico]: http://ruby.morphball.net/vit-ruby-ico_en.html
 250 [icon itself]: http://ruby.morphball.net/icon/vit-ruby.ico