f1065548974888d553392f4b5826e663bf817104
[openssl.git] / INSTALL
1
2  INSTALLATION ON THE UNIX PLATFORM
3  ---------------------------------
4
5  [For instructions for compiling OpenSSL on Windows systems, see INSTALL.W32].
6
7  To install OpenSSL, you will need:
8
9   * Perl
10   * C compiler
11   * A supported Unix operating system
12
13  Quick Start
14  -----------
15
16  If you want to just get on with it, do:
17
18   $ ./config                  [if this fails, go to step 1b below]
19   $ make
20   $ make rehash
21   $ make test
22   $ make install
23
24  This will build and install OpenSSL in the default location, which is (for
25  historical reasons) /usr/local/ssl. If you want to install it anywhere else,
26  do this after running `./config':
27
28   $ perl util/ssldir.pl /new/install/path
29
30  There are several options to ./config to customize the build:
31
32   rsaref    Build with RSADSI's RSAREF toolkit.
33   no-asm    Build with no assembler code.
34   386       Use the 80386 instruction set only (the default x86 code is
35             more efficient, but requires at least a 486).
36
37  If anything goes wrong, follow the detailed instructions below. If your
38  operating system is not (yet) supported by OpenSSL, see the section on
39  porting to a new system.
40
41  Installation in Detail
42  ----------------------
43
44  1a. Configure OpenSSL for your operation system automatically:
45
46        $ ./config
47
48      This guesses at your operating system (and compiler, if necessary) and
49      configures OpenSSL based on this guess. Check the first line of output to
50      see if it guessed correctly. If it did not get it correct or you want to
51      use a different compiler then go to step 1b. Otherwise go to step 2.
52
53  1b. Configure OpenSSL for your operating system manually
54
55      OpenSSL knows about a range of different operating system, hardware and
56      compiler combinations. To see the ones it knows about, run
57
58        $ ./Configure
59
60      Pick a suitable name from the list that matches your system. For most
61      operating systems there is a choice between using "cc" or "gcc".  When
62      you have identified your system (and if necessary compiler) use this name
63      as the argument to ./Configure. For example, a "linux-elf" user would
64      run:
65
66        $ ./Configure linux-elf
67
68      If your system is not available, you will have to edit the Configure
69      program and add the correct configuration for your system.
70
71      Configure configures various files by converting an existing .org file
72      into the real file. If you edit any files, remember that if a
73      corresponding .org file exists them the next time you run ./Configure
74      your changes will be lost when the file gets re-created from the .org
75      file. The files that are created from .org files are:
76
77        Makefile.ssl
78        crypto/des/des.h
79        crypto/des/des_locl.h
80        crypto/md2/md2.h
81        crypto/rc4/rc4.h
82        crypto/rc4/rc4_enc.c
83        crypto/rc2/rc2.h
84        crypto/bf/bf_locl.h
85        crypto/idea/idea.h
86        crypto/bn/bn.h
87
88   2. Set the install directory
89
90      If the install directory will be the default of /usr/local/ssl, skip to
91      the next stage. Otherwise, run
92
93         $ perl util/ssldir.pl /new/install/path
94
95      This configures the installation location into the "install" target of
96      the top-level Makefile, and also updates some defines in an include file
97      so that the default certificate directory is under the proper
98      installation directory. It also updates a few utility files used in the
99      build process.
100
101   3. Build OpenSSL by running:
102
103        $ make
104
105      This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the
106      OpenSSL binary ("openssl"). The libraries will be built in the top-level
107      directory, and the binary will be in the "apps" directory.
108
109   4. After a successful build, the libraries should be tested. Run:
110
111        $ make rehash
112        $ make test
113
114      (The first line makes the test certificates in the "certs" directory
115      accessable via an hash name, which is required for some of the tests).
116
117   5. If everything tests ok, install OpenSSL with
118
119        $ make install
120
121      This will create the installation directory (if it does not exist) and
122      then create the following subdirectories:
123
124        bin            Contains the openssl binary and a few other 
125                       utility programs. 
126        include        Contains the header files needed if you want to
127                       compile programs with libcrypto or libssl.
128        lib            Contains the library files themselves and the
129                       OpenSSL configuration file "openssl.cnf".
130        certs          Initially empty, this is the default location
131                       for certificate files.
132        private        Initially empty, this is the default location
133                       for private key files.
134
135
136 --------------------------------------------------------------------------------
137 The orignal Unix build instructions from SSLeay follow. 
138 Note: some of this may be out of date and no longer applicable
139 --------------------------------------------------------------------------------
140
141 # When bringing the SSLeay distribution back from the evil intel world
142 # of Windows NT, do the following to make it nice again under unix :-)
143 # You don't normally need to run this.
144 sh util/fixNT.sh        # This only works for NT now - eay - 21-Jun-1996
145
146 # If you have perl, and it is not in /usr/local/bin, you can run
147 perl util/perlpath.pl /new/path
148 # and this will fix the paths in all the scripts.  DO NOT put
149 # /new/path/perl, just /new/path. The build
150 # environment always run scripts as 'perl perlscript.pl' but some of the
151 # 'applications' are easier to usr with the path fixed.
152
153 # Edit crypto/cryptlib.h, tools/c_rehash, and Makefile.ssl
154 # to set the install locations if you don't like
155 # the default location of /usr/local/ssl
156 # Do this by running
157 perl util/ssldir.pl /new/ssl/home
158 # if you have perl, or by hand if not.
159
160 # If things have been stuffed up with the sym links, run
161 make -f Makefile.ssl links
162 # This will re-populate lib/include with symlinks and for each
163 # directory, link Makefile to Makefile.ssl
164
165 # Setup the machine dependent stuff for the top level makefile
166 # and some select .h files
167 # If you don't have perl, this will bomb, in which case just edit the
168 # top level Makefile.ssl
169 ./Configure 'system type'
170
171 # The 'Configure' command contains default configuration parameters
172 # for lots of machines.  Configure edits 5 lines in the top level Makefile
173 # It modifies the following values in the following files
174 Makefile.ssl            CC CFLAG EX_LIBS BN_MULW
175 crypto/des/des.h        DES_LONG
176 crypto/des/des_locl.h   DES_PTR
177 crypto/md2/md2.h        MD2_INT
178 crypto/rc4/rc4.h        RC4_INT
179 crypto/rc4/rc4_enc.c    RC4_INDEX
180 crypto/rc2/rc2.h        RC2_INT
181 crypto/bf/bf_locl.h     BF_INT
182 crypto/idea/idea.h      IDEA_INT
183 crypto/bn/bn.h          BN_LLONG (and defines one of SIXTY_FOUR_BIT,
184                                   SIXTY_FOUR_BIT_LONG, THIRTY_TWO_BIT,
185                                   SIXTEEN_BIT or EIGHT_BIT)
186 Please remember that all these files are actually copies of the file with
187 a .org extention.  So if you change crypto/des/des.h, the next time
188 you run Configure, it will be runover by a 'configured' version of
189 crypto/des/des.org.  So to make the changer the default, change the .org
190 files.  The reason these files have to be edited is because most of
191 these modifications change the size of fundamental data types.
192 While in theory this stuff is optional, it often makes a big
193 difference in performance and when using assember, it is importaint
194 for the 'Bignum bits' match those required by the assember code.
195 A warning for people using gcc with sparc cpu's.  Gcc needs the -mv8
196 flag to use the hardware multiply instruction which was not present in
197 earlier versions of the sparc CPU.  I define it by default.  If you
198 have an old sparc, and it crashes, try rebuilding with this flag
199 removed.  I am leaving this flag on by default because it makes
200 things run 4 times faster :-)
201
202 # clean out all the old stuff
203 make clean
204
205 # Do a make depend only if you have the makedepend command installed
206 # This is not needed but it does make things nice when developing.
207 make depend
208
209 # make should build everything
210 make
211
212 # fix up the demo certificate hash directory if it has been stuffed up.
213 make rehash
214
215 # test everything
216 make test
217
218 # install the lot
219 make install
220
221 # It is worth noting that all the applications are built into the one
222 # program, ssleay, which is then has links from the other programs
223 # names to it.
224 # The applicatons can be built by themselves, just don't define the
225 # 'MONOLITH' flag.  So to build the 'enc' program stand alone,
226 gcc -O2 -Iinclude apps/enc.c apps/apps.c libcrypto.a
227
228 # Other useful make options are
229 make makefile.one
230 # which generate a 'makefile.one' file which will build the complete
231 # SSLeay distribution with temp. files in './tmp' and 'installable' files
232 # in './out'
233
234 # Have a look at running
235 perl util/mk1mf.pl help
236 # this can be used to generate a single makefile and is about the only
237 # way to generate makefiles for windows.
238
239 # There is actually a final way of building SSLeay.
240 gcc -O2 -c -Icrypto -Iinclude crypto/crypto.c
241 gcc -O2 -c -Issl -Iinclude ssl/ssl.c
242 # and you now have the 2 libraries as single object files :-).
243 # If you want to use the assember code for your particular platform
244 # (DEC alpha/x86 are the main ones, the other assember is just the
245 # output from gcc) you will need to link the assember with the above generated
246 # object file and also do the above compile as
247 gcc -O2 -DBN_ASM -c -Icrypto -Iinclude crypto/crypto.c
248
249 This last option is probably the best way to go when porting to another
250 platform or building shared libraries.  It is not good for development so
251 I don't normally use it.
252
253 To build shared libararies under unix, have a look in shlib, basically 
254 you are on your own, but it is quite easy and all you have to do
255 is compile 2 (or 3) files.
256
257 For mult-threading, have a read of doc/threads.doc.  Again it is quite
258 easy and normally only requires some extra callbacks to be defined
259 by the application.
260 The examples for solaris and windows NT/95 are in the mt directory.
261
262 have fun
263
264 eric 25-Jun-1997
265
266 IRIX 5.x will build as a 32 bit system with mips1 assember.
267 IRIX 6.x will build as a 64 bit system with mips3 assember.  It conforms
268 to n32 standards. In theory you can compile the 64 bit assember under
269 IRIX 5.x but you will have to have the correct system software installed.