From 0c9ffbeba9f19c0bde8ee9c6d3bea04f8867885c Mon Sep 17 00:00:00 2001 From: ng0 Date: Tue, 5 Sep 2017 11:36:23 +0000 Subject: [PATCH] doc: gnunet-c-tutorial: More @file, @code. --- doc/gnunet-c-tutorial.texi | 98 ++++++++++++++++++++------------------ 1 file changed, 52 insertions(+), 46 deletions(-) diff --git a/doc/gnunet-c-tutorial.texi b/doc/gnunet-c-tutorial.texi index b4ed0e786..ba443e674 100644 --- a/doc/gnunet-c-tutorial.texi +++ b/doc/gnunet-c-tutorial.texi @@ -249,16 +249,24 @@ the programmer. @subsection Configure your peer -First of all we need to configure your peer. Each peer is started with a configuration containing settings for GNUnet itself and its services. This configuration is based on the default configuration shipped with GNUnet and can be modified. The default configuration is located in the $PREFIX/share/gnunet/config.d directory. When starting a peer, you can specify a customized configuration using the the $-c$ command line switch when starting the ARM service and all other services. When using a modified configuration the default values are loaded and only values specified in the configuration file will replace the default values. - -Since we want to start additional peers later, we need -some modifications from the default configuration. We need to create a separate service home and a file containing our modifications for this peer: +First of all we need to configure your peer. Each peer is started with a configuration +containing settings for GNUnet itself and its services. This configuration is based on the +default configuration shipped with GNUnet and can be modified. The default configuration +is located in the @file{$PREFIX/share/gnunet/config.d} directory. When starting a peer, you +can specify a customized configuration using the the @command{-c} command line switch when +starting the ARM service and all other services. When using a modified configuration the +default values are loaded and only values specified in the configuration file will replace +the default values. + +Since we want to start additional peers later, we need some modifications from the default +configuration. We need to create a separate service home and a file containing our +modifications for this peer: @example $ mkdir ~/gnunet1/ $ touch peer1.conf @end example -Now add the following lines to peer1.conf to use this directory. For +Now add the following lines to @file{peer1.conf} to use this directory. For simplified usage we want to prevent the peer to connect to the GNUnet network since this could lead to confusing output. This modifications will replace the default settings: @@ -274,11 +282,11 @@ Each GNUnet instance (called peer) has an identity (peer ID) based on a cryptographic public private key pair. The peer ID is the printable hash of the public key. -GNUnet services are controlled by a master service the so called Automatic Restart Manager (ARM). +GNUnet services are controlled by a master service, the so called @dfn{Automatic Restart Manager} (ARM). ARM starts, stops and even restarts services automatically or on demand when a client connects. You interact with the ARM service using the gnunet-arm tool. -GNUnet can then be started with gnunet-arm -s and stopped with -gnunet-arm -e. An additional service not automatically started +GNUnet can then be started with @command{gnunet-arm -s} and stopped with +@command{gnunet-arm -e}. An additional service not automatically started can be started using @command{gnunet-arm -i } and stopped using @command{gnunet-arm -k }. @@ -298,9 +306,9 @@ I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'. In this section, we will monitor the behaviour of our peer's DHT service with respect to a specific key. First we will start GNUnet and then start the DHT service and use the DHT monitor tool -to monitor the PUT and GET commands we issue ussing the gnunet-dht-put and -gnunet-dht-get commands. Using the ``monitor'' line given below, you can observe the behavior of -your own peer's DHT with respect to the specified KEY: +to monitor the PUT and GET commands we issue ussing the @command{gnunet-dht-put} and +@command{gnunet-dht-get} commands. Using the ``monitor'' line given below, you can observe +the behavior of your own peer's DHT with respect to the specified KEY: @example $ gnunet-arm -c ~/peer1.conf -s # start gnunet with all default services @@ -308,7 +316,7 @@ $ gnunet-arm -c ~/peer1.conf -i dht # start DHT service $ cd ~/gnunet/src/dht; $ ./gnunet-dht-monitor -c ~/peer1.conf -k KEY @end example -Now open a separate terminal and change again to the gnunet/src/dht directory: +Now open a separate terminal and change again to the @file{gnunet/src/dht} directory: @example $ cd ~/gnunet/src/dht $ ./gnunet-dht-put -c ~/peer1.conf -k KEY -d VALUE # put VALUE under KEY in the DHT @@ -390,7 +398,7 @@ the first one to be a hostlist server by adding the following lines to OPTIONS = -p @end example -Then change {\tt peer2.conf} and replace the ``@code{SERVERS}'' line in the ``@code{[hostlist]}'' section with +Then change @file{peer2.conf} and replace the ``@code{SERVERS}'' line in the ``@code{[hostlist]}'' section with ``@code{http://localhost:8080/}''. Restart both peers using: @example $ gnunet-arm -c peer1.conf -e # stop first peer @@ -408,13 +416,12 @@ by you. @subsubsection How to connect manually If you want to use the @code{peerinfo} tool to connect your peers, you should: -\begin{itemize} -\itemsep0em - \item{Set {\tt FORCESTART = NO} in section {\tt hostlist} (to not connect to the global GNUnet)} - \item{Start both peers running {\tt gnunet-arm -c peer1.conf -s} and {\tt gnunet-arm -c peer2.conf -s}} - \item{Get @code{HELLO} message of the first peer running {\tt gnunet-peerinfo -c peer1.conf -g}} - \item{Give the output to the second peer by running {\tt gnunet-peerinfo -c peer2.conf -p ''}} -\end{itemize} +@itemize +@item Set @code{FORCESTART = NO} in section @code{hostlist} (to not connect to the global GNUnet) +@item Start both peers running @command{gnunet-arm -c peer1.conf -s} and @command{gnunet-arm -c peer2.conf -s} +@item Get @code{HELLO} message of the first peer running @command{gnunet-peerinfo -c peer1.conf -g} +@item Give the output to the second peer by running @command{gnunet-peerinfo -c peer2.conf -p ''} +@end itemize Check that they are connected using @command{gnunet-core -c peer1.conf}, which should give you the other peer's peer identity: @@ -440,7 +447,7 @@ environment on a single host. This function takes a configuration file which will be used as a template configuration for the peers. The testbed takes care of modifying relevant -options in the peers' configuration such as SERVICEHOME, PORT, UNIXPATH to +options in the peers' configuration such as @code{SERVICEHOME}, @code{PORT}, @code{UNIXPATH} to unique values so that peers run without running into conflicts. It also checks and assigns the ports in configurations only if they are free. @@ -449,7 +456,7 @@ configuration file. Various available options and details about them can be found in the testbed default configuration file @file{src/testbed/testbed.conf}. With the testbed API, a sample test case can be structured as follows: -% Is there a way to pick a more readable font for this include? +@c* Is there a way to pick a more readable font for this include? \lstset{language=C} \lstinputlisting{testbed_test.c} The source code for the above listing can be found at @@ -475,7 +482,7 @@ waiting operations can be executed. Operations will be canceled if they are marked as ``done'' before their completion. An operation is treated as completed when it succeeds or fails. Completion of -an operation is either conveyed as events through \textit{controller event +an operation is either conveyed as events through @i{controller event callback} or through respective operation completion callbacks. In functions which support completion notification through both controller event callback and operation completion callback, first the controller event callback will be @@ -493,13 +500,13 @@ system is discouraged as their locations are dynamically created and will be different among various runs of testbed. To make access to these configurations easy, testbed API provides the function @code{GNUNET\_TESTBED\_service\_connect()}. This function fetches the -configuration of a given peer and calls the \textit{Connect Adapter}. +configuration of a given peer and calls the @i{Connect Adapter}. In the example code, it is the @code{dht\_ca}. A connect adapter is expected to open the connection to the needed service by using the provided configuration and return the created service connection handle. Successful connection to the needed service is signaled through @code{service\_connect\_comp\_cb}. -A dual to connect adapter is the \textit{Disconnect Adapter}. This callback is +A dual to connect adapter is the @i{Disconnect Adapter}. This callback is called after the connect adapter has been called when the operation from @code{GNUNET\_TESTBED\_service\_connect()} is marked as ``done''. It has to disconnect from the service with the provided service handle (@code{op\_result}). @@ -567,11 +574,10 @@ in the @file{gnunet-ext} root. @section Writing a Client Application When writing any client application (for example, a command-line -tool), the basic structure is to start with the {\tt - GNUNET\_PROGRAM\_run} function. This function will parse -command-line options, setup the scheduler and then invoke the {\tt - run} function (with the remaining non-option arguments) and a handle -to the parsed configuration (and the configuration file name that was +tool), the basic structure is to start with the @code{GNUNET\_PROGRAM\_run} +function. This function will parse command-line options, setup the scheduler +and then invoke the @code{run} function (with the remaining non-option arguments) +and a handle to the parsed configuration (and the configuration file name that was used, which is typically not needed): \lstset{language=C} @@ -610,8 +616,8 @@ main (int argc, char *const *argv) Options can then be added easily by adding global variables and expanding the {\tt options} array. For example, the following would -add a string-option and a binary flag (defaulting to {\tt NULL} and -{\tt GNUNET\_NO} respectively): +add a string-option and a binary flag (defaulting to @code{NULL} and +@code{GNUNET\_NO} respectively): \lstset{language=C} \begin{lstlisting} @@ -634,8 +640,8 @@ static int a_flag; @end example Issues such as displaying some helpful text describing options using -the {\tt --help} argument and error handling are taken care of when -using this approach. Other {\tt GNUNET\_GETOPT\_}-functions can be used +the @code{--help} argument and error handling are taken care of when +using this approach. Other @code{GNUNET\_GETOPT\_}-functions can be used to obtain integer value options, increment counters, etc. You can even write custom option parsers for special circumstances not covered by the available handlers. To check if an argument was specified by the @@ -643,14 +649,14 @@ user you initialize the variable with a specific value (e.g. NULL for a string and GNUNET\_SYSERR for a integer) and check after parsing happened if the values were modified. -Inside the {\tt run} method, the program would perform the +Inside the @code{run} method, the program would perform the application-specific logic, which typically involves initializing and using some client library to interact with the service. The client library is supposed to implement the IPC whereas the service provides more persistent P2P functions. Exercise: Add a few command-line options and print them inside -of {\tt run}. What happens if the user gives invalid arguments?} +of @code{run}. What happens if the user gives invalid arguments?} @subsection Writing a Client Library} @@ -664,7 +670,7 @@ Then, a client-service protocol needs to be designed. This typically involves defining various message formats in a header that will be included by both the service and the client library (but is otherwise not shared and hence located within the service's directory and not -installed by {\tt make install}). Each message must start with a {\tt +installed by @command{make install}). Each message must start with a {\tt struct GNUNET\_MessageHeader} and must be shorter than 64k. By convention, all fields in IPC (and P2P) messages must be in big-endian format (and thus should be read using {\tt ntohl} and similar @@ -692,7 +698,7 @@ with the service, a connection must be created: As a result a {\tt GNUNET\_MQ\_Handle} is returned which can to used henceforth to transmit messages to the service. -The complete MQ API can be found in {\tt gnunet\_mq\_lib.h}. +The complete MQ API can be found in @file{gnunet\_mq\_lib.h}. The {\tt hanlders} array in the example above is incomplete. Here is where you will define which messages you expect to receive from the service, and which functions handle them. @@ -880,13 +886,13 @@ client_disconnect_cb (void *cls, Exercise: Write a stub service that processes no messages at all in your code. Create a default configuration for it, integrate it with the build system and start the service from {\tt - gnunet-service-arm} using {\tt gnunet-arm -i NAME}.} + gnunet-service-arm} using @command{gnunet-arm -i NAME}. Exercise: Figure out how to set the closure ({\tt cls}) for handlers - of a service.} + of a service. Exercise: Figure out how to send messages from the service back to the - client.} + client. Each handler function in the service {\bf must} eventually (possibly in some asynchronous continuation) call {\tt GNUNET\_SERVICE\_client\_continue()}. @@ -961,7 +967,7 @@ to not keep a very long queue in memory. Exercise: Start one peer with a new service that has a message handler and start a second peer that only has your ``old'' service without message handlers. Which ``connect'' handlers are invoked when -the two peers are connected? Why?} +the two peers are connected? Why? @subsection Sending P2P Messages @@ -1451,13 +1457,13 @@ restarted service with the peer. GNUnet provides a powerful logging mechanism providing log levels @code{ERROR}, @code{WARNING}, @code{INFO} and @code{DEBUG}. The current log level is -configured using the \lstinline|$GNUNET_FORCE_LOG| environmental variable. -The @code{DEBUG} level is only available if \lstinline|--enable-logging=verbose| was used when -running @code{configure}. More details about logging can be found under +configured using the @code{$GNUNET_FORCE_LOG} environmental variable. +The @code{DEBUG} level is only available if @command{--enable-logging=verbose} was used when +running @command{configure}. More details about logging can be found under @uref{https://gnunet.org/logging}. You should also probably enable the creation of core files, by setting -{\tt ulimit}, and echo'ing 1 into @file{/proc/sys/kernel/core\_uses\_pid}. +@code{ulimit}, and echo'ing 1 into @file{/proc/sys/kernel/core\_uses\_pid}. Then you can investigate the core dumps with @command{gdb}, which is often the fastest method to find simple errors. -- 2.25.1