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