.. _install-windows:

==============================
Building Cyrus SASL on Windows
==============================

Note, that Cyrus SASL on Windows is still laregely a "work in progress".
So far only the main library, plugins (SASLDB using SleepyCat, no MySQL)
and several applications (see the list below) can be built. In particular,
saslauthd doesn't compile on Windows.

Prerequisites
=============

Visual Studio.
    We have tested Visual Studio 6 and Visual Studio 7 (.NET).
    By default we are using Visual Studio 7 (both 2002 and 2003 versions were tested). If you want to use Visual Studio 6,
    you need to remove the leading # character from the line containing ``#VCVER=6`` in win32/common.mak.

The latest Platform SDK.
    We are currently using March 2006. (The earliest tested version was November 2001.)

SleepyCat
    SleepyCat's include files and libraries are required to buil SASLDB plugin,
    saslpasswd2.exe and sasldblistusers2.exe. We have tested SleepyCat 4.1.X-4.4.X.

Cygwin (for building from GIT)
    The `Cygwin <http://www.cygwin.com/>`_ Unix-compatibility
    environment to create the ``_init.c`` files needed for dynamic
    loading. Cygwin is *not* required for building from our tar
    distribution.

Step by step
============

These directions assume that you've untarred the library or used GIT
and the sources are in ``C:\SASL``.

Preparing to build (GIT only!)
------------------------------

Start a cygwin shell and create the dynamic loading stubs::

    % cd /cygdrive/c/sasl/plugins
    % sh makeinit.sh

Building using NMake
--------------------

Open a "Windows 2000 build environment" from the SDK's Start Menu and
use ``nmake /f NTMakefile`` to build.

To build a debug verison, use ``nmake /f NTMakefile
CFG=Debug``. For a production version, ``nmake /f NTMakefile
CFG=Release``. If you don't specify CFG parameter, production
version will be built by default.

As Windows build requires SleepyCat, there are additional options
that have to be provided to NMake on the command line.
If SleepyCat sources are located in ``c:\packages\db\4.1.24``
and built library in ``c:\packages\db\4.1.24\build_win32\Release_static``,
you should add something like
``DB_INCLUDE=c:\packages\db\4.1.24\build_win32``
and ``DB_LIBPATH=c:\packages\db\4.1.24\build_win32\Release_static``.

Also note, that the ``DB_LIB`` defines the name of the SleepyCat library
to link against. It defaults to libdb41s.lib.

If you don't pass the parameters described above, NMake will pick the
defaults, which is probably not what you want.

Another option of interest is ``STATIC``.
It specifies which version of the standard C library
to use. The default is "no", meaning that the standard C library
from the MSVCRT.DLL will be used.

Example::

    Targeting Windows 2000 and IE 5.0 RETAIL

    C:\Program Files\Microsoft SDK> cd \sasl

    C:\sasl> nmake /f NTMakefile DB_INCLUDE=c:\packages\db\4.1.24\build_win32
    DB_LIBPATH=c:\packages\db\4.1.24\build_win32\Release_static

    No configuration specified. Defaulting to Release.
    Using MSVCRT.dll as C library by default.
    Defaulting SleepyCat library name to libdb41s.lib.
    Codegeneration defaulting to /MD.


SASL NTMakefile also understands "clean" target that you can use to clean all files generated by the compiler.

::

    C:\sasl> nmake /f NTMakefile clean

    Microsoft (R) Program Maintenance Utility Version 7.00.9466
    Copyright (C) Microsoft Corporation.  All rights reserved.

            cd lib && nmake /f NTMakefile                    clean

    Microsoft (R) Program Maintenance Utility Version 7.00.9466
    Copyright (C) Microsoft Corporation.  All rights reserved.

    No configuration specified. Defaulting to Release.
    Using MSVCRT.dll as C library by default.
    Defaulting SleepyCat library name to libdb41s.lib.
    Defaulting SleepyCat include path to c:\work\isode\db\build_win32.
    Defaulting SleepyCat library path to c:\work\isode\db\build_win32\Release_static.


Building additional plugins
---------------------------

Specify "GSSAPI=<type>" parameter if you want to enable GSSAPI plugin.
Currently only <type>=CyberSafe is supported and this will build the plugin
that links against CyberSafe Kerberos.

GSSAPI depends on ``GSSAPI_INCLUDE`` and ``GSSAPI_LIBPATH`` parameters.
You can either specify them on the command line or edit the defaults in win32\common.mak

Specify "SQL=<type>" parameter if you want to enable SQL plugin.
Currently only <type>=SQLITE is supported and this will build the plugin
that links against SQLITE (www.sqlite.org).

SQL=<SQLITE> depends on ``SQLITE_INCLUDES`` and ``SQLITE_LIBPATH`` parameters.
You can either specify them on the command line or edit the defaults in win32\common.mak

Specify "NTLM=1" parameter if you want to enable NTLM plugin.
I.e. ``nmake /f NTMakefile NTLM=1``

Specify "SRP=1" parameter if you want to enable SRP plugin.
You can also specify "DO_SRP_SETPASS=1" if you want to enable SRP setpass functionality.

Specify "OTP=1" parameter if you want to enable OTP plugin.

NTLM, SRP and OTP plugins depend on OpenSSL. You can either specify
``OPENSSL_INCLUDE`` and ``OPENSSL_LIBPATH`` parameters on the command
line or edit the defaults in win32\common.mak
Note, that unless you are building one of those plugins, OpenSSL is not required!

If you want to build multiple additional plugins at once, you can specify
multiple parameters described above, for example ``nmake /f NTMakefile NTLM=1 SRP=1 OPT=1``

Limitations
-----------

Currently all plugins except KerberosV4 (kerberos4.c) and PASSDSS (passdss.c) can be built on Windows.
However limited testings was done for some plugins as listed below:

* GSSAPI - tested using CyberSafe,
* SASLDB - only SleepyCat version can be built,
* SQL - using SQLITE, not tested


The following executables were built and tested (to some extent):

* sample

    * sample-client
    * sample-server

* utils

    * sasldblistusers2
    * saslpasswd2
    * testsuite
    * pluginviewer
    * Note that saslauthd is *NOT* in this list.
