
		Copyright 2013-2015 Guardtime, Inc.

	This file is part of the Guardtime client SDK.

	Licensed under the Apache License, Version 2.0 (the "License").
	You may not use this file except in compliance with the License.
	You may obtain a copy of the License at
		http://www.apache.org/licenses/LICENSE-2.0
	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES, CONDITIONS, OR OTHER LICENSES OF ANY KIND, either
	express or implied. See the License for the specific language governing
	permissions and limitations under the License.
	"Guardtime" and "KSI" are trademarks or registered trademarks of
	Guardtime, Inc., and no license to trademarks is granted; Guardtime
	reserves and retains all trademark rights.


Building with Microsoft Visual Studio
=====================================

	This document describes how to build KSI C API as static and dynamic library
	using Microsoft Visual Studio tools and different libraries.


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

	To be able to build GT KSI API one must have the following software pieces:

		1) Microsoft Visual Studio 10 or Windows SDK 7.1 for building tools.
		2) Network provider (must have one)
			2.1) Lib Curl 0.9.8g (recommended).
			2.2) Windows native WinINet
			2.4) Windows native WinHTTP
		3) Cryptography provider (must have one)
			3.1) OpenSSL 0.9.8g (recommended)
			3.2) Windows native CryptoAPI

	Lib Curl must be build from binaries when Visual Studio 14 and lib Curl are
	used for building API:
		1) Download cURL 7.37 binaries from git.
		2) Build cURL using Visual Studio Command prompt and the following command
			in cURL winbuild directory:
			nmake /f MakeFile.vc mode=static VC=12 MACHINE=x86
		3) Find out what kind of RTL was used from bulding logs.
		4) Rename libcurl_a.lib to correct name depending on which RTL
			was used (e.g. rename to libcurlMD.lib if MD was used).
		5) Install cURL:
			5.1) move build to desired location and rename the directory
			5.2) Copy curl.exe from bin folder to system32
			5.3) Add curl path to system variables

	When KSI API uses OpenSSl or Curl the location of libraries must be specified.
	See make file options CURL_DIR, OPENSSL_DIR. The structure of the directories
	must be as described below. The name of static library or import library files
	must contain description of C runtime library (RTL). After build, rename
	libcurl(RTL).dll as libcurl.dll and libeay32(RTL).dll as libeay32.dll. Windows
	native libraries are already installed with Windows.


	For CURL:

	dll
	   |libcurlMT.lib
	   |libcurlMTd.lib
	   |libcurlMD.lib
	   |libcurlMD.dll
	   |libcurlMDd.lib
	   |libcurlMDd.dll
	include
	|curl
	lib
	   |libcurlMT.lib
	   |libcurlMTd.lib
	   |libcurlMD.lib
	   |libcurlMDd.lib


	For OpenSSL:

	dll
	   |libeay32MT.lib
	   |libeay32MTd.lib
	   |libeay32MD.lib
	   |libeay32MD.dll
	   |libeay32MDd.lib
	   |libeay32MDd.dll
	include
	|openssl
	lib
	   |libeay32MT.lib
	   |libeay32MTd.lib
	   |libeay32MD.lib
	   |libeay32MDd.lib


Build process
=====================================

	Below is the abstract structure of the project that describes the location
	of the source code, make files and output. Root directory contains top-level
	build scripts that are used to build KSI C API. After successful build out
	directory is created.


	|WinBuild32.bat
	|WinBuild62.bat
	|makefile
	|
	|src
	|  |ksi
	|	 | *.c
	|	 | *.h
	|	 | makefile
	|  |example
	|	 | *.c
	|	 | *.h
	|	 | makefile
	|
	|test
	|  | *.c
	|  | *.h
	|  | makefile
	|
	|out
	|  |lib
	|	 | *.lib
	|  |dll
	|	 | *.dll
	|  |bin
	|	 | *.exe
	|  |include
	|	 |ksi
	|		| *.h


Configuring build scripts
=====================================

	For building process, above described top level-make file or
	WinBuild32.bat/WinBuild64.bat must be called.

	Make file can be executed via CMD shell or Visual Studio command prompt shell.
	When using CMD shell environment must be configured using setenv command.
	For example for 64-bit build setenv /x64.


	Make file has following options:

		1) DLL				- select if dll or lib is to be built. Default is lib.
		2) RTL				- select C run-time library (MT, MTd, MD, MDd).
							Default is MT. Note: MT and MTd can only be used with DLL=lib.
		3) NET_PROVIDER		- select the network provider. Possible values are:
							NONE, FILE, CURL, WININET and WINHTTP. When using CURL CURL_DIR
							must be specified. When not specified explicitly,
							CURL is used as default. NONE is used to disable all network
							providers. To be able to run tests at least FILE provider
							must be used.
							In order to compile without any network provider use NONE.
		4) CRYPTO_PROVIDER	- select the cryptography provider for both hashing
							and PKI. Possible values are: OPENSSL and CRYPTOAPI.
							When using OPENSSL OPENSSL_DIR must be specified.
							Default is OPENSSL.
		5) HASH_PROVIDER	- select the cryptography provider for hashing.
							Possible values are: OPENSSL and CRYPTOAPI. When
							using OPENSSL OPENSSL_DIR must be specified. Default
							is OPENSSL.
		6) TRUST_PROVIDER	- select the cryptography provider for PKI. Possible
							values are: OPENSSL and CRYPTOAPI. When using OPENSSL
							OPENSSL_DIR must be specified. Default is OPENSSL.
		3) CURL_DIR 		- Directory containing Curl library and include files.
		4) OPENSSL_DIR 		- Directory containing OpenSLL library and include
							files.
		5) OPENSSL_CA_FILE	- OPENSSL certificate file.
		6) OPENSSL_CA_DIR	- OPENSSL certificate directory.
		5) LDEXTRA 			- extra flags for linker.
		6) CCEXTRA 			- extra flags for compiler.


	Make file has following tasks:

		1) default		- build library using DLL and RTL option.
		2) all 			- build all libraries, examples and tests. RTL and DLL
						options are used when linking tests and examples.
		3) libraries	- build all libraries using every possible RTL options.
		4) libMT		- build static library linked against MT C RTL.
		5) libMTd		- build static library linked against MTd C RTL.
		6) libMD		- build static library linked against MD C RTL.
		7) libMDd		- build static library linked against MDd C RTL.
		8) dllMD		- build dynamic library linked against MD C RTL.
		9) dllMDd		- build dynamic library linked against MDd C RTL.
		10) example		- build examples. RTL and DLL options are used.
		11) tests		- build tests. RTL and DLL options are used.
		12) test 		- build and run tests. RTL and DLL options are used.
		13) clean		- clean the build.



Examples
=====================================

	Build static library linked against Windows native libraries and RTL as MD
	using cURL as network provider and CryptoAPI as hash provider:
	nmake RTL=MD DLL=lib CURL_DIR=<path to cURL dir> NET_PROVIDER=CURL
	CRYPTO_PROVIDER=CRYPTOAPI

	Build static library linked against Windows native libraries and RTL as MT:
	nmake RTL=MT DLL=lib NET_PROVIDER=WININET CRYPTO_PROVIDER=CRYPTOAPI

	Build static library linked against Windows native CryptoAPI as hash provider
	and OpenSSL as trust provider (PKI):
	nmake RTL=MT DLL=lib NET_PROVIDER=WININET TRUST_PROVIDER=OPENSSL
	HASH_PROVIDER=CRYPTOAPI OPENSSL_DIR=C:\openssl

	Build dynamic library linked against Windows native libraries with RTL as MTD:
	nmake NET_PROVIDER=WININET CRYPTO_PROVIDER=CRYPTOAPI dllMDd
