Attached is a proposed modification to the README file, including recent comments...
[gnutls:gnutls.git] / README
1 GnuTLS README -- Important introductory notes.
2
3 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
4               2008, 2009, 2010  Free Software Foundation, Inc.
5
6 See the end of this document for copying conditions.
7
8 GnuTLS implements the TLS/SSL (Transport Layer Security aka Secure
9 Sockets Layer) protocol.  GnuTLS is a GNU project.  Additional
10 information can be found at <http://www.gnu.org/software/gnutls/>
11 and <http://www.gnutls.org/>.
12
13
14 README
15 ------
16 This README is targeted for users of the library who build from
17 sources but do not necessarily develop.  If you are interested
18 in developing and contributing to the GnuTLS project, please
19 see README-alpha and visit 
20 http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html.
21
22
23 COMPILATION
24 -----------
25 A typical command sequence for building the library is shown below.
26 A complete list of options available for configure can be found
27 by running './configure --help'.
28
29     cd gnutls-2.10.3
30     ./configure --prefix=/usr
31     make
32     sudo make install
33
34 The commands above build and install the static archives (libgnutls.a
35 and libgnutls-extra.a), the shared object (libgnutls.so  and
36 libgnutls-extra.so), and additional binaries such as certtool and
37 gnutls-cli.
38
39 The library depends on libnettle OR libgcrypt (but never both).  GnuTLS
40 currently uses libnettle as the default cryptographic library.  Versions
41 2.10.3 and prior used libgcrypt as the default cryptographic library.
42 Nettle can be found at http://www.gnu.org/software/nettle/, while
43 libgcrypt can be found at <ftp://ftp.gnupg.org/pub/gcrypt/libgcrypt/>.
44
45 To configure libnettle for installation and use by GnuTLS, a typical
46 command sequence would be:
47
48     cd nettle-2.1
49     ./configure --prefix=/usr --disable-openssl --enable-shared
50     make
51     sudo make install
52
53 For the Nettle project, --enable-shared will instruct automake and
54 friends to build and install both the static archive (libnettle.a)
55 and the shared object (libnettle.so).
56
57 In case you are compiling for an embedded system, you can disable
58 unneeded features of GnuTLS.  In general, it is usually best not to
59 disable anything (for future mailing list questions and possible bugs).
60
61 Depending on your installation, additional libraries, such as libtasn1
62 and zlib, may be required.
63
64
65 DOCUMENTATION
66 -------------
67 See the documentation in doc/ and online at
68 http://www.gnu.org/software/gnutls/manual/html_node/index.htm.
69
70
71 EXAMPLES
72 --------
73 See the examples in doc/examples/ and online at 'How To Use GnuTLS in
74 Applications' at http://www.gnu.org/software/gnutls/manual/html_node/How-
75 to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications.
76 The examples include client, server, and multi-threaded examples.
77
78
79 SECURITY ADVISORIES
80 -------------------
81 The project collects and publishes information on past security 
82 incidents and vulnerabilities.  Open information exchange, including
83 information which is [sometimes] suppressed in non-open or non-free
84 projects, is one of the goals of the GnuTLS project.  Please visit
85 http://www.gnu.org/software/gnutls/security.html.
86
87
88 MAILING LISTS
89 -------------
90 The GnuTLS project maintains mailing lists for users, developers, and
91 commits.  Please see http://www.gnu.org/software/gnutls/lists.html.
92
93
94 LICENSING
95 ---------
96 Since version 0.4.2, the GnuTLS library has been released under the GNU
97 Lesser General Public License (LGPL).  Previous versions were licensed
98 under the GNU General Public License (GPL).
99
100 We changed the license for most of the GnuTLS components because other
101 free libraries exist and offer similar functionality with lax licenses.
102 We want GnuTLS to be usable in the same places as those other libraries.
103 We kept some parts of GnuTLS under the GPL because they are unique, and
104 the terms of the license under GPL provides free software projects (which
105 deserve our help) an advantage over non-free projects (which do not
106 deserve our help, since they refuse to share with us).  For information, see
107 http://www.gnu.org/philosophy/why-not-lgpl.html.
108
109 The GNU LPGL applies to the main gnutls library, while
110 the gnutls-extra library is under the GPL.  The gnutls-extra library
111 contains the code for "GnuTLS Inner Application" support and the
112 OpenSSL compatibility layer.  The gnutls library is located in the
113 lib/ directory, while the gnutls-extra library is at libextra/.
114
115
116 BUGS
117 ----
118 Currently GnuTLS needs testing.  Thorough testing is very important and
119 expensive.  Often times, the developers do not have access to a particular
120 piece of hardware or configuration to reproduce a scenario.  Notifying
121 the developers about a possible bug will greatly help the project.  
122
123 If you believe you have found a bug, please report it to bug-gnutls@gnu.org
124 together with any applicable information.  A web interface for the system
125 is available at http://savannah.gnu.org/support/?group=gnutls.
126
127 Applicable information would include why the issue is a GnuTLS bug (if
128 not readily apparent), output from 'uname -a', the version of the library or
129 tool being used, a stack trace if available ('bt full' if under gdb), and
130 perhaps a network trace.  Vague queries or piecemeal messages are difficult
131 to act upon and don't help the development effort.
132
133 Additional information can be found at the project's Bug Report page at
134 http://www.gnu.org/software/gnutls/manual/html_node/Bug-Reports.html.
135
136
137 PATCHES
138 -------
139 Patches are welcome and encouraged.  Details of contributing can be found
140 at http://www.gnu.org/software/gnutls/manual/html_node/Contributing.html.
141
142 Patches are submitted through the bug tracking system.  When submitting
143 patches, please be sure to use sources from the git repository.  To
144 create a patch for the project from a local git repository, please use
145 the following commands.  'gnutls' should be the local directory of a
146 previous git clone, and <filename> should reflect a descriptive name for
147 the patch.
148
149     cd gnutls
150     git diff > <filename>.patch
151
152 ----------------------------------------------------------------------
153 Copying and distribution of this file, with or without modification,
154 are permitted in any medium without royalty provided the copyright
155 notice and this notice are preserved.