=======================
Running Pure on Windows
=======================

This document provides some information pertaining to the Windows version of
Pure, available from the Pure website in the form of an MSI package. Please
note that the Windows version has a custom directory layout which is more in
line with standard Windows applications, and will by default be installed in
the standard ``Program Files`` directory on your system.

Normally, most things should be set up properly after you installed the MSI
package, but here are a few things that you should know when running the
Windows version:

* The Pure interpreter requires the ``PURELIB`` environment variable to point
  to the directory containing the prelude and other library modules, available
  in the ``lib`` subdirectory of the Pure program directory. Also, the
  ``PATH`` environment variable should contain both the Pure program directory
  and the ``lib`` subdirectory, so that you can run the interpreter and
  compiled programs from the command line. Both environment variables are set
  automatically during installation. To make this work, you have to install
  the package with administrator rights.

* The package includes a shortcut to run the Pure interpreter in a command
  window, as well as a shortcut for the online documentation that you're
  looking at. It also includes the :program:`PurePad` application, a GUI
  frontend to the Pure interpreter which lets you edit and run Pure scripts on
  Windows, see :doc:`purepad`. After installation you can find these items in
  the ``Pure`` submenu of the Program menu.

* Pure scripts can be edited in any text editor. Syntax highlighting and
  programming modes are provided for Emacs_, Vim_ and various other popular
  text editors. After installation you can find these in the ``etc``
  subdirectory of the program directory. Please check the files in this
  directory for installation instructions.

* The interpreter has a few interactive commands (``ls``, ``pwd``, etc.) which
  require Unix-like utilities. To make these work, we recommend installing the
  CoreUtils package from the GnuWin32_ project, and setting your ``PATH``
  accordingly.

.. _Emacs: http://www.gnu.org/software/emacs/
.. _Vim: http://www.vim.org/
.. _GnuWin32: http://gnuwin32.sf.net/

**Optional Bits and Pieces**

.. _mingw: http://www.mingw.org/
.. _LLVM download page: http://llvm.org/releases
.. _clang: http://clang.llvm.org/
.. _dragonegg: http://dragonegg.llvm.org/
.. _7-Zip: http://www.7-zip.org/

The Windows package contains all that's needed to run Pure programs with the
interpreter. However, in order to be able to run the Pure batch compiler and
to make full use of the Pure/C interface on Windows, you may need to install
some third-party programming tools:

* mingw_ is a full version of the GNU C/C++ compiler for Windows systems.
  You'll need this in order to create native executables and libraries with
  the Pure batch compiler. It is also needed for running the
  :program:`pure-gen` utility included in this package, which can be used to
  create Pure interfaces to C libraries from the corresponding C headers.
  And, last but not least you can also use mingw to compile the LLVM tools and
  the Pure interpreter yourself, if you prefer that.

  Using mingw 4.4 or later is recommended. There's an installer available at
  the mingw website, see http://www.mingw.org/wiki/Getting_Started for
  details. You'll want to install both the C/C++ compilers and the MSYS
  environment. You'll also have to modify the ``PATH`` environment variable so
  that it points to the directory containing the mingw binaries, usually
  ``c:\mingw\bin``.

* The batch compiler also requires the LLVM toolchain for mingw32/x86,
  available from the `LLVM download page`_. In addition, in order to use the
  C/C++ code inlining feature of the Pure interpreter, you'll need an
  LLVM-enabled C/C++ compiler such as clang_. (That's pretty much the only
  option on Windows right now; at the time of this writing, the dragonegg_
  plugin for gcc hasn't been ported to Windows yet.)

  This Pure release has been built and tested with LLVM 3.1, so that is the
  version that you should get. For your convenience, here is the direct
  download link of the binary package which contains both the LLVM toolchain
  and the clang compiler:

  http://llvm.org/releases/3.1/clang+llvm-3.1-i386-mingw32-EXPERIMENTAL.tar.bz2

  You should unpack this tarball (using, e.g., 7-Zip_) to a directory on your
  harddisk (say, ``c:\llvm``), and modify the ``PATH`` environment variable so
  that it points to the ``bin`` subdirectory of this folder.

* Finally, the Pure program directory needs to be added to the gcc
  ``LIBRARY_PATH`` environment variable, so that some Windows-specific addon
  libraries are found when linking compiled programs. This should be done
  automatically during installation, but it's a good idea to check the value
  of ``LIBRARY_PATH`` after installation and edit it as needed.
