mention dependencies in readme
[gnutls:gnutls.git] / README
1 GnuTLS README -- Important introductory notes.
2 Copyright (C) 2000-2012 Free Software Foundation, Inc.
3 See the end of this document for copying conditions.
4
5 GnuTLS implements the TLS/SSL (Transport Layer Security aka Secure
6 Sockets Layer) protocol.  GnuTLS is a GNU project.  Additional
7 information can be found at <http://www.gnu.org/software/gnutls/>
8 and <http://www.gnutls.org/>.
9
10
11 README
12 ------
13 This README is targeted for users of the library who build from
14 sources but do not necessarily develop.  If you are interested
15 in developing and contributing to the GnuTLS project, please
16 see README-alpha and visit
17 http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html.
18
19
20 COMPILATION
21 -----------
22 A typical command sequence for building the library is shown below.
23 A complete list of options available for configure can be found
24 by running './configure --help'.
25
26     cd gnutls-<version>
27     ./configure --prefix=/usr
28     make
29     sudo make install
30
31 The commands above build and install the static archive (libgnutls.a),
32 the shared object (libgnutls.so), and additional binaries such as certtool 
33 and gnutls-cli.
34
35 The library depends on libnettle. Optionally it may use the 
36 following libraries:
37  * p11-kit: for smart card support
38      http://p11-glue.freedesktop.org/p11-kit.html
39  * libtspi: for Trusted Platform Module (TPM) support, 
40      http://trousers.sourceforge.net/
41  * libunbound: For DNSSEC/DANE support,
42      http://unbound.net/
43  * libz: For compression support.
44      http://www.zlib.net/
45  * libtasn1: For ASN.1 parsing (a copy is included, if not found)
46      http://www.gnu.org/software/libtasn1/
47
48 Versions 2.10.3 and prior used libgcrypt as the default cryptographic library.
49 Nettle can be found at http://www.gnu.org/software/nettle/, while
50 p11-kit can be found at <http://p11-glue.freedesktop.org/p11-kit.html>.
51
52 To configure libnettle for installation and use by GnuTLS, a typical
53 command sequence would be:
54
55     cd nettle-<version>
56     ./configure --prefix=/usr --disable-openssl --enable-shared
57     make
58     sudo make install
59
60 For the Nettle project, --enable-shared will instruct automake and
61 friends to build and install both the static archive (libnettle.a)
62 and the shared object (libnettle.so).
63
64 In case you are compiling for an embedded system, you can disable
65 unneeded features of GnuTLS.  In general, it is usually best not to
66 disable anything (for future mailing list questions and possible bugs).
67
68 Depending on your installation, additional libraries, such as libtasn1
69 and zlib, may be required.
70
71
72 DOCUMENTATION
73 -------------
74 See the documentation in doc/ and online at
75 http://www.gnu.org/software/gnutls/manual.
76
77
78 EXAMPLES
79 --------
80 See the examples in doc/examples/ and online at 'How To Use GnuTLS in
81 Applications' at http://www.gnu.org/software/gnutls/manual.
82
83
84 SECURITY ADVISORIES
85 -------------------
86 The project collects and publishes information on past security
87 incidents and vulnerabilities.  Open information exchange, including
88 information which is [sometimes] suppressed in non-open or non-free
89 projects, is one of the goals of the GnuTLS project.  Please visit
90 http://www.gnu.org/software/gnutls/security.html.
91
92
93 MAILING LISTS
94 -------------
95 The GnuTLS project maintains mailing lists for users, developers, and
96 commits.  Please see http://www.gnu.org/software/gnutls/lists.html.
97
98
99 LICENSING
100 ---------
101 Since GnuTLS version 3.0.0, the core library has been released under
102 the GNU Lesser General Public License (LGPL) version 3 or later.
103
104 The GNU LGPL applies to the main GnuTLS library, while the
105 included applications as well as gnutls-openssl 
106 library are under the GNU GPL version 3.  The gnutls library is 
107 located in the lib/ directory, while the applications in src/ and
108 gnutls-openssl library is at extra/.
109
110 For any copyright year range specified as YYYY-ZZZZ in this package
111 note that the range specifies every single year in that closed interval.
112
113
114 BUGS
115 ----
116 Thorough testing is very important and expensive.  Often, the 
117 developers do not have access to a particular piece of hardware or 
118 configuration to reproduce a scenario.  Notifying the developers about a 
119 possible bug will greatly help the project.  
120
121 If you believe you have found a bug, please report it to bug-gnutls@gnu.org
122 together with any applicable information.  A web interface for the system
123 is available at http://savannah.gnu.org/support/?group=gnutls.
124
125 Applicable information would include why the issue is a GnuTLS bug (if
126 not readily apparent), output from 'uname -a', the version of the library or
127 tool being used, a stack trace if available ('bt full' if under gdb or
128 valgrind output), and perhaps a network trace.  Vague queries or piecemeal 
129 messages are difficult to act upon and don't help the development effort.
130
131 Additional information can be found at the project's manual.
132
133
134 PATCHES
135 -------
136 Patches are welcome and encouraged. Patches can be submitted through the 
137 bug tracking system or the mailing list.  When submitting patches, please 
138 be sure to use sources from the git repository, and preferrably from the 
139 master branch.  To create a patch for the project from a local git repository, 
140 please use the following commands. 'gnutls' should be the local directory 
141 of a previous git clone.
142
143     cd gnutls
144     git add the-file-you-modified.c another-file.c
145     git commit the-file-you-modified.c another-file.c
146     git format-patch
147
148 For more information on use of Git, visit http://git-scm.com/
149
150 ----------------------------------------------------------------------
151 Copying and distribution of this file, with or without modification,
152 are permitted in any medium without royalty provided the copyright
153 notice and this notice are preserved.