Preparing the release
[libgcrypt.git] / README
1                     libgcrypt - The GNU crypto library
2                    ------------------------------------
3                             Version 1.4.1
4
5     Copyright 2000, 2002, 2003, 2004, 2007,
6               2008 Free Software Foundation, Inc.
7
8     This file is free software; as a special exception the author gives
9     unlimited permission to copy and/or distribute it, with or without
10     modifications, as long as this notice is preserved.
11
12     This file is distributed in the hope that it will be useful, but
13     WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
14     implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
15
16
17
18     Overview
19     --------
20
21     Libgcrypt is a general purpose crypto library based on the code
22     used in GnuPG.  Libgcrypt depends on the library `libgpg-error',
23     which must be installed correctly before Libgcrypt is to be built.
24     Libgcrypt is distributed under the LGPL, see the section "License"
25     below for details.
26
27
28     Build Instructions
29     ------------------
30
31     The download canonical location for libgcrypt is:
32
33       ftp://ftp.gnupg.org/gcrypt/libgcrypt/
34      
35     To build libgcrypt you need libgpg-error:
36
37       ftp://ftp.gnupg.org/gcrypt/libgpg-error/
38
39     You should get the latest versions of course.
40
41     After building and installing the libgpg-error package, you may
42     continue with Libgcrypt installation As with allmost all GNU
43     packages, you just have to do
44
45        ./configure
46        make
47        make check
48        make install
49
50     The "make check" is not required but a good idea to see whether
51     the library works as expected.  The check takes some while and
52     prints some benchmarking results.  Before doing "make install" you
53     probably need to become root.
54
55     To build libgcrypt for Microsoft Windows, you need to have the
56     mingw32 cross-building toolchain installed.  Instead of running a
57     plain configure you use
58
59       ./autogen.sh --build-w32
60       make
61       make install
62       
63     By default this command sequences expectsd a libgpg-error
64     installed below $HOME/w32root and installs libgcrypt to that
65     directory too.  See the autogen.sh code for details.
66
67     The documentation is available as an Info file (gcrypt.info).  To
68     build documentation in PDF, run this:
69
70       cd doc
71       make pdf
72
73
74
75     Mailing List
76     ------------
77
78     You may want to join the developer's mailing list
79     gcrypt-devel@gnupg.org by sending mail with a subject of
80     "subscribe" to gcrypt-devel-request@gnupg.org.  An archive of this
81     list is available at http://lists.gnupg.org .
82
83
84     Configure options 
85     -----------------
86     Here is a list of configure options which are sometimes useful 
87     for installation.
88
89      --enable-m-guard
90                      Enable the integrated malloc checking code. Please
91                      note that this feature does not work on all CPUs
92                      (e.g. SunOS 5.7 on UltraSparc-2) and might give
93                      you a bus error.
94
95      --disable-asm
96                      Do not use assembler modules.  It is not possible 
97                      to use this on some CPU types.
98                     
99      --enable-ld-version-script
100                      Libgcrypt tries to build a library where internal
101                      symbols are not exported.  This requires support
102                      from ld and is currently enabled for a few OSes.
103                      If you know that your ld supports the so called
104                      ELF version scripts, you can use this option to
105                      force its use.  OTOH, if you get error message
106                      from the linker, you probably want to use this
107                      option to disable the use of version scripts.
108                      Note, that you should never ever use an
109                      undocumented symbol or one which is prefixed with
110                      an underscore. 
111
112      --enable-ciphers=list
113      --enable-pubkey-ciphers=list
114      --enable-digests=list
115                      If not otherwise specified, all algorithms
116                      included in the libgcrypt source tree are built.
117                      An exception are algorithms, which depend on
118                      features not provided by the system, like 64bit
119                      data types.  With these switches it is possible
120                      to select exactly those algorithm modules, which
121                      should be built.  The algorithms are to be
122                      separated by spaces, commas or colons.  To view
123                      the list used with the current build the program
124                      tests/version may be used.
125
126      --disable-endian-check
127                      Don't let configure test for the endianness but
128                      try to use the OS provided macros at compile
129                      time.  This is helpful to create OS X fat binaries.
130
131      --enable-random-daemon
132                      Include support for a global random damon and
133                      build the daemon.  This is an experimental feature.
134
135      --enable-mpi-path=EXTRA_PATH
136                      Prepend EXTRA_PATH to list of CPU specific
137                      optimizations.  For example, if you want to add
138                      optimizations forn a Intel Pentium 4 compatible
139                      CPU, you may use
140                         --enable-mpi-path=pentium4/sse2:pentium4/mmx
141                      Take care: The generated library may crash on
142                      non-compatible CPUs.
143
144      --enable-random=NAME 
145                      Force the use of the random gathering module
146                      NAME.  Default is either to use /dev/random or
147                      the auto mode.  Possible values for NAME are:
148                        egd - Use the module which accesses the
149                              Entropy Gathering Daemon. See the webpages
150                              for more information about it.
151                       unix - Use the standard Unix module which does not
152                              have a very good performance.
153                      linux - Use the module which accesses /dev/random.
154                              This is the first choice and the default one
155                              for GNU/Linux or *BSD.
156                       auto - Compile linux, egd and unix in and 
157                              automagically select at runtime.
158   
159      --disable-padlock-support
160                      Disable support for the PadLock engine of VIA
161                      processors.  The default is to use PadLock if
162                      available.  Try this if you get problems with
163                      assembler code.
164
165
166
167     License
168     -------
169     
170     The library is distributed under the terms of the GNU Lesser
171     General Public License (LGPL); see the file COPYING.LIB for the
172     actual terms.  The helper programs (gcryptrnd and getrandom) as
173     well as the documentation are distributed under the terms of the
174     GNU General Public License (GPL); see the file COPYING for teh
175     actual terms.
176
177     This library used to be available under the GPL - this was changed
178     with version 1.1.7 with the rationale that there are now many free
179     crypto libraries available and many of them come with capabilities
180     similar to Libcrypt.  We decided that to foster the use of
181     cryptography in Free Software an LGPLed library would make more
182     sense because it avoids problems due to license incompatibilities
183     between some Free Software licenses and the GPL.
184
185     Please note that in many cases it is better for a library to be
186     licensed under the GPL, so that it provides an advantage for free
187     software projects.  The Lesser GPL is so named because it does
188     less to protect the freedom of the users of the code that it
189     covers.  See http://www.gnu.org/philosophy/why-not-lgpl.html for
190     more explanation.
191
192
193     Contact
194     -------
195
196     See the file AUTHORS.
197
198     Commercial grade support for Libgcrypt is available; please see
199     http://www.gnupg.org/service.html .
200
201
202   This file is Free Software; as a special exception the authors gives
203   unlimited permission to copy and/or distribute it, with or without
204   modifications, as long as this notice is preserved. For conditions
205   of the whole package, please see the file COPYING.  This file is
206   distributed in the hope that it will be useful, but WITHOUT ANY
207   WARRANTY, to the extent permitted by law; without even the implied
208   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
209