Add configure option --enable-large-data-tests.
[libgcrypt.git] / README
1                     Libgcrypt - The GNU Crypto Library
2                    ------------------------------------
3                              Version 1.6
4
5        Copyright (C) 1989,1991-2012 Free Software Foundation, Inc.
6
7     Libgcrypt is free software.  See the file AUTHORS for full copying
8     notices, and LICENSES for notices about contributions that require
9     these additional notices to be distributed.
10
11
12     Overview
13     --------
14
15     Libgcrypt is a general purpose crypto library based on the code
16     used in GnuPG.  Libgcrypt depends on the library `libgpg-error',
17     which must be installed correctly before Libgcrypt is to be built.
18     Libgcrypt is distributed under the LGPL, see the section "License"
19     below for details.
20
21
22     Build Instructions
23     ------------------
24
25     The download canonical location for libgcrypt is:
26
27       ftp://ftp.gnupg.org/gcrypt/libgcrypt/
28
29     To build libgcrypt you need libgpg-error:
30
31       ftp://ftp.gnupg.org/gcrypt/libgpg-error/
32
33     You should get the latest versions of course.
34
35     After building and installing the libgpg-error package, you may
36     continue with Libgcrypt installation As with allmost all GNU
37     packages, you just have to do
38
39        ./configure
40        make
41        make check
42        make install
43
44     The "make check" is not required but a good idea to see whether
45     the library works as expected.  The check takes some while and
46     prints some benchmarking results.  Before doing "make install" you
47     probably need to become root.
48
49     To build libgcrypt for Microsoft Windows, you need to have the
50     mingw32 cross-building toolchain installed.  Instead of running a
51     plain configure you use
52
53       ./autogen.sh --build-w32
54       make
55       make install
56
57     By default this command sequences expectsd a libgpg-error
58     installed below $HOME/w32root and installs libgcrypt to that
59     directory too.  See the autogen.sh code for details.
60
61     The documentation is available as an Info file (gcrypt.info).  To
62     build documentation in PDF, run this:
63
64       cd doc
65       make pdf
66
67
68
69     Mailing List
70     ------------
71
72     You may want to join the developer's mailing list
73     gcrypt-devel@gnupg.org by sending mail with a subject of
74     "subscribe" to gcrypt-devel-request@gnupg.org.  An archive of this
75     list is available at http://lists.gnupg.org .
76
77
78     Configure options
79     -----------------
80     Here is a list of configure options which are sometimes useful
81     for installation.
82
83      --enable-large-data-tests
84                      With this option a "make check" will take really
85                      long due to extra checks for the hash algorithms.
86
87      --enable-m-guard
88                      Enable the integrated malloc checking code. Please
89                      note that this feature does not work on all CPUs
90                      (e.g. SunOS 5.7 on UltraSparc-2) and might give
91                      you a bus error.
92
93      --disable-asm
94                      Do not use assembler modules.  It is not possible
95                      to use this on some CPU types.
96
97      --enable-ld-version-script
98                      Libgcrypt tries to build a library where internal
99                      symbols are not exported.  This requires support
100                      from ld and is currently enabled for a few OSes.
101                      If you know that your ld supports the so called
102                      ELF version scripts, you can use this option to
103                      force its use.  OTOH, if you get error message
104                      from the linker, you probably want to use this
105                      option to disable the use of version scripts.
106                      Note, that you should never ever use an
107                      undocumented symbol or one which is prefixed with
108                      an underscore.
109
110      --enable-ciphers=list
111      --enable-pubkey-ciphers=list
112      --enable-digests=list
113                      If not otherwise specified, all algorithms
114                      included in the libgcrypt source tree are built.
115                      An exception are algorithms, which depend on
116                      features not provided by the system, like 64bit
117                      data types.  With these switches it is possible
118                      to select exactly those algorithm modules, which
119                      should be built.  The algorithms are to be
120                      separated by spaces, commas or colons.  To view
121                      the list used with the current build the program
122                      tests/version may be used.
123
124      --disable-endian-check
125                      Don't let configure test for the endianness but
126                      try to use the OS provided macros at compile
127                      time.  This is helpful to create OS X fat binaries.
128
129      --enable-random-daemon
130                      Include support for a global random daemon and
131                      build the daemon.  This is an experimental feature.
132
133      --enable-mpi-path=EXTRA_PATH
134                      Prepend EXTRA_PATH to list of CPU specific
135                      optimizations.  For example, if you want to add
136                      optimizations forn a Intel Pentium 4 compatible
137                      CPU, you may use
138                         --enable-mpi-path=pentium4/sse2:pentium4/mmx
139                      Take care: The generated library may crash on
140                      non-compatible CPUs.
141
142      --enable-random=NAME
143                      Force the use of the random gathering module
144                      NAME.  Default is either to use /dev/random or
145                      the auto mode.  Possible values for NAME are:
146                        egd - Use the module which accesses the
147                              Entropy Gathering Daemon. See the webpages
148                              for more information about it.
149                       unix - Use the standard Unix module which does not
150                              have a very good performance.
151                      linux - Use the module which accesses /dev/random.
152                              This is the first choice and the default one
153                              for GNU/Linux or *BSD.
154                       auto - Compile linux, egd and unix in and
155                              automagically select at runtime.
156
157      --enable-hmac-binary-check
158                      Include support to check the binary at runtime
159                      against a HMAC checksum.  This works only in FIPS
160                      mode and on systems providing the dladdr function.
161
162      --disable-padlock-support
163                      Disable support for the PadLock engine of VIA
164                      processors.  The default is to use PadLock if
165                      available.  Try this if you get problems with
166                      assembler code.
167
168      --disable-aesni-support
169                      Disable support for the AES-NI instructions of
170                      newer Intel CPUs.  The default is to use AES-NI
171                      if available.  Try this if you get problems with
172                      assembler code.
173
174      --disable-O-flag-munging
175                      Some code is too complex for some compilers while
176                      in higher optimization modes, thus the compiler
177                      invocation is modified to use a lower
178                      optimization level.  Usually this works very well
179                      but on some platforms these rules break the
180                      invocation.  This option may be used to disable
181                      the feature under the assumption that either good
182                      CFLAGS are given or the compiler can grok the code.
183
184
185
186
187     Build Problems
188     --------------
189
190     We can't check all assembler files, so if you have problems
191     assembling them (or the program crashes) use --disable-asm with
192     ./configure.  If you opt to delete individual replacement files in
193     hopes of using the remaining ones, be aware that the configure
194     scripts may consider several subdirectories to get all available
195     assembler files; be sure to delete the correct ones.  Never delete
196     udiv-qrnnd.S in any CPU directory, because there may be no C
197     substitute (in mpi/genereic).  Don't forget to delete
198     "config.cache" and run "./config.status --recheck".  We got a few
199     reports about problems using versions of gcc earlier than 2.96
200     along with a non-GNU assembler (as).  If this applies to your
201     platform, you can either upgrade gcc to a more recent version, or
202     use the GNU assembler.
203
204     Some make tools are broken - the best solution is to use GNU's
205     make.  Try gmake or grab the sources from a GNU archive and
206     install them.
207
208     Specific problems on some machines:
209
210       * IBM RS/6000 running AIX
211
212         Due to a change in gcc (since version 2.8) the MPI stuff may
213         not build. In this case try to run configure using:
214             CFLAGS="-g -O2 -mcpu=powerpc" ./configure
215
216       * SVR4.2 (ESIX V4.2 cc)
217
218         Due to problems with the ESIX as(1), you probably want to do:
219             CFLAGS="-O -K pentium" ./configure --disable-asm
220
221       * SunOS 4.1.4
222
223          ./configure ac_cv_sys_symbol_underscore=yes
224
225       * Sparc64 CPUs
226
227         We have reports about failures in the AES module when
228         compiling using gcc (e.g. version 4.1.2) and the option -O3;
229         using -O2 solves the problem.
230
231
232     License
233     -------
234
235     The library is distributed under the terms of the GNU Lesser
236     General Public License (LGPL); see the file COPYING.LIB for the
237     actual terms.  The helper programs (e.g. gcryptrnd and getrandom)
238     as well as the documentation are distributed under the terms of
239     the GNU General Public License (GPL); see the file COPYING for the
240     actual terms.
241
242     This library used to be available under the GPL - this was changed
243     with version 1.1.7 with the rationale that there are now many free
244     crypto libraries available and many of them come with capabilities
245     similar to Libcrypt.  We decided that to foster the use of
246     cryptography in Free Software an LGPLed library would make more
247     sense because it avoids problems due to license incompatibilities
248     between some Free Software licenses and the GPL.
249
250     Please note that in many cases it is better for a library to be
251     licensed under the GPL, so that it provides an advantage for free
252     software projects.  The Lesser GPL is so named because it does
253     less to protect the freedom of the users of the code that it
254     covers.  See http://www.gnu.org/philosophy/why-not-lgpl.html for
255     more explanation.
256
257
258     Contact
259     -------
260
261     See the file AUTHORS.
262
263     Commercial grade support for Libgcrypt is available; please see
264     http://www.gnupg.org/service.html .
265
266
267   This file is Free Software; as a special exception the authors gives
268   unlimited permission to copy and/or distribute it, with or without
269   modifications, as long as this notice is preserved. For conditions
270   of the whole package, please see the file COPYING.  This file is
271   distributed in the hope that it will be useful, but WITHOUT ANY
272   WARRANTY, to the extent permitted by law; without even the implied
273   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.