win32/README.txt

   1 \r
   2                              Windows port\r
   3                              ------------\r
   4 \r
   5 This directory contains the files required to build this software on the\r
   6 native Windows platform.\r
   7 \r
   8 As a rule of thumb, the root of this directory contains files needed\r
   9 to build the library using the command-line tools, while various\r
  10 subdirectories contain project files for various IDEs.\r
  11 \r
  12 \r
  13   1. Building the library
  14   =================================\r============
  15 \r
  16 Building from command line is the easiest, preferred and the only
  17 currently supported method. \r
  18 \r
  19 In order to build from the command-line you need to make sure that\r
  20 your compiler works from the command line. This is not always the\r
  21 case, often the required environment variables are missing. If you are\r
  22 not sure, test if this works first. If it doesn't, you will first have\r
  23 to configure your compiler suite to run from the command-line - please\r
  24 refer to your compiler's documentation regarding that.\r
  25 \r
  26 The first thing you want to do is configure the source. You can have\r
  27 the configuration script do this automatically for you. The\r
  28 configuration script is written in JScript, a Microsoft's\r
  29 implementation of the ECMA scripting language. Almost every Windows\r
  30 machine can execute this through the Windows Scripting Host. If your\r
  31 system lacks the ability to execute JScript for some reason, you must\r
  32 perform the configuration manually.\r
  33 \r
  34 The second step is compiling the source and, optionally, installing it\r
  35 to the location of your choosing.\r
  36 \r
  37 \r
  38   1.1 Configuring the source automatically\r
  39   ----------------------------------------\r
  40 \r
  41 The configuration script accepts numerous options. Some of these\r
  42 affect features which will be available in the compiled software,\r
  43 others affect the way the software is built and installed. To see a\r
  44 full list of options supported by the configuration script, run\r
  45 \r
  46   cscript configure.js help\r
  47 \r
  48 from the win32 subdirectory. The configuration script will present you\r
  49 the options it accepts and give a biref explanation of these. In every\r
  50 case you will have two sets of options. The first set is specific to\r
  51 the software you are building and the second one is specific to the\r
  52 Windows port.\r
  53 \r
  54 Once you have decided which options suit you, run the script with that\r
  55 options. Here is an example:\r
  56 \r
  57   cscript configure.js prefix=c:\opt include=c:\opt\include \r
  58     lib=c:\opt\lib debug=yes\r
  59 \r
  60 The previous example will configure the process to install the library\r
  61 in c:\opt, use c:\opt\include and c:\opt\lib as additional search\r
  62 paths for the compiler and the linker and build executables with debug\r
  63 symbols.\r
  64 \r
  65 Note: Please do not use path names which contain spaces. This will\r
  66 fail. Allowing this would require me to put almost everything in the\r
  67 Makefile in quotas and that looks quite ugly with my\r
  68 syntax-highlighting engine. If you absolutely must use spaces in paths\r
  69 send me an email and tell me why. If there are enough of you out there\r
  70 who need this, or if a single one has a very good reason, I will\r
  71 modify the Makefile to allow spaces in paths.\r
  72 \r
  73 \r
  74   1.2 (Not) Configuring the source manually\r
  75   -----------------------------------------\r
  76 \r
  77 The manual configuration is pretty straightforward, but I would\r
  78 suggest rather to get a JScript engine and let the configure script do\r
  79 it for you. This process involves editing the apropriate Makefile to\r
  80 suit your needs, as well as manually generating certain *.h files from\r
  81 their *.h.in sources.\r
  82 \r
  83 If you really have no idea what I am talking about and ask yourself\r
  84 what in Gods name do I mean with '*.h files and their *.h.in sources',\r
  85 then you really should do an automatic configuration. Which files must\r
  86 be generated and what needs to be done with their sources in order to\r
  87 generate them is something people who have built this software before\r
  88 allready know. You will not find any explanations for that\r
  89 here. Please configure the source manually only if you allready know\r
  90 what you must do. Otherwise, you have the choice of either getting a\r
  91 precompiled binary distribution, or performing the automatic\r
  92 configuration.\r
  93 \r\r
  94   1.3 Compiling\r
  95   -------------\r
  96 \r
  97 After the configuration stage has been completed, you want to build\r
  98 the software. To do that, type\r
  99 \r
 100   nmake\r
 101 \r
 102 in the win32 subdirectory.When the building completes, you will find\r
 103 the executable files in win32\binaries directory.\r
 104  \r
 105 You can install the software into the directory you specified to the\r
 106 configure script during the configure stage by typing\r
 107 \r
 108   nmake install\r
 109 \r
 110 That would be it, enjoy.\r
 111 \r
 112   2. Building your appliation
 113   =================================\r============
 114
 115 On Windows there is no easy way to automatically configure compilation
 116 options or paths. You have to do everything manualy. Start up your
 117 favorite IDE or text editor and read on.
 118
 119   2.1 Global Defines.
 120   -------------\r-------------\r-------------\r------
 121
 122 If you want to use automatic crypto library configuration (xmlsec/crypto.h file)
 123 you need to add one of the following global defines:
 124
 125     #define XMLSEC_CRYPTO_OPENSSL
 126     #define XMLSEC_CRYPTO_GNUTLS
 127     #define XMLSEC_CRYPTO_NSS
 128
 129 Also you'll need to define all configuration parameters used during XML Security
 130 Library compilation (XMLSEC_OPENSSL_096, XMLSEC_NO_AES, XMLSEC_NO_X509,...).
 131
 132   2.1 Additional Global Defines for static linking.
 133   -------------\r-------------\r-------------\r------\r
 134
 135 Also if you (*and only if*) are linking libraries staticaly, you'll need to add following
 136 global defines:
 137
 138   2.2 Setting include and library paths.
 139   -------------\r-------------\r-------------\r------\r
 140
 141 As usual, you need to have correct include and library paths to xmlsec, libxml,
 142 libxslt, iconv, openssl or any other library used in your application.
 143
 144   2.3 Selecting correct Windows runtime libraries.
 145   -------------\r-------------\r-------------\r------\r
 146
 147 Windows basically has 6 different C runtimes. The first one is called libc.lib
 148 and can only be linked to statically and used only in single-threaded mode.
 149 The second one is also can only be linked staticaly and used in multi-threaded
 150 mode. The third one is called msvcrt.dll and can only be linked to dynamically.
 151 These three then live in their debug and release incarnations, which results in
 152 six C runtimes. The rule is simple: exactly the same runtime must be used
 153 throughout the application. Client code *MUST* use the same runtime as XMLSec,
 154 LibXML, LibXSLT, OpenSSL or any other library used.
 155
 156 If you downloaded XMLSec, LibXML, LibXSLT and OpenSSL binaries from Igor's
 157 page then all libraries are all linked to msvcrt.dll ("Multithreaded DLL"
 158 (NOT DEBUG!); /MD compiler switch). The click-next click-finish wizardry
 159 from Visual Studio chooses the single-threaded libc.lib as the default
 160 when you create a new project. And this causes great problems because
 161 you program crashes on first IO operation, first malloc/free from different
 162 runtimes or something even more trivial.
 163
 164 Do not forget that if you need a different runtime for some reason, then
 165 you MUST recompile not only XMLSec, but LibXML, LibXSLT and OpenSSL as well.
 166
 167 \r
 168 March 2002, Igor Zlatkovic <igor@stud.fh-frankfurt.de>\r