From d5224cf485343f445dead0516d991d0c5cee644b Mon Sep 17 00:00:00 2001 From: ng0 Date: Wed, 6 Sep 2017 09:30:43 +0000 Subject: [PATCH] doc: gnunet-c-tutorial.texi, chapters/installation.texi: fix compilation warnings. --- doc/chapters/installation.texi | 226 ++++++++++----------------------- doc/gnunet-c-tutorial.texi | 41 +++--- 2 files changed, 87 insertions(+), 180 deletions(-) diff --git a/doc/chapters/installation.texi b/doc/chapters/installation.texi index a04478878..be458981f 100644 --- a/doc/chapters/installation.texi +++ b/doc/chapters/installation.texi @@ -49,21 +49,14 @@ These packages must be installed before a typical GNUnet installation can be performed: @table @asis -@item -GNU libmicrohttpd 0.9.30 or higher -@item -GNU libextractor 1.0 or higher -@item -GNU libtool 2.2 or higher -@item -GNU libunistring 0.9.1.1 or higher -@item -GNU libidn 1.0.0 or higher -@item -@uref{https://gnupg.org/software/libgcrypt/index.html, GNU libgcrypt} +@item GNU libmicrohttpd 0.9.30 or higher +@item GNU libextractor 1.0 or higher +@item GNU libtool 2.2 or higher +@item GNU libunistring 0.9.1.1 or higher +@item GNU libidn 1.0.0 or higher +@item @uref{https://gnupg.org/software/libgcrypt/index.html, GNU libgcrypt} @uref{https://gnupg.org/ftp/gcrypt/libgcrypt/, 1.6.0} or higher -@item -@uref{https://gnutls.org/, GnuTLS} +@item @uref{https://gnutls.org/, GnuTLS} @uref{https://www.gnupg.org/ftp/gcrypt/gnutls/v3.2/, 3.2.7} or higher, compile with libunbound for DANE support; GnuTLS also requires GNU nettle 2.7 (update: GnuTLS 3.2.7 appears NOT to work against GNU nettle @@ -72,41 +65,27 @@ against nettle 2.7 and, in case you get some error on the reference to `rpl_strerror' being undefined, follow the instructions on@ @uref{http://lists.gnupg.org/pipermail/gnutls-devel/2013-November/006588.html, this} post (and the link inside it)). -@item -@uref{https://gnunet.org/gnurl, gnURL} libgnurl 7.34.0 or higher, +@item @uref{https://gnunet.org/gnurl, gnURL} libgnurl 7.34.0 or higher, must be compiled after @code{GnuTLS} -@item -libglpk 4.45 or higher -@item -@uref{http://www.openssl.org/, OpenSSL} (binary) 1.0 or higher -@item -TeX Live 2012 or higher, optional (for gnunet-bcd) -@item -libpulse 2.0 or higher, optional (for gnunet-conversation) -@item -libopus 1.0.1 or higher, optional (for gnunet-conversation) -@item -libogg 1.3.0 or higher, optional (for gnunet-conversation) -@item -certool (binary) +@item libglpk 4.45 or higher +@item @uref{http://www.openssl.org/, OpenSSL} (binary) 1.0 or higher +@item TeX Live 2012 or higher, optional (for gnunet-bcd) +@item libpulse 2.0 or higher, optional (for gnunet-conversation) +@item libopus 1.0.1 or higher, optional (for gnunet-conversation) +@item libogg 1.3.0 or higher, optional (for gnunet-conversation) +@item certool (binary) optional for convenient installation of the GNS proxy (available as part of Debian's libnss3-tools) -@item -python-zbar 0.10 or higher, optional (for gnunet-qr) -@item -libsqlite 3.8.0 or higher (note that the code will compile and often work with lower +@item python-zbar 0.10 or higher, optional (for gnunet-qr) +@item libsqlite 3.8.0 or higher (note that the code will compile and often work with lower version numbers, but you may get subtle bugs with respect to quota management in certain rare cases); alternatively, MySQL or Postgres can also be installed, but those databases will require more complex configurations (not recommended for first-time users) -@item -zlib any version we tested worked -@item -Gtk+ 3.0 or higher, optional (for gnunet-gtk) -@item -libgladeui must match Gtk+ version, optional (for gnunet-gtk) -@item -libqrencode 3.0 or higher, optional (for gnunet-namestore-gtk) +@item zlib any version we tested worked +@item Gtk+ 3.0 or higher, optional (for gnunet-gtk) +@item libgladeui must match Gtk+ version, optional (for gnunet-gtk) +@item libqrencode 3.0 or higher, optional (for gnunet-namestore-gtk) @end table @@ -147,30 +126,18 @@ In terms of internal dependencies, a minimum file-sharing system consists of the following GNUnet processes (in order of dependency): @itemize @bullet -@item -gnunet-service-arm -@item -gnunet-service-resolver (required by all) -@item -gnunet-service-statistics (required by all) -@item -gnunet-service-peerinfo -@item -gnunet-service-transport (requires peerinfo) -@item -gnunet-service-core (requires transport) -@item -gnunet-daemon-hostlist (requires core) -@item -gnunet-daemon-topology (requires hostlist, peerinfo) -@item -gnunet-service-datastore -@item -gnunet-service-dht (requires core) -@item -gnunet-service-identity -@item -gnunet-service-fs (requires identity, mesh, dht, datastore, core) +@item gnunet-service-arm +@item gnunet-service-resolver (required by all) +@item gnunet-service-statistics (required by all) +@item gnunet-service-peerinfo +@item gnunet-service-transport (requires peerinfo) +@item gnunet-service-core (requires transport) +@item gnunet-daemon-hostlist (requires core) +@item gnunet-daemon-topology (requires hostlist, peerinfo) +@item gnunet-service-datastore +@item gnunet-service-dht (requires core) +@item gnunet-service-identity +@item gnunet-service-fs (requires identity, mesh, dht, datastore, core) @end itemize @@ -178,92 +145,39 @@ A minimum VPN system consists of the following GNUnet processes (in order of dependency): @itemize @bullet -@item -gnunet-service-arm - -@item -gnunet-service-resolver (required by all) - -@item -gnunet-service-statistics (required by all) - -@item -gnunet-service-peerinfo - -@item -gnunet-service-transport (requires peerinfo) - -@item -gnunet-service-core (requires transport) - -@item -gnunet-daemon-hostlist (requires core) - -@item -gnunet-service-dht (requires core) - -@item -gnunet-service-mesh (requires dht, core) - -@item -gnunet-service-dns (requires dht) - -@item -gnunet-service-regex (requires dht) - -@item -gnunet-service-vpn (requires regex, dns, mesh, dht) +@item gnunet-service-arm +@item gnunet-service-resolver (required by all) +@item gnunet-service-statistics (required by all) +@item gnunet-service-peerinfo +@item gnunet-service-transport (requires peerinfo) +@item gnunet-service-core (requires transport) +@item gnunet-daemon-hostlist (requires core) +@item gnunet-service-dht (requires core) +@item gnunet-service-mesh (requires dht, core) +@item gnunet-service-dns (requires dht) +@item gnunet-service-regex (requires dht) +@item gnunet-service-vpn (requires regex, dns, mesh, dht) @end itemize A minimum GNS system consists of the following GNUnet processes (in order of dependency): @itemize @bullet - -@item -gnunet-service-arm - -@item -gnunet-service-resolver (required by all) - -@item -gnunet-service-statistics (required by all) - -@item -gnunet-service-peerinfo - -@item -gnunet-service-transport (requires peerinfo) - -@item -gnunet-service-core (requires transport) - -@item -gnunet-daemon-hostlist (requires core) - -@item -gnunet-service-dht (requires core) - -@item -gnunet-service-mesh (requires dht, core) - -@item -gnunet-service-dns (requires dht) - -@item -gnunet-service-regex (requires dht) - -@item -gnunet-service-vpn (requires regex, dns, mesh, dht) - -@item -gnunet-service-identity - -@item -gnunet-service-namestore (requires identity) - -@item -gnunet-service-gns (requires vpn, dns, dht, namestore, identity) +@item gnunet-service-arm +@item gnunet-service-resolver (required by all) +@item gnunet-service-statistics (required by all) +@item gnunet-service-peerinfo +@item gnunet-service-transport (requires peerinfo) +@item gnunet-service-core (requires transport) +@item gnunet-daemon-hostlist (requires core) +@item gnunet-service-dht (requires core) +@item gnunet-service-mesh (requires dht, core) +@item gnunet-service-dns (requires dht) +@item gnunet-service-regex (requires dht) +@item gnunet-service-vpn (requires regex, dns, mesh, dht) +@item gnunet-service-identity +@item gnunet-service-namestore (requires identity) +@item gnunet-service-gns (requires vpn, dns, dht, namestore, identity) @end itemize @node Pre-installation notes @@ -284,21 +198,11 @@ GNU/Linux distribution requires you to install the following dependencies (ideally in this order): @itemize @bullet - -@item -libgpgerror and libgcrypt - -@item -libnettle and libunbound (possibly from distribution), GnuTLS - -@item -libgnurl (read the README) - -@item -GNU libmicrohttpd - -@item -GNU libextractor (make sure to first install the various mandatory and optional +@item libgpgerror and libgcrypt +@item libnettle and libunbound (possibly from distribution), GnuTLS +@item libgnurl (read the README) +@item GNU libmicrohttpd +@item GNU libextractor (make sure to first install the various mandatory and optional dependencies including development headers from your distribution) @end itemize diff --git a/doc/gnunet-c-tutorial.texi b/doc/gnunet-c-tutorial.texi index 3b3e90e4f..824834c92 100644 --- a/doc/gnunet-c-tutorial.texi +++ b/doc/gnunet-c-tutorial.texi @@ -171,7 +171,7 @@ $ export PATH=$PATH:$PREFIX/bin $ echo export PATH=$PREFIX/bin:\\$PATH >> ~/.bashrc $ mkdir ~/.config/ $ touch ~/.config/gnunet.conf -@example +@end example @subsection Common Issues - Check your GNUnet installation @@ -202,21 +202,24 @@ PASS: test_gnunet_prefix ============= 1 test passed ============= -@example - +@end example @section Background: GNUnet Architecture GNUnet is organized in layers and services. Each service is composed of a main service implementation and a client library for other programs to use the service's functionality, described by an API. This approach is shown in -figure~\ref{fig:service}. Some services provide an additional command line -tool to enable the user to interact with the service. +@c** FIXME: enable this once the commented block below works: +@c** figure~\ref{fig:service}. +Some services provide an additional command line tool to enable the user to +interact with the service. Very often it is other GNUnet services that will use these APIs to build the higher layers of GNUnet on top of the lower ones. Each layer expands or extends the functionality of the service below (for instance, to build a mesh on top of -a DHT). See figure ~\ref{fig:interaction} for an illustration of this approach. +a DHT). +@c** FXIME: See comment above. +@c** See figure ~\ref{fig:interaction} for an illustration of this approach. @c \begin{figure}[!h] @c \begin{center} @@ -326,7 +329,7 @@ $ gnunet-statistics -c ~/peer1.conf -s dht # print statistics about DHT service @end example -@subsection Starting Two Peers by Hand} +@subsection Starting Two Peers by Hand This section describes how to start two peers on the same machine by hand. The process is rather painful, but the description is somewhat instructive. @@ -351,7 +354,7 @@ $ cat $PREFIX/share/gnunet/config.d/*.conf > peer2.conf Now you have to edit @file{peer2.conf} and change: @itemize @item @code{GNUNET\_TEST\_HOME} under @code{PATHS} -@tem Every (uncommented) value for ``@code{PORT}'' (add 10000) in any +@item Every (uncommented) value for ``@code{PORT}'' (add 10000) in any section (the option may be commented out if @code{PORT} is prefixed by "\#", in this case, UNIX domain sockets are used and the PORT option does not need to be touched) @@ -580,10 +583,10 @@ used, which is typically not needed): @verbatiminclude tutorial-examples/001.c @end example -@subsection Handling command-line options} +@subsection Handling command-line options Options can then be added easily by adding global variables and -expanding the {\tt options} array. For example, the following would +expanding the @code{options} array. For example, the following would add a string-option and a binary flag (defaulting to @code{NULL} and @code{GNUNET\_NO} respectively): @example @@ -609,7 +612,7 @@ more persistent P2P functions. Exercise: Add a few command-line options and print them inside of @code{run}. What happens if the user gives invalid arguments? -@subsection Writing a Client Library} +@subsection Writing a Client Library The first and most important step in writing a client library is to decide on an API for the library. Typical API calls include @@ -630,7 +633,7 @@ Unique message types must be defined for each message struct in the @file{gnunet\_protocols.h} header (or an extension-specific include file). -@subsubsection Connecting to the Service} +@subsubsection Connecting to the Service Before a client library can implement the application-specific protocol with the service, a connection must be created: @@ -647,7 +650,7 @@ receive from the service, and which functions handle them. The @code{error\_cb} is a function that is to be called whenever there are errors communicating with the service. -@subsubsection Sending messages} +@subsubsection Sending messages In GNUnet, messages are always sent beginning with a @code{struct GNUNET\_MessageHeader} in big endian format. This header defines the size and the type of the @@ -676,7 +679,7 @@ unsigned integer (as payload) to a service using some given client handle. -@subsubsection Receiving Replies from the Service} +@subsubsection Receiving Replies from the Service Clients can receive messages from the service using the handlers specified in the @code{handlers} array we specified when connecting @@ -700,7 +703,7 @@ should call a callback provided to your helper function's API. Exercise: Figure out where you can pass values to the closures (@code{cls}). -@subsection Writing a user interface} +@subsection Writing a user interface Given a client library, all it takes to access a service now is to combine calls to the client library with parsing command-line @@ -725,7 +728,7 @@ the description of the client-service protocol @file{SERVICE.h} and P2P protocol @file{gnunet-service-SERVICE.h} and several files for tests, including test code and configuration files. -@subsection Starting a Service} +@subsection Starting a Service The key API definition for creating a service is the @code{GNUNET\_SERVICE\_MAIN} macro: @example @@ -778,7 +781,7 @@ is connect to the @code{CORE} service using: @verbatiminclude tutorial-examples/009.c @end example -@subsection New P2P connections} +@subsection New P2P connections Before any traffic with a different peer can be exchanged, the peer must be known to the service. This is notified by the @code{CORE} @code{connects} callback, @@ -830,7 +833,7 @@ messages lost? How can you transmit messages faster? What happens if you stop the peer that is receiving your messages? -@subsection End of P2P connections} +@subsection End of P2P connections If a message handler returns @code{GNUNET\_SYSERR}, the remote peer shuts down or there is an unrecoverable network disconnection, CORE notifies the service that @@ -865,7 +868,7 @@ The first step is to start a connection to the PEERSTORE service: The service handle @code{peerstore_handle} will be needed for all subsequent PEERSTORE operations. -@subsection Storing records} +@subsection Storing records To store a new record, use the following function: @example -- 2.25.1