From b585097048884e063ac25aecc26a6802ee3faa4d Mon Sep 17 00:00:00 2001 From: Chris Luke Date: Tue, 3 May 2016 16:34:59 -0400 Subject: [PATCH] VPP-57 Add Doxygen to VPP - Configures Doxygen. - Adds a source filter to do magic on our use of the preprocessor to do constructor stuff to make Doxygen grok it better. - Adds a convenience helper to the root Makefile. - Adds a README.md to the root directory (and which Doxygem uses as its "mainpage". - Add several other documentative files. - Currently using SVG for call graphs, though this may have a load-time performance impact in browsers. Change-Id: I25fc6fb5bf634319dcb36a7f0e32031921c125ac Signed-off-by: Chris Luke --- .gitignore | 3 + Makefile | 25 + README.md | 94 ++ doxygen/assets/doxy-vpp.css | 47 + doxygen/assets/logo_fdio.png | Bin 0 -> 3092 bytes doxygen/dir.dox.sample | 6 + doxygen/doxygen.cfg | 2433 ++++++++++++++++++++++++++++++++++++++++++ doxygen/filter_c.py | 37 + doxygen/layout.xml | 194 ++++ svm/dir.dox | 5 + vlib/dir.dox | 5 + vlib/example/dir.dox | 6 + vlib/vlib/dir.dox | 5 + vlib/vlib/unix/cli.c | 176 ++- vpp/vnet/main.c | 8 - vppinfra/dir.dox | 3 + vppinfra/tools/dir.dox | 3 + vppinfra/vppinfra/dir.dox | 3 + vppinfra/vppinfra/vec.h | 4 +- 19 files changed, 2996 insertions(+), 61 deletions(-) create mode 100644 README.md create mode 100644 doxygen/assets/doxy-vpp.css create mode 100644 doxygen/assets/logo_fdio.png create mode 100644 doxygen/dir.dox.sample create mode 100644 doxygen/doxygen.cfg create mode 100755 doxygen/filter_c.py create mode 100644 doxygen/layout.xml create mode 100644 svm/dir.dox create mode 100644 vlib/dir.dox create mode 100644 vlib/example/dir.dox create mode 100644 vlib/vlib/dir.dox create mode 100644 vppinfra/dir.dox create mode 100644 vppinfra/tools/dir.dox create mode 100644 vppinfra/vppinfra/dir.dox diff --git a/.gitignore b/.gitignore index a104623c240..e3182fd9c80 100644 --- a/.gitignore +++ b/.gitignore @@ -57,3 +57,6 @@ test-driver # cscope and ctags /cscope.* /tags + +# Generated documentation +/build-root/docs diff --git a/Makefile b/Makefile index 8050f876e5e..dee25667db6 100644 --- a/Makefile +++ b/Makefile @@ -39,7 +39,9 @@ endif RPM_DEPENDS_GROUPS = 'Development Tools' RPM_DEPENDS = redhat-lsb glibc-static java-1.8.0-openjdk-devel yum-utils RPM_DEPENDS += openssl-devel https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm apr-devel +#RPM_DEPENDS += doxygen # TODO EPEL_DEPENDS = libconfuse-devel ganglia-devel +#EPEL_DEPENDS += graphviz # TODO ifneq ($(wildcard $(STARTUP_DIR)/startup.conf),) STARTUP_CONF ?= $(STARTUP_DIR)/startup.conf @@ -209,3 +211,26 @@ ctags: ctags.files cscope: cscope.files @cscope -b -q -v + +DOXY_INPUT = \ + README.md \ + vppinfra \ + svm \ + vlib \ + vlib-api \ + vnet \ + vpp \ + vpp-api + +.PHONY: doxygen +doxygen: + @mkdir -p "$(BR)/docs" + ROOT="$(WS_ROOT)" \ + BUILD_ROOT="$(BR)" \ + INPUT="$(addprefix $(WS_ROOT)/,$(DOXY_INPUT))" \ + HTML=YES \ + VERSION="`git describe --tags --dirty`" \ + doxygen doxygen/doxygen.cfg + +wipe-doxygen: + rm -rf "$(BR)/docs" diff --git a/README.md b/README.md new file mode 100644 index 00000000000..2a71d27e10e --- /dev/null +++ b/README.md @@ -0,0 +1,94 @@ +Vector Packet Processing +======================== + +## Introduction. + +The VPP platform is an extensible framework that provides out-of-the-box +production quality switch/router functionality. It is the open source version +of Cisco's Vector Packet Processing (VPP) technology: a high performance, +packet-processing stack that can run on commodity CPUs. + +The benefits of this implementation of VPP are its high performance, proven +technology, its modularity and flexibility, and rich feature set. + +For more information on VPP and its features please visit the +[FD.io website](http://fd.io/) and +[What is VPP?](https://wiki.fd.io/view/VPP/What_is_VPP%3F) pages. + + +## Directory layout. + +Directory name | Description +---------------------- | ------------------------------------------- + build-data | Build metadata + build-root | Build output directory + doxygen | Documentation generator configuration + dpdk | DPDK patches and build infrastructure + g2 | Event log visualization tool + gmod | perf related? + perftool | Performance tool + sample-plugin | A sample plugin +@ref svm | Shared virtual memory allocation library + test | Unit tests +@ref vlib | VPP application library source +@ref vlib-api | VPP API library source +@ref vnet | VPP networking source +@ref vpp | VPP application source +@ref vpp-api | VPP application API source + vppapigen | VPP API generator source + vpp-api-test | VPP API test program source +@ref vppinfra | VPP core library source + +(If the page you are viewing is not generated by Doxygen then +ignore any @@ref labels in the above table.) + + +## Getting started. + +In general anyone interested in building, developing or running VPP should +consult the [VPP wiki](https://wiki.fd.io/view/VPP) for more complete +documentation. + +In particular, readers are recommended to take a look at [Pulling, Building, +Running, Hacking, Pushing](https://wiki.fd.io/view/VPP/Pulling,_Building,_Run +ning,_Hacking_and_Pushing_VPP_Code) which provides extensive step-by-step +coverage of the topic. + +For the impatient, some salient information is distilled below. + + +### Quick-start: On an existing Linux host. + +To install system dependencies, build VPP and then install it, simply run the +build script. This should be performed a non-privileged user with `sudo` +access from the project base directory: + + ./build-root/vagrant/build.sh + +If you want a more fine-grained approach because you intend to do some +development work, the `Makefile` in the root directory of the source tree +provides several convenience shortcuts as `make` targets that may be of +interest. To see the available targets run: + + make + + +### Quick-start: Vagrant. + +The directory `build-root/vagrant` contains a `VagrantFile` and supporting +scripts to bootstrap a working VPP inside a Vagrant-managed Virtual Machine. +This VM can then be used to test concepts with VPP or as a development +platform to extend VPP. Some obvious caveats apply when using a VM for VPP +since its performance will never match that of bare metal; if your work is +timing or performance sensitive, consider using bare metal in addition or +instead of the VM. + +For this to work you will need a working installation of Vagrant. Instructions +for this can be found [on the Setting up Vagrant wiki page] +(https://wiki.fd.io/view/DEV/Setting_Up_Vagrant). + + +## More information. + +Visit the [VPP wiki](https://wiki.fd.io/view/VPP) for details on more +advanced building strategies and development notes. diff --git a/doxygen/assets/doxy-vpp.css b/doxygen/assets/doxy-vpp.css new file mode 100644 index 00000000000..3b74eb6f66b --- /dev/null +++ b/doxygen/assets/doxy-vpp.css @@ -0,0 +1,47 @@ +/* VPP CSS overrides */ + +body, table, div, p, dl { + font: initial; + font-family: Lucida Grande, Verdana, Geneva, Arial, sans-serif; + font-size: small; +} + +code, tt { + font: initial; + font-family: Consolas, Courier, monospace; + font-size: small; +} + +pre { + font-size: 105%; +} + + +.title { + font: initial; + font-family: Lucida Grande, Verdana, Geneva, Arial, sans-serif; + font-size: 150%; + font-weight: bold; +} + + +.mdescLeft, .mdescRight, +.memItemLeft, .memItemRight, +.memTemplItemLeft, .memTemplItemRight, .memTemplParams { + font-family: Consolas, Courier, monospace; +} + +.memname { + font-family: Consolas, Courier, monospace; + font-weight: bold; + font-size: 105%; +} + +.paramname { + font-family: Consolas, Courier, monospace; + font-weight: bold; +} + +a.el { + font-family: Consolas, Courier, monospace; +} diff --git a/doxygen/assets/logo_fdio.png b/doxygen/assets/logo_fdio.png new file mode 100644 index 0000000000000000000000000000000000000000..ddfef2c733558a51ab83712d13ee9ba33282b425 GIT binary patch literal 3092 zcmV+v4D0iWP)004R>004l5008;`004mK004C`008P>0026e000+ooVrmw00006 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