Revert "Missing perldoc markup around < literal"
[openssl.git] / INSTALL.NW
1
2 INSTALLATION ON THE NETWARE PLATFORM
3 ------------------------------------
4
5 Notes about building OpenSSL for NetWare.
6
7
8 BUILD PLATFORM:
9 ---------------
10 The build scripts (batch files, perl scripts, etc) have been developed and
11 tested on W2K.  The scripts should run fine on other Windows platforms
12 (NT, Win9x, WinXP) but they have not been tested.  They may require some
13 modifications.
14
15
16 Supported NetWare Platforms - NetWare 5.x, NetWare 6.x:
17 -------------------------------------------------------
18 OpenSSL can either use the WinSock interfaces introduced in NetWare 5,
19 or the BSD socket interface.  Previous versions of NetWare, 4.x and 3.x,
20 are only supported if OpenSSL is build for CLIB and BSD sockets;
21 WinSock builds only support NetWare 5 and up.
22
23 On NetWare there are two c-runtime libraries.  There is the legacy CLIB 
24 interfaces and the newer LIBC interfaces.  Being ANSI-C libraries, the 
25 functionality in CLIB and LIBC is similar but the LIBC interfaces are built 
26 using Novell Kernal Services (NKS) which is designed to leverage 
27 multi-processor environments.
28
29 The NetWare port of OpenSSL can be configured to build using CLIB or LIBC.
30 The CLIB build was developed and tested using NetWare 5.0 sp6.0a.  The LIBC 
31 build was developed and tested using the NetWare 6.0 FCS.  
32
33 The necessary LIBC functionality ships with NetWare 6.  However, earlier 
34 NetWare 5.x versions will require updates in order to run the OpenSSL LIBC
35 build (NetWare 5.1 SP8 is known to work).
36
37 As of June 2005, the LIBC build can be configured to use BSD sockets instead
38 of WinSock sockets. Call Configure (usually through netware\build.bat) using
39 a target of "netware-libc-bsdsock" instead of "netware-libc".
40
41 As of June 2007, support for CLIB and BSD sockets is also now available
42 using a target of "netware-clib-bsdsock" instead of "netware-clib";
43 also gcc builds are now supported on both Linux and Win32 (post 0.9.8e).
44
45 REQUIRED TOOLS:
46 ---------------
47 Based upon the configuration and build options used, some or all of the
48 following tools may be required:
49
50 * Perl for Win32 - required (http://www.activestate.com/ActivePerl)
51    Used to run the various perl scripts on the build platform.
52
53 * Perl 5.8.0 for NetWare v3.20 (or later) - required 
54    (http://developer.novell.com) Used to run the test script on NetWare 
55    after building.
56
57 * Compiler / Linker - required:
58    Metrowerks CodeWarrior PDK 2.1 (or later) for NetWare (commercial):
59       Provides command line tools used for building.
60       Tools:
61       mwccnlm.exe  - C/C++ Compiler for NetWare
62       mwldnlm.exe  - Linker for NetWare
63       mwasmnlm.exe - x86 assembler for NetWare (if using assembly option)
64
65    gcc / nlmconv Cross-Compiler, available from Novell Forge (free):
66          http://forge.novell.com/modules/xfmod/project/?aunixnw
67
68 * Assemblers - optional:
69    If you intend to build using the assembly options you will need an
70    assembler.  Work has been completed to support two assemblers, Metrowerks
71    and NASM.  However, during development, a bug was found in the Metrowerks
72    assembler which generates incorrect code.  Until this problem is fixed,
73    the Metrowerks assembler cannot be used.
74
75    mwasmnlm.exe - Metrowerks x86 assembler - part of CodeWarrior tools.
76          (version 2.2 Built Aug 23, 1999 - not useable due to code
77           generation bug)
78
79    nasmw.exe - Netwide Assembler NASM
80          version 0.98 was used in development and testing
81
82 * Make Tool - required:
83    In order to build you will need a make tool.  Two make tools are
84    supported, GNU make (gmake.exe) or Microsoft nmake.exe.
85
86    make.exe - GNU make for Windows (version 3.75 used for development)
87          http://gnuwin32.sourceforge.net/packages/make.htm
88
89    nmake.exe - Microsoft make (Version 6.00.8168.0 used for development)
90          http://support.microsoft.com/kb/132084/EN-US/
91
92 * Novell Developer Kit (NDK) - required: (http://developer.novell.com)
93
94    CLIB - BUILDS:
95
96       WinSock2 Developer Components for NetWare:
97          For initial development, the October 27, 2000 version was used.
98          However, future versions should also work.
99
100          NOTE:  The WinSock2 components include headers & import files for
101          NetWare, but you will also need the winsock2.h and supporting
102          headers (pshpack4.h, poppack.h, qos.h) delivered in the
103          Microsoft SDK.  Note: The winsock2.h support headers may change
104          with various versions of winsock2.h.  Check the dependencies
105          section on the NDK WinSock2 download page for the latest
106          information on dependencies. These components are unsupported by
107          Novell. They are provided as a courtesy, but it is strongly
108          suggested that all development be done using LIBC, not CLIB.
109
110          As of June 2005, the WinSock2 components are available at:
111          http://forgeftp.novell.com//ws2comp/
112
113
114       NLM and NetWare libraries for C (including CLIB and XPlat):
115          If you are going to build a CLIB version of OpenSSL, you will
116          need the CLIB headers and imports.  The March, 2001 NDK release or 
117          later is recommended.
118
119          Earlier versions should work but haven't been tested.  In recent
120          versions the import files have been consolidated and function
121          names moved.  This means you may run into link problems
122          (undefined symbols) when using earlier versions.   The functions
123          are available in earlier versions, but you will have to modifiy
124          the make files to include additional import files (see
125          openssl\util\pl\netware.pl).
126
127
128    LIBC - BUILDS:
129    
130       Libraries for C (LIBC) - LIBC headers and import files
131          If you are going to build a LIBC version of OpenSSL, you will
132          need the LIBC headers and imports.  The March 14, 2002 NDK release or
133          later is required.  
134          
135          NOTE: The LIBC SDK includes the necessary WinSock2 support.
136          It is not necessary to download the WinSock2 NDK when building for
137          LIBC. The LIBC SDK also includes the appropriate BSD socket support
138          if configuring to use BSD sockets.
139
140
141 BUILDING:
142 ---------
143 Before building, you will need to set a few environment variables.  You can
144 set them manually or you can modify the "netware\set_env.bat" file.
145
146 The set_env.bat file is a template you can use to set up the path
147 and environment variables you will need to build.  Modify the
148 various lines to point to YOUR tools and run set_env.bat.
149
150    netware\set_env.bat <target> [compiler]
151
152       target        - "netware-clib" - CLIB NetWare build
153                     - "netware-libc" - LIBC NetWare build
154
155       compiler      - "gnuc"         - GNU GCC Compiler
156                     - "codewarrior"  - MetroWerks CodeWarrior (default)
157
158 If you don't use set_env.bat, you will need to set up the following
159 environment variables:
160
161    PATH - Set PATH to point to the tools you will use.
162
163    INCLUDE - The location of the NDK include files.
164          
165             CLIB ex: set INCLUDE=c:\ndk\nwsdk\include\nlm
166             LIBC ex: set INCLUDE=c:\ndk\libc\include
167
168    PRELUDE - The absolute path of the prelude object to link with.  For
169             a CLIB build it is recommended you use the "clibpre.o" files shipped
170             with the Metrowerks PDK for NetWare.  For a LIBC build you should 
171             use the "libcpre.o" file delivered with the LIBC NDK components.
172
173             CLIB ex: set PRELUDE=c:\ndk\nwsdk\imports\clibpre.o
174             LIBC ex: set PRELUDE=c:\ndk\libc\imports\libcpre.o
175
176    IMPORTS - The locaton of the NDK import files.
177
178             CLIB ex: set IMPORTS=c:\ndk\nwsdk\imports
179             LIBC ex: set IMPORTS=c:\ndk\libc\imports
180
181
182 In order to build, you need to run the Perl scripts to configure the build
183 process and generate a make file.  There is a batch file,
184 "netware\build.bat", to automate the process.
185
186 Build.bat runs the build configuration scripts and generates a make file.
187 If an assembly option is specified, it also runs the scripts to generate 
188 the assembly code.  Always run build.bat from the "openssl" directory.
189
190    netware\build [target] [debug opts] [assembly opts] [configure opts]
191
192       target        - "netware-clib" - CLIB NetWare build (WinSock Sockets)
193                     - "netware-clib-bsdsock" - CLIB NetWare build (BSD Sockets)
194                     - "netware-libc" - LIBC NetWare build (WinSock Sockets)
195                     - "netware-libc-bsdsock" - LIBC NetWare build (BSD Sockets)
196  
197       debug opts    - "debug"  - build debug
198
199       assembly opts - "nw-mwasm" - use Metrowerks assembler
200                       "nw-nasm"  - use NASM assembler
201                       "no-asm"   - don't use assembly
202
203       configure opts- all unrecognized arguments are passed to the
204                       perl 'configure' script. See that script for
205                       internal documentation regarding options that
206                       are available.
207
208    examples:
209
210       CLIB build, debug, without assembly:
211          netware\build.bat netware-clib debug no-asm
212
213       LIBC build, non-debug, using NASM assembly, add mdc2 support:
214          netware\build.bat netware-libc nw-nasm enable-mdc2
215
216       LIBC build, BSD sockets, non-debug, without assembly:
217          netware\build.bat netware-libc-bsdsock no-asm
218
219 Running build.bat generates a make file to be processed by your make 
220 tool (gmake or nmake):
221
222    CLIB ex: gmake -f netware\nlm_clib_dbg.mak 
223    LIBC ex: gmake -f netware\nlm_libc.mak 
224    LIBC ex: gmake -f netware\nlm_libc_bsdsock.mak 
225
226
227 You can also run the build scripts manually if you do not want to use the
228 build.bat file.  Run the following scripts in the "\openssl"
229 subdirectory (in the order listed below):
230
231    perl configure no-asm [other config opts] [netware-clib|netware-libc|netware-libc-bsdsock]
232       configures no assembly build for specified netware environment
233       (CLIB or LIBC).
234
235    perl util\mkfiles.pl >MINFO
236       generates a listing of source files (used by mk1mf)
237
238    perl util\mk1mf.pl no-asm [other config opts] [netware-clib|netware-libc|netware-libc-bsdsock >netware\nlm.mak
239       generates the makefile for NetWare
240
241    gmake -f netware\nlm.mak
242       build with the make tool (nmake.exe also works)
243
244 NOTE:  If you are building using the assembly option, you must also run the
245 various Perl scripts to generate the assembly files.  See build.bat
246 for an example of running the various assembly scripts.  You must use the
247 "no-asm" option to build without assembly.  The configure and mk1mf scripts
248 also have various other options.  See the scripts for more information.
249
250
251 The output from the build is placed in the following directories:
252
253    CLIB Debug build:
254       out_nw_clib.dbg     - static libs & test nlm(s)
255       tmp_nw_clib.dbg     - temporary build files
256       outinc_nw_clib      - necessary include files
257
258    CLIB Non-debug build:
259       out_nw_clib         - static libs & test nlm(s)
260       tmp_nw_clib         - temporary build files
261       outinc_nw_clib      - necesary include files
262
263    LIBC Debug build:
264       out_nw_libc.dbg     - static libs & test nlm(s)
265       tmp_nw_libc.dbg     - temporary build files
266       outinc_nw_libc      - necessary include files
267
268    LIBC Non-debug build:
269       out_nw_libc         - static libs & test nlm(s)
270       tmp_nw_libc         - temporary build files
271       outinc_nw_libc      - necesary include files
272
273
274 TESTING:
275 --------
276 The build process creates the OpenSSL static libs ( crypto.lib, ssl.lib,
277 rsaglue.lib ) and several test programs.  You should copy the test programs
278 to your NetWare server and run the tests.
279
280 The batch file "netware\cpy_tests.bat" will copy all the necessary files
281 to your server for testing.  In order to run the batch file, you need a
282 drive mapped to your target server.  It will create an "OpenSSL" directory
283 on the drive and copy the test files to it.  CAUTION: If a directory with the
284 name of "OpenSSL" already exists, it will be deleted.
285
286 To run cpy_tests.bat:
287
288    netware\cpy_tests [output directory] [NetWare drive]
289
290       output directory - "out_nw_clib.dbg", "out_nw_libc", etc.
291       NetWare drive    - drive letter of mapped drive
292
293       CLIB ex: netware\cpy_tests out_nw_clib m:
294       LIBC ex: netware\cpy_tests out_nw_libc m:
295
296
297 The Perl script, "do_tests.pl", in the "OpenSSL" directory on the server
298 should be used to execute the tests.  Before running the script, make sure
299 your SEARCH PATH includes the "OpenSSL" directory.  For example, if you
300 copied the files to the "sys:" volume you use the command:
301
302    SEARCH ADD SYS:\OPENSSL
303
304
305 To run do_tests.pl type (at the console prompt):
306
307    perl \openssl\do_tests.pl [options]
308
309       options:
310          -p    - pause after executing each test
311
312 The do_tests.pl script generates a log file "\openssl\test_out\tests.log"
313 which should be reviewed for errors.  Any errors will be denoted by the word
314 "ERROR" in the log.
315
316 DEVELOPING WITH THE OPENSSL SDK:
317 --------------------------------
318 Now that everything is built and tested, you are ready to use the OpenSSL
319 libraries in your development.
320
321 There is no real installation procedure, just copy the static libs and
322 headers to your build location.  The libs (crypto.lib & ssl.lib) are
323 located in the appropriate "out_nw_XXXX" directory 
324 (out_nw_clib, out_nw_libc, etc).  
325
326 The headers are located in the appropriate "outinc_nw_XXX" directory 
327 (outinc_nw_clib, outinc_nw_libc).  
328
329 One suggestion is to create the following directory 
330 structure for the OpenSSL SDK:
331
332    \openssl
333       |- bin
334       |   |- openssl.nlm
335       |   |- (other tests you want)
336       |
337       |- lib
338       |   | - crypto.lib
339       |   | - ssl.lib
340       |
341       |- include
342       |   | - openssl
343       |   |    | - (all the headers in "outinc_nw\openssl")
344
345
346 The program "openssl.nlm" can be very useful.  It has dozens of
347 options and you may want to keep it handy for debugging, testing, etc.
348
349 When building your apps using OpenSSL, define "NETWARE".  It is needed by
350 some of the OpenSSL headers.  One way to do this is with a compile option,
351 for example "-DNETWARE".
352
353
354
355 NOTES:
356 ------
357
358 Resource leaks in Tests
359 ------------------------
360 Some OpenSSL tests do not clean up resources and NetWare reports
361 the resource leaks when the tests unload.  If this really bugs you,
362 you can stop the messages by setting the developer option off at the console
363 prompt (set developer option = off).  Or better yet, fix the tests to
364 clean up the resources!
365
366
367 Multi-threaded Development
368 ---------------------------
369 The NetWare version of OpenSSL is thread-safe, however multi-threaded
370 applications must provide the necessary locking function callbacks.  This
371 is described in doc\threads.doc.  The file "openssl-x.x.x\crypto\threads\mttest.c"
372 is a multi-threaded test program and demonstrates the locking functions.
373
374
375 What is openssl2.nlm?
376 ---------------------
377 The openssl program has numerous options and can be used for many different
378 things.  Many of the options operate in an interactive mode requiring the
379 user to enter data.  Because of this, a default screen is created for the
380 program.  However, when running the test script it is not desirable to
381 have a separate screen.  Therefore, the build also creates openssl2.nlm.
382 Openssl2.nlm is functionally identical but uses the console screen.
383 Openssl2 can be used when a non-interactive mode is desired.
384
385 NOTE:  There are may other possibilities (command line options, etc)
386 which could have been used to address the screen issue.  The openssl2.nlm
387 option was chosen because it impacted only the build not the code.
388
389
390 Why only static libraries?
391 --------------------------
392 Globals, globals, and more globals.  The OpenSSL code uses many global
393 variables that are allocated and initialized when used for the first time.
394
395 On NetWare, most applications (at least historically) run in the kernel.
396 When running in the kernel, there is one instance of global variables.
397 For regular application type NLM(s) this isn't a problem because they are
398 the only ones using the globals.  However, for a library NLM (an NLM which
399 exposes functions and has no threads of execution), the globals cause
400 problems.  Applications could inadvertently step on each other if they
401 change some globals.  Even worse, the first application that triggers a
402 global to be allocated and initialized has the allocated memory charged to
403 itself.  Now when that application unloads, NetWare will clean up all the
404 applicaton's memory.  The global pointer variables inside OpenSSL now
405 point to freed memory.  An abend waiting to happen!
406
407 To work correctly in the kernel, library NLM(s) that use globals need to
408 provide a set of globals (instance data) for each application.  Another
409 option is to require the library only be loaded in a protected address
410 space along with the application using it.
411
412 Modifying the OpenSSL code to provide a set of globals (instance data) for
413 each application isn't technically difficult, but due to the large number
414 globals it would require substantial code changes and it wasn't done.  Hence,
415 the build currently only builds static libraries which are then linked
416 into each application.
417
418 NOTE:  If you are building a library NLM that uses the OpenSSL static
419 libraries, you will still have to deal with the global variable issue.
420 This is because when you link in the OpenSSL code you bring in all the
421 globals.  One possible solution for the global pointer variables is to
422 register memory functions with OpenSSL which allocate memory and charge it
423 to your library NLM (see the function CRYPTO_set_mem_functions).  However,
424 be aware that now all memory allocated by OpenSSL is charged to your NLM.
425
426
427 CodeWarrior Tools and W2K
428 ---------------------------
429 There have been problems reported with the CodeWarrior Linker
430 (mwldnlm.exe) in the PDK 2.1 for NetWare when running on Windows 2000.  The
431 problems cause the link step to fail.  The only work around is to obtain an
432 updated linker from Metrowerks.  It is expected Metrowerks will release
433 PDK 3.0 (in beta testing at this time - May, 2001) in the near future which
434 will fix these problems.
435
436
437 Makefile "vclean"
438 ------------------
439 The generated makefile has a "vclean" target which cleans up the build
440 directories.  If you have been building successfully and suddenly
441 experience problems, use "vclean" (gmake -f netware\nlm_xxxx.mak vclean) and retry.
442
443
444 "Undefined Symbol" Linker errors
445 --------------------------------
446 There have been linker errors reported when doing a CLIB build.  The problems
447 occur because some versions of the CLIB SDK import files inadvertently 
448 left out some symbols.  One symbol in particular is "_lrotl".  The missing
449 functions are actually delivered in the binaries, but they were left out of
450 the import files.  The issues should be fixed in the September 2001 release 
451 of the NDK.  If you experience the problems you can temporarily
452 work around it by manually adding the missing symbols to your version of 
453 "clib.imp".
454