Commit | Line | Data |
---|---|---|
a4a9692d DL |
1 | Building and Installing Emacs |
2 | on Windows NT and Windows 95 | |
3 | ||
4 | You need a compiler package to build and install Emacs on NT or Win95. | |
5 | If you don't have one, precompiled versions are available in | |
6 | ftp://ftp.cs.washington.edu/pub/ntemacs/<version>. | |
7 | ||
8 | Configuring: | |
9 | ||
10 | (1) In previous versions, you needed to edit makefile.def | |
11 | to reflect the compiler package that you are using. You should no | |
12 | longer have to do this if you have defined the INCLUDE and LIB | |
13 | environment variables, as is customary for use with Windows compilers. | |
14 | (Unless you are using MSVCNT 1.1, in which case you will need | |
15 | to set MSVCNT11 to be a non-zero value at the top of makefile.def.) | |
16 | ||
17 | (2) Choose the directory into which Emacs will be installed, and | |
18 | edit makefile.def to define INSTALL_DIR to be this directory. | |
19 | (Alternatively, if you have INSTALL_DIR set as an environment | |
20 | variable, the build process will ignore the value in makefile.def | |
21 | and use the value of the environment variable instead.) Note | |
22 | that if it is not installed in the directory in which it is built, | |
23 | the ~16 MB of lisp files will be copied into the installation directory. | |
24 | ||
25 | Also, makefile.def is sometimes unpacked read-only; use | |
26 | ||
27 | > attrib -r makefile.def | |
28 | ||
29 | to make it writable. | |
30 | ||
31 | (3) You may need to edit nt/paths.h to specify some other device | |
32 | instead of `C:'. | |
33 | ||
34 | Building: | |
35 | ||
36 | (4) The target to compile the sources is "all", and is recursive starting | |
37 | one directory up. The makefiles for the NT port are in files named | |
38 | "makefile.nt". To get things started, type in this directory: | |
39 | ||
40 | > nmake -f makefile.nt all | |
41 | ||
42 | or use the ebuild.bat file. | |
43 | ||
44 | When the files are compiled, you will see some warning messages declaring | |
45 | that some functions don't return a value, or that some data conversions | |
46 | will be lossy, etc. You can safely ignore these messages. The warnings | |
47 | may be fixed in the main FSF source at some point, but until then we | |
48 | will just live with them. | |
49 | ||
50 | NOTE: You should not have to edit src\paths.h to get Emacs to run | |
51 | correctly. All of the variables in src\paths.h are configured | |
52 | during start up using the nt\emacs.bat file (which gets installed | |
53 | as bin\emacs.bat -- see below). | |
54 | ||
55 | Installing: | |
56 | ||
57 | (5) Currently, Emacs requires a number of environment variables to be set | |
58 | for it to run correctly. A batch file, emacs.bat, is provided that | |
59 | sets these variables appropriately and then runs the executable | |
60 | (emacs.bat is generated using the definition of INSTALL_DIR in | |
61 | nt\makefile.def and the contents of nt\emacs.bat.in). | |
62 | ||
63 | (6) The install process will install the files necessary to run Emacs in | |
64 | INSTALL_DIR (which may be the directory in which it was built), | |
65 | and create a program manager/folder icon in a folder called GNU Emacs. | |
66 | From this directory, type: | |
67 | ||
68 | > nmake -f makefile.nt install | |
69 | ||
70 | or use the install.bat file. | |
71 | ||
72 | (7) Create the Emacs startup file. This file can be named either .emacs, | |
73 | as on Unix, or _emacs. Note that Emacs requires the environment | |
74 | variable HOME to be set in order for it to locate the startup file. | |
75 | HOME could be set, for example, in the System panel of the Control | |
76 | Panel on NT, or in autoexec.bat on Win95. | |
77 | ||
78 | (8) Start up Emacs. | |
79 | ||
80 | The installation process should have run the addpm.exe program, which | |
81 | does two things. First, it will create a set of registry keys that | |
82 | tell Emacs where to find its support files (lisp, info, etc.). | |
83 | Second, it will create a folder containing an icon linked to | |
84 | runemacs.exe (a wrapper program for invoking Emacs). You can | |
85 | also invoke addpm.exe by hand, giving the absolute directory name | |
86 | of the installation directory as the first argument: | |
87 | ||
88 | addpm.exe %INSTALL_DIR% | |
89 | ||
90 | Now, to run Emacs, simply click on the icon in the newly created | |
91 | folder or invoke runemacs.exe from a command prompt. | |
92 | ||
93 | Another alternative for running Emacs is to use the emacs.bat batch | |
94 | file in the bin directory (this was the traditional method of invoking | |
95 | Emacs). Edit the emacs.bat file to change the emacs_dir environment | |
96 | variable to point to the Emacs installation directory and invoke the | |
97 | emacs.bat file to run Emacs. | |
98 | ||
99 | Note that, on Win95, you are likely to get "Out of environment space" | |
100 | messages when invoking the emacs.bat batch file. The problem is that | |
101 | the console process in which the script is executed runs out of memory | |
102 | in which to set the Emacs environment variables. To get around this | |
103 | problem, create a shortcut icon to the emacs.bat script. Then right | |
104 | click on the icon and select Properties. In the dialog box that pops | |
105 | up, select the Memory tab and then change the Environment memory | |
106 | allocation from "Auto" to "1024". Close the dialog box and then | |
107 | double click on the icon to start Emacs. | |
108 | ||
109 | Debugging: | |
110 | ||
111 | (9) You should be able to debug Emacs using the MSVC debugger as you would | |
112 | any other program. To ensure that Emacs uses the lisp files associated | |
113 | with the source distribution that you are debugging, it is useful | |
114 | to set the Emacs environment variables to point Emacs to the | |
115 | source distribution. You can use the debug.bat batch file in this | |
116 | directory to setup the environment and invoke msdev on the | |
117 | emacs.exe executable. | |
118 | ||
119 | Emacs functions implemented in C use a naming convention that | |
120 | reflects their names in lisp. The names of the C routines are | |
121 | the lisp names prefixed with 'F', and with dashes converted to | |
122 | underscores. For example, the function call-process is implemented | |
123 | in C by Fcall_process. Similarly, lisp variables are prefixed | |
124 | with 'V', again with dashes converted to underscores. These | |
125 | conventions enable you to easily set breakpoints or examine familiar | |
126 | lisp variables by name. | |
127 | ||
128 | Since Emacs data is often in the form of a lisp object, and the | |
129 | Lisp_Object type is difficult to examine manually in the debugger, | |
130 | Emacs provides a helper routine called debug_print that prints out | |
131 | a readable representation of a Lisp_Object. The output from | |
132 | debug_print is sent to stderr, and to the debugger via the | |
133 | OutputDebugString routine. The output sent to stderr should be | |
134 | displayed in the console window that was opened when the emacs.exe | |
135 | executable was started. The output sent to the debugger should be | |
136 | displayed in its "Debug" output window. | |
137 | ||
138 | When you are in the process of debugging Emacs and you would like | |
139 | to examine the contents of a Lisp_Object variable, popup the | |
140 | QuickWatch window (QuickWatch has an eyeglass symbol on its button | |
141 | in the toolbar). In the text field at the top of the window, enter | |
142 | debug_print(<variable>) and hit return. For example, start | |
143 | and run Emacs in the debugger until it is waiting for user input. | |
144 | Then click on the Break button in the debugger to halt execution. | |
145 | Emacs should halt in ZwUserGetMessage waiting for an input event. | |
146 | Use the Call Stack window to select the procedure w32_msp_pump | |
147 | up the call stack (see below for why you have to do this). Open | |
148 | the QuickWatch window and enter debug_print(Vexec_path). Evaluating | |
149 | this expression will then print out the contents of the lisp | |
150 | variable exec-path. | |
151 | ||
152 | If QuickWatch reports that the symbol is unknown, then check the | |
153 | call stack in the Call Stack window. If the selected frame in the | |
154 | call stack is not an Emacs procedure, then the debugger won't | |
155 | recognize Emacs symbols. Instead, select a frame that is inside | |
156 | an Emacs procedure and try using debug_print again. | |
157 | ||
158 | If QuickWatch invokes debug_print but nothing happens, then check | |
159 | the thread that is selected in the debugger. If the selected | |
160 | thread is not the last thread to run (the "current" thread), then | |
161 | it cannot be used to execute debug_print. Use the Debug menu | |
162 | to select the current thread and try using debug_print again. | |
163 | Note that the debugger halts execution (e.g., due to a breakpoint) | |
164 | in the context of the current thread, so this should only be a problem | |
165 | if you've explicitly switched threads. |