From 79324b0fa7a02739df6295532b3f8f98b9a4105a Mon Sep 17 00:00:00 2001 From: Simon Josefsson Date: Mon, 2 Jul 2007 14:11:26 +0200 Subject: Improve installation instructions. --- doc/gnutls.texi | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 193 insertions(+), 6 deletions(-) (limited to 'doc/gnutls.texi') diff --git a/doc/gnutls.texi b/doc/gnutls.texi index 333513fee9..2b5ef1fc9b 100644 --- a/doc/gnutls.texi +++ b/doc/gnutls.texi @@ -73,7 +73,6 @@ Documentation License''. @menu * Preface:: -* Obtaining and Installing:: * The Library:: * Introduction to TLS:: * Authentication methods:: @@ -123,13 +122,83 @@ Updated versions of the @acronym{GnuTLS} software and this document will be available from @url{http://www.gnutls.org/} and @url{http://www.gnu.org/software/gnutls/}. -@node Obtaining and Installing -@chapter Obtaining and Installing +@menu +* Getting help:: +* Commercial Support:: +* Downloading and Installing:: +* Bug Reports:: +* Contributing:: +@end menu + +@node Getting help +@section Getting help + +A mailing list where users may help each other exists, and you can +reach it by sending e-mail to @email{help-gnutls@@gnu.org}. Archives +of the mailing list discussions, and an interface to manage +subscriptions, is available through the World Wide Web at +@url{http://lists.gnu.org/mailman/listinfo/help-gnutls}. + +A mailing list for developers are also available, see +@url{http://www.gnu.org/software/gnutls/lists.html}. + +Bug reports should be sent to @email{bug-gnutls@@gnu.org}, see +@xref{Bug Reports}. + +@node Commercial Support +@section Commercial Support + +Commercial support is available for users of GnuTLS. The kind of +support that can be purchased may include: + +@itemize + +@item Implement new features. +Such as a new TLS extension. + +@item Port GnuTLS to new platforms. +This could include porting to an embedded platforms that may need +memory or size optimization. + +@item Integrating TLS as a security environment in your existing project. + +@item System design of components related to TLS. + +@end itemize + +If you are interested, please write to: + +@verbatim +Simon Josefsson Datakonsult +Hagagatan 24 +113 47 Stockholm +Sweden + +E-mail: simon@josefsson.org +@end verbatim + +If your company provide support related to GnuTLS and would like to be +mentioned here, contact the author (@pxref{Bug Reports}). + +@node Downloading and Installing +@section Downloading and Installing +@cindex Installation +@cindex Download GnuTLS is available for download from the following URL: @url{http://www.gnutls.org/download.html} +The latest version is stored in a file, e.g., +@samp{gsasl-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}} +value is the highest version number in the directory. + +GnuTLS uses a Linux-like development cycle: even minor version numbers +indicate a stable release and a odd minor version number indicates a +development release. For example, GnuTLS 1.6.3 denote a stable +release since 6 is even, and GnuTLS 1.7.11 denote a development +release since 7 is odd. + GnuTLS depends on Libgcrypt, and you will need to install Libgcrypt before installing GnuTLS. Libgcrypt is available from @url{ftp://ftp.gnupg.org/gcrypt/libgcrypt}. Libgcrypt needs another @@ -140,9 +209,12 @@ installing Libgcrypt. Libgpg-error is available from Don't forget to verify the cryptographic signature after downloading source code packages. -Compiling GnuTLS should be straight-forward: just unpack the package, -invoke @code{./configure} and then @code{make check install}. There -are a number of compile-time parameters, as discussed below. +The package is then extracted, configured and built like many other +packages that use Autoconf. For detailed information on configuring +and building it, refer to the @file{INSTALL} file that is part of the +distribution archive. Typically you invoke @code{./configure} and +then @code{make check install}. There are a number of compile-time +parameters, as discussed below. The compression libraries (libz and lzo) are optional dependencies. You can get libz from @url{http://www.zlib.net/}. You can get lzo @@ -171,6 +243,121 @@ functionality in GnuTLS. Regarding the Guile bindings, there are additional installation considerations, see @xref{Guile Preparations}. +A few @code{configure} options may be relevant, summarized in the +table. + +@table @code + +@item --disable-srp-authentication +@itemx --disable-psk-authentication +@itemx --disable-anon-authentication +@itemx --disable-tls-authorization +@itemx --disable-extra-pki +@itemx --disable-openpgp-authentication +@itemx --disable-openssl-compatibility +Disable or enable particular features. Generally not recommended. + +@end table + +For the complete list, refer to the output from @code{configure +--help}. + +@node Bug Reports +@section Bug Reports +@cindex Reporting Bugs + +If you think you have found a bug in GnuTLS, please investigate it and +report it. + +@itemize @bullet + +@item Please make sure that the bug is really in GnuTLS, and +preferably also check that it hasn't already been fixed in the latest +version. + +@item You have to send us a test case that makes it possible for us to +reproduce the bug. + +@item You also have to explain what is wrong; if you get a crash, or +if the results printed are not good and in that case, in what way. +Make sure that the bug report includes all information you would need +to fix this kind of bug for someone else. + +@end itemize + +Please make an effort to produce a self-contained report, with +something definite that can be tested or debugged. Vague queries or +piecemeal messages are difficult to act on and don't help the +development effort. + +If your bug report is good, we will do our best to help you to get a +corrected version of the software; if the bug report is poor, we won't +do anything about it (apart from asking you to send better bug +reports). + +If you think something in this manual is unclear, or downright +incorrect, or if the language needs to be improved, please also send a +note. + +Send your bug report to: + +@center @samp{bug-gnutls@@gnu.org} + +@node Contributing +@section Contributing +@cindex Contributing +@cindex Hacking + +If you want to submit a patch for inclusion -- from solve a typo you +discovered, up to adding support for a new feature -- you should +submit it as a bug report (@pxref{Bug Reports}). There are some +things that you can do to increase the chances for it to be included +in the official package. + +Unless your patch is very small (say, under 10 lines) we require that +you assign the copyright of your work to the Free Software Foundation. +This is to protect the freedom of the project. If you have not +already signed papers, we will send you the necessary information when +you submit your contribution. + +For contributions that doesn't consist of actual programming code, the +only guidelines are common sense. Use it. + +For code contributions, a number of style guides will help you: + +@itemize @bullet + +@item Coding Style. +Follow the GNU Standards document (@pxref{top, GNU Coding Standards,, +standards}). + +If you normally code using another coding standard, there is no +problem, but you should use @samp{indent} to reformat the code +(@pxref{top, GNU Indent,, indent}) before submitting your work. + +@item Use the unified diff format @samp{diff -u}. + +@item Return errors. +No reason whatsoever should abort the execution of the library. Even +memory allocation errors, e.g. when malloc return NULL, should work +although result in an error code. + +@item Design with thread safety in mind. +Don't use global variables. Don't even write to per-handle global +variables unless the documented behaviour of the function you write is +to write to the per-handle global variable. + +@item Avoid using the C math library. +It causes problems for embedded implementations, and in most +situations it is very easy to avoid using it. + +@item Document your functions. +Use comments before each function headers, that, if properly +formatted, are extracted into Texinfo manuals and GTK-DOC web pages. + +@item Supply a ChangeLog and NEWS entries, where appropriate. + +@end itemize @node The Library @chapter The Library -- cgit v1.2.1