wenv Documentation Release 0.2.1 Sebastian M. Ernst Jul 10, 2020 Contents 1 Introduction 3 1.1 Synopsis.................................................3 1.2 Motivation................................................3 1.3 Implementation..............................................4 1.4 Use cases.................................................4 2 Installation 5 2.1 Getting Wine ...............................................5 2.2 Getting wenv ...............................................5 2.3 Possible problem: OSError: [WinError 6] Invalid handle ..............6 2.4 Installing wenv in development mode..................................6 3 Examples 7 4 Configuration 9 4.1 Configuration files............................................9 4.2 Configuration environment variables..................................9 4.3 Configurable parameters......................................... 10 5 Usage 13 5.1 Command: wenv init ........................................ 13 5.2 Command: wenv clean ........................................ 13 5.3 Command: wenv help ........................................ 13 5.4 Command: wenv python ....................................... 13 5.5 Command: wenv pip ......................................... 14 5.6 Command: wenv init_coverage ................................. 14 6 API: class Env 15 6.1 Constructor: Env(**kwargs) ..................................... 15 6.2 Method: ensure() ........................................... 15 6.3 Method: wine_47766_workaround() ............................... 15 6.4 Method: setup_wineprefix(overwrite = False) ..................... 16 6.5 Method: setup_pythonprefix(overwrite = False) .................... 16 6.6 Method: setup_pip() ........................................ 16 6.7 Method: install_package(name, update = False) .................... 16 6.8 Method: uninstall_package(name) ............................... 16 6.9 Method: list_packages() ..................................... 16 i 6.10 Method: shebang() .......................................... 16 6.11 Method: cli() ............................................. 16 6.12 Method: uninstall() ........................................ 16 6.13 Method: setup_coverage_activate() ............................. 17 7 Security 19 8 Bugs 21 8.1 How to bisect issues........................................... 21 9 FAQ 23 9.1 Why?................................................... 23 9.2 What are actual use cases for this project?................................ 23 9.3 How does it work?............................................ 23 9.4 Is it secure?................................................ 23 10 Indices and tables 25 Index 27 ii wenv Documentation, Release 0.2.1 Running Python on Wine. wenv is a Python package (currently in development status 4/beta). It allows to run Python on top of Wine on Linux, MacOS or BSD. It handles required plumbing related to making Python and a number of Python modules work on Wine. wenv creates isolated virtual environments which can be transparently used from a Unix command line and which seamlessly integrate into Unix Python virtual environments. Contents 1 wenv Documentation, Release 0.2.1 2 Contents CHAPTER 1 Introduction 1.1 Synopsis wenv is a Python package (currently in development status 4/beta). It allows to run Python on top of Wine on Linux, MacOS or BSD. It handles required plumbing related to making Python and a number of Python modules work on Wine. wenv creates isolated virtual environments which can be transparently used from a Unix command line and which seamlessly integrate into Unix Python virtual environments. 1.2 Motivation wenv was derived from the Python package zugbruecke. zugbruecke allows to call routines in Windows DLLs from Python code running on Unices / Unix-like systems such as Linux, MacOS or BSD. wenv’s code started out as infras- tructure for zugbruecke. Eventually, it became too complex on its own and - at the same time - began to enable new and interesting use cases beyond the scope of zugbruecke. Technically, the basic problem is how to install (and run) just any version or distribution of Python on Wine. The in- stallers of most Python distributions including Anaconda and even CPython itself tend to be broken on most versions of Wine (“garbage” in Wine jargon). For a while, ActiveState’s ActivePython was the only “easy” way of directly installing Python on Wine, but even this path was (and still is) extremely unreliable. The commonly recommended workaround is to install Python directly on Windows and copy the resulting installation directory tree over to Unix/Wine. First, this is not an option for everybody as it requires a Windows installation. Second, it is also notoriously unreliable. While researching options for developing zugbruecke, CPython’s embeddable package for Windows showed up on the radar. It is a simple ZIP-file without any installer. By merely unpacking it, one can run Python without an issue. With some manual tweaking and tuning of both the unpacked folder and Wine, it becomes possible to make pip work and install just about anything on top. wenv essentially takes care of the entire process automatically. 3 wenv Documentation, Release 0.2.1 1.3 Implementation wenv has two roles. First, it downloads, installs and configures both CPython and pip. The process is based on CPython’s embeddable package distribution for Windows. Second, wenv provides a thin launcher for staring Python (or just any Python application) on Wine. The installer and launcher themselves are also written in Python and run on any Unix-version of Python. The launcher sets the stage in Unix Python before using an exec syscall to replace itself with Windows Python. 1.4 Use cases • Running Python apps & scripts written for Windows on Unix. • Running critical portions of Python apps depending on Windows on Unix - while the remaining uncritical por- tions of those apps can directly run on Unix. Inter-process communication can bridge the gap. • Testing the Windows compatibility of Python apps directly on Unix. • Accessing proprietary DLLs through ctypes, cffi, swig, sip, f2py and friends. Also see the zugbruecke project. • Running a Windows version of Python as a Jupyter kernel next to a Unix version, see the wenv-kernel project. 4 Chapter 1. Introduction CHAPTER 2 Installation 2.1 Getting Wine For using wenv, you need to install Wine first. Depending on your platform, there are different ways of doing that. • Installation instructions for various Linux distributions • Installation instructions for Mac OS X • Installation instructions for FreeBSD Currently, Wine >= 4.x is supported (tested). If you are limited to an older version of Wine such as 2.x or 3.x, you have one option: Try to set the pythonversion configuration parameter to 3.5.4. 2.2 Getting wenv The latest stable release version can be installed with pip: pip install wenv If you are interested in testing the latest work from the development branch, you can try it like this: pip install git+https://github.com/pleiszenburg/wenv.git@develop After installing the package with pip, you must initialize the “Wine Python environment” by running wenv init. If you are relying on wenv, please notice that it uses semantic versioning. Breaking changes are indicated by increasing the first version number, the major version. Going for example from 0.0.x to 1.0.0 or going from 0.1.y to 1.0.0 therefore indicates a breaking change. 5 wenv Documentation, Release 0.2.1 2.3 Possible problem: OSError: [WinError 6] Invalid handle On older versions of Linux such as Ubuntu 14.04 alias Trusty Tahr (released 2014), you may observe errors when run- ning wenv python. Most commonly, they will present themselves as OSError: [WinError 6] Invalid handle: 'z:\\... triggered by calling os.listdir on a symbolic link (“symlink”) to a folder. A clean solution is to upgrade to a younger version of Linux. E.g. Ubuntu 16.04 alias Xenial Xerus (released 2016) is known to work. 2.4 Installing wenv in development mode If you are interested in contributing to wenv, you might want to install it in development mode. You can find the latest instructions on how to do this in the CONTRIBUTING file of this project on Github. 6 Chapter 2. Installation CHAPTER 3 Examples Fire up a shell and try the following: (env) user@comp:~> uname Linux (env) user@comp:~> python-m platform Linux (env) user@comp:~> wenv python-m platform Windows wenv pip works just like one would expect. Have a look at the output of wenv help for more commands and in- formation. For use as a shebang, wenv python has an alias: One can write #!/usr/bin/env _wenv_python at the top of scripts. wenv python can also be used as a Jupyter kernel, side-by-side with a Unix-version of Python. Have a look at the wenv-kernel project. 7 wenv Documentation, Release 0.2.1 8 Chapter 3. Examples CHAPTER 4 Configuration wenv can configure itself automatically or can be configured with files and environment variables manually. 4.1 Configuration files wenv uses JSON configuration files named .wenv.json. They are expected in the following locations (in that order): • The current working directory • A directory specified in the WENV environment variable • The user profile folder (~ / /home/{username}) • /etc There is one optional addition to the above rules: The path specified in the WENV environment variable can directly point to a configuration file. I.e. the WENV environment variable can also contain a path similar to /path/to/ some/file.json. Configuration options are being looked for location after location in the above listed places. If, after