diff --git a/README.md b/README.md index 7d04f2ca682..78cf28ebc17 100644 --- a/README.md +++ b/README.md @@ -1,89 +1,140 @@ -# winevdm on 64-bit Windows +# winevdm for Win64 -![screenshot](screenshot.PNG) +— Run apps for 16-bit Windows (Windows 1.x, 2.x, 3.0, 3.1, etc.) on 64-bit Windows — -[Download stable version](https://github.com/otya128/winevdm/releases) +This is an altered version of winevdm (a 16-bit Windows emulator for the [wine project](www.winehq.org)), ported to 64-bit Windows. + +![CALC.EXE for Windows 1.0 running on Windows 10](screenshot.PNG) + +It can also run DOS executables (DOS emulator-like), but DOS support is limited. You can set the DOS version with the VDMDOSVER environment variable. + +--- + +# How to use it? + +## 1. Download [Download latest version (unstable)](https://ci.appveyor.com/project/otya128/winevdm/) -16-bit Windows (Windows 1.x, 2.x, 3.0, 3.1, etc.) on 64-bit Windows +1. Go to one of the two environments (`THIS_BUILD_IS_RECOMMENDED_...` or `THIS_BUILD_IS_NOT_RECOMMENDED_...`). +2. Select the `Artifacts` tab. +3. Download the zip archive. -An altered version of winevdm (a 16-bit Windows emulator), ported to 64-bit Windows. +[Download stable version (outdated!)](https://github.com/otya128/winevdm/releases) -# How to compile(Visual Studio) +## 2. Try it (recommended before installation!) -+ Install Visual Studio 2017 -+ Edit PropertySheet.props -+ Compile +1. Unpack the downloaded zip archive to a safe place that doesn't require admin privileges. +2. Drag and drop the Win16 executable file to **`otvdm.exe`** or execute **`otvdmw.exe`** and choose the Win16 executable. + + If you get an error that **`VCRUNTIME140.dll`** is missing, install [Microsoft Visual C++ Redistributable for Visual Studio 2017 (32-bit)](https://aka.ms/vs/15/release/vc_redist.x86.exe). -# How to compile(cmake) +## 3. How to install -```sh -git clone https://github.com/otya128/winevdm.git -cd winevdm -mkdir build -cd build -cmake .. -make -``` +### Some background first: -# How to run +> What is 'installing winevdm'? +> +> When 64-bit Windows detects a 16-bit installer, it has a mechanism to start a 32-bit replacement installer. +> +> Installing **`install(w).inf`** **modifies the Windows registry** to hijack this mechanism so that when you try to start any 16-bit executable, instead winevdm is started runnning the 16-bit executable. This does not work for Windows 1.0 or DOS executables. -+ If you get an error that VCRUNTIME140.dll is missing, install [Microsoft Visual C++ Redistributable for Visual Studio 2017 (32-bit)](https://aka.ms/vs/15/release/vc_redist.x86.exe) -+ Drag and drop Win16 executable file to otvdm.exe or execute otvdmw.exe. +> **General note:** It does not harm to know admin essentials like e.g. how to work with a command prompt, a bit of *batch*, how the Windows registry works etc. before messing with system internals like smuggling in a 16-bit Windows layer. -# How to install +### Installing winevdm: -+ Download or compile -+ Edit install.inf -+ Right-click on install.inf and select "Install" -+ You can execute Win16 binaries directly! +1. Download (see above) or compile (build instructions [here](#How-to-compile)). +2. Put (unpack, move) winevdm to a top-level directory, e.g. `C:\winevdm\%version-dir%`. +3. Install (requires admin privileges): + + Launch `install` to see the otvdm console window every time a 16-bit executable is run (installs `install.inf`). + + Launch `install (no console)` for the otvdm console window to stay hidden (installs `installw.inf`). +4. You can run Win16 executables directly! -**If you install v0.4.x, you should replace [Strings] section of install.inf with these and install install.inf again.** -```ini -[Strings] -NtVdm64=SOFTWARE\Microsoft\Windows NT\CurrentVersion\NtVdm64 -CommandLine="""%m"" %c" -MappedExeName=otvdm.exe -``` +> **Note:** If you install v0.4.x, you should replace [Strings] section of `install.inf` and `installw.inf` with these and install again: +> ```ini +> [Strings] +> NtVdm64=SOFTWARE\Microsoft\Windows NT\CurrentVersion\NtVdm64 +> CommandLine="""%m"" %c" +> MappedExeName=otvdm.exe +> ``` + +### Customizing winevdm + +// TODO: Document otvdm.ini (probably in separate file) -# How does it work? +## Reporting issues: -This program contains the following items +When you report an issue, we will likely ask you to create a *"trace"* to analyze what went wrong: + +1. Open a command prompt, navigate to a directory to which you want the trace to be written. +2. Set the `WINEDEBUG` environment variable: + ```cmd + set WINEDEBUG=+all,-snoop,-ldt,-fixup,-module,-global,-local,-disasm,-syslevel,-thunk + ``` +3. Run the 16-bit executable with standard error stream redirected to the file `trace.txt`: + ```cmd + %path-to-old-executable-file% 2> trace.txt + ``` + Or in case you have not installed yet: + ```cmd + %path-to-otvdm.exe% %path-to-old-executable-file% 2> trace.txt + ``` +4. Upload the trace file to the GitHub issue. + + +--- + +# How does winevdm work? + +This program contains the following items: + CPU Emulator - + 64-bit Windows cannot modify LDT(NtSetInformationProcess(,ProcessLdtInformation,,) always returns error) -+ wine based Win16->Win32 conversion codes: + + 64-bit Windows cannot modify LDT (NtSetInformationProcess(,ProcessLdtInformation,,) always returns error) ++ wine based Win16→Win32 conversion codes: ```c BOOL16 WINAPI DestroyWindow16( HWND16 hwnd ) { return DestroyWindow( WIN_Handle32(hwnd) ); } ``` - Relay routines from 16-bit to 32-bit are autogenerated by convspec + These relay routines from 16-bit to 32-bit are autogenerated by convspec: ```spec 53 pascal -ret16 DestroyWindow(word) DestroyWindow16 ``` ++ 16-bit ↔ native HANDLE conversion + DOS emulation for Win16 -+ 16-bit <=> native HANDLE conversion + Fix compatibility problems, fix compatibility problems -## install.inf +## `Windows` directory redirection -When 64-bit Windows detects a 16-bit installer, it has a mechanism to start an alternative installer which is not 16-bit. -This program uses it. +Some Win16 programs try to save their settings in `%WINDIR%\.ini`. -## WINDOWS directory redirection +In recent Windows versions, saving to `%WINDIR%` is forbidden, so winevdm redirects this path to a custom directory. -Some Win16 programs try to save their settings in %WINDIR%\.ini +## Registry redirection -In recent Windows, it is not allowed to save to %WINDIR%, so it redirects. +// TODO: Document possible implications (e.g. OLE) # winevdm ```bat winevdm.exe [--app-name app.exe] command line winevdm.exe CALC.EXE ``` -It can also run DOS executables (DOS emulator-like). -You can set the DOS version with the VDMDOSVER environment variable. +# How to compile + +## Visual Studio + ++ Install Visual Studio 2017 ++ Edit PropertySheet.props ++ Compile + +## CMake + +```sh +git clone https://github.com/otya128/winevdm.git +cd winevdm +mkdir build +cd build +cmake .. +make +```