From 4f538ab32a2d8f0da3f9c68abdd0dc3c27a50859 Mon Sep 17 00:00:00 2001 From: ng0 Date: Mon, 23 Oct 2017 13:06:41 +0000 Subject: doc batch commit --- doc/documentation/Makefile.am | 8 + doc/documentation/chapters/developer.texi | 1389 ++++++++++++++------------ doc/documentation/chapters/installation.texi | 1117 +++++++++++---------- 3 files changed, 1371 insertions(+), 1143 deletions(-) (limited to 'doc') diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am index 21852a9c3..c95728d25 100644 --- a/doc/documentation/Makefile.am +++ b/doc/documentation/Makefile.am @@ -182,6 +182,14 @@ doc-all-install: # @cp -r images $(DESTDIR)/$(infoimagedir) +dev-build: version.texi version2.texi + @makeinfo --pdf gnunet.texi + @makeinfo --pdf gnunet-c-tutorial.texi + @makeinfo --html gnunet.texi + @makeinfo --html gnunet-c-tutorial.texi + @makeinfo --no-split gnunet.texi + @makeinfo --no-split gnunet-c-tutorial.texi + # TODO: Add more to clean. clean: @rm gnunet.pdf diff --git a/doc/documentation/chapters/developer.texi b/doc/documentation/chapters/developer.texi index 81a9a6c1f..f92257292 100644 --- a/doc/documentation/chapters/developer.texi +++ b/doc/documentation/chapters/developer.texi @@ -771,24 +771,27 @@ if (NULL == (value = lookup_function())) @{ error(); return; @} deep(er) nesting. Thus, we would write: @example -next = head; while (NULL != (pos = next)) @{ next = pos->next; if (! -should_free (pos)) continue; GNUNET_CONTAINER_DLL_remove (head, tail, pos); -GNUNET_free (pos); @} +next = head; while (NULL != (pos = next)) @{ + next = pos->next; if (! should_free (pos)) + continue; + GNUNET_CONTAINER_DLL_remove (head, tail, pos); + GNUNET_free (pos); @} @end example - instead of + @example -next = head; while (NULL != (pos = next)) @{ next = -pos->next; if (should_free (pos)) @{ +next = head; while (NULL != (pos = next)) @{ + next = pos->next; if (should_free (pos)) @{ /* unnecessary nesting! */ - GNUNET_CONTAINER_DLL_remove (head, tail, pos); GNUNET_free (pos); @} @} + GNUNET_CONTAINER_DLL_remove (head, tail, pos); + GNUNET_free (pos); @} @} @end example -@item We primarily use @code{for} and @code{while} loops. A @code{while} -loop is used if the method for advancing in the loop is not a -straightforward increment operation. In particular, we use: +@item We primarily use @code{for} and @code{while} loops. +A @code{while} loop is used if the method for advancing in the loop is +not a straightforward increment operation. In particular, we use: @example next = head; @@ -802,7 +805,6 @@ while (NULL != (pos = next)) @} @end example - to free entries in a list (as the iteration changes the structure of the list due to the free; the equivalent @code{for} loop does no longer follow the simple @code{for} paradigm of @code{for(INIT;TEST;INC)}). @@ -889,8 +891,8 @@ If you want to compile and run benchmarks, run configure with the @code{--enable-benchmarks} option. If you want to obtain code coverage results, run configure with the -@code{--enable-coverage} option and run the coverage.sh script in -@file{contrib/}. +@code{--enable-coverage} option and run the @file{coverage.sh} script in +the @file{contrib/} directory. @c *********************************************************************** @node Developing extensions for GNUnet using the gnunet-ext template @@ -905,7 +907,9 @@ development of GNUnet services, command line tools, APIs and tests. First of all you have to obtain gnunet-ext from git: -@code{git clone https://gnunet.org/git/gnunet-ext.git} +@example +git clone https://gnunet.org/git/gnunet-ext.git +@end example The next step is to bootstrap and configure it. For configure you have to provide the path containing GNUnet with @@ -922,7 +926,9 @@ path, you have to add @code{/path/to/gnunet} to the file @file{/etc/ld.so.conf} and run @code{ldconfig} or your add it to the environmental variable @code{LD_LIBRARY_PATH} by using -@code{export LD_LIBRARY_PATH=/path/to/gnunet/lib} +@example +export LD_LIBRARY_PATH=/path/to/gnunet/lib +@end example @c *********************************************************************** @node Writing testcases @@ -942,9 +948,9 @@ progress information and not display debug messages by default. The success or failure of a testcase must be indicated by returning zero (success) or non-zero (failure) from the main method of the testcase. The integration with the autotools is relatively straightforward and only -requires modifications to the @code{Makefile.am} in the directory -containing the testcase. For a testcase testing the code in @code{foo.c} -the @code{Makefile.am} would contain the following lines: +requires modifications to the @file{Makefile.am} in the directory +containing the testcase. For a testcase testing the code in @file{foo.c} +the @file{Makefile.am} would contain the following lines: @example check_PROGRAMS = test_foo TESTS = $(check_PROGRAMS) test_foo_SOURCES = @@ -1122,16 +1128,28 @@ The following code illustrates spawning and killing an ARM process from a testcase: @example -static void run (void *cls, char *const *args, const char -*cfgfile, const struct GNUNET_CONFIGURATION_Handle *cfg) @{ struct -GNUNET_OS_Process *arm_pid; arm_pid = GNUNET_OS_start_process (NULL, NULL, -"gnunet-service-arm", "gnunet-service-arm", "-c", cfgname, NULL); +static void run (void *cls, + char *const *args, + const char *cfgfile, + const struct GNUNET_CONFIGURATION_Handle *cfg) @{ + struct GNUNET_OS_Process *arm_pid; + arm_pid = GNUNET_OS_start_process (NULL, + NULL, + "gnunet-service-arm", + "gnunet-service-arm", + "-c", + cfgname, + NULL); /* do real test work here */ - if (0 != GNUNET_OS_process_kill (arm_pid, SIGTERM)) GNUNET_log_strerror - (GNUNET_ERROR_TYPE_WARNING, "kill"); GNUNET_assert (GNUNET_OK == - GNUNET_OS_process_wait (arm_pid)); GNUNET_OS_process_close (arm_pid); @} - -GNUNET_PROGRAM_run (argc, argv, "NAME-OF-TEST", "nohelp", options, &run, cls); + if (0 != GNUNET_OS_process_kill (arm_pid, SIGTERM)) + GNUNET_log_strerror + (GNUNET_ERROR_TYPE_WARNING, "kill"); + GNUNET_assert (GNUNET_OK == GNUNET_OS_process_wait (arm_pid)); + GNUNET_OS_process_close (arm_pid); @} + +GNUNET_PROGRAM_run (argc, argv, + "NAME-OF-TEST", + "nohelp", options, &run, cls); @end example @@ -1183,8 +1201,11 @@ The code in the test should look like this: int main (int argc, char *argv[]) @{ - [run test, generate data] GAUGER("YOUR_MODULE", "METRIC_NAME", (float)value, - "UNIT"); @} + [run test, generate data] + GAUGER("YOUR_MODULE", + "METRIC_NAME", + (float)value, + "UNIT"); @} @end example @@ -1310,10 +1331,8 @@ found in the standard path. This can be addressed by setting the variable `HELPER_BINARY_PATH' to the path of the testbed helper. Testbed API will then use this path to start helper binaries both locally and remotely. -Testbed API can accessed by including "gnunet_testbed_service.h" file and -linking with -lgnunettestbed. - - +Testbed API can accessed by including the +"@file{gnunet_testbed_service.h}" file and linking with -lgnunettestbed. @c *********************************************************************** @menu @@ -1628,16 +1647,20 @@ Install Distribute for zope.interface <= 3.8.0 (4.0 and 4.0.1 will not work): @example -wget https://pypi.python.org/packages/source/z/zope.interface/zope.interface-3.8.0.tar.gz -tar zvfz zope.interface-3.8.0.tar.gz@ cd zope.interface-3.8.0 +export PYPI="https://pypi.python.org/packages/source" +wget $PYPI/z/zope.interface/zope.interface-3.8.0.tar.gz +tar zvfz zope.interface-3.8.0.tar.gz +cd zope.interface-3.8.0 sudo python setup.py install @end example Install the buildslave software (0.8.6 was the latest version): @example -wget http://buildbot.googlecode.com/files/buildbot-slave-0.8.6p1.tar.gz -tar xvfz buildbot-slave-0.8.6p1.tar.gz@ cd buildslave-0.8.6p1 +export GCODE="http://buildbot.googlecode.com/files" +wget $GCODE/buildbot-slave-0.8.6p1.tar.gz +tar xvfz buildbot-slave-0.8.6p1.tar.gz +cd buildslave-0.8.6p1 sudo python setup.py install @end example @@ -1670,8 +1693,8 @@ contrib/tasklists/install_buildslave_fc8.xml -a -p The master and the and the slaves have need to have credentials and the master has to have all nodes configured. This can be done with the -@code{create_buildbot_configuration.py} script in the @code{scripts} -directory +@file{create_buildbot_configuration.py} script in the @file{scripts} +directory. This scripts takes a list of nodes retrieved directly from PlanetLab or read from a file and a configuration template and creates: @@ -1687,14 +1710,22 @@ that the script replaces the following tags in the template: %GPLMT_BUILDER_DEFINITION :@ GPLMT_BUILDER_SUMMARY@ GPLMT_SLAVES@ %GPLMT_SCHEDULER_BUILDERS -Create configuration for all nodes assigned to a slice:@ @code{@ -./create_buildbot_configuration.py -u -p -s -m -t