Debian Codegraph @

README.win

raw
1 ##########################################################################
2 # This program is Copyright (C) 1986-2002 by Jonathan Payne. JOVE is #
3 # provided by Jonathan and Jovehacks without charge and without #
4 # warranty. You may copy, modify, and/or distribute JOVE, provided that #
5 # this notice is included in all the source files and documentation. #
6 ##########################################################################
7
8 [Updated in Feb 2023]
9
10 Jove for WIN32
11 ==============
12
13 While Windows (or DOS) are not primary platforms for the JOVE developers,
14 some effort is been made to test JOVE on both.
15
16 A pre-compiled (via MINGW) and ready-to-run copy of JOVE for WIN32 is
17 distributed in archives with the names
18 jove-N.N.N.N-x86_64-w64-mingw32.zip (64bit binaries, 4.17.0.5 on),
19 jove-N.N.N.N-i686-w64-mingw32.zip (32bit binaries). Older distributions
20 (4.16, early 4.17) used joveNNNw.zip (for example, jove416w.zip for
21 version 4.16).
22
23 Jove for WIN32 has usually been lightly tested on the Win7 platform, but
24 is expected to work on older versions like Windows/95, 98, NT, 2000, XP,
25 etc, and might work on newer versions like Win8 and Win10. Test and bug
26 reports are welcome, though the Jove developers are primarily from Unix-land.
27
28 Jove for WIN32 does not function under the WIN32s environment (which is a
29 special subsystem of Windows 3.1). The primary reason is that WIN32s
30 doesn't support the WIN32 Console API, which Jove for WIN32 depends on in
31 order to display text on the screen and accept and interpret keystrokes.
32 For such environments, use the MSDOS version.
33
34 On Windows 11 (and perhaps later), Windows Terminal binds Ctrl-V to Paste.
35 The workaround is to use Settings -> Actions, look for the Paste binding to
36 Ctrl-v in the list and select it, click in the little trashcan that appears
37 to delete it, confirm and then Save. Others have reported this a few times
38 to Windows Terminal, e.g. github.com/microsoft/terminal/issues/11267 so
39 maybe it will get fixed one day.
40
41 Jove can be built for WIN32 (that is, Windows versions after Windows/95)
42 natively with Microsoft Visual C (MSVC), or cross-compiled with
43 {i686,x86-64}-w64-mingw32 on Linux. The MSDOS source distribution zip may
44 be preferable for MSVC builds because it contains pre-built documentation
45 files which must be created on a UNIX system, and excludes some things
46 only of use on UNIX (for example, X Window System support). The filename
47 of the MSDOS source distribution is a name that includes the version
48 number joveNNNs.zip (for example, jove417s.zip for version 4.17), created
49 by running 'make zip' on a Unix/Linux/*BSD system,
50 make zip
51
52 The original port of Jove to WIN32 was performed by Jim Patterson
53 ([email protected]) with the help and advice of D. Hugh Redelmeier
54 as well as early testing and feedback by Gary Puckering
55 ([email protected]).
56
57 Building Jove for WIN32
58 =======================
59
60 To build for WIN32 natively using Microsoft Visual C++ (2.0 or later),
61 unpack a source distribution, setup the Visual C environment (typically,
62 by running vcvars32.bat or starting a Developer Command window from
63 Visual Studio), and use
64
65 nmake /f Makefile.msc
66
67 To cross-compile on a Unix/Linux machine with MinGW installed
68 (e.g. on a modern Debian/Ubuntu/Mint, try "apt install mingw-w64"),
69 and then use
70
71 JMAKE_UNAME=i686-w64-mingw32 ./jmake.sh
72
73 (DESTDIR=/none is a hack to avoid some Makefile
74 complaints, it does not get used otherwise)
75
76 Advantages of WIN32 version (over DOS)
77 ======================================
78
79 Since Windows/NT and Windows/95 support native DOS applications like Jove,
80 using the 16-bit version of JOVE is a perfectly acceptable alternative to
81 using the WIN32 version. However, the WIN32 version does provide several
82 advantages, as follows:
83
84 1. Long filenames. Windows/NT and Windows/95 allow filenames that go
85 beyond DOS's 8.3 naming limitations. Jove for WIN32 uses long filenames by
86 default, whereas Jove for DOS can only see the 8.3 versions of filenames.
87 Jove for WIN32 is also able to directly access files in UNC format, i.e.
88 with an explicit network name. Jove for DOS can only access network files
89 via an associated drive letter.
90
91 2. Window sizing. WIN32 consoles can be dynamically resized. When running
92 a 16-bit application like JOVE, resizing is disabled. However, Jove for
93 WIN32 responds to resizing events and reconfigures its display, just like it
94 does under UNIX when it receives a SIGWINCH signal.
95
96 3. 32-bit limits. Jove for WIN32 is a 32-bit application, and so is less
97 prone to size constraints than its 16-bit DOS cousin (though through clever
98 coding even 16-bit DOS Jove is able to handle a lot files of a considerable size).
99 It is hoped that Jove works on 64bit Windows as well.
100
101 4. 32-bit Performance. Jove for WIN32 should perform, and behave, better
102 than Jove for DOS on a suitable platform for several reasons.
103 - Flat address space (no segment register loading).
104 - Poll-free operation. Jove for DOS uses a polling loop as it waits for
105 input if it needs to display the time on the mode line or wait for a
106 delayed refresh. Jove for WIN32 can use WIN32 Wait... functions to do
107 this, which permit it to cooperate with other tasks more effectively.
108
109 5. Its own Icon. Since Jove for WIN32 is a Windows executable, it can have
110 its own icon. No more hunting around in MORICONS.DLL for something
111 suitable. (If you don't like my planet icon, feel free to craft another;
112 I'm not an artist)!
113
114 6. Non-Intel platforms, in theory. Jove for WIN32 might port easily to other WIN32
115 platforms e.g. Alpha and PowerPC (though it hasn't actually been built on any of
116 these). The performance advantage of having native applications might be
117 considerable, since these platforms must use software emulation to run 16-bit
118 DOS applications. (If anyone has such a platform, and wants to use JOVE on it,
119 please open a github issue, would love to hear about the port)
120
121 One functional difference is that under Windows/95 there is
122 apparently no way to dynamically resize the console window as there is under
123 Windows/NT. There is no code specifically to support Windows/95, though
124 some design decisions were based on the need to support it.
125
126 ENVIRONMENT VARIABLES USED BY JOVE:
127 ===================================
128
129 COMSPEC
130 This variable is used to specify the default program to run as the SHELL.
131 It can be overridden by the JOVE variable "shell" or by the SHELL environment
132 variable.
133
134 TMPDIR (or TEMP)
135 JOVE uses the value of TMPDIR, or if that is not set, TEMP to
136 determine the directory where it should put its temporary file. The
137 default is c:\tmp (set by TMPDIR in the makefile when JOVE was
138 compiled), and this is probably not what you want. In general editing
139 is faster, if TEMP points to a ramdisk, like "set temp=d:". You have
140 to know however that the temporary file can grow quite big when
141 editing many big files at once. So please make sure that you have
142 enough space available on your ramdisk. If JOVE runs out of space on
143 the device which holds the temporary file, you have to leave the
144 editor immediately. You can save your work without any trouble, but
145 you have to start over. Please note also that the Large Model version
146 of JOVE has a big cache for the temporary file in memory, which makes
147 it quite fast even if you don't have a ramdisk. It is an MSDOS
148 convention to use TEMP; use TMPDIR if you intend that the directory
149 is solely for JOVE.
150
151 JOVESHARE
152 This variable specifies the path to the directory that contains
153 (1) cmds.txt (the file of command and variable descriptions used by
154 the describe-command and describe-variable commands) (2) the
155 system-wide jove.rc (the first file that is sourced (executed) by JOVE
156 when it starts up) and (3) The teach-jove tutorial, which can be
157 loaded by either starting JOVE with the -T option (case-sensitive options)
158 or by invoking the teach-jove command within JOVE.
159 A relative path will be interpreted as relative to the location of
160 the JOVE executable binary. The default is "doc" (set by JSHAREDIR in the
161 Makefile when JOVE was compiled), which is fine for either running
162 JJOVE.EXE from the source directory, or JOVE.EXE from the binary
163 distributions.
164
165 JOVELIB
166 This variable specifies the path to the directory that contains
167 RECOVER.EXE, needed for the JOVE -r option, to recover any data
168 after a machine or JOVE crash (hopefully rare). Default is empty,
169 which means the same directory as the JOVE executable (same
170 relative interpretation as JOVESHARE)
171
172 HOME
173 The directory which is to be considered the user's home (as in UNIX).
174 The default is the current directory on the current disk when JOVE was
175 started. JOVE looks in this directory for the user's jove.rc startup
176 file (this will be sourced after the system-wide jove.rc, unless HOME
177 and JOVESHARE are the same). In filenames, an initial ~/ denotes the
178 home directory.
179
180 HOMEDRIVE, HOMEPATH
181 These variables are used together, or not at all. If HOME is not set but
182 HOMEDRIVE and HOMEPATH are, then the home directory is taken to be the
183 concatenation of their values. HOMEDRIVE and HOMEPATH are part of the
184 default Windows NT user environment. They are not typically set on a
185 Windows 95 system (but Jove will use them as described if they are).
186
187 SHELL
188 This defines an alternate shell for JOVE to use when running commands with
189 shell-command. It overrides COMSPEC if provided.
190
191 Managing the console for Jove
192 =============================
193
194 In many (but not all) respects, WIN32 Consoles are more flexible than DOS
195 shell windows. Here are a few tricks for setting up a Jove console the way
196 you like it.
197
198 - Jove will set up its screen to match the current Window. This is often
199 the same size as the current "console buffer" but the window may be
200 smaller in size in which case scroll bars will appear. When the screen
201 buffer changes size, Jove will resize its screen buffer. However, Jove
202 can't always tell if the window size changes. Use a clear-and-redraw
203 (typically bound to ESC ^L) to force Jove to resize its screen.
204
205 - You can use a MODE command to interactively cause Jove to resize its
206 window if you want to do this, say, from a jove.rc file. For example,
207 this sets up a 40 line 100 column window:
208
209 shell-command-no-buffer mode con lines=40 cols=100
210
211 - A better way to set up the screen size under NT is to use the window
212 properties. If you choose to save these settings, they will then apply
213 whenever you run that application.
214
215 - You can set up a "file association" for Jove under NT, and set up the
216 Jove as the program to handle a file. It's not immediately obvious how
217 to change the default screen size. The problem is that with an
218 association, the file you launch is what the settings are tied to; each
219 different file gets its own file settings. To get around this, use this
220 as the command line instead:
221
222 start jove %1
223
224 This works because the window settings are associated with the window
225 title, not the application. When started this way the window title is
226 always "Jove", so settings can be used for all files launched with that
227 association.
228
229 This has an unfortunate size effect of obscuring the Jove window,
230 however. If someone finds a better setup, please broadcast it!
231
232 Development Notes:
233 ==================
234
235 Since Jove was originally developed on Unix, and is still primarily
236 developed/tested in the Linux/Unix/*BSD world, it is still an awkward
237 fit for Windows, unfortunately.
238
239 Jove for WIN32 and Jove for DOS share some code, but also have considerable
240 OS-specific code. The following manifests are used to flag code for the
241 MS-DOS and/or WIN32 versions of Jove (they are explained more fully in
242 sysdep.txt)
243
244 IBMPCDOS - flags features specific to IBM PC hardware running DOS.
245 MSDOS - describes code that is specific to the 16-bit DOS version of Jove.
246 WIN32 - describes code specific to the 32-bit Windows version of Jove.
247 MSFILESYSTEM - enables aspects of Jove to support Microsoft file systems.
248 MSDOS_PROCS - enables use of the spawn series of APIs that replace fork/exec.
249 DIRECTORY_ADD_SLASH indicates that file browsing will flag directories.
250 TEXTFILE_ADD_CR instructs Jove to strip/add CRs from lines of text files.
251 FILENAME_CASEINSENSITIVE indicates that case is not significant for filenames.
252
253 Most of the support code for Jove for WIN32 resides in the file win32.c.
254 The MSDOS files MSDOS.C and PCSCR.C are not used for Jove for WIN32.
255
256 TO DO
257 =====
258
259 There are some opportunities for additional work to make Jove for WIN32 more
260 useable and functional.
261
262 1. Add IPROC support. WIN32 supports pipes, which mean that it's
263 conceptually possible to support IPROCs using methods similar to that of the
264 UNIX PIPEPROC support. In fact, WIN32 IPROC should be somewhat cleaner than
265 PIPEPROCs because the API avoids the need for a third process. However, the
266 reality of WIN32 pipes seems to be somewhat different, and my own attempts
267 to get them to work have so far failed (though the single direction pipes
268 used for a simple SUBSHELL do seem to function okay).
269
270 2. Add MOUSE support. The current input model for WIN32 could easily be
271 extended to support mouse events. It's just necessary to enable the mouse
272 in the SetConsoleMode call, and then process the mouse events as they
273 arrive. The main obstacle is in coming up with a good command model. There
274 are two different mouse command models supported by Jove right now, one for
275 X and one for SunView; no doubt there are reasons that neither one is
276 totally appropriate in the Windows world.
277
278 Known Bugs:
279 ==========
280
281 - Under Windows 95, the CAPS LOCK key also shifts non-alpha keys (e.g.
282 numerics and []). This seems to be a bug in the Windows 95 Console API
283 implementation: the Event.KeyEvent.uChar.AsciiChar field for the keyboard
284 event is set incorrectly.
285
286 - The much touted icon doesn't appear under Windows 95. Once Windows 95 sees
287 that it's not a "real Windows application", it assumes that a standard
288 console icon is good enough.
289
290 - Occasionally, when Jove is started under Windows 95, it does not display
291 anything until a key is pressed. We haven't tracked down what
292 circumstances cause this; it seems to happen more often with certain
293 machine configurations.