WinZsh - Z shell for Windows

README

Note: most of the WinZsh-specific information will likely move into a man page in the future.

Zsh (non WinZsh-specific) Documentation

The original zsh documentation is included with the WinZsh distribution in the following formates: man pages, info, and html. It can be found in the usr/man, usr/info, and usr/doc/zsh-$ZSH_VERSION/html-docs folders respectively.

If you do not have a man page reader, you can use the included man zsh script, originally written by Wu Yongwei for MSYS and modified to work in WinZsh. Note: this script requires some common Unix tools such as sed, less and groff, you can find these at the GnuWin32 project. Please report any bugs you find with it to WinZsh, not to MSYS or MinGW. You could also try compiling the MinGW man reader, which is supposedly in development but the latest snapshot is dated 2006-03-22.

Supported Operating Systems

WinZsh runs on 32 bit Windows NT based systems. It is known to run well on Windows 2000 & XP, but is currently somewhat unstable on Vista and Windows 7. 64 bit versions of Windows are not currently supported.

Compiling the Source

Prerequisites:
- Currently the source is only known to compile with Microsoft Visual C++ 6.0 (sorry). Note: MSVC9 (the 2008 Express Edition) currently compiles, but throws an exception when running 'ls'.
- Sed and awk are needed to generate some headers, ensure that these are in your path so that make can find them. Sed and {g|m|n}awk from the GnuWin32 project work fine.
Download and extract the source.
Open a cmd.exe prompt.
Run 'vcvars32.bat' from your Visual C++ installation. This will setup your environment variables so that Windows can find the compiler tools.
'cd' into the 'Src' directory.
Copy the configuration header file and makefile to the appropriate directories by typing 'copy winnt\config.h.winnt ..\config.h' and 'copy winnt\Makefile.msvc Makefile'.
Compile with 'nmake MSVC={6|9}'.
To include debugging support, compile with 'nmake MSVC={6|9} DBG=1'instead.

Paths

All paths must be '/' (forward slash) separated, not '\' (back slash) separated, the same as in Unix. '\' is the shell escape character, also the same as in Unix.
Paths should include a drive letter as well, for example 'C:/bin'. Of course, this also applies to path variables such as HOME or PATH. If you specify a path without a drive letter, e.g., '/', '/bin' etc., WinZsh will interpret this as the root of the current drive, e.g. 'C:/', 'C:/bin' if you happen to be in the C: drive, or 'D:/', 'D:/bin' if you happen to be in the D: drive. This is not recommended, as the results could be unpredictable. To be sure you get the results you expect, always include the drive letter in the path, or use a variable (such as '$ZSHROOT/bin' if ZSHROOT is set).
The path separator in WinZsh is ';' (semicolon), since the Unix path separator ':' (colon) is already used in the drive letter. This is the same behavior as in Windows, but obviously differs from Unix. Note: in zsh, special path environment variables such as PATH and MANPATH are arrays if referred to in lowercase. For example, you can specify your PATH as 'path=(C:/bin C:/Program\ Files/gnuwin32/bin $path)' and avoid the whole path separator issue altogether.

Known Bugs

zed does not work too well.
binding a key to 'xxx-menu-complete' will cause the shell to crash if you type the bound key on an empty line.

Basic things to know

Drive changes done with 'cd <drive:>' (Or setopt autocd to get DOS-like behavior as a side-effect.)
.COM files will need to be executed by specifying the extension (edit.com, instead of just edit).
International keyboards should work if you 'setopt printeightbit'. Note that this will re-init the keymaps, so you may have to redo some bindkey mappings. (NOREBIND now has no effect whatsoever.)
Also, if you change the console font (on NT) from the default raster type to anything else, international characters may not be displayed properly.
zsh sets the code-page to 1252 (ansi) when it starts. For international versions (far east for example,) this screws up the console. To avoid the problem, set ZSH_DONTSETCP in the system environment, before zsh starts.

WinZsh-specific Variables (or custom handling of standard variables)

ZSHROOT

If the variable ZSHROOT is set, it will be prepended to the program name if the program is not found during the normal search. So, if you type '/bin/zsh' (or have that in a shell script), the shell will try:

/bin/zsh
/bin/zsh.exe
$ZSHROOT/bin/zsh
$ZSHROOT/bin/zsh.exe

(Note that a script with a line like #!C:/bin/zsh.exe will not be affected by 3 or 4).

HOME

WinZsh sets the HOME directory if it's not already set and ZDOTDIR is not set either. In this case HOME is set to $USERPROFILE.

If ZDOTDIR is set and HOME is not set, WinZsh sets home to 'youdonthavehomeset'. This is to avoid crashing in places where the shell expects a home directory. Picking a real default would defeat the purpose of not setting home.

WinZsh-specific Builtin Commands

start

Like cmd.exe's start

title

Like cmd.exe's title

cls

Clear entire screen buffer instead of visible window

ps

This will likely be removed in the future, use Windows builtins such as tasklist instead.
list processes. with -w, lists window titles as well.

shutdown

This will likely be removed in the future, use Windows builtins such as shutdown instead.

shutdown -[r|l|f] now

(Even though no time argument is supported, "now" must be specified, EXCEPT with -l .This is to prevent you from accidentally shutting the machine down.) -r reboots, -l logs you off and -f forces apps to terminate.

The default action is to shut the machine down.

WinZsh-specific Options

WINNTIGNORECASE: Ignore case in completions
WINNTLAMEPATHFIX: Convert the PATH environment variable back to '\'-delimited instead of '/'-delimited when each child process is forked.
WINNTNOASSOCIATIONS: Do not try applications associated with extensions if exec() fails.
WINNTCONVERTBACKSLASH: Convert backslashes to '/' when comparing named directories etc. May be useful if you derive HOME from '\'-delimited environment variables.
WINNTWAITFORGUIAPPS: When set, makes the shell wait for win32 GUI apps to terminate instead of spawning them asynchronously.
WINNTNOQUOTEPROTECT: Turn off trying to escape quotes (") in a command. While the escaping works with cygnus tools, it does not seem to work with the MKS tools. Whatever side-effects you suffer when you set this option are beyond my means to fix.

WinZsh specific handling of Arrow keys, etc. and bindkey

Since windows does not generate codes for the keypad (arrow keys, ins, delete etc.,) you will need to use a special options to bindkey to bind these keys, namely,

bindkey -N \\0xx some-funky-function

where the numeric code is between 0 and 33.

The following shows the default bindings for each key:: /* F1 */ z_undefinedkey,; /* F2 */ z_undefinedkey,; /* F3 */ z_undefinedkey,; /* F4 */ z_undefinedkey,; /* F5 */ z_undefinedkey,; /* F6 */ z_undefinedkey,; /* F7 */ z_undefinedkey,; /* F8 */ z_undefinedkey,; /* F9 */ z_undefinedkey,; /* F10 */ z_undefinedkey,; /* F11 */ z_undefinedkey,; /* F12 */ z_undefinedkey,; /* F13 */ z_undefinedkey,; /* F14 */ z_undefinedkey,; /* F15 */ z_undefinedkey,; /* F16 */ z_undefinedkey,; /* F17 */ z_undefinedkey,; /* F18 */ z_undefinedkey,; /* F19 */ z_undefinedkey,; /* F20 */ z_undefinedkey,; /* F21 */ z_undefinedkey,; /* F22 */ z_undefinedkey,; /* F23 */ z_undefinedkey,; /* F24 */ z_undefinedkey,; /* Pgup */ z_undefinedkey,; /* Pgdn */ z_undefinedkey,; /* end */ z_endofddne,; /* home */ z_beginningofddne,; /* left-arrow*/ z_backwardchar,; /* up-arrow */ z_upddneorhistory,; /* right-arrow */ z_forwardchar,; /* down-arrow */ z_downddneorhistory,; /* Ins */ z_overwritemode,; /* Del */ z_deletechar,

For example, to bind F-1 to run-help, you would need:

bindkey -N \\000 run-help

To bind left-arrow:

bindkey -N \\034 beginning-of-line (note that \034 is 28 decimal)