=======================
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.

* 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**

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, either llvm-gcc_ or clang_. LLVM 2.9 or later
  is required. For your convenience, here are the direct download links for
  the LLVM 2.9 release:

  |  http://llvm.org/releases/2.9/llvm-2.9-mingw32-i386.tar.bz2
  |  http://llvm.org/releases/2.9/clang-2.9-mingw32-i386.tar.bz2
  |  http://llvm.org/releases/2.9/llvm-gcc4.2-2.9-x86-mingw32.tar.bz2

  Again, you'll have to modify the ``PATH`` environment variable so that it
  points to the directory containing the LLVM and compiler binaries
  (``c:\llvm\bin``, etc.). Also note that if you want to use clang rather than
  llvm-gcc for compiling inline C/C++ code in Pure, you'll have to set the
  ``PURE_CC`` and ``PURE_CXX`` environment variables to ``clang`` and
  ``clang++``, respectively; please check the "Inline Code" section in
  :doc:`pure` for details.

.. _mingw: http://www.mingw.org/
.. _LLVM download page: http://llvm.org/releases
.. _llvm-gcc: http://llvm.org/docs/CommandGuide/html/llvmgcc.html
.. _clang: http://clang.llvm.org/

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.
