1=begin
2
3= How to build ruby using Visual C++
4
5== Requirement
6
7(1) Windows XP or later.
8
9(2) Visual C++ 6.0 or later. (strongly recommended VC++ 10 or later)
10
11    Note: if you want to build x64 or ia64 version, use native compiler for
12          x64/ia64.
13
14(3) Please set environment variable (({INCLUDE})), (({LIB})), (({PATH}))
15    to run required commands properly from the command line.
16
17    Note: building ruby requires following commands.
18     * nmake
19     * cl
20     * lib
21     * dumpbin
22
23(4) If you want to build from SVN source, following commands are required.
24     * bison
25     * sed
26     * ruby 1.8 or later
27
28(5) Enable Command Extension of your command line.  It's the default behavior
29    of cmd.exe.  If you want to enable it explicitly, run cmd.exe with /E:ON
30    option.
31
32== How to compile and install
33
34(1) Execute win32\configure.bat on your build directory.
35    You can specify the target platform as an argument.
36    For example, run `((%configure --target=i686-mswin32%))'
37    You can also specify the install directory.
38    For example, run `((%configure --prefix=<install_directory>%))'
39    Default of the install directory is /usr .
40    The default ((|<PLATFORM>|)) is `(({i386-mswin32}))'.
41
42(2) Change ((|RUBY_INSTALL_NAME|)) and ((|RUBY_SO_NAME|)) in (({Makefile}))
43    if you want to change the name of the executable files.
44    And add ((|RUBYW_INSTALL_NAME|)) to change the name of the
45    executable without console window if also you want.
46
47(3) Run `((%nmake%))'
48
49(4) Run `((%nmake test%))'
50
51(5) Run `((%nmake install%))'
52
53== Icons
54
55Any icon files(*.ico) in the build directory, directories specified with
56((|icondirs|)) make variable and (({win32})) directory under the ruby
57source directory will be included in DLL or executable files, according
58to their base names.
59    $(RUBY_INSTALL_NAME).ico or ruby.ico   --> $(RUBY_INSTALL_NAME).exe
60    $(RUBYW_INSTALL_NAME).ico or rubyw.ico --> $(RUBYW_INSTALL_NAME).exe
61    the others                             --> $(RUBY_SO_NAME).dll
62
63Although no icons are distributed with the ruby source or in the official
64site, you can use anything you like. For example, followings are written
65in Japanese, but you can download at least.
66
67* ((<URL:http://homepage1.nifty.com/a_nakata/ruby/>)) or
68  ((<icon itself|URL:http://homepage1.nifty.com/a_nakata/ruby/RubyIcon.ico>))
69
70== Build examples
71
72* Build on the ruby source directory.
73
74  ex.)
75    ruby source directory:  C:\ruby
76    build directory:        C:\ruby
77    install directory:      C:\usr\local
78
79    C:
80    cd \ruby
81    win32\configure --prefix=/usr/local
82    nmake
83    nmake test
84    nmake install
85
86* Build on the relative directory from the ruby source directory.
87
88  ex.)
89    ruby source directory:  C:\ruby
90    build directory:        C:\ruby\mswin32
91    install directory:      C:\usr\local
92
93    C:
94    cd \ruby
95    mkdir mswin32
96    cd mswin32
97    ..\win32\configure --prefix=/usr/local
98    nmake
99    nmake test
100    nmake install
101
102* Build on the different drive.
103
104  ex.)
105    ruby source directory:  C:\src\ruby
106    build directory:        D:\build\ruby
107    install directory:      C:\usr\local
108
109    D:
110    cd D:\build\ruby
111    C:\src\ruby\win32\configure --prefix=/usr/local
112    nmake
113    nmake test
114    nmake install DESTDIR=C:
115
116* Build x64 version (requires native x64 VC++ compiler)
117
118  ex.)
119    ruby source directory:  C:\ruby
120    build directory:        C:\ruby
121    install directory:      C:\usr\local
122
123    C:
124    cd \ruby
125    win32\configure --prefix=/usr/local --target=x64-mswin64
126    nmake
127    nmake test
128    nmake install
129
130== Bugs
131
132You can ((*NOT*)) use a path name that contains any white space characters as
133the ruby source directory, this restriction comes from the behavior of
134(({!INCLUDE})) directives of (({NMAKE})).
135((- you may call it a bug. -))
136
137You can build ruby in any directory including the source directory,
138except (({win32})) directory in the source directory.
139This is restriction originating in the path search method of (({NMAKE})).
140
141=end
142