From 179c186e19d76a8e3057d653998fe38d0ba3791f Mon Sep 17 00:00:00 2001 From: "Jon A. Cruz" Date: Wed, 15 Jul 2015 19:22:43 -0700 Subject: [PATCH] Adding doxygen setup and info for the testing framework. Signed-off-by: Jon A. Cruz Reviewed-by: Pekka Paalanen --- .gitignore | 2 + Makefile.am | 22 +++++++++ README | 6 +++ configure.ac | 20 ++++++++ doc/doxygen/devtools.dox | 51 ++++++++++++++++++++ doc/doxygen/tooldev.doxygen.in | 11 +++++ doc/doxygen/tools.dox | 31 +++++++++++++ doc/doxygen/tools.doxygen.in | 10 ++++ doc/doxygen/tools_arch_new.gv | 85 ++++++++++++++++++++++++++++++++++ doc/doxygen/tools_arch_old.gv | 53 +++++++++++++++++++++ 10 files changed, 291 insertions(+) create mode 100644 doc/doxygen/devtools.dox create mode 100644 doc/doxygen/tooldev.doxygen.in create mode 100644 doc/doxygen/tools.dox create mode 100644 doc/doxygen/tools.doxygen.in create mode 100644 doc/doxygen/tools_arch_new.gv create mode 100644 doc/doxygen/tools_arch_old.gv diff --git a/.gitignore b/.gitignore index 2e6a9e2b..b13bf553 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,8 @@ cscope.out /config.sub /configure /depcomp +/docs/developer +/docs/tools /install-sh /libtool /ltmain.sh diff --git a/Makefile.am b/Makefile.am index e8b76c26..a3590c06 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1058,6 +1058,7 @@ WESTON_LOG_COMPILER = $(srcdir)/tests/weston-tests-env clean-local: -rm -rf logs + -rm -rf $(DOCDIRS) # To remove when automake 1.11 support is dropped export abs_builddir @@ -1352,6 +1353,27 @@ EXTRA_DIST += \ CLEANFILES += $(man_MANS) +if ENABLE_DEVDOCS +DOXYGEN_INDICES = docs/developer/html/index.html docs/tools/html/index.html + +docs/developer/html/index.html: doc/doxygen/tooldev.doxygen | docs/developer + cd doc/doxygen && $(DOXYGEN) tooldev.doxygen + +docs/tools/html/index.html: doc/doxygen/tools.doxygen | docs/tools + cd doc/doxygen && $(DOXYGEN) tools.doxygen +endif + +DOCDIRS = \ + docs/developer \ + docs/tools + +$(DOCDIRS): + $(MKDIR_P) $@ + +.PHONY: doc $(DOXYGEN_INDICES) + +doc: $(DOXYGEN_INDICES) + protocol/%-protocol.c : $(top_srcdir)/protocol/%.xml $(AM_V_GEN)$(MKDIR_P) $(dir $@) && $(wayland_scanner) code < $< > $@ diff --git a/README b/README index 97a552c9..3fdfb37f 100644 --- a/README +++ b/README @@ -18,6 +18,12 @@ weston and its dependencies. The test suite can be invoked via `make check`; see http://wayland.freedesktop.org/testing.html for additional details. +Developer documentation can be built via `make doc`. Output will be in +the build root under + +docs/developer/html/index.html +docs/tools/html/index.html + Libweston diff --git a/configure.ac b/configure.ac index d24fb0b4..e5bbc0d7 100644 --- a/configure.ac +++ b/configure.ac @@ -61,6 +61,25 @@ AC_CHECK_FUNCS([mkostemp strchrnul initgroups posix_fallocate]) COMPOSITOR_MODULES="wayland-server >= 1.8.0 pixman-1 >= 0.25.2" +AC_CONFIG_FILES([doc/doxygen/tools.doxygen doc/doxygen/tooldev.doxygen]) + +AC_ARG_ENABLE(devdocs, + AS_HELP_STRING([--disable-devdocs], + [do not enable building of developer documentation]),, + enable_devdocs=auto) +if test "x$enable_devdocs" != "xno"; then + AC_CHECK_PROGS([DOXYGEN], [doxygen]) + if test "x$DOXYGEN" = "x" -a "x$enable_devdocs" = "xyes"; then + AC_MSG_ERROR([Developer documentation explicitly requested, but Doxygen couldn't be found]) + fi + if test "x$DOXYGEN" != "x"; then + enable_devdocs=yes + else + enable_devdocs=no + fi +fi +AM_CONDITIONAL(ENABLE_DEVDOCS, test "x$enable_devdocs" = "xyes") + AC_ARG_ENABLE(egl, [ --disable-egl],, enable_egl=yes) AM_CONDITIONAL(ENABLE_EGL, test x$enable_egl = xyes) @@ -549,6 +568,7 @@ AC_MSG_RESULT([ Build wcap utility ${enable_wcap_tools} Build Fullscreen Shell ${enable_fullscreen_shell} + Enable developer documentation ${enable_devdocs} weston-launch utility ${enable_weston_launch} systemd-login support ${have_systemd_login} diff --git a/doc/doxygen/devtools.dox b/doc/doxygen/devtools.dox new file mode 100644 index 00000000..2d6672fb --- /dev/null +++ b/doc/doxygen/devtools.dox @@ -0,0 +1,51 @@ +/* + * Copyright © 2015 Samsung Electronics Co., Ltd + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files (the + * "Software"), to deal in the Software without restriction, including + * without limitation the rights to use, copy, modify, merge, publish, + * distribute, sublicense, and/or sell copies of the Software, and to + * permit persons to whom the Software is furnished to do so, subject to + * the following conditions: + * + * The above copyright notice and this permission notice (including the + * next paragraph) shall be included in all copies or substantial + * portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +/** +@mainpage + +- @ref zunitc - Simple test framework + +@section tools_overview Overview + +The tools area currently consists of one sub-project (@ref zunitc) that is +refined from the prior single weston/tests source folder. + +@subsection tools_overview_old Old Code Organization + +The original 'tests' folder contained basic weston testing with an +integrated test runner framework. Over time things progressed to the +stage where splitting apart into discrete layers was warranted. + +@dotfile tools_arch_old.gv "Original test code organization" + +@subsection tools_overview_new New Code Organization + +The test code that is not weston-specific gets split out to a separate +folder and/or folders. + +@dotfile tools_arch_new.gv "Refactored test code organization" + +*/ diff --git a/doc/doxygen/tooldev.doxygen.in b/doc/doxygen/tooldev.doxygen.in new file mode 100644 index 00000000..8b033b32 --- /dev/null +++ b/doc/doxygen/tooldev.doxygen.in @@ -0,0 +1,11 @@ +PROJECT_NAME = "Tool Internals" +OUTPUT_DIRECTORY = @top_builddir@/docs/developer +JAVADOC_AUTOBRIEF = YES +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_ALL = YES +INPUT = \ + @top_srcdir@/doc/doxygen/devtools.dox \ + @top_srcdir@/tools/zunitc +RECURSIVE = YES +GENERATE_LATEX = NO +DOTFILE_DIRS = @top_srcdir@/doc/doxygen diff --git a/doc/doxygen/tools.dox b/doc/doxygen/tools.dox new file mode 100644 index 00000000..9bbc11d6 --- /dev/null +++ b/doc/doxygen/tools.dox @@ -0,0 +1,31 @@ +/* + * Copyright © 2015 Samsung Electronics Co., Ltd + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files (the + * "Software"), to deal in the Software without restriction, including + * without limitation the rights to use, copy, modify, merge, publish, + * distribute, sublicense, and/or sell copies of the Software, and to + * permit persons to whom the Software is furnished to do so, subject to + * the following conditions: + * + * The above copyright notice and this permission notice (including the + * next paragraph) shall be included in all copies or substantial + * portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +/** +@mainpage + +- @ref zunitc - Simple test framework + +*/ diff --git a/doc/doxygen/tools.doxygen.in b/doc/doxygen/tools.doxygen.in new file mode 100644 index 00000000..1b3b078d --- /dev/null +++ b/doc/doxygen/tools.doxygen.in @@ -0,0 +1,10 @@ +PROJECT_NAME = "Tools" +OUTPUT_DIRECTORY = @top_builddir@/docs/tools +JAVADOC_AUTOBRIEF = YES +OPTIMIZE_OUTPUT_FOR_C = YES +INPUT = \ + @top_srcdir@/doc/doxygen/tools.dox \ + @top_srcdir@/tools/zunitc/doc/zunitc.dox \ + @top_srcdir@/tools/zunitc/inc/zunitc/zunitc.h +GENERATE_LATEX = NO +DOTFILE_DIRS = @top_srcdir@/doc/doxygen diff --git a/doc/doxygen/tools_arch_new.gv b/doc/doxygen/tools_arch_new.gv new file mode 100644 index 00000000..e4626f3f --- /dev/null +++ b/doc/doxygen/tools_arch_new.gv @@ -0,0 +1,85 @@ +/* + * Copyright © 2015 Samsung Electronics Co., Ltd + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files (the + * "Software"), to deal in the Software without restriction, including + * without limitation the rights to use, copy, modify, merge, publish, + * distribute, sublicense, and/or sell copies of the Software, and to + * permit persons to whom the Software is furnished to do so, subject to + * the following conditions: + * + * The above copyright notice and this permission notice (including the + * next paragraph) shall be included in all copies or substantial + * portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +digraph toolarch_new { + rankdir = "TB"; + + node[shape=record] + + subgraph cluster_0 { + label = "./tests"; + + keyboard_test_c [label = "{keyboard-test.c|tests\l}"] + text_test_c [label = "{text-test.c|tests\l}"] + vertex_clip_test_c [label = "{vertex-clip-test.c|tests\l}"] + + spacer [shape = point, style = invis] + + weston_test_client_helper [label = "{weston-test-client-helper.h/.c|Weston test protocol\l}"] + + weston_test_c [label = "{weston-test.c|Extension protocol\nimplementation}"] + } + + subgraph cluster_1 { + label = "./tools/waycheck"; + + waycheck [label = "{waycheck.c| \n \n }"] + } + + subgraph cluster_2 { + label = "./tools/wayland_fixtures"; + + wtst_fixtures [label = "{wtst_fixtures.h/c|Wayland tracking structs\lWayland callbacks\l}"] + } + + subgraph cluster_3 { + label = "./tools/zunitc"; + + zunitc [label = "{zunitc|Test definition macros\lTest running functions\lTest reporting functions\lTest run lifecycle\l}"] + } + + keyboard_test_c -> weston_test_client_helper + keyboard_test_c -> wtst_fixtures + keyboard_test_c -> zunitc + vertex_clip_test_c -> zunitc + text_test_c -> weston_test_client_helper + text_test_c -> wtst_fixtures + text_test_c -> zunitc + + waycheck -> wtst_fixtures + waycheck -> zunitc + + wtst_fixtures -> zunitc + + edge [style = dashed, arrowhead = open] + weston_test_client_helper -> weston_test_c + + edge [style = invis] + weston_test_client_helper -> zunitc + + text_test_c -> spacer + keyboard_test_c -> spacer + spacer -> weston_test_client_helper +} diff --git a/doc/doxygen/tools_arch_old.gv b/doc/doxygen/tools_arch_old.gv new file mode 100644 index 00000000..1b381232 --- /dev/null +++ b/doc/doxygen/tools_arch_old.gv @@ -0,0 +1,53 @@ +/* + * Copyright © 2015 Samsung Electronics Co., Ltd + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files (the + * "Software"), to deal in the Software without restriction, including + * without limitation the rights to use, copy, modify, merge, publish, + * distribute, sublicense, and/or sell copies of the Software, and to + * permit persons to whom the Software is furnished to do so, subject to + * the following conditions: + * + * The above copyright notice and this permission notice (including the + * next paragraph) shall be included in all copies or substantial + * portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +digraph toolarch_old { + rankdir = "TB"; + + node[shape = record] + + subgraph cluster_0 { + label = "./tests"; + + keyboard_test_c [label = "{keyboard-test.c|tests\l}"] + text_test_c [label = "{text-test.c|tests\l}"] + vertex_clip_test_c [label = "{vertex-clip-test.c|tests\l}"] + + weston_test_client_helper [label = "{weston-test-client-helper.h/.c|Wayland tracking structs\lWeston test protocol\lWayland callbacks\lTest run lifecycle\l}"] + + weston_test_c [label = "{weston-test.c|Extension protocol\nimplementation}"] + weston_test_runner [label = "{weston-test-runner.h/.c|Test definition macros\lTest running functions\lTest reporting functions\lTest run lifecycle\l}"] + } + + weston_test_client_helper -> weston_test_runner + keyboard_test_c -> weston_test_client_helper + keyboard_test_c -> weston_test_runner + vertex_clip_test_c -> weston_test_runner + text_test_c -> weston_test_client_helper + text_test_c -> weston_test_runner + + edge [style = dashed, arrowhead = open] + weston_test_client_helper -> weston_test_c +}