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