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