From 7101471b5fc9ad10a0a0c06fb2aaeb5a568dbf56 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 25 Oct 2018 15:46:45 +0200 Subject: doc/documentation split into doc/tutorial and doc/handbook for clarity and to avoid automake freakout --- doc/Makefile.am | 2 +- doc/documentation/.gitignore | 9 - doc/documentation/Makefile.am | 245 - doc/documentation/TODO | 106 - doc/documentation/agpl-3.0.texi | 698 -- doc/documentation/chapters/configuration.texi | 5 - doc/documentation/chapters/contributing.texi | 117 - doc/documentation/chapters/developer.texi | 8817 -------------------- doc/documentation/chapters/installation.texi | 2233 ----- doc/documentation/chapters/keyconcepts.texi | 317 - doc/documentation/chapters/philosophy.texi | 81 - doc/documentation/chapters/preface.texi | 173 - doc/documentation/chapters/user.texi | 2293 ----- doc/documentation/chapters/vocabulary.texi | 72 - doc/documentation/docstyle.css | 76 - doc/documentation/fdl-1.3.texi | 505 -- doc/documentation/gendocs.sh | 504 -- doc/documentation/gendocs_template | 91 - doc/documentation/gendocs_template_min | 93 - doc/documentation/gnunet-c-tutorial.texi | 1559 ---- doc/documentation/gnunet.texi | 247 - doc/documentation/gpl-3.0.texi | 717 -- doc/documentation/htmlxref.cnf | 668 -- doc/documentation/images/daemon_lego_block.png | Bin 7636 -> 0 bytes doc/documentation/images/daemon_lego_block.svg | 126 - doc/documentation/images/gns.dot | 42 - doc/documentation/images/gns.eps | 585 -- doc/documentation/images/gns.jpg | Bin 41765 -> 0 bytes doc/documentation/images/gnunet-0-10-peerinfo.png | Bin 80127 -> 0 bytes .../images/gnunet-fs-gtk-0-10-star-tab.png | Bin 63464 -> 0 bytes .../images/gnunet-gtk-0-10-download-area.png | Bin 7634 -> 0 bytes .../images/gnunet-gtk-0-10-fs-menu.png | Bin 8614 -> 0 bytes .../images/gnunet-gtk-0-10-fs-publish-editing.png | Bin 55507 -> 0 bytes .../images/gnunet-gtk-0-10-fs-publish-select.png | Bin 43448 -> 0 bytes .../gnunet-gtk-0-10-fs-publish-with-file.png | Bin 27371 -> 0 bytes .../gnunet-gtk-0-10-fs-publish-with-file_0.png | Bin 27371 -> 0 bytes .../images/gnunet-gtk-0-10-fs-publish.png | Bin 26496 -> 0 bytes .../images/gnunet-gtk-0-10-fs-published.png | Bin 59635 -> 0 bytes .../images/gnunet-gtk-0-10-fs-search.png | Bin 72151 -> 0 bytes doc/documentation/images/gnunet-gtk-0-10-fs.png | Bin 55706 -> 0 bytes .../images/gnunet-gtk-0-10-gns-a-done.png | Bin 30880 -> 0 bytes doc/documentation/images/gnunet-gtk-0-10-gns-a.png | Bin 29895 -> 0 bytes doc/documentation/images/gnunet-gtk-0-10-gns.png | Bin 63783 -> 0 bytes .../images/gnunet-gtk-0-10-identity.png | Bin 62404 -> 0 bytes .../images/gnunet-gtk-0-10-search-selected.png | Bin 104599 -> 0 bytes .../images/gnunet-gtk-0-10-traffic.png | Bin 68515 -> 0 bytes .../images/gnunet-namestore-gtk-phone.png | Bin 32631 -> 0 bytes .../images/gnunet-namestore-gtk-vpn.png | Bin 35836 -> 0 bytes doc/documentation/images/gnunet-setup-exit.png | Bin 30062 -> 0 bytes .../images/gnunet-tutorial-service.png | Bin 40142 -> 0 bytes .../images/gnunet-tutorial-system.png | Bin 46982 -> 0 bytes doc/documentation/images/iceweasel-preferences.png | Bin 57047 -> 0 bytes doc/documentation/images/iceweasel-proxy.png | Bin 38773 -> 0 bytes doc/documentation/images/lego_stack.svg | 737 -- doc/documentation/images/service_lego_block.png | Bin 15157 -> 0 bytes doc/documentation/images/service_lego_block.svg | 345 - doc/documentation/images/service_stack.png | Bin 18862 -> 0 bytes doc/documentation/images/structure.dot | 124 - doc/documentation/index.html | 58 - doc/documentation/run-gendocs.sh | 18 - doc/documentation/testbed_test.c | 99 - doc/documentation/tutorial-examples/001.c | 29 - doc/documentation/tutorial-examples/002.c | 17 - doc/documentation/tutorial-examples/003.c | 11 - doc/documentation/tutorial-examples/004.c | 5 - doc/documentation/tutorial-examples/005.c | 9 - doc/documentation/tutorial-examples/006.c | 31 - doc/documentation/tutorial-examples/007.c | 10 - doc/documentation/tutorial-examples/008.c | 22 - doc/documentation/tutorial-examples/009.c | 9 - doc/documentation/tutorial-examples/010.c | 8 - doc/documentation/tutorial-examples/011.c | 8 - doc/documentation/tutorial-examples/012.c | 4 - doc/documentation/tutorial-examples/013.1.c | 3 - doc/documentation/tutorial-examples/013.c | 12 - doc/documentation/tutorial-examples/014.c | 9 - doc/documentation/tutorial-examples/015.c | 8 - doc/documentation/tutorial-examples/016.c | 4 - doc/documentation/tutorial-examples/017.c | 4 - doc/documentation/tutorial-examples/018.c | 2 - doc/documentation/tutorial-examples/019.c | 18 - doc/documentation/tutorial-examples/020.c | 25 - doc/documentation/tutorial-examples/021.c | 13 - doc/documentation/tutorial-examples/022.c | 8 - doc/documentation/tutorial-examples/023.c | 17 - doc/documentation/tutorial-examples/024.c | 9 - .../tutorial-examples/025.Makefile.am | 15 - doc/documentation/tutorial-examples/026.c | 52 - doc/handbook/.gitignore | 9 + doc/handbook/Makefile.am | 201 + doc/handbook/TODO | 106 + doc/handbook/agpl-3.0.texi | 698 ++ doc/handbook/chapters/configuration.texi | 5 + doc/handbook/chapters/contributing.texi | 117 + doc/handbook/chapters/developer.texi | 8817 ++++++++++++++++++++ doc/handbook/chapters/installation.texi | 2233 +++++ doc/handbook/chapters/keyconcepts.texi | 317 + doc/handbook/chapters/philosophy.texi | 81 + doc/handbook/chapters/preface.texi | 173 + doc/handbook/chapters/user.texi | 2293 +++++ doc/handbook/chapters/vocabulary.texi | 72 + doc/handbook/docstyle.css | 76 + doc/handbook/fdl-1.3.texi | 505 ++ doc/handbook/gendocs.sh | 504 ++ doc/handbook/gendocs_template | 91 + doc/handbook/gendocs_template_min | 93 + doc/handbook/gnunet.texi | 247 + doc/handbook/gpl-3.0.texi | 717 ++ doc/handbook/htmlxref.cnf | 668 ++ doc/handbook/images/daemon_lego_block.png | Bin 0 -> 7636 bytes doc/handbook/images/daemon_lego_block.svg | 126 + doc/handbook/images/gns.dot | 42 + doc/handbook/images/gns.eps | 585 ++ doc/handbook/images/gns.jpg | Bin 0 -> 41765 bytes doc/handbook/images/gnunet-0-10-peerinfo.png | Bin 0 -> 80127 bytes .../images/gnunet-fs-gtk-0-10-star-tab.png | Bin 0 -> 63464 bytes .../images/gnunet-gtk-0-10-download-area.png | Bin 0 -> 7634 bytes doc/handbook/images/gnunet-gtk-0-10-fs-menu.png | Bin 0 -> 8614 bytes .../images/gnunet-gtk-0-10-fs-publish-editing.png | Bin 0 -> 55507 bytes .../images/gnunet-gtk-0-10-fs-publish-select.png | Bin 0 -> 43448 bytes .../gnunet-gtk-0-10-fs-publish-with-file.png | Bin 0 -> 27371 bytes .../gnunet-gtk-0-10-fs-publish-with-file_0.png | Bin 0 -> 27371 bytes doc/handbook/images/gnunet-gtk-0-10-fs-publish.png | Bin 0 -> 26496 bytes .../images/gnunet-gtk-0-10-fs-published.png | Bin 0 -> 59635 bytes doc/handbook/images/gnunet-gtk-0-10-fs-search.png | Bin 0 -> 72151 bytes doc/handbook/images/gnunet-gtk-0-10-fs.png | Bin 0 -> 55706 bytes doc/handbook/images/gnunet-gtk-0-10-gns-a-done.png | Bin 0 -> 30880 bytes doc/handbook/images/gnunet-gtk-0-10-gns-a.png | Bin 0 -> 29895 bytes doc/handbook/images/gnunet-gtk-0-10-gns.png | Bin 0 -> 63783 bytes doc/handbook/images/gnunet-gtk-0-10-identity.png | Bin 0 -> 62404 bytes .../images/gnunet-gtk-0-10-search-selected.png | Bin 0 -> 104599 bytes doc/handbook/images/gnunet-gtk-0-10-traffic.png | Bin 0 -> 68515 bytes doc/handbook/images/gnunet-namestore-gtk-phone.png | Bin 0 -> 32631 bytes doc/handbook/images/gnunet-namestore-gtk-vpn.png | Bin 0 -> 35836 bytes doc/handbook/images/gnunet-setup-exit.png | Bin 0 -> 30062 bytes doc/handbook/images/gnunet-tutorial-service.png | Bin 0 -> 40142 bytes doc/handbook/images/gnunet-tutorial-system.png | Bin 0 -> 46982 bytes doc/handbook/images/iceweasel-preferences.png | Bin 0 -> 57047 bytes doc/handbook/images/iceweasel-proxy.png | Bin 0 -> 38773 bytes doc/handbook/images/lego_stack.svg | 737 ++ doc/handbook/images/service_lego_block.png | Bin 0 -> 15157 bytes doc/handbook/images/service_lego_block.svg | 345 + doc/handbook/images/service_stack.png | Bin 0 -> 18862 bytes doc/handbook/images/structure.dot | 124 + doc/handbook/index.html | 58 + doc/handbook/run-gendocs.sh | 18 + doc/tutorial/Makefile.am | 145 + doc/tutorial/examples/001.c | 29 + doc/tutorial/examples/002.c | 17 + doc/tutorial/examples/003.c | 11 + doc/tutorial/examples/004.c | 5 + doc/tutorial/examples/005.c | 9 + doc/tutorial/examples/006.c | 31 + doc/tutorial/examples/007.c | 10 + doc/tutorial/examples/008.c | 22 + doc/tutorial/examples/009.c | 9 + doc/tutorial/examples/010.c | 8 + doc/tutorial/examples/011.c | 8 + doc/tutorial/examples/012.c | 4 + doc/tutorial/examples/013.1.c | 3 + doc/tutorial/examples/013.c | 12 + doc/tutorial/examples/014.c | 9 + doc/tutorial/examples/015.c | 8 + doc/tutorial/examples/016.c | 4 + doc/tutorial/examples/017.c | 4 + doc/tutorial/examples/018.c | 2 + doc/tutorial/examples/019.c | 18 + doc/tutorial/examples/020.c | 25 + doc/tutorial/examples/021.c | 13 + doc/tutorial/examples/022.c | 8 + doc/tutorial/examples/023.c | 17 + doc/tutorial/examples/024.c | 9 + doc/tutorial/examples/025.Makefile.am | 15 + doc/tutorial/examples/026.c | 52 + doc/tutorial/examples/testbed_test.c | 99 + doc/tutorial/fdl-1.3.texi | 505 ++ doc/tutorial/gnunet-tutorial.texi | 1568 ++++ 177 files changed, 22738 insertions(+), 22123 deletions(-) delete mode 100644 doc/documentation/.gitignore delete mode 100644 doc/documentation/Makefile.am delete mode 100644 doc/documentation/TODO delete mode 100644 doc/documentation/agpl-3.0.texi delete mode 100644 doc/documentation/chapters/configuration.texi delete mode 100644 doc/documentation/chapters/contributing.texi delete mode 100644 doc/documentation/chapters/developer.texi delete mode 100644 doc/documentation/chapters/installation.texi delete mode 100644 doc/documentation/chapters/keyconcepts.texi delete mode 100644 doc/documentation/chapters/philosophy.texi delete mode 100644 doc/documentation/chapters/preface.texi delete mode 100644 doc/documentation/chapters/user.texi delete mode 100644 doc/documentation/chapters/vocabulary.texi delete mode 100644 doc/documentation/docstyle.css delete mode 100644 doc/documentation/fdl-1.3.texi delete mode 100755 doc/documentation/gendocs.sh delete mode 100644 doc/documentation/gendocs_template delete mode 100644 doc/documentation/gendocs_template_min delete mode 100644 doc/documentation/gnunet-c-tutorial.texi delete mode 100644 doc/documentation/gnunet.texi delete mode 100644 doc/documentation/gpl-3.0.texi delete mode 100644 doc/documentation/htmlxref.cnf delete mode 100644 doc/documentation/images/daemon_lego_block.png delete mode 100644 doc/documentation/images/daemon_lego_block.svg delete mode 100644 doc/documentation/images/gns.dot delete mode 100644 doc/documentation/images/gns.eps delete mode 100644 doc/documentation/images/gns.jpg delete mode 100644 doc/documentation/images/gnunet-0-10-peerinfo.png delete mode 100644 doc/documentation/images/gnunet-fs-gtk-0-10-star-tab.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-download-area.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-fs-menu.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-fs-publish-editing.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-fs-publish-select.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-fs-publish-with-file.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-fs-publish-with-file_0.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-fs-publish.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-fs-published.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-fs-search.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-fs.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-gns-a-done.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-gns-a.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-gns.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-identity.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-search-selected.png delete mode 100644 doc/documentation/images/gnunet-gtk-0-10-traffic.png delete mode 100644 doc/documentation/images/gnunet-namestore-gtk-phone.png delete mode 100644 doc/documentation/images/gnunet-namestore-gtk-vpn.png delete mode 100644 doc/documentation/images/gnunet-setup-exit.png delete mode 100644 doc/documentation/images/gnunet-tutorial-service.png delete mode 100644 doc/documentation/images/gnunet-tutorial-system.png delete mode 100644 doc/documentation/images/iceweasel-preferences.png delete mode 100644 doc/documentation/images/iceweasel-proxy.png delete mode 100644 doc/documentation/images/lego_stack.svg delete mode 100644 doc/documentation/images/service_lego_block.png delete mode 100644 doc/documentation/images/service_lego_block.svg delete mode 100644 doc/documentation/images/service_stack.png delete mode 100644 doc/documentation/images/structure.dot delete mode 100644 doc/documentation/index.html delete mode 100755 doc/documentation/run-gendocs.sh delete mode 100644 doc/documentation/testbed_test.c delete mode 100644 doc/documentation/tutorial-examples/001.c delete mode 100644 doc/documentation/tutorial-examples/002.c delete mode 100644 doc/documentation/tutorial-examples/003.c delete mode 100644 doc/documentation/tutorial-examples/004.c delete mode 100644 doc/documentation/tutorial-examples/005.c delete mode 100644 doc/documentation/tutorial-examples/006.c delete mode 100644 doc/documentation/tutorial-examples/007.c delete mode 100644 doc/documentation/tutorial-examples/008.c delete mode 100644 doc/documentation/tutorial-examples/009.c delete mode 100644 doc/documentation/tutorial-examples/010.c delete mode 100644 doc/documentation/tutorial-examples/011.c delete mode 100644 doc/documentation/tutorial-examples/012.c delete mode 100644 doc/documentation/tutorial-examples/013.1.c delete mode 100644 doc/documentation/tutorial-examples/013.c delete mode 100644 doc/documentation/tutorial-examples/014.c delete mode 100644 doc/documentation/tutorial-examples/015.c delete mode 100644 doc/documentation/tutorial-examples/016.c delete mode 100644 doc/documentation/tutorial-examples/017.c delete mode 100644 doc/documentation/tutorial-examples/018.c delete mode 100644 doc/documentation/tutorial-examples/019.c delete mode 100644 doc/documentation/tutorial-examples/020.c delete mode 100644 doc/documentation/tutorial-examples/021.c delete mode 100644 doc/documentation/tutorial-examples/022.c delete mode 100644 doc/documentation/tutorial-examples/023.c delete mode 100644 doc/documentation/tutorial-examples/024.c delete mode 100644 doc/documentation/tutorial-examples/025.Makefile.am delete mode 100644 doc/documentation/tutorial-examples/026.c create mode 100644 doc/handbook/.gitignore create mode 100644 doc/handbook/Makefile.am create mode 100644 doc/handbook/TODO create mode 100644 doc/handbook/agpl-3.0.texi create mode 100644 doc/handbook/chapters/configuration.texi create mode 100644 doc/handbook/chapters/contributing.texi create mode 100644 doc/handbook/chapters/developer.texi create mode 100644 doc/handbook/chapters/installation.texi create mode 100644 doc/handbook/chapters/keyconcepts.texi create mode 100644 doc/handbook/chapters/philosophy.texi create mode 100644 doc/handbook/chapters/preface.texi create mode 100644 doc/handbook/chapters/user.texi create mode 100644 doc/handbook/chapters/vocabulary.texi create mode 100644 doc/handbook/docstyle.css create mode 100644 doc/handbook/fdl-1.3.texi create mode 100755 doc/handbook/gendocs.sh create mode 100644 doc/handbook/gendocs_template create mode 100644 doc/handbook/gendocs_template_min create mode 100644 doc/handbook/gnunet.texi create mode 100644 doc/handbook/gpl-3.0.texi create mode 100644 doc/handbook/htmlxref.cnf create mode 100644 doc/handbook/images/daemon_lego_block.png create mode 100644 doc/handbook/images/daemon_lego_block.svg create mode 100644 doc/handbook/images/gns.dot create mode 100644 doc/handbook/images/gns.eps create mode 100644 doc/handbook/images/gns.jpg create mode 100644 doc/handbook/images/gnunet-0-10-peerinfo.png create mode 100644 doc/handbook/images/gnunet-fs-gtk-0-10-star-tab.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-download-area.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-fs-menu.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-fs-publish-editing.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-fs-publish-select.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-fs-publish-with-file.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-fs-publish-with-file_0.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-fs-publish.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-fs-published.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-fs-search.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-fs.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-gns-a-done.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-gns-a.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-gns.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-identity.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-search-selected.png create mode 100644 doc/handbook/images/gnunet-gtk-0-10-traffic.png create mode 100644 doc/handbook/images/gnunet-namestore-gtk-phone.png create mode 100644 doc/handbook/images/gnunet-namestore-gtk-vpn.png create mode 100644 doc/handbook/images/gnunet-setup-exit.png create mode 100644 doc/handbook/images/gnunet-tutorial-service.png create mode 100644 doc/handbook/images/gnunet-tutorial-system.png create mode 100644 doc/handbook/images/iceweasel-preferences.png create mode 100644 doc/handbook/images/iceweasel-proxy.png create mode 100644 doc/handbook/images/lego_stack.svg create mode 100644 doc/handbook/images/service_lego_block.png create mode 100644 doc/handbook/images/service_lego_block.svg create mode 100644 doc/handbook/images/service_stack.png create mode 100644 doc/handbook/images/structure.dot create mode 100644 doc/handbook/index.html create mode 100755 doc/handbook/run-gendocs.sh create mode 100644 doc/tutorial/Makefile.am create mode 100644 doc/tutorial/examples/001.c create mode 100644 doc/tutorial/examples/002.c create mode 100644 doc/tutorial/examples/003.c create mode 100644 doc/tutorial/examples/004.c create mode 100644 doc/tutorial/examples/005.c create mode 100644 doc/tutorial/examples/006.c create mode 100644 doc/tutorial/examples/007.c create mode 100644 doc/tutorial/examples/008.c create mode 100644 doc/tutorial/examples/009.c create mode 100644 doc/tutorial/examples/010.c create mode 100644 doc/tutorial/examples/011.c create mode 100644 doc/tutorial/examples/012.c create mode 100644 doc/tutorial/examples/013.1.c create mode 100644 doc/tutorial/examples/013.c create mode 100644 doc/tutorial/examples/014.c create mode 100644 doc/tutorial/examples/015.c create mode 100644 doc/tutorial/examples/016.c create mode 100644 doc/tutorial/examples/017.c create mode 100644 doc/tutorial/examples/018.c create mode 100644 doc/tutorial/examples/019.c create mode 100644 doc/tutorial/examples/020.c create mode 100644 doc/tutorial/examples/021.c create mode 100644 doc/tutorial/examples/022.c create mode 100644 doc/tutorial/examples/023.c create mode 100644 doc/tutorial/examples/024.c create mode 100644 doc/tutorial/examples/025.Makefile.am create mode 100644 doc/tutorial/examples/026.c create mode 100644 doc/tutorial/examples/testbed_test.c create mode 100644 doc/tutorial/fdl-1.3.texi create mode 100644 doc/tutorial/gnunet-tutorial.texi (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index f60bde084..4443b42f8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,6 @@ # This Makefile.am is in the public domain if DOCUMENTATION - SUBDIRS = man doxygen documentation + SUBDIRS = man doxygen handbook tutorial endif if !DOCUMENTATION SUBDIRS = man doxygen diff --git a/doc/documentation/.gitignore b/doc/documentation/.gitignore deleted file mode 100644 index f490c3412..000000000 --- a/doc/documentation/.gitignore +++ /dev/null @@ -1,9 +0,0 @@ -stamp-1 -version2.texi -manual -*.fn -*.fns -*.ky -*.pg -*.tp -*.vr diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am deleted file mode 100644 index cd3fca854..000000000 --- a/doc/documentation/Makefile.am +++ /dev/null @@ -1,245 +0,0 @@ -# This Makefile.am is in the public domain -docdir = $(datadir)/doc/gnunet/ - -infoimagedir = $(infodir)/images - -#DOT_FILES = images/$(wildcard *.dot) - -#DOT_VECTOR_GRAPHICS = \ -# $(DOT_FILES:%.dot=%.eps) \ -# $(DOT_FILES:%.dot=%.pdf) - -AM_MAKEINFOHTMLFLAGS = --no-split --css-ref=docstyle.css - -dist_infoimage_DATA = \ - images/gnunet-gtk-0-10-gns-a-done.png \ - images/gnunet-gtk-0-10-gns-a.png \ - images/daemon_lego_block.png \ - images/gnunet-gtk-0-10-gns.png \ - images/gnunet-0-10-peerinfo.png \ - images/gnunet-gtk-0-10-identity.png \ - images/gnunet-fs-gtk-0-10-star-tab.png \ - images/gnunet-gtk-0-10-download-area.png \ - images/gnunet-gtk-0-10-search-selected.png \ - images/gnunet-gtk-0-10-fs-menu.png \ - images/gnunet-gtk-0-10-traffic.png \ - images/gnunet-gtk-0-10-fs.png \ - images/gnunet-namestore-gtk-phone.png \ - images/gnunet-gtk-0-10-fs-publish-editing.png \ - images/gnunet-namestore-gtk-vpn.png \ - images/gnunet-gtk-0-10-fs-published.png \ - images/gnunet-setup-exit.png \ - images/gnunet-gtk-0-10-fs-publish.png \ - images/iceweasel-preferences.png \ - images/gnunet-gtk-0-10-fs-publish-select.png \ - images/iceweasel-proxy.png \ - images/gnunet-gtk-0-10-fs-publish-with-file_0.png \ - images/service_lego_block.png \ - images/gnunet-gtk-0-10-fs-publish-with-file.png \ - images/service_stack.png \ - images/gnunet-gtk-0-10-fs-search.png \ - images/gnunet-tutorial-service.png \ - images/gnunet-tutorial-system.png \ - images/daemon_lego_block.svg \ - images/lego_stack.svg \ - images/service_lego_block.svg \ - images/structure.dot \ - images/gns.dot - -# images/$(wildcard *.png) \ -# images/$(wildcard *.svg) -# $(DOT_FILES:%.dot=%.png) - -#DOT_OPTIONS = \ -# -Gratio=.9 -Gnodesep=.005 -Granksep=.00005 \ -# -Nfontsite=9 -Nheight=.1 -Nwidth=.1 - -# .dot.png: -# $(AM_V_DOT)$(DOT) -Tpng $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \ -# mv "$(srcdir)/$@.tmp" "$(srcdir)/$@" - -# .dot.pdf: -# $(AM_V_DOT)$(DOT) -Tpdf $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \ -# mv "$(srcdir)/$@.tmp" "$(srcdir)/$@" - -# .dot.eps: -# $(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \ -# mv "$(srcdir)/$@.tmp" "$(srcdir)/$@" - -# .png.eps: -# $(AM_V_GEN)convert "$<" "$@-tmp.eps"; \ -# mv "$@-tmp.eps" "$@" - -# pdf-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.pdf) -# info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png) -# ps-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps) \ -# $(top_srcdir)/%D%/images/coreutils-size-map.eps -# dvi-local: ps-local - - -gnunet_tutorial_examples = \ - tutorial-examples/001.c \ - tutorial-examples/002.c \ - tutorial-examples/003.c \ - tutorial-examples/004.c \ - tutorial-examples/005.c \ - tutorial-examples/006.c \ - tutorial-examples/007.c \ - tutorial-examples/008.c \ - tutorial-examples/009.c \ - tutorial-examples/010.c \ - tutorial-examples/011.c \ - tutorial-examples/012.c \ - tutorial-examples/013.c \ - tutorial-examples/013.1.c \ - tutorial-examples/014.c \ - tutorial-examples/015.c \ - tutorial-examples/016.c \ - tutorial-examples/017.c \ - tutorial-examples/018.c \ - tutorial-examples/019.c \ - tutorial-examples/020.c \ - tutorial-examples/021.c \ - tutorial-examples/022.c \ - tutorial-examples/023.c \ - tutorial-examples/024.c \ - tutorial-examples/025.Makefile.am \ - tutorial-examples/026.c - -info_TEXINFOS = \ - gnunet.texi \ - gnunet-c-tutorial.texi - -gnunet_TEXINFOS = \ - chapters/developer.texi \ - chapters/preface.texi \ - chapters/philosophy.texi \ - chapters/installation.texi \ - chapters/user.texi \ - chapters/vocabulary.texi \ - chapters/configuration.texi \ - chapters/contributing.texi \ - fdl-1.3.texi \ - gpl-3.0.texi - -EXTRA_DIST = \ - $(gnunet_TEXINFOS) \ - $(gnunet_tutorial_examples) \ - htmlxref.cnf \ - gversion.texi - run-gendocs.sh \ - docstyle.css - - -# $(DOT_FILES) \ -# $(DOT_VECTOR_GRAPHICS) - -DISTCLEANFILES = \ - gnunet.cps \ - gnunet-c-tutorial.cps \ - chapters/developer.cps \ - chapters/installation.cps \ - chapter/philosophy.cps \ - chapters/user.cps \ - chapters/configuration.cps \ - chapters/terminology.cps \ - chapters/vocabulary.cps \ - fdl-1.3.cps \ - agpl-3.0.cps \ - gpl-3.0.cps - -# if HAVE_EXTENDED_DOCUMENTATION_BUILDING -daemon_lego_block.png: images/daemon_lego_block.svg - convert images/daemon_lego_block.svg images/daemon_lego_block.png && - pngcrush images/daemon_lego_block.png images/daemon_lego_block.png - -service_lego_block.png: images/service_lego_block.svg - convert images/service_lego_block.svg images/service_lego_block.png && - pngcrush images/service_lego_block.png images/serivce_lego_block.png - -lego_stack.png: images/lego_stack.svg - convert images/lego_stack.svg images/lego_stack.png && - pngcrush images/lego_stack.png images/lego_stack.png - -# XXX: is this sed invocation portable enough? otherwise try tr(1). -version.texi/replacement: version.texi/replacement/revert - @sed -i "s/GPACKAGE_VERSION/$(PACKAGE_VERSION)/g" gversion.texi - -version.texi/replacement/revert: - @echo "@set VERSION GPACKAGE_VERSION" > gversion.texi - @echo "@set EDITION GPACKAGE_VERSION" >> gversion.texi - -if SECTION7 -gnunet-c-tutorial.7: version.texi/replacement - @echo Attempting to output an mdoc formatted section 7 document - @texi2mdoc -I$(pwd):$(pwd)/chapters gnunet-c-tutorial.texi > ../man/gnunet-c-tutorial.7 - -gnunet-documentation.7: version.texi/replacement - @echo Attempting to output an mdoc formatted section 7 document - @texi2mdoc -I$(pwd):$(pwd)/chapters gnunet.texi > ../man/gnunet-documentation.7 - -# TODO: (Maybe) other outputs resulting from this. -endif - -# FIXME: rm *.html and *.pdf -#doc-clean: -# @rm *.aux *.log *.toc *.cp *.cps - -all: version.texi/replacement - -doc-all-install: - @mkdir -p $(DESTDIR)/$(docdir) - @mkdir -p $(DESTDIR)/$(infoimagedir) - @mkdir -p $(DESTDIR)/$(infodir) - @install -m 0755 gnunet.pdf $(DESTDIR)/$(docdir) - @install -m 0755 gnunet-c-tutorial.pdf $(DESTDIR)/$(docdir) - @install -m 0755 gnunet-c-tutorial.info $(DESTDIR)/$(infodir) - @install -m 0755 gnunet.info $(DESTDIR)/$(infodir) - @install gnunet.html $(DESTDIR)/$(docdir) - @install gnunet-c-tutorial.html $(DESTDIR)/$(docdir) - -doc-gendoc-install: - @mkdir -p $(DESTDIR)/$(docdir) - @cp -r manual $(DESTDIR)/$(docdir) - -# @cp -r images $(DESTDIR)/$(infoimagedir) - -dev-build: version.texi/replacement - @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: version.texi/replacement/revert - @rm -f gnunet.pdf - @rm -f gnunet.html - @rm -f gnunet.info - @rm -f gnunet.info-1 - @rm -f gnunet.info-2 - @rm -f gnunet.info-3 - @rm -f gnunet-c-tutorial.pdf - @rm -f gnunet-c-tutorial.info - @rm -f gnunet-c-tutorial.html - @rm -fr gnunet.t2p - @rm -fr gnunet-c-tutorial.t2p - @rm -fr manual - -# CLEANFILES = \ -# gnunet.log \ -# gnunet-c-tutorial.log \ -# $(wildcard *.aux) \ -# $(wildcard *.toc) \ -# $(wildcard *.cp) \ -# $(wildcard *.cps) - -#.PHONY: version.texi -# if HAVE_EXTENDED_DOCUMENTATION_BUILDING_PDF - -# if HAVE_EXTENDED_DOCUMENTATION_BUILDING_HTML - -# endif -# endif -# endif diff --git a/doc/documentation/TODO b/doc/documentation/TODO deleted file mode 100644 index fa1ce7a23..000000000 --- a/doc/documentation/TODO +++ /dev/null @@ -1,106 +0,0 @@ --*- mode: org -*- - -TODO - or: the Documentation Masterplan. - -To some extent this duplicates the Mantis tickets on this topic. - -* Motivation -My motivation is to read into good documentations and create a self-contained collection of books, -which can be understood without expecting too much background knowledge in every topic. -** User Handbook: -The content of the User book should be mostly concerned with our current and future graphical (gtk -as well as terminal user interface) applications. After reading Preface and maybe Philosophy, the -person reading the User Handbook should understand with the least possible strugle the application -they intend to use. Examples should be given and concepts explained. -** Installation Handbook: -As seen with requests on the mailinglist, we will have to pick up people where they are, similar -to the User Handbook. People already used to compiling and installing should have the chance to -skip to the end, everyone else should: have step-by-step instructions, which will either already -include OS specific notes or will be followed by OS specific instructions. It is up for discussion -if configuring GNUnet is 'User Handbook' or 'Installation Handbook', the current mixture in -the Installation Handbook is not good. -** Contributors Handbook: -This chapter could either be reduced to a couple of sections following the theme of 'contributing -to GNUnet' or the chapter could be extended. If we extend it, we should explain a range of topics -that can be useful for contributors. It can be understood as a recommended reading in addition to -the Developer Handbook then, and the Developer Handbook could simply become a better commented -reference for the code-base. -** Developer Handbook: -As outlined in the last sentences, the Developer Handbook could be reduced to the necessary bits -with enough comments to be understood without reading into the papers published over the years. - - -* DONE 1. Drupal books export to LaTeX. -* DONE 2. LaTeX conversion to Texinfo. -* DONE 3. (initial) Fixup of syntax errors introduced in conversion chain. -* TODO 4. Update content. -* TODO 5. Create API Reference or similar -* TODO 6. Create Concept Index -* TODO 7. Create Procedure Index -* TODO 8. Create Type Index -* TODO 9. Create Functions Index -* TODO 10. Properly address concerns and criticism people had/have on the old and current documentation. -* TODO 11. Reorder structure -* TODO more TODO. - - -* Status Progress / Completion Levels - -** chapters/philosophy: around 100% fixed after initial export. - -* System Integration Tasks - -* Which Texlive modules are needed for every output we generate? -* Generate the images from their dot sources. - -* How to use (hack) on this - -This section will find its way into the documentation sooner or later. -Potentially outdated or inaccurate bits. - -** with guix - -Adjust accordingly, ie read the Guix Documentation: -guix environment gnunet-doc -and -guix build -f contrib/packages/guix/gnunet-doc.scm - -** without guix - -You need to have Texinfo and Texlive in your path. -sh bootstrap -./configure --enable-documentation -cd doc -make (format you want) - -for example: make html, make info, make pdf - -* structure (relations) (old!) - -** gnunet.texi - -> chapters/developer.texi - -> chapters/installation.texi - -> chapters/philosophy.texi - -> chapters/user.texi - -> chapters/vocabulary.texi - -> images/* - -> gpl-3.0.texi - -> fdl-1.3.texi - -** gnunet-c-tutorial.texi - -> figs/Service.pdf - -> figs/System.pdf - -> tutorial-examples/*.c - -> gpl-3.0.texi - -> fdl-1.3.texi - -- gnunet-c-tutorial-v1.pdf: original LaTeX "gnunet-c-tutorial.pdf". -- man folder: the man pages. -- doxygen folder -- outdated-and-old-installation-instructions.txt: self described within the file. - - -Use `gendocs', add to the manual/ directory of the web site. - - $ cd doc - $ gendocs.sh gnunet "GNUnet 0.10.X Reference Manual" diff --git a/doc/documentation/agpl-3.0.texi b/doc/documentation/agpl-3.0.texi deleted file mode 100644 index eabb0c6df..000000000 --- a/doc/documentation/agpl-3.0.texi +++ /dev/null @@ -1,698 +0,0 @@ -@c The GNU Affero General Public License. -@center Version 3, 19 November 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{https://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU Affero General Public License is a free, copyleft license -for software and other kinds of works, specifically designed to ensure -cooperation with the community in the case of network server software. - -The licenses for most software and other practical works are -designed to take away your freedom to share and change the works. By -contrast, our General Public Licenses are intended to guarantee your -freedom to share and change all versions of a program--to make sure it -remains free software for all its users. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -Developers that use our General Public Licenses protect your rights -with two steps: (1) assert copyright on the software, and (2) offer -you this License which gives you legal permission to copy, distribute -and/or modify the software. - -A secondary benefit of defending all users' freedom is that -improvements made in alternate versions of the program, if they -receive widespread use, become available for other developers to -incorporate. Many developers of free software are heartened and -encouraged by the resulting cooperation. However, in the case of -software used on network servers, this result may fail to come about. -The GNU General Public License permits making a modified version and -letting the public access it on a server without ever releasing its -source code to the public. - -The GNU Affero General Public License is designed specifically to -ensure that, in such cases, the modified source code becomes available -to the community. It requires the operator of a network server to -provide the source code of the modified version running there to the -users of that server. Therefore, public use of a modified version, on -a publicly accessible server, gives the public access to the source -code of the modified version. - -An older license, called the Affero General Public License and -published by Affero, was designed to accomplish similar goals. This is -a different license, not a version of the Affero GPL, but Affero has -released a new version of the Affero GPL which permits relicensing under -this license. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU Affero General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Remote Network Interaction; Use with the GNU General Public License. - -Notwithstanding any other provision of this License, if you modify the -Program, your modified version must prominently offer all users interacting -with it remotely through a computer network (if your version supports such -interaction) an opportunity to receive the Corresponding Source of your -version by providing access to the Corresponding Source from a network -server at no charge, through some standard or customary means of -facilitating copying of software. This Corresponding Source shall include -the Corresponding Source for any work covered by version 3 of the GNU -General Public License that is incorporated pursuant to the following -paragraph. - -Notwithstanding any other provision of this License, you have permission to -link or combine any covered work with a work licensed under version 3 of -the GNU General Public License into a single combined work, and to convey -the resulting work. The terms of this License will continue to apply to -the part which is the covered work, but the work with which it is combined -will remain governed by version 3 of the GNU General Public License. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU Affero General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU Affero General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU Affero General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU Affero General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU Affero General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -Affero General Public License for more details. - -You should have received a copy of the GNU Affero General Public License -along with this program. If not, see @url{https://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If your software can interact with users remotely through a computer -network, you should also make sure that it provides a way for users to -get its source. For example, if your program is a web application, its -interface could display a ``Source'' link that leads users to an archive -of the code. There are many ways you could offer source, and different -solutions will be better for different programs; see section 13 for the -specific requirements. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU AGPL, see -@url{https://www.gnu.org/licenses/}. diff --git a/doc/documentation/chapters/configuration.texi b/doc/documentation/chapters/configuration.texi deleted file mode 100644 index 286c72e7a..000000000 --- a/doc/documentation/chapters/configuration.texi +++ /dev/null @@ -1,5 +0,0 @@ -@node Configuration Handbook -@chapter Configuration Handbook - -This chapter has yet to be written. It is intended to be about in-depth -configuration of GNUnet. diff --git a/doc/documentation/chapters/contributing.texi b/doc/documentation/chapters/contributing.texi deleted file mode 100644 index f4493e6c1..000000000 --- a/doc/documentation/chapters/contributing.texi +++ /dev/null @@ -1,117 +0,0 @@ -@node GNUnet Contributors Handbook -@chapter GNUnet Contributors Handbook - -@menu -* Contributing to GNUnet:: -* Licenses of contributions:: -* Copyright Assignment:: -* Contributing to the Reference Manual:: -* Contributing testcases:: -@end menu - -@node Contributing to GNUnet -@section Contributing to GNUnet - -@cindex licenses -@cindex licenses of contributions -@node Licenses of contributions -@section Licenses of contributions - -GNUnet is a @uref{https://www.gnu.org/, GNU} package. -All code contributions must thus be put under the -@uref{https://www.gnu.org/licenses/agpl.html, GNU Affero Public License (AGPL)}. -All documentation should be put under FSF approved licenses -(see @uref{https://www.gnu.org/copyleft/fdl.html, fdl}). - -By submitting documentation, translations, and other content to GNUnet -you automatically grant the right to publish code under the -GNU Public License and documentation under either or both the -GNU Public License or the GNU Free Documentation License. -When contributing to the GNUnet project, GNU standards and the -@uref{https://www.gnu.org/philosophy/philosophy.html, GNU philosophy} -should be adhered to. - -@cindex copyright assignment -@node Copyright Assignment -@section Copyright Assignment -We require a formal copyright assignment for GNUnet contributors -to GNUnet e.V.; nevertheless, we do allow pseudonymous contributions. -By signing the copyright agreement and submitting your code (or -documentation) to us, you agree to share the rights to your code -with GNUnet e.V.; GNUnet e.V. receives non-exclusive ownership -rights, and in particular is allowed to dual-license the code. You -retain non-exclusive rights to your contributions, so you can also -share your contributions freely with other projects. - -GNUnet e.V. will publish all accepted contributions under the AGPLv3 -or any later version. The association may decide to publish -contributions under additional licenses (dual-licensing). - -We do not intentionally remove your name from your contributions; -however, due to extensive editing it is not always trivial to -attribute contributors properly. If you find that you significantly -contributed to a file (or the project as a whole) and are not listed -in the respective authors file or section, please do let us know. - -@node Contributing to the Reference Manual -@section Contributing to the Reference Manual - -@itemize @bullet - -@item When writing documentation, please use -@uref{https://en.wikipedia.org/wiki/Singular_they, gender-neutral wording} -when referring to people, such as singular “they”, “their”, “them”, and so -forth. - -@item Keep line length below 74 characters, except for URLs. -URLs break in the PDF output when they contain linebreaks. - -@item Do not use tab characters (see chapter 2.1 texinfo manual) - -@item Write texts in the third person perspective. - -@c FIXME: This is questionable, it feels like bike shed painging to do -@c this for several k lines. It only helps to jump between sentences in -@c editors afaik. -@c @item Use 2 spaces between sentences, so instead of: - -@c @example -@c We do this and the other thing. This is done by foo. -@c @end example - -@c Write: - -@c @example -@c We do this and the other thing. This is done by foo. -@c @end example - -@end itemize - -@node Contributing testcases -@section Contributing testcases - -In the core of gnunet, we restrict new testcases to a small subset -of languages, in order of preference: -@enumerate -@item C -@item Portable Shell Scripts -@item Python (@geq{}3.6) -@end enumerate - -We welcome efforts to remove our existing python-2.7 scripts to -replace them either with portable shell scripts or, -at your choice, python-3.6+. - -If you contribute new python based testcases, we advise you to -not repeat our past misfortunes and write the tests in a standard -test framework like for example pytest. - -For writing portable shell scripts, these tools are useful: -@uref{https://github.com/koalaman/shellcheck, Shellcheck}, -@uref{https://salsa.debian.org/debian/devscripts/blob/master/scripts/checkbashisms.pl, checkbashisms}, -@uref{http://www.etalabs.net/sh_tricks.html}, -@uref{https://wiki.ubuntu.com/DashAsBinSh}, -and @uref{https://mywiki.wooledge.org/Bashism} - -@c You could also run "bin/check_shell_script" (which we still have -@c to write). diff --git a/doc/documentation/chapters/developer.texi b/doc/documentation/chapters/developer.texi deleted file mode 100644 index d9c92247b..000000000 --- a/doc/documentation/chapters/developer.texi +++ /dev/null @@ -1,8817 +0,0 @@ -@c *********************************************************************** -@node GNUnet Developer Handbook -@chapter GNUnet Developer Handbook - -This book is intended to be an introduction for programmers that want to -extend the GNUnet framework. GNUnet is more than a simple peer-to-peer -application. - -For developers, GNUnet is: - -@itemize @bullet -@item developed by a community that believes in the GNU philosophy -@item Free Software (Free as in Freedom), licensed under the -GNU Affero General Public License -(@uref{https://www.gnu.org/licenses/licenses.html#AGPL}) -@item A set of standards, including coding conventions and -architectural rules -@item A set of layered protocols, both specifying the communication -between peers as well as the communication between components -of a single peer -@item A set of libraries with well-defined APIs suitable for -writing extensions -@end itemize - -In particular, the architecture specifies that a peer consists of many -processes communicating via protocols. Processes can be written in almost -any language. -@code{C}, @code{Java} and @code{Guile} APIs exist for accessing existing -services and for writing extensions. -It is possible to write extensions in other languages by -implementing the necessary IPC protocols. - -GNUnet can be extended and improved along many possible dimensions, and -anyone interested in Free Software and Freedom-enhancing Networking is -welcome to join the effort. This Developer Handbook attempts to provide -an initial introduction to some of the key design choices and central -components of the system. -This part of the GNUNet documentation is far from complete, -and we welcome informed contributions, be it in the form of -new chapters, sections or insightful comments. - -@menu -* Developer Introduction:: -* Internal dependencies:: -* Code overview:: -* System Architecture:: -* Subsystem stability:: -* Naming conventions and coding style guide:: -* Build-system:: -* Developing extensions for GNUnet using the gnunet-ext template:: -* Writing testcases:: -* Building GNUnet and its dependencies:: -* TESTING library:: -* Performance regression analysis with Gauger:: -* TESTBED Subsystem:: -* libgnunetutil:: -* Automatic Restart Manager (ARM):: -* TRANSPORT Subsystem:: -* NAT library:: -* Distance-Vector plugin:: -* SMTP plugin:: -* Bluetooth plugin:: -* WLAN plugin:: -* ATS Subsystem:: -* CORE Subsystem:: -* CADET Subsystem:: -* NSE Subsystem:: -* HOSTLIST Subsystem:: -* IDENTITY Subsystem:: -* NAMESTORE Subsystem:: -* PEERINFO Subsystem:: -* PEERSTORE Subsystem:: -* SET Subsystem:: -* STATISTICS Subsystem:: -* Distributed Hash Table (DHT):: -* GNU Name System (GNS):: -* GNS Namecache:: -* REVOCATION Subsystem:: -* File-sharing (FS) Subsystem:: -* REGEX Subsystem:: -* REST Subsystem:: -@end menu - -@node Developer Introduction -@section Developer Introduction - -This Developer Handbook is intended as first introduction to GNUnet for -new developers that want to extend the GNUnet framework. After the -introduction, each of the GNUnet subsystems (directories in the -@file{src/} tree) is (supposed to be) covered in its own chapter. In -addition to this documentation, GNUnet developers should be aware of the -services available on the GNUnet server to them. - -New developers can have a look a the GNUnet tutorials for C and java -available in the @file{src/} directory of the repository or under the -following links: - -@c ** FIXME: Link to files in source, not online. -@c ** FIXME: Where is the Java tutorial? -@itemize @bullet -@item @xref{Top, Introduction,, gnunet-c-tutorial, The GNUnet C Tutorial}. -@c broken link -@c @item @uref{https://gnunet.org/git/gnunet.git/plain/doc/gnunet-c-tutorial.pdf, GNUnet C tutorial} -@item GNUnet Java tutorial -@end itemize - -In addition to the GNUnet Reference Documentation you are reading, -the GNUnet server at @uref{https://gnunet.org} contains -various resources for GNUnet developers and those -who aspire to become regular contributors. -They are all conveniently reachable via the "Developer" -entry in the navigation menu. Some additional tools (such as static -analysis reports) require a special developer access to perform certain -operations. If you want (or require) access, you should contact -@uref{http://grothoff.org/christian/, Christian Grothoff}, -GNUnet's maintainer. - -@c FIXME: A good part of this belongs on the website or should be -@c extended in subsections explaining usage of this. A simple list -@c is just taking space people have to read. -The public subsystems on the GNUnet server that help developers are: - -@itemize @bullet - -@item The version control system (git) keeps our code and enables -distributed development. -It is publicly accessible at @uref{https://gnunet.org/git/}. -Only developers with write access can commit code, everyone else is -encouraged to submit patches to the GNUnet-developers mailinglist: -@uref{https://lists.gnu.org/mailman/listinfo/gnunet-developers, https://lists.gnu.org/mailman/listinfo/gnunet-developers} - -@item The bugtracking system (Mantis). -We use it to track feature requests, open bug reports and their -resolutions. -It can be accessed at -@uref{https://gnunet.org/bugs/, https://gnunet.org/bugs/}. -Anyone can report bugs. - -@item Our site installation of the -Continuous Integration (CI) system @code{Buildbot} is used -to check GNUnet builds automatically on a range of platforms. -The web interface of this CI is exposed at -@uref{https://gnunet.org/buildbot/, https://gnunet.org/buildbot/}. -Builds are triggered automatically 30 minutes after the last commit to -our repository was made. - -@item The current quality of our automated test suite is assessed using -Code coverage analysis. This analysis is run daily; however the webpage -is only updated if all automated tests pass at that time. Testcases that -improve our code coverage are always welcome. - -@item We try to automatically find bugs using a static analysis scan. -This scan is run daily; however the webpage is only updated if all -automated tests pass at the time. Note that not everything that is -flagged by the analysis is a bug, sometimes even good code can be marked -as possibly problematic. Nevertheless, developers are encouraged to at -least be aware of all issues in their code that are listed. - -@item We use Gauger for automatic performance regression visualization. -@c FIXME: LINK! -Details on how to use Gauger are here. - -@item We use @uref{http://junit.org/, junit} to automatically test -@command{gnunet-java}. -Automatically generated, current reports on the test suite are here. -@c FIXME: Likewise. - -@item We use Cobertura to generate test coverage reports for gnunet-java. -Current reports on test coverage are here. -@c FIXME: Likewise. - -@end itemize - - - -@c *********************************************************************** -@menu -* Project overview:: -@end menu - -@node Project overview -@subsection Project overview - -The GNUnet project consists at this point of several sub-projects. This -section is supposed to give an initial overview about the various -sub-projects. Note that this description also lists projects that are far -from complete, including even those that have literally not a single line -of code in them yet. - -GNUnet sub-projects in order of likely relevance are currently: - -@table @asis - -@item @command{gnunet} -Core of the P2P framework, including file-sharing, VPN and -chat applications; this is what the Developer Handbook covers mostly -@item @command{gnunet-gtk} -Gtk+-based user interfaces, including: - -@itemize @bullet -@item @command{gnunet-fs-gtk} (file-sharing), -@item @command{gnunet-statistics-gtk} (statistics over time), -@item @command{gnunet-peerinfo-gtk} -(information about current connections and known peers), -@item @command{gnunet-chat-gtk} (chat GUI) and -@item @command{gnunet-setup} (setup tool for "everything") -@end itemize - -@item @command{gnunet-fuse} -Mounting directories shared via GNUnet's file-sharing -on GNU/Linux distributions -@item @command{gnunet-update} -Installation and update tool -@item @command{gnunet-ext} -Template for starting 'external' GNUnet projects -@item @command{gnunet-java} -Java APIs for writing GNUnet services and applications -@item @command{gnunet-java-ext} -@item @command{eclectic} -Code to run GNUnet nodes on testbeds for research, development, -testing and evaluation -@c ** FIXME: Solve the status and location of gnunet-qt -@item @command{gnunet-qt} -Qt-based GNUnet GUI (is it deprecated?) -@item @command{gnunet-cocoa} -cocoa-based GNUnet GUI (is it deprecated?) -@item @command{gnunet-guile} -Guile bindings for GNUnet -@item @command{gnunet-python} -Python bindings for GNUnet - -@end table - -We are also working on various supporting libraries and tools: -@c ** FIXME: What about gauger, and what about libmwmodem? - -@table @asis -@item @command{libextractor} -GNU libextractor (meta data extraction) -@item @command{libmicrohttpd} -GNU libmicrohttpd (embedded HTTP(S) server library) -@item @command{gauger} -Tool for performance regression analysis -@item @command{monkey} -Tool for automated debugging of distributed systems -@item @command{libmwmodem} -Library for accessing satellite connection quality reports -@item @command{libgnurl} -gnURL (feature-restricted variant of cURL/libcurl) -@item @command{www} -work in progress of the new gnunet.org website (Jinja2 framework based to -replace our current Drupal website) -@item @command{bibliography} -Our collected bibliography, papers, references, and so forth -@item @command{gnunet-videos-} -Videos about and around gnunet activities -@end table - -Finally, there are various external projects (see links for a list of -those that have a public website) which build on top of the GNUnet -framework. - -@c *********************************************************************** -@node Internal dependencies -@section Internal dependencies - -This section tries to give an overview of what processes a typical GNUnet -peer running a particular application would consist of. All of the -processes listed here should be automatically started by -@command{gnunet-arm -s}. -The list is given as a rough first guide to users for failure diagnostics. -Ideally, end-users should never have to worry about these internal -dependencies. - -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) -@end itemize - -@noindent -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) -@end itemize - -@noindent -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) -@end itemize - -@c *********************************************************************** -@node Code overview -@section Code overview - -This section gives a brief overview of the GNUnet source code. -Specifically, we sketch the function of each of the subdirectories in -the @file{gnunet/src/} directory. The order given is roughly bottom-up -(in terms of the layers of the system). - -@table @asis -@item @file{util/} --- libgnunetutil -Library with general utility functions, all -GNUnet binaries link against this library. Anything from memory -allocation and data structures to cryptography and inter-process -communication. The goal is to provide an OS-independent interface and -more 'secure' or convenient implementations of commonly used primitives. -The API is spread over more than a dozen headers, developers should study -those closely to avoid duplicating existing functions. -@pxref{libgnunetutil}. -@item @file{hello/} --- libgnunethello -HELLO messages are used to -describe under which addresses a peer can be reached (for example, -protocol, IP, port). This library manages parsing and generating of HELLO -messages. -@item @file{block/} --- libgnunetblock -The DHT and other components of GNUnet -store information in units called 'blocks'. Each block has a type and the -type defines a particular format and how that binary format is to be -linked to a hash code (the key for the DHT and for databases). The block -library is a wrapper around block plugins which provide the necessary -functions for each block type. -@item @file{statistics/} --- statistics service -The statistics service enables associating -values (of type uint64_t) with a component name and a string. The main -uses is debugging (counting events), performance tracking and user -entertainment (what did my peer do today?). -@item @file{arm/} --- Automatic Restart Manager (ARM) -The automatic-restart-manager (ARM) service -is the GNUnet master service. Its role is to start gnunet-services, to -re-start them when they crashed and finally to shut down the system when -requested. -@item @file{peerinfo/} --- peerinfo service -The peerinfo service keeps track of which peers are known -to the local peer and also tracks the validated addresses for each peer -(in the form of a HELLO message) for each of those peers. The peer is not -necessarily connected to all peers known to the peerinfo service. -Peerinfo provides persistent storage for peer identities --- peers are -not forgotten just because of a system restart. -@item @file{datacache/} --- libgnunetdatacache -The datacache library provides (temporary) block storage for the DHT. -Existing plugins can store blocks in Sqlite, Postgres or MySQL databases. -All data stored in the cache is lost when the peer is stopped or -restarted (datacache uses temporary tables). -@item @file{datastore/} --- datastore service -The datastore service stores file-sharing blocks in -databases for extended periods of time. In contrast to the datacache, data -is not lost when peers restart. However, quota restrictions may still -cause old, expired or low-priority data to be eventually discarded. -Existing plugins can store blocks in Sqlite, Postgres or MySQL databases. -@item @file{template/} --- service template -Template for writing a new service. Does nothing. -@item @file{ats/} --- Automatic Transport Selection -The automatic transport selection (ATS) service -is responsible for deciding which address (i.e. -which transport plugin) should be used for communication with other peers, -and at what bandwidth. -@item @file{nat/} --- libgnunetnat -Library that provides basic functions for NAT traversal. -The library supports NAT traversal with -manual hole-punching by the user, UPnP and ICMP-based autonomous NAT -traversal. The library also includes an API for testing if the current -configuration works and the @code{gnunet-nat-server} which provides an -external service to test the local configuration. -@item @file{fragmentation/} --- libgnunetfragmentation -Some transports (UDP and WLAN, mostly) have restrictions on the maximum -transfer unit (MTU) for packets. The fragmentation library can be used to -break larger packets into chunks of at most 1k and transmit the resulting -fragments reliably (with acknowledgment, retransmission, timeouts, -etc.). -@item @file{transport/} --- transport service -The transport service is responsible for managing the -basic P2P communication. It uses plugins to support P2P communication -over TCP, UDP, HTTP, HTTPS and other protocols.The transport service -validates peer addresses, enforces bandwidth restrictions, limits the -total number of connections and enforces connectivity restrictions (i.e. -friends-only). -@item @file{peerinfo-tool/} --- gnunet-peerinfo -This directory contains the gnunet-peerinfo binary which can be used to -inspect the peers and HELLOs known to the peerinfo service. -@item @file{core/} -The core service is responsible for establishing encrypted, authenticated -connections with other peers, encrypting and decrypting messages and -forwarding messages to higher-level services that are interested in them. -@item @file{testing/} --- libgnunettesting -The testing library allows starting (and stopping) peers -for writing testcases. -It also supports automatic generation of configurations for peers -ensuring that the ports and paths are disjoint. libgnunettesting is also -the foundation for the testbed service -@item @file{testbed/} --- testbed service -The testbed service is used for creating small or large scale deployments -of GNUnet peers for evaluation of protocols. -It facilitates peer deployments on multiple -hosts (for example, in a cluster) and establishing various network -topologies (both underlay and overlay). -@item @file{nse/} --- Network Size Estimation -The network size estimation (NSE) service -implements a protocol for (securely) estimating the current size of the -P2P network. -@item @file{dht/} --- distributed hash table -The distributed hash table (DHT) service provides a -distributed implementation of a hash table to store blocks under hash -keys in the P2P network. -@item @file{hostlist/} --- hostlist service -The hostlist service allows learning about -other peers in the network by downloading HELLO messages from an HTTP -server, can be configured to run such an HTTP server and also implements -a P2P protocol to advertise and automatically learn about other peers -that offer a public hostlist server. -@item @file{topology/} --- topology service -The topology service is responsible for -maintaining the mesh topology. It tries to maintain connections to friends -(depending on the configuration) and also tries to ensure that the peer -has a decent number of active connections at all times. If necessary, new -connections are added. All peers should run the topology service, -otherwise they may end up not being connected to any other peer (unless -some other service ensures that core establishes the required -connections). The topology service also tells the transport service which -connections are permitted (for friend-to-friend networking) -@item @file{fs/} --- file-sharing -The file-sharing (FS) service implements GNUnet's -file-sharing application. Both anonymous file-sharing (using gap) and -non-anonymous file-sharing (using dht) are supported. -@item @file{cadet/} --- cadet service -The CADET service provides a general-purpose routing abstraction to create -end-to-end encrypted tunnels in mesh networks. We wrote a paper -documenting key aspects of the design. -@item @file{tun/} --- libgnunettun -Library for building IPv4, IPv6 packets and creating -checksums for UDP, TCP and ICMP packets. The header -defines C structs for common Internet packet formats and in particular -structs for interacting with TUN (virtual network) interfaces. -@item @file{mysql/} --- libgnunetmysql -Library for creating and executing prepared MySQL -statements and to manage the connection to the MySQL database. -Essentially a lightweight wrapper for the interaction between GNUnet -components and libmysqlclient. -@item @file{dns/} -Service that allows intercepting and modifying DNS requests of -the local machine. Currently used for IPv4-IPv6 protocol translation -(DNS-ALG) as implemented by "pt/" and for the GNUnet naming system. The -service can also be configured to offer an exit service for DNS traffic. -@item @file{vpn/} --- VPN service -The virtual public network (VPN) service provides a virtual -tunnel interface (VTUN) for IP routing over GNUnet. -Needs some other peers to run an "exit" service to work. -Can be activated using the "gnunet-vpn" tool or integrated with DNS using -the "pt" daemon. -@item @file{exit/} -Daemon to allow traffic from the VPN to exit this -peer to the Internet or to specific IP-based services of the local peer. -Currently, an exit service can only be restricted to IPv4 or IPv6, not to -specific ports and or IP address ranges. If this is not acceptable, -additional firewall rules must be added manually. exit currently only -works for normal UDP, TCP and ICMP traffic; DNS queries need to leave the -system via a DNS service. -@item @file{pt/} -protocol translation daemon. This daemon enables 4-to-6, -6-to-4, 4-over-6 or 6-over-4 transitions for the local system. It -essentially uses "DNS" to intercept DNS replies and then maps results to -those offered by the VPN, which then sends them using mesh to some daemon -offering an appropriate exit service. -@item @file{identity/} -Management of egos (alter egos) of a user; identities are -essentially named ECC private keys and used for zones in the GNU name -system and for namespaces in file-sharing, but might find other uses later -@item @file{revocation/} -Key revocation service, can be used to revoke the -private key of an identity if it has been compromised -@item @file{namecache/} -Cache for resolution results for the GNU name system; -data is encrypted and can be shared among users, -loss of the data should ideally only result in a -performance degradation (persistence not required) -@item @file{namestore/} -Database for the GNU name system with per-user private information, -persistence required -@item @file{gns/} -GNU name system, a GNU approach to DNS and PKI. -@item @file{dv/} -A plugin for distance-vector (DV)-based routing. -DV consists of a service and a transport plugin to provide peers -with the illusion of a direct P2P connection for connections -that use multiple (typically up to 3) hops in the actual underlay network. -@item @file{regex/} -Service for the (distributed) evaluation of regular expressions. -@item @file{scalarproduct/} -The scalar product service offers an API to perform a secure multiparty -computation which calculates a scalar product between two peers -without exposing the private input vectors of the peers to each other. -@item @file{consensus/} -The consensus service will allow a set of peers to agree -on a set of values via a distributed set union computation. -@item @file{rest/} -The rest API allows access to GNUnet services using RESTful interaction. -The services provide plugins that can exposed by the rest server. -@c FIXME: Where did this disappear to? -@c @item @file{experimentation/} -@c The experimentation daemon coordinates distributed -@c experimentation to evaluate transport and ATS properties. -@end table - -@c *********************************************************************** -@node System Architecture -@section System Architecture - -@c FIXME: For those irritated by the textflow, we are missing images here, -@c in the short term we should add them back, in the long term this should -@c work without images or have images with alt-text. - -GNUnet developers like LEGOs. The blocks are indestructible, can be -stacked together to construct complex buildings and it is generally easy -to swap one block for a different one that has the same shape. GNUnet's -architecture is based on LEGOs: - -@c @image{images/service_lego_block,5in,,picture of a LEGO block stack - 3 APIs as connectors upon Network Protocol on top of a Service} - -This chapter documents the GNUnet LEGO system, also known as GNUnet's -system architecture. - -The most common GNUnet component is a service. Services offer an API (or -several, depending on what you count as "an API") which is implemented as -a library. The library communicates with the main process of the service -using a service-specific network protocol. The main process of the service -typically doesn't fully provide everything that is needed --- it has holes -to be filled by APIs to other services. - -A special kind of component in GNUnet are user interfaces and daemons. -Like services, they have holes to be filled by APIs of other services. -Unlike services, daemons do not implement their own network protocol and -they have no API: - -The GNUnet system provides a range of services, daemons and user -interfaces, which are then combined into a layered GNUnet instance (also -known as a peer). - -Note that while it is generally possible to swap one service for another -compatible service, there is often only one implementation. However, -during development we often have a "new" version of a service in parallel -with an "old" version. While the "new" version is not working, developers -working on other parts of the service can continue their development by -simply using the "old" service. Alternative design ideas can also be -easily investigated by swapping out individual components. This is -typically achieved by simply changing the name of the "BINARY" in the -respective configuration section. - -Key properties of GNUnet services are that they must be separate -processes and that they must protect themselves by applying tight error -checking against the network protocol they implement (thereby achieving a -certain degree of robustness). - -On the other hand, the APIs are implemented to tolerate failures of the -service, isolating their host process from errors by the service. If the -service process crashes, other services and daemons around it should not -also fail, but instead wait for the service process to be restarted by -ARM. - - -@c *********************************************************************** -@node Subsystem stability -@section Subsystem stability - -This section documents the current stability of the various GNUnet -subsystems. Stability here describes the expected degree of compatibility -with future versions of GNUnet. For each subsystem we distinguish between -compatibility on the P2P network level (communication protocol between -peers), the IPC level (communication between the service and the service -library) and the API level (stability of the API). P2P compatibility is -relevant in terms of which applications are likely going to be able to -communicate with future versions of the network. IPC communication is -relevant for the implementation of language bindings that re-implement the -IPC messages. Finally, API compatibility is relevant to developers that -hope to be able to avoid changes to applications build on top of the APIs -of the framework. - -The following table summarizes our current view of the stability of the -respective protocols or APIs: - -@multitable @columnfractions .20 .20 .20 .20 -@headitem Subsystem @tab P2P @tab IPC @tab C API -@item util @tab n/a @tab n/a @tab stable -@item arm @tab n/a @tab stable @tab stable -@item ats @tab n/a @tab unstable @tab testing -@item block @tab n/a @tab n/a @tab stable -@item cadet @tab testing @tab testing @tab testing -@item consensus @tab experimental @tab experimental @tab experimental -@item core @tab stable @tab stable @tab stable -@item datacache @tab n/a @tab n/a @tab stable -@item datastore @tab n/a @tab stable @tab stable -@item dht @tab stable @tab stable @tab stable -@item dns @tab stable @tab stable @tab stable -@item dv @tab testing @tab testing @tab n/a -@item exit @tab testing @tab n/a @tab n/a -@item fragmentation @tab stable @tab n/a @tab stable -@item fs @tab stable @tab stable @tab stable -@item gns @tab stable @tab stable @tab stable -@item hello @tab n/a @tab n/a @tab testing -@item hostlist @tab stable @tab stable @tab n/a -@item identity @tab stable @tab stable @tab n/a -@item multicast @tab experimental @tab experimental @tab experimental -@item mysql @tab stable @tab n/a @tab stable -@item namestore @tab n/a @tab stable @tab stable -@item nat @tab n/a @tab n/a @tab stable -@item nse @tab stable @tab stable @tab stable -@item peerinfo @tab n/a @tab stable @tab stable -@item psyc @tab experimental @tab experimental @tab experimental -@item pt @tab n/a @tab n/a @tab n/a -@item regex @tab stable @tab stable @tab stable -@item revocation @tab stable @tab stable @tab stable -@item social @tab experimental @tab experimental @tab experimental -@item statistics @tab n/a @tab stable @tab stable -@item testbed @tab n/a @tab testing @tab testing -@item testing @tab n/a @tab n/a @tab testing -@item topology @tab n/a @tab n/a @tab n/a -@item transport @tab stable @tab stable @tab stable -@item tun @tab n/a @tab n/a @tab stable -@item vpn @tab testing @tab n/a @tab n/a -@end multitable - -Here is a rough explanation of the values: - -@table @samp -@item stable -No incompatible changes are planned at this time; for IPC/APIs, if -there are incompatible changes, they will be minor and might only require -minimal changes to existing code; for P2P, changes will be avoided if at -all possible for the 0.10.x-series - -@item testing -No incompatible changes are -planned at this time, but the code is still known to be in flux; so while -we have no concrete plans, our expectation is that there will still be -minor modifications; for P2P, changes will likely be extensions that -should not break existing code - -@item unstable -Changes are planned and will happen; however, they -will not be totally radical and the result should still resemble what is -there now; nevertheless, anticipated changes will break protocol/API -compatibility - -@item experimental -Changes are planned and the result may look nothing like -what the API/protocol looks like today - -@item unknown -Someone should think about where this subsystem headed - -@item n/a -This subsystem does not have an API/IPC-protocol/P2P-protocol -@end table - -@c *********************************************************************** -@node Naming conventions and coding style guide -@section Naming conventions and coding style guide - -Here you can find some rules to help you write code for GNUnet. - -@c *********************************************************************** -@menu -* Naming conventions:: -* Coding style:: -@end menu - -@node Naming conventions -@subsection Naming conventions - - -@c *********************************************************************** -@menu -* include files:: -* binaries:: -* logging:: -* configuration:: -* exported symbols:: -* private (library-internal) symbols (including structs and macros):: -* testcases:: -* performance tests:: -* src/ directories:: -@end menu - -@node include files -@subsubsection include files - -@itemize @bullet -@item _lib: library without need for a process -@item _service: library that needs a service process -@item _plugin: plugin definition -@item _protocol: structs used in network protocol -@item exceptions: -@itemize @bullet -@item gnunet_config.h --- generated -@item platform.h --- first included -@item plibc.h --- external library -@item gnunet_common.h --- fundamental routines -@item gnunet_directories.h --- generated -@item gettext.h --- external library -@end itemize -@end itemize - -@c *********************************************************************** -@node binaries -@subsubsection binaries - -@itemize @bullet -@item gnunet-service-xxx: service process (has listen socket) -@item gnunet-daemon-xxx: daemon process (no listen socket) -@item gnunet-helper-xxx[-yyy]: SUID helper for module xxx -@item gnunet-yyy: command-line tool for end-users -@item libgnunet_plugin_xxx_yyy.so: plugin for API xxx -@item libgnunetxxx.so: library for API xxx -@end itemize - -@c *********************************************************************** -@node logging -@subsubsection logging - -@itemize @bullet -@item services and daemons use their directory name in -@code{GNUNET_log_setup} (i.e. 'core') and log using -plain 'GNUNET_log'. -@item command-line tools use their full name in -@code{GNUNET_log_setup} (i.e. 'gnunet-publish') and log using -plain 'GNUNET_log'. -@item service access libraries log using -'@code{GNUNET_log_from}' and use '@code{DIRNAME-api}' for the -component (i.e. 'core-api') -@item pure libraries (without associated service) use -'@code{GNUNET_log_from}' with the component set to their -library name (without lib or '@file{.so}'), -which should also be their directory name (i.e. '@file{nat}') -@item plugins should use '@code{GNUNET_log_from}' -with the directory name and the plugin name combined to produce -the component name (i.e. 'transport-tcp'). -@item logging should be unified per-file by defining a -@code{LOG} macro with the appropriate arguments, -along these lines: - -@example -#define LOG(kind,...) -GNUNET_log_from (kind, "example-api",__VA_ARGS__) -@end example - -@end itemize - -@c *********************************************************************** -@node configuration -@subsubsection configuration - -@itemize @bullet -@item paths (that are substituted in all filenames) are in PATHS -(have as few as possible) -@item all options for a particular module (@file{src/MODULE}) -are under @code{[MODULE]} -@item options for a plugin of a module -are under @code{[MODULE-PLUGINNAME]} -@end itemize - -@c *********************************************************************** -@node exported symbols -@subsubsection exported symbols - -@itemize @bullet -@item must start with @code{GNUNET_modulename_} and be defined in -@file{modulename.c} -@item exceptions: those defined in @file{gnunet_common.h} -@end itemize - -@c *********************************************************************** -@node private (library-internal) symbols (including structs and macros) -@subsubsection private (library-internal) symbols (including structs and macros) - -@itemize @bullet -@item must NOT start with any prefix -@item must not be exported in a way that linkers could use them or@ other -libraries might see them via headers; they must be either -declared/defined in C source files or in headers that are in the -respective directory under @file{src/modulename/} and NEVER be declared -in @file{src/include/}. -@end itemize - -@node testcases -@subsubsection testcases - -@itemize @bullet -@item must be called @file{test_module-under-test_case-description.c} -@item "case-description" maybe omitted if there is only one test -@end itemize - -@c *********************************************************************** -@node performance tests -@subsubsection performance tests - -@itemize @bullet -@item must be called @file{perf_module-under-test_case-description.c} -@item "case-description" maybe omitted if there is only one performance -test -@item Must only be run if @code{HAVE_BENCHMARKS} is satisfied -@end itemize - -@c *********************************************************************** -@node src/ directories -@subsubsection src/ directories - -@itemize @bullet -@item gnunet-NAME: end-user applications (i.e., gnunet-search, gnunet-arm) -@item gnunet-service-NAME: service processes with accessor library (i.e., -gnunet-service-arm) -@item libgnunetNAME: accessor library (_service.h-header) or standalone -library (_lib.h-header) -@item gnunet-daemon-NAME: daemon process without accessor library (i.e., -gnunet-daemon-hostlist) and no GNUnet management port -@item libgnunet_plugin_DIR_NAME: loadable plugins (i.e., -libgnunet_plugin_transport_tcp) -@end itemize - -@cindex Coding style -@node Coding style -@subsection Coding style - -@c XXX: Adjust examples to GNU Standards! -@itemize @bullet -@item We follow the GNU Coding Standards (@pxref{Top, The GNU Coding Standards,, standards, The GNU Coding Standards}); -@item Indentation is done with spaces, two per level, no tabs; -@item C99 struct initialization is fine; -@item declare only one variable per line, for example: - -@noindent -instead of - -@example -int i,j; -@end example - -@noindent -write: - -@example -int i; -int j; -@end example - -@c TODO: include actual example from a file in source - -@noindent -This helps keep diffs small and forces developers to think precisely about -the type of every variable. -Note that @code{char *} is different from @code{const char*} and -@code{int} is different from @code{unsigned int} or @code{uint32_t}. -Each variable type should be chosen with care. - -@item While @code{goto} should generally be avoided, having a -@code{goto} to the end of a function to a block of clean up -statements (free, close, etc.) can be acceptable. - -@item Conditions should be written with constants on the left (to avoid -accidental assignment) and with the @code{true} target being either the -@code{error} case or the significantly simpler continuation. For example: - -@example -if (0 != stat ("filename," &sbuf)) @{ - error(); - @} - else @{ - /* handle normal case here */ - @} -@end example - -@noindent -instead of - -@example -if (stat ("filename," &sbuf) == 0) @{ - /* handle normal case here */ - @} else @{ - error(); - @} -@end example - -@noindent -If possible, the error clause should be terminated with a @code{return} (or -@code{goto} to some cleanup routine) and in this case, the @code{else} clause -should be omitted: - -@example -if (0 != stat ("filename," &sbuf)) @{ - error(); - return; - @} -/* handle normal case here */ -@end example - -This serves to avoid deep nesting. The 'constants on the left' rule -applies to all constants (including. @code{GNUNET_SCHEDULER_NO_TASK}), -NULL, and enums). With the two above rules (constants on left, errors in -'true' branch), there is only one way to write most branches correctly. - -@item Combined assignments and tests are allowed if they do not hinder -code clarity. For example, one can write: - -@example -if (NULL == (value = lookup_function())) @{ - error(); - return; - @} -@end example - -@item Use @code{break} and @code{continue} wherever possible to avoid -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); - @} -@end example - -instead of - -@example -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); - @} - @} -@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: - -@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); -@} -@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)}). -However, for loops that do follow the simple @code{for} paradigm we do -use @code{for}, even if it involves linked lists: - -@example -/* simple iteration over a linked list */ -for (pos = head; - NULL != pos; - pos = pos->next) -@{ - use (pos); -@} -@end example - - -@item The first argument to all higher-order functions in GNUnet must be -declared to be of type @code{void *} and is reserved for a closure. We do -not use inner functions, as trampolines would conflict with setups that -use non-executable stacks. -The first statement in a higher-order function, which unusually should -be part of the variable declarations, should assign the -@code{cls} argument to the precise expected type. For example: - -@example -int callback (void *cls, char *args) @{ - struct Foo *foo = cls; - int other_variables; - - /* rest of function */ -@} -@end example - - -@item It is good practice to write complex @code{if} expressions instead -of using deeply nested @code{if} statements. However, except for addition -and multiplication, all operators should use parens. This is fine: - -@example -if ( (1 == foo) || ((0 == bar) && (x != y)) ) - return x; -@end example - - -However, this is not: - -@example -if (1 == foo) - return x; -if (0 == bar && x != y) - return x; -@end example - -@noindent -Note that splitting the @code{if} statement above is debatable as the -@code{return x} is a very trivial statement. However, once the logic after -the branch becomes more complicated (and is still identical), the "or" -formulation should be used for sure. - -@item There should be two empty lines between the end of the function and -the comments describing the following function. There should be a single -empty line after the initial variable declarations of a function. If a -function has no local variables, there should be no initial empty line. If -a long function consists of several complex steps, those steps might be -separated by an empty line (possibly followed by a comment describing the -following step). The code should not contain empty lines in arbitrary -places; if in doubt, it is likely better to NOT have an empty line (this -way, more code will fit on the screen). -@end itemize - -@c *********************************************************************** -@node Build-system -@section Build-system - -If you have code that is likely not to compile or build rules you might -want to not trigger for most developers, use @code{if HAVE_EXPERIMENTAL} -in your @file{Makefile.am}. -Then it is OK to (temporarily) add non-compiling (or known-to-not-port) -code. - -If you want to compile all testcases but NOT run them, run configure with -the @code{--enable-test-suppression} option. - -If you want to run all testcases, including those that take a while, run -configure with the @code{--enable-expensive-testcases} option. - -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 @file{coverage.sh} script in -the @file{contrib/} directory. - -@cindex gnunet-ext -@node Developing extensions for GNUnet using the gnunet-ext template -@section Developing extensions for GNUnet using the gnunet-ext template - -For developers who want to write extensions for GNUnet we provide the -gnunet-ext template to provide an easy to use skeleton. - -gnunet-ext contains the build environment and template files for the -development of GNUnet services, command line tools, APIs and tests. - -First of all you have to obtain gnunet-ext from 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 -@code{--with-gnunet=/path/to/gnunet} and the prefix where you want the -install the extension using @code{--prefix=/path/to/install}: - -@example -./bootstrap -./configure --prefix=/path/to/install --with-gnunet=/path/to/gnunet -@end example - -When your GNUnet installation is not included in the default linker search -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 - -@example -export LD_LIBRARY_PATH=/path/to/gnunet/lib -@end example - -@cindex writing testcases -@node Writing testcases -@section Writing testcases - -Ideally, any non-trivial GNUnet code should be covered by automated -testcases. Testcases should reside in the same place as the code that is -being tested. The name of source files implementing tests should begin -with @code{test_} followed by the name of the file that contains -the code that is being tested. - -Testcases in GNUnet should be integrated with the autotools build system. -This way, developers and anyone building binary packages will be able to -run all testcases simply by running @code{make check}. The final -testcases shipped with the distribution should output at most some brief -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 @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 = test_foo.c -test_foo_LDADD = $(top_builddir)/src/util/libgnunetutil.la -@end example - -Naturally, other libraries used by the testcase may be specified in the -@code{LDADD} directive as necessary. - -Often testcases depend on additional input files, such as a configuration -file. These support files have to be listed using the @code{EXTRA_DIST} -directive in order to ensure that they are included in the distribution. - -Example: - -@example -EXTRA_DIST = test_foo_data.conf -@end example - -Executing @code{make check} will run all testcases in the current -directory and all subdirectories. Testcases can be compiled individually -by running @code{make test_foo} and then invoked directly using -@code{./test_foo}. Note that due to the use of plugins in GNUnet, it is -typically necessary to run @code{make install} before running any -testcases. Thus the canonical command @code{make check install} has to be -changed to @code{make install check} for GNUnet. - -@c *********************************************************************** -@cindex Building GNUnet -@node Building GNUnet and its dependencies -@section Building GNUnet and its dependencies - -In the following section we will outline how to build GNUnet and -some of its dependencies. We will assume a fair amount of knowledge -for building applications under UNIX-like systems. Furthermore we -assume that the build environment is sane and that you are aware of -any implications actions in this process could have. -Instructions here can be seen as notes for developers (an extension to -the 'HACKING' section in README) as well as package maintainers. -@b{Users should rely on the available binary packages.} -We will use Debian as an example Operating System environment. Substitute -accordingly with your own Operating System environment. - -For the full list of dependencies, consult the appropriate, up-to-date -section in the @file{README} file. - -First, we need to build or install (depending on your OS) the following -packages. If you build them from source, build them in this exact order: - -@example -libgpgerror, libgcrypt, libnettle, libunbound, GnuTLS (with libunbound -support) -@end example - -After we have build and installed those packages, we continue with -packages closer to GNUnet in this step: libgnurl (our libcurl fork), -GNU libmicrohttpd, and GNU libextractor. Again, if your package manager -provides one of these packages, use the packages provided from it -unless you have good reasons (package version too old, conflicts, etc). -We advise against compiling widely used packages such as GnuTLS -yourself if your OS provides a variant already unless you take care -of maintenance of the packages then. - -In the optimistic case, this command will give you all the dependencies: - -@example -sudo apt-get install libgnurl libmicrohttpd libextractor -@end example - -From experience we know that at the very least libgnurl is not -available in some environments. You could substitute libgnurl -with libcurl, but we recommend to install libgnurl, as it gives -you a predefined libcurl with the small set GNUnet requires. In -the past namespaces of libcurl and libgnurl were shared, which -caused problems when you wanted to integrate both of them in one -Operating System. This has been resolved, and they can be installed -side by side now. - -@cindex libgnurl -@cindex compiling libgnurl -GNUnet and some of its function depend on a limited subset of cURL/libcurl. -Rather than trying to enforce a certain configuration on the world, we -opted to maintain a microfork of it that ensures we can link against the -right set of features. We called this specialized set of libcurl -``libgnurl''. It is fully ABI compatible with libcurl and currently used -by GNUnet and some of its dependencies. - -We download libgnurl and its digital signature from the GNU fileserver, -assuming @env{TMPDIR} exists. - -Note: TMPDIR might be @file{/tmp}, @env{TMPDIR}, @env{TMP} or any other -location. For consistency we assume @env{TMPDIR} points to @file{/tmp} -for the remainder of this section. - -@example -cd \$TMPDIR -wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z -wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z.sig -@end example - -Next, verify the digital signature of the file: - -@example -gpg --verify gnurl-7.60.0.tar.Z.sig -@end example - -If gpg fails, you might try with @command{gpg2} on your OS. If the error -states that ``the key can not be found'' or it is unknown, you have to -retrieve the key (A88C8ADD129828D7EAC02E52E22F9BBFEE348588) from a -keyserver first: - -@example -gpg --keyserver pgp.mit.edu --recv-keys A88C8ADD129828D7EAC02E52E22F9BBFEE348588 -@end example - -and rerun the verification command. - -libgnurl will require the following packages to be present at runtime: -gnutls (with DANE support / libunbound), libidn, zlib and at compile time: -libtool, groff, perl, pkg-config, and python 2.7. - -Once you have verified that all the required packages are present on your -system, we can proceed to compile libgnurl: - -@example -tar -xvf gnurl-7.60.0.tar.Z -cd gnurl-7.60.0 -sh configure --disable-ntlm-wb -make -make -C tests test -sudo make install -@end example - -After you've compiled and installed libgnurl, we can proceed to building -GNUnet. - - - - -First, in addition to the GNUnet sources you might require downloading the -latest version of various dependencies, depending on how recent the -software versions in your distribution of GNU/Linux are. -Most distributions do not include sufficiently recent versions of these -dependencies. -Thus, a typically installation on a "modern" 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 -@end itemize - -Make sure to first install the various mandatory and optional -dependencies including development headers from your distribution. - -Other dependencies that you should strongly consider to install is a -database (MySQL, sqlite or Postgres). -The following instructions will assume that you installed at least sqlite. -For most distributions you should be able to find pre-build packages for -the database. Again, make sure to install the client libraries @b{and} the -respective development headers (if they are packaged separately) as well. - -You can find specific, detailed instructions for installing of the -dependencies (and possibly the rest of the GNUnet installation) in the -platform-specific descriptions, which can be found in the Index. -Please consult them now. -If your distribution is not listed, please study the build -instructions for Debian stable, carefully as you try to install the -dependencies for your own distribution. -Contributing additional instructions for further platforms is always -appreciated. -Please take in mind that operating system development tends to move at -a rather fast speed. Due to this you should be aware that some of -the instructions could be outdated by the time you are reading this. -If you find a mistake, please tell us about it (or even better: send -a patch to the documentation to fix it!). - -Before proceeding further, please double-check the dependency list. -Note that in addition to satisfying the dependencies, you might have to -make sure that development headers for the various libraries are also -installed. -There maybe files for other distributions, or you might be able to find -equivalent packages for your distribution. - -While it is possible to build and install GNUnet without having root -access, we will assume that you have full control over your system in -these instructions. -First, you should create a system user @emph{gnunet} and an additional -group @emph{gnunetdns}. On the GNU/Linux distributions Debian and Ubuntu, -type: - -@example -sudo adduser --system --home /var/lib/gnunet --group \ ---disabled-password gnunet -sudo addgroup --system gnunetdns -@end example - -@noindent -On other Unixes and GNU systems, this should have the same effect: - -@example -sudo useradd --system --groups gnunet --home-dir /var/lib/gnunet -sudo addgroup --system gnunetdns -@end example - -Now compile and install GNUnet using: - -@example -tar xvf gnunet-@value{VERSION}.tar.gz -cd gnunet-@value{VERSION} -./configure --with-sudo=sudo --with-nssdir=/lib -make -sudo make install -@end example - -If you want to be able to enable DEBUG-level log messages, add -@code{--enable-logging=verbose} to the end of the -@command{./configure} command. -@code{DEBUG}-level log messages are in English only and -should only be useful for developers (or for filing -really detailed bug reports). - -@noindent -Next, edit the file @file{/etc/gnunet.conf} to contain the following: - -@example -[arm] -START_SYSTEM_SERVICES = YES -START_USER_SERVICES = NO -@end example - -@noindent -You may need to update your @code{ld.so} cache to include -files installed in @file{/usr/local/lib}: - -@example -# ldconfig -@end example - -@noindent -Then, switch from user @code{root} to user @code{gnunet} to start -the peer: - -@example -# su -s /bin/sh - gnunet -$ gnunet-arm -c /etc/gnunet.conf -s -@end example - -You may also want to add the last line in the gnunet user's @file{crontab} -prefixed with @code{@@reboot} so that it is executed whenever the system -is booted: - -@example -@@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s -@end example - -@noindent -This will only start the system-wide GNUnet services. -Type @command{exit} to get back your root shell. -Now, you need to configure the per-user part. For each -user that should get access to GNUnet on the system, run -(replace alice with your username): - -@example -sudo adduser alice gnunet -@end example - -@noindent -to allow them to access the system-wide GNUnet services. Then, each -user should create a configuration file @file{~/.config/gnunet.conf} -with the lines: - -@example -[arm] -START_SYSTEM_SERVICES = NO -START_USER_SERVICES = YES -DEFAULTSERVICES = gns -@end example - -@noindent -and start the per-user services using - -@example -$ gnunet-arm -c ~/.config/gnunet.conf -s -@end example - -@noindent -Again, adding a @code{crontab} entry to autostart the peer is advised: - -@example -@@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s -@end example - -@noindent -Note that some GNUnet services (such as SOCKS5 proxies) may need a -system-wide TCP port for each user. -For those services, systems with more than one user may require each user -to specify a different port number in their personal configuration file. - -Finally, the user should perform the basic initial setup for the GNU Name -System (GNS) certificate authority. This is done by running: - -@example -$ gnunet-gns-proxy-setup-ca -@end example - -@noindent -The first generates the default zones, whereas the second setups the GNS -Certificate Authority with the user's browser. Now, to activate GNS in the -normal DNS resolution process, you need to edit your -@file{/etc/nsswitch.conf} where you should find a line like this: - -@example -hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 -@end example - -@noindent -The exact details may differ a bit, which is fine. Add the text -@emph{"gns [NOTFOUND=return]"} after @emph{"files"}. -Keep in mind that we included a backslash ("\") here just for -markup reasons. You should write the text below on @b{one line} -and @b{without} the "\": - -@example -hosts: files gns [NOTFOUND=return] mdns4_minimal \ -[NOTFOUND=return] dns mdns4 -@end example - -@c FIXME: Document new behavior. -You might want to make sure that @file{/lib/libnss_gns.so.2} exists on -your system, it should have been created during the installation. - - -@c ********************************************************************** -@cindex TESTING library -@node TESTING library -@section TESTING library - -The TESTING library is used for writing testcases which involve starting a -single or multiple peers. While peers can also be started by testcases -using the ARM subsystem, using TESTING library provides an elegant way to -do this. The configurations of the peers are auto-generated from a given -template to have non-conflicting port numbers ensuring that peers' -services do not run into bind errors. This is achieved by testing ports' -availability by binding a listening socket to them before allocating them -to services in the generated configurations. - -An another advantage while using TESTING is that it shortens the testcase -startup time as the hostkeys for peers are copied from a pre-computed set -of hostkeys instead of generating them at peer startup which may take a -considerable amount of time when starting multiple peers or on an embedded -processor. - -TESTING also allows for certain services to be shared among peers. This -feature is invaluable when testing with multiple peers as it helps to -reduce the number of services run per each peer and hence the total -number of processes run per testcase. - -TESTING library only handles creating, starting and stopping peers. -Features useful for testcases such as connecting peers in a topology are -not available in TESTING but are available in the TESTBED subsystem. -Furthermore, TESTING only creates peers on the localhost, however by -using TESTBED testcases can benefit from creating peers across multiple -hosts. - -@menu -* API:: -* Finer control over peer stop:: -* Helper functions:: -* Testing with multiple processes:: -@end menu - -@cindex TESTING API -@node API -@subsection API - -TESTING abstracts a group of peers as a TESTING system. All peers in a -system have common hostname and no two services of these peers have a -same port or a UNIX domain socket path. - -TESTING system can be created with the function -@code{GNUNET_TESTING_system_create()} which returns a handle to the -system. This function takes a directory path which is used for generating -the configurations of peers, an IP address from which connections to the -peers' services should be allowed, the hostname to be used in peers' -configuration, and an array of shared service specifications of type -@code{struct GNUNET_TESTING_SharedService}. - -The shared service specification must specify the name of the service to -share, the configuration pertaining to that shared service and the -maximum number of peers that are allowed to share a single instance of -the shared service. - -TESTING system created with @code{GNUNET_TESTING_system_create()} chooses -ports from the default range @code{12000} - @code{56000} while -auto-generating configurations for peers. -This range can be customised with the function -@code{GNUNET_TESTING_system_create_with_portrange()}. This function is -similar to @code{GNUNET_TESTING_system_create()} except that it take 2 -additional parameters --- the start and end of the port range to use. - -A TESTING system is destroyed with the function -@code{GNUNET_TESTING_system_destory()}. This function takes the handle of -the system and a flag to remove the files created in the directory used -to generate configurations. - -A peer is created with the function -@code{GNUNET_TESTING_peer_configure()}. This functions takes the system -handle, a configuration template from which the configuration for the peer -is auto-generated and the index from where the hostkey for the peer has to -be copied from. When successful, this function returns a handle to the -peer which can be used to start and stop it and to obtain the identity of -the peer. If unsuccessful, a NULL pointer is returned with an error -message. This function handles the generated configuration to have -non-conflicting ports and paths. - -Peers can be started and stopped by calling the functions -@code{GNUNET_TESTING_peer_start()} and @code{GNUNET_TESTING_peer_stop()} -respectively. A peer can be destroyed by calling the function -@code{GNUNET_TESTING_peer_destroy}. When a peer is destroyed, the ports -and paths in allocated in its configuration are reclaimed for usage in new -peers. - -@c *********************************************************************** -@node Finer control over peer stop -@subsection Finer control over peer stop - -Using @code{GNUNET_TESTING_peer_stop()} is normally fine for testcases. -However, calling this function for each peer is inefficient when trying to -shutdown multiple peers as this function sends the termination signal to -the given peer process and waits for it to terminate. It would be faster -in this case to send the termination signals to the peers first and then -wait on them. This is accomplished by the functions -@code{GNUNET_TESTING_peer_kill()} which sends a termination signal to the -peer, and the function @code{GNUNET_TESTING_peer_wait()} which waits on -the peer. - -Further finer control can be achieved by choosing to stop a peer -asynchronously with the function @code{GNUNET_TESTING_peer_stop_async()}. -This function takes a callback parameter and a closure for it in addition -to the handle to the peer to stop. The callback function is called with -the given closure when the peer is stopped. Using this function -eliminates blocking while waiting for the peer to terminate. - -An asynchronous peer stop can be canceled by calling the function -@code{GNUNET_TESTING_peer_stop_async_cancel()}. Note that calling this -function does not prevent the peer from terminating if the termination -signal has already been sent to it. It does, however, cancels the -callback to be called when the peer is stopped. - -@c *********************************************************************** -@node Helper functions -@subsection Helper functions - -Most of the testcases can benefit from an abstraction which configures a -peer and starts it. This is provided by the function -@code{GNUNET_TESTING_peer_run()}. This function takes the testing -directory pathname, a configuration template, a callback and its closure. -This function creates a peer in the given testing directory by using the -configuration template, starts the peer and calls the given callback with -the given closure. - -The function @code{GNUNET_TESTING_peer_run()} starts the ARM service of -the peer which starts the rest of the configured services. A similar -function @code{GNUNET_TESTING_service_run} can be used to just start a -single service of a peer. In this case, the peer's ARM service is not -started; instead, only the given service is run. - -@c *********************************************************************** -@node Testing with multiple processes -@subsection Testing with multiple processes - -When testing GNUnet, the splitting of the code into a services and clients -often complicates testing. The solution to this is to have the testcase -fork @code{gnunet-service-arm}, ask it to start the required server and -daemon processes and then execute appropriate client actions (to test the -client APIs or the core module or both). If necessary, multiple ARM -services can be forked using different ports (!) to simulate a network. -However, most of the time only one ARM process is needed. Note that on -exit, the testcase should shutdown ARM with a @code{TERM} signal (to give -it the chance to cleanly stop its child processes). - -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); - /* 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); -@end example - - -An alternative way that works well to test plugins is to implement a -mock-version of the environment that the plugin expects and then to -simply load the plugin directly. - -@c *********************************************************************** -@node Performance regression analysis with Gauger -@section Performance regression analysis with Gauger - -To help avoid performance regressions, GNUnet uses Gauger. Gauger is a -simple logging tool that allows remote hosts to send performance data to -a central server, where this data can be analyzed and visualized. Gauger -shows graphs of the repository revisions and the performance data recorded -for each revision, so sudden performance peaks or drops can be identified -and linked to a specific revision number. - -In the case of GNUnet, the buildbots log the performance data obtained -during the tests after each build. The data can be accessed on GNUnet's -Gauger page. - -The menu on the left allows to select either the results of just one -build bot (under "Hosts") or review the data from all hosts for a given -test result (under "Metrics"). In case of very different absolute value -of the results, for instance arm vs. amd64 machines, the option -"Normalize" on a metric view can help to get an idea about the -performance evolution across all hosts. - -Using Gauger in GNUnet and having the performance of a module tracked over -time is very easy. First of course, the testcase must generate some -consistent metric, which makes sense to have logged. Highly volatile or -random dependent metrics probably are not ideal candidates for meaningful -regression detection. - -To start logging any value, just include @code{gauger.h} in your testcase -code. Then, use the macro @code{GAUGER()} to make the Buildbots log -whatever value is of interest for you to @code{gnunet.org}'s Gauger -server. No setup is necessary as most Buildbots have already everything -in place and new metrics are created on demand. To delete a metric, you -need to contact a member of the GNUnet development team (a file will need -to be removed manually from the respective directory). - -The code in the test should look like this: - -@example -[other includes] -#include - -int main (int argc, char *argv[]) @{ - - [run test, generate data] - GAUGER("YOUR_MODULE", - "METRIC_NAME", - (float)value, - "UNIT"); @} -@end example - -Where: - -@table @asis - -@item @strong{YOUR_MODULE} is a category in the gauger page and should be -the name of the module or subsystem like "Core" or "DHT" -@item @strong{METRIC} is -the name of the metric being collected and should be concise and -descriptive, like "PUT operations in sqlite-datastore". -@item @strong{value} is the value -of the metric that is logged for this run. -@item @strong{UNIT} is the unit in -which the value is measured, for instance "kb/s" or "kb of RAM/node". -@end table - -If you wish to use Gauger for your own project, you can grab a copy of the -latest stable release or check out Gauger's Subversion repository. - -@cindex TESTBED Subsystem -@node TESTBED Subsystem -@section TESTBED Subsystem - -The TESTBED subsystem facilitates testing and measuring of multi-peer -deployments on a single host or over multiple hosts. - -The architecture of the testbed module is divided into the following: -@itemize @bullet - -@item Testbed API: An API which is used by the testing driver programs. It -provides with functions for creating, destroying, starting, stopping -peers, etc. - -@item Testbed service (controller): A service which is started through the -Testbed API. This service handles operations to create, destroy, start, -stop peers, connect them, modify their configurations. - -@item Testbed helper: When a controller has to be started on a host, the -testbed API starts the testbed helper on that host which in turn starts -the controller. The testbed helper receives a configuration for the -controller through its stdin and changes it to ensure the controller -doesn't run into any port conflict on that host. -@end itemize - - -The testbed service (controller) is different from the other GNUnet -services in that it is not started by ARM and is not supposed to be run -as a daemon. It is started by the testbed API through a testbed helper. -In a typical scenario involving multiple hosts, a controller is started -on each host. Controllers take up the actual task of creating peers, -starting and stopping them on the hosts they run. - -While running deployments on a single localhost the testbed API starts the -testbed helper directly as a child process. When running deployments on -remote hosts the testbed API starts Testbed Helpers on each remote host -through remote shell. By default testbed API uses SSH as a remote shell. -This can be changed by setting the environmental variable -GNUNET_TESTBED_RSH_CMD to the required remote shell program. This -variable can also contain parameters which are to be passed to the remote -shell program. For e.g: - -@example -export GNUNET_TESTBED_RSH_CMD="ssh -o BatchMode=yes \ --o NoHostAuthenticationForLocalhost=yes %h" -@end example - -Substitutions are allowed in the command string above, -this allows for substitutions through placemarks which begin with a `%'. -At present the following substitutions are supported - -@itemize @bullet -@item %h: hostname -@item %u: username -@item %p: port -@end itemize - -Note that the substitution placemark is replaced only when the -corresponding field is available and only once. Specifying - -@example -%u@@%h -@end example - -doesn't work either. If you want to user username substitutions for -@command{SSH}, use the argument @code{-l} before the -username substitution. - -For example: -@example -ssh -l %u -p %p %h -@end example - -The testbed API and the helper communicate through the helpers stdin and -stdout. As the helper is started through a remote shell on remote hosts -any output messages from the remote shell interfere with the communication -and results in a failure while starting the helper. For this reason, it is -suggested to use flags to make the remote shells produce no output -messages and to have password-less logins. The default remote shell, SSH, -the default options are: - -@example --o BatchMode=yes -o NoHostBasedAuthenticationForLocalhost=yes" -@end example - -Password-less logins should be ensured by using SSH keys. - -Since the testbed API executes the remote shell as a non-interactive -shell, certain scripts like .bashrc, .profiler may not be executed. If -this is the case testbed API can be forced to execute an interactive -shell by setting up the environmental variable -@code{GNUNET_TESTBED_RSH_CMD_SUFFIX} to a shell program. - -An example could be: - -@example -export GNUNET_TESTBED_RSH_CMD_SUFFIX="sh -lc" -@end example - -The testbed API will then execute the remote shell program as: - -@example -$GNUNET_TESTBED_RSH_CMD -p $port $dest $GNUNET_TESTBED_RSH_CMD_SUFFIX \ -gnunet-helper-testbed -@end example - -On some systems, problems may arise while starting testbed helpers if -GNUnet is installed into a custom location since the helper may not be -found in the standard path. This can be addressed by setting the variable -`@code{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 the -@file{gnunet_testbed_service.h} file and linking with -@code{-lgnunettestbed}. - -@c *********************************************************************** -@menu -* Supported Topologies:: -* Hosts file format:: -* Topology file format:: -* Testbed Barriers:: -* Automatic large-scale deployment in the PlanetLab testbed:: -* TESTBED Caveats:: -@end menu - -@node Supported Topologies -@subsection Supported Topologies - -While testing multi-peer deployments, it is often needed that the peers -are connected in some topology. This requirement is addressed by the -function @code{GNUNET_TESTBED_overlay_connect()} which connects any given -two peers in the testbed. - -The API also provides a helper function -@code{GNUNET_TESTBED_overlay_configure_topology()} to connect a given set -of peers in any of the following supported topologies: - -@itemize @bullet - -@item @code{GNUNET_TESTBED_TOPOLOGY_CLIQUE}: All peers are connected with -each other - -@item @code{GNUNET_TESTBED_TOPOLOGY_LINE}: Peers are connected to form a -line - -@item @code{GNUNET_TESTBED_TOPOLOGY_RING}: Peers are connected to form a -ring topology - -@item @code{GNUNET_TESTBED_TOPOLOGY_2D_TORUS}: Peers are connected to -form a 2 dimensional torus topology. The number of peers may not be a -perfect square, in that case the resulting torus may not have the uniform -poloidal and toroidal lengths - -@item @code{GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI}: Topology is generated -to form a random graph. The number of links to be present should be given - -@item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD}: Peers are connected to -form a 2D Torus with some random links among them. The number of random -links are to be given - -@item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING}: Peers are -connected to form a ring with some random links among them. The number of -random links are to be given - -@item @code{GNUNET_TESTBED_TOPOLOGY_SCALE_FREE}: Connects peers in a -topology where peer connectivity follows power law - new peers are -connected with high probability to well connected peers. -(See Emergence of Scaling in Random Networks. Science 286, -509-512, 1999 -(@uref{https://gnunet.org/git/bibliography.git/plain/docs/emergence_of_scaling_in_random_networks__barabasi_albert_science_286__1999.pdf, pdf})) - -@item @code{GNUNET_TESTBED_TOPOLOGY_FROM_FILE}: The topology information -is loaded from a file. The path to the file has to be given. -@xref{Topology file format}, for the format of this file. - -@item @code{GNUNET_TESTBED_TOPOLOGY_NONE}: No topology -@end itemize - - -The above supported topologies can be specified respectively by setting -the variable @code{OVERLAY_TOPOLOGY} to the following values in the -configuration passed to Testbed API functions -@code{GNUNET_TESTBED_test_run()} and -@code{GNUNET_TESTBED_run()}: - -@itemize @bullet -@item @code{CLIQUE} -@item @code{RING} -@item @code{LINE} -@item @code{2D_TORUS} -@item @code{RANDOM} -@item @code{SMALL_WORLD} -@item @code{SMALL_WORLD_RING} -@item @code{SCALE_FREE} -@item @code{FROM_FILE} -@item @code{NONE} -@end itemize - - -Topologies @code{RANDOM}, @code{SMALL_WORLD} and @code{SMALL_WORLD_RING} -require the option @code{OVERLAY_RANDOM_LINKS} to be set to the number of -random links to be generated in the configuration. The option will be -ignored for the rest of the topologies. - -Topology @code{SCALE_FREE} requires the options -@code{SCALE_FREE_TOPOLOGY_CAP} to be set to the maximum number of peers -which can connect to a peer and @code{SCALE_FREE_TOPOLOGY_M} to be set to -how many peers a peer should be at least connected to. - -Similarly, the topology @code{FROM_FILE} requires the option -@code{OVERLAY_TOPOLOGY_FILE} to contain the path of the file containing -the topology information. This option is ignored for the rest of the -topologies. @xref{Topology file format}, for the format of this file. - -@c *********************************************************************** -@node Hosts file format -@subsection Hosts file format - -The testbed API offers the function -@code{GNUNET_TESTBED_hosts_load_from_file()} to load from a given file -details about the hosts which testbed can use for deploying peers. -This function is useful to keep the data about hosts -separate instead of hard coding them in code. - -Another helper function from testbed API, @code{GNUNET_TESTBED_run()} -also takes a hosts file name as its parameter. It uses the above -function to populate the hosts data structures and start controllers to -deploy peers. - -These functions require the hosts file to be of the following format: -@itemize @bullet -@item Each line is interpreted to have details about a host -@item Host details should include the username to use for logging into the -host, the hostname of the host and the port number to use for the remote -shell program. All thee values should be given. -@item These details should be given in the following format: -@example -@@: -@end example -@end itemize - -Note that having canonical hostnames may cause problems while resolving -the IP addresses (See this bug). Hence it is advised to provide the hosts' -IP numerical addresses as hostnames whenever possible. - -@c *********************************************************************** -@node Topology file format -@subsection Topology file format - -A topology file describes how peers are to be connected. It should adhere -to the following format for testbed to parse it correctly. - -Each line should begin with the target peer id. This should be followed by -a colon(`:') and origin peer ids separated by `|'. All spaces except for -newline characters are ignored. The API will then try to connect each -origin peer to the target peer. - -For example, the following file will result in 5 overlay connections: -[2->1], [3->1],[4->3], [0->3], [2->0]@ -@code{@ 1:2|3@ 3:4| 0@ 0: 2@ } - -@c *********************************************************************** -@node Testbed Barriers -@subsection Testbed Barriers - -The testbed subsystem's barriers API facilitates coordination among the -peers run by the testbed and the experiment driver. The concept is -similar to the barrier synchronisation mechanism found in parallel -programming or multi-threading paradigms - a peer waits at a barrier upon -reaching it until the barrier is reached by a predefined number of peers. -This predefined number of peers required to cross a barrier is also called -quorum. We say a peer has reached a barrier if the peer is waiting for the -barrier to be crossed. Similarly a barrier is said to be reached if the -required quorum of peers reach the barrier. A barrier which is reached is -deemed as crossed after all the peers waiting on it are notified. - -The barriers API provides the following functions: -@itemize @bullet -@item @strong{@code{GNUNET_TESTBED_barrier_init()}:} function to -initialize a barrier in the experiment -@item @strong{@code{GNUNET_TESTBED_barrier_cancel()}:} function to cancel -a barrier which has been initialized before -@item @strong{@code{GNUNET_TESTBED_barrier_wait()}:} function to signal -barrier service that the caller has reached a barrier and is waiting for -it to be crossed -@item @strong{@code{GNUNET_TESTBED_barrier_wait_cancel()}:} function to -stop waiting for a barrier to be crossed -@end itemize - - -Among the above functions, the first two, namely -@code{GNUNET_TESTBED_barrier_init()} and -@code{GNUNET_TESTBED_barrier_cancel()} are used by experiment drivers. All -barriers should be initialised by the experiment driver by calling -@code{GNUNET_TESTBED_barrier_init()}. This function takes a name to -identify the barrier, the quorum required for the barrier to be crossed -and a notification callback for notifying the experiment driver when the -barrier is crossed. @code{GNUNET_TESTBED_barrier_cancel()} cancels an -initialised barrier and frees the resources allocated for it. This -function can be called upon a initialised barrier before it is crossed. - -The remaining two functions @code{GNUNET_TESTBED_barrier_wait()} and -@code{GNUNET_TESTBED_barrier_wait_cancel()} are used in the peer's -processes. @code{GNUNET_TESTBED_barrier_wait()} connects to the local -barrier service running on the same host the peer is running on and -registers that the caller has reached the barrier and is waiting for the -barrier to be crossed. Note that this function can only be used by peers -which are started by testbed as this function tries to access the local -barrier service which is part of the testbed controller service. Calling -@code{GNUNET_TESTBED_barrier_wait()} on an uninitialised barrier results -in failure. @code{GNUNET_TESTBED_barrier_wait_cancel()} cancels the -notification registered by @code{GNUNET_TESTBED_barrier_wait()}. - - -@c *********************************************************************** -@menu -* Implementation:: -@end menu - -@node Implementation -@subsubsection Implementation - -Since barriers involve coordination between experiment driver and peers, -the barrier service in the testbed controller is split into two -components. The first component responds to the message generated by the -barrier API used by the experiment driver (functions -@code{GNUNET_TESTBED_barrier_init()} and -@code{GNUNET_TESTBED_barrier_cancel()}) and the second component to the -messages generated by barrier API used by peers (functions -@code{GNUNET_TESTBED_barrier_wait()} and -@code{GNUNET_TESTBED_barrier_wait_cancel()}). - -Calling @code{GNUNET_TESTBED_barrier_init()} sends a -@code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_INIT} message to the master -controller. The master controller then registers a barrier and calls -@code{GNUNET_TESTBED_barrier_init()} for each its subcontrollers. In this -way barrier initialisation is propagated to the controller hierarchy. -While propagating initialisation, any errors at a subcontroller such as -timeout during further propagation are reported up the hierarchy back to -the experiment driver. - -Similar to @code{GNUNET_TESTBED_barrier_init()}, -@code{GNUNET_TESTBED_barrier_cancel()} propagates -@code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_CANCEL} message which causes -controllers to remove an initialised barrier. - -The second component is implemented as a separate service in the binary -`gnunet-service-testbed' which already has the testbed controller service. -Although this deviates from the gnunet process architecture of having one -service per binary, it is needed in this case as this component needs -access to barrier data created by the first component. This component -responds to @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT} messages from -local peers when they call @code{GNUNET_TESTBED_barrier_wait()}. Upon -receiving @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT} message, the -service checks if the requested barrier has been initialised before and -if it was not initialised, an error status is sent through -@code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message to the local -peer and the connection from the peer is terminated. If the barrier is -initialised before, the barrier's counter for reached peers is incremented -and a notification is registered to notify the peer when the barrier is -reached. The connection from the peer is left open. - -When enough peers required to attain the quorum send -@code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT} messages, the controller -sends a @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message to its -parent informing that the barrier is crossed. If the controller has -started further subcontrollers, it delays this message until it receives -a similar notification from each of those subcontrollers. Finally, the -barriers API at the experiment driver receives the -@code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} when the barrier is -reached at all the controllers. - -The barriers API at the experiment driver responds to the -@code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message by echoing it -back to the master controller and notifying the experiment controller -through the notification callback that a barrier has been crossed. The -echoed @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message is -propagated by the master controller to the controller hierarchy. This -propagation triggers the notifications registered by peers at each of the -controllers in the hierarchy. Note the difference between this downward -propagation of the @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} -message from its upward propagation --- the upward propagation is needed -for ensuring that the barrier is reached by all the controllers and the -downward propagation is for triggering that the barrier is crossed. - -@cindex PlanetLab testbed -@node Automatic large-scale deployment in the PlanetLab testbed -@subsection Automatic large-scale deployment in the PlanetLab testbed - -PlanetLab is a testbed for computer networking and distributed systems -research. It was established in 2002 and as of June 2010 was composed of -1090 nodes at 507 sites worldwide. - -To automate the GNUnet we created a set of automation tools to simplify -the large-scale deployment. We provide you a set of scripts you can use -to deploy GNUnet on a set of nodes and manage your installation. - -Please also check @uref{https://gnunet.org/installation-fedora8-svn} and -@uref{https://gnunet.org/installation-fedora12-svn} to find detailed -instructions how to install GNUnet on a PlanetLab node. - - -@c *********************************************************************** -@menu -* PlanetLab Automation for Fedora8 nodes:: -* Install buildslave on PlanetLab nodes running fedora core 8:: -* Setup a new PlanetLab testbed using GPLMT:: -* Why do i get an ssh error when using the regex profiler?:: -@end menu - -@node PlanetLab Automation for Fedora8 nodes -@subsubsection PlanetLab Automation for Fedora8 nodes - -@c *********************************************************************** -@node Install buildslave on PlanetLab nodes running fedora core 8 -@subsubsection Install buildslave on PlanetLab nodes running fedora core 8 -@c ** Actually this is a subsubsubsection, but must be fixed differently -@c ** as subsubsection is the lowest. - -Since most of the PlanetLab nodes are running the very old Fedora core 8 -image, installing the buildslave software is quite some pain. For our -PlanetLab testbed we figured out how to install the buildslave software -best. - -@c This is a very terrible way to suggest installing software. -@c FIXME: Is there an official, safer way instead of blind-piping a -@c script? -@c FIXME: Use newer pypi URLs below. -Install Distribute for Python: - -@example -curl http://python-distribute.org/distribute_setup.py | sudo python -@end example - -Install Distribute for zope.interface <= 3.8.0 (4.0 and 4.0.1 will not -work): - -@example -export PYPI=@value{PYPI-URL} -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 -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 - -The setup will download the matching twisted package and install it. -It will also try to install the latest version of zope.interface which -will fail to install. Buildslave will work anyway since version 3.8.0 -was installed before! - -@c *********************************************************************** -@node Setup a new PlanetLab testbed using GPLMT -@subsubsection Setup a new PlanetLab testbed using GPLMT - -@itemize @bullet -@item Get a new slice and assign nodes -Ask your PlanetLab PI to give you a new slice and assign the nodes you -need -@item Install a buildmaster -You can stick to the buildbot documentation:@ -@uref{http://buildbot.net/buildbot/docs/current/manual/installation.html} -@item Install the buildslave software on all nodes -To install the buildslave on all nodes assigned to your slice you can use -the tasklist @code{install_buildslave_fc8.xml} provided with GPLMT: - -@example -./gplmt.py -c contrib/tumple_gnunet.conf -t \ -contrib/tasklists/install_buildslave_fc8.xml -a -p -@end example - -@item Create the buildmaster configuration and the slave setup commands - -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 -@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: - -@itemize @bullet -@item a tasklist which can be executed with gplmt to setup the slaves -@item a master.cfg file containing a PlanetLab nodes -@end itemize - -A configuration template is included in the , most important is -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: - -@example -./create_buildbot_configuration.py -u \ --p -s -m \ --t