From 1f2f13c9f6f01b1044540371ee7d9d709da7d6a9 Mon Sep 17 00:00:00 2001 From: Tushar Gohad Date: Wed, 3 Sep 2014 15:45:38 -0700 Subject: [PATCH 1/4] Constrain Doxygen to just the frontend/backend API headers Signed-off-by: Tushar Gohad --- doc/Doxyfile | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index 11fce98..7a4c36b 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -140,7 +140,7 @@ INLINE_INHERITED_MEMB = NO # shortest path that makes the file name unique will be used # The default value is: YES. -FULL_PATH_NAMES = YES +FULL_PATH_NAMES = NO # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. # Stripping is only done if one of the specified strings matches the left-hand @@ -242,7 +242,7 @@ TCL_SUBST = # members will be omitted, etc. # The default value is: NO. -OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_FOR_C = YES # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or # Python sources only. Doxygen will then generate output that is more tailored @@ -427,7 +427,7 @@ EXTRACT_PACKAGE = NO # included in the documentation. # The default value is: NO. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, @@ -460,7 +460,7 @@ EXTRACT_ANON_NSPACES = NO # section is generated. This option has no effect if EXTRACT_ALL is enabled. # The default value is: NO. -HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_MEMBERS = YES # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set @@ -751,7 +751,8 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = "../src" "../include" +INPUT = ../include/erasurecode/erasurecode.h \ + ../include/erasurecode/erasurecode_backend.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -973,7 +974,7 @@ USE_HTAGS = NO # See also: Section \class. # The default value is: YES. -VERBATIM_HEADERS = YES +VERBATIM_HEADERS = NO #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index From 942f1e701dedea12f2387da2db4ef4c3cb559024 Mon Sep 17 00:00:00 2001 From: Tushar Gohad Date: Sat, 6 Sep 2014 22:26:52 -0700 Subject: [PATCH 2/4] Use printable ascii chars in README + other cleanup Signed-off-by: Tushar Gohad --- README.md | 179 ++++++++++++++++++++++++------------------------------ 1 file changed, 79 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index ca3febf..b2be7b5 100644 --- a/README.md +++ b/README.md @@ -43,56 +43,23 @@ Backend Support --------------- ``` c -/* =~=*=~==~=*=~==~=*=~= Supported EC backends =~=*=~==~=*=~==~=*=~==~=*=~== */ typedef enum { - EC_BACKEND_NULL = 0, - EC_BACKEND_JERASURE_RS_VAND = 1, - EC_BACKEND_JERASURE_RS_CAUCHY = 2, - EC_BACKEND_FLAT_XOR_HD = 3, + EC_BACKEND_NULL = 0, /* "null" */ + EC_BACKEND_JERASURE_RS_VAND = 1, /* "jerasure_rs_vand" */ + EC_BACKEND_JERASURE_RS_CAUCHY = 2, /* "jerasure_rs_cauchy" */ + EC_BACKEND_FLAT_XOR_HD = 3, /* "flat_xor_hd */ EC_BACKENDS_MAX, } ec_backend_id_t; -/* Supported EC backends */ -static const char *ec_backend_names[EC_BACKENDS_MAX] = { - "null", - "jerasure_rs_vand", - "jerasure_rs_cauchy", - "flat_xor_hd", -}; ``` ---- -Erasure Code Fragment Checksum Support --------------------------------------- - -``` c - -/* ~=*=~==~=*=~= EC Fragment metadata - supported checksum types ~=*=~==~=*=~ */ - -/* Checksum types supported for fragment metadata stored in each fragment */ -typedef enum { - CHKSUM_NONE = 0, - CHKSUM_CRC32 = 1, - CHKSUM_MD5 = 2, - CHKSUM_TYPES_MAX, -} ec_checksum_type_t; - -/* Supported checksum types */ -static const char *ec_chksum_types[CHKSUM_TYPES_MAX] = { - "none", - "crc32", - "md5", -}; -``` ----- - User Arguments -------------- ``` c -/* =~=*=~==~=*=~== EC Arguments - Common and backend-specific =~=*=~==~=*=~== */ /** * Common and backend-specific args @@ -118,6 +85,7 @@ struct ec_args { * future backend args */ ec_checksum_type_t ct; /* fragment checksum type */ }; + ``` --- @@ -126,7 +94,6 @@ User-facing API Functions ------------------------- ``` c -/* =~=*=~==~=*=~== liberasurecode frontend API functions =~=*=~==~=~=*=~==~= */ /* liberasurecode frontend API functions */ @@ -298,11 +265,29 @@ int liberasurecode_fragments_needed(int desc, int *fragments_to_exclude, int *fragments_needed); +``` -/* ==~=*=~==~=*=~== liberasurecode fragment metadata routines ==~*==~=*=~==~ */ +Erasure Code Fragment Checksum Types Supported +---------------------------------------------- -#define LIBERASURECODE_MAX_CHECKSUM_LEN 8 -typedef struct __attribute__((__packed__)) +``` c + +/* Checksum types supported for fragment metadata stored in each fragment */ +typedef enum { + CHKSUM_NONE = 0, /* "none" (default) */ + CHKSUM_CRC32 = 1, /* "crc32" */ + CHKSUM_MD5 = 2, /* "md5" */ + CHKSUM_TYPES_MAX, +} ec_checksum_type_t; + +``` + +Erasure Code Fragment Checksum API +---------------------------------- + +``` c + +struct fragment_metadata { uint32_t idx; /* 4 */ @@ -313,8 +298,6 @@ fragment_metadata uint8_t chksum_mismatch; /* 1 */ } fragment_metadata_t; -#define FRAGSIZE_2_BLOCKSIZE(fragment_size) \ - (fragment_size - sizeof(fragment_header_t)) /** * Get opaque metadata for a fragment. The metadata is opaque to the @@ -345,8 +328,6 @@ int liberasurecode_get_fragment_metadata(int desc, int liberasurecode_verify_stripe_metadata(int desc, char **fragments, int num_fragments); -/* ==~=*=~===~=*=~==~=*=~== liberasurecode Helpers ==~*==~=*=~==~=~=*=~==~= */ - /** * This computes the aligned size of a buffer passed into * the encode function. The encode function must pad fragments @@ -372,6 +353,7 @@ int liberasurecode_get_aligned_data_size(int desc, uint64_t data_len); * @return minimum data length length, or -error code on error */ int liberasurecode_get_minimum_encode_size(int desc); + ``` ---- @@ -379,18 +361,15 @@ Error Codes ----------- ``` c -/* ==~=*=~===~=*=~==~=*=~== liberasurecode Error codes =~=*=~==~=~=*=~==~== */ /* Error codes */ typedef enum { - EBACKENDNOTSUPP = 200, - EECMETHODNOTIMPL = 201, - EBACKENDINITERR = 202, - EBACKENDINUSE = 203, - EBACKENDNOTAVAIL = 204, + EBACKENDNOTSUPP = 200, /* EC Backend not supported by the library */ + EECMETHODNOTIMPL = 201, /* EC Backend method not implemented */ + EBACKENDINITERR = 202, /* EC Backend could not be initialized */ + EBACKENDINUSE = 203, /* EC Backend in use (locked) */ } LIBERASURECODE_ERROR_CODES; -/* =~=*=~==~=*=~==~=*=~==~=*=~===~=*=~==~=*=~===~=*=~==~=*=~===~=*=~==~=*=~= */ ``` --- @@ -413,54 +392,54 @@ top-level directory: Code organization ================= ``` - ├── include - │   ├── erasurecode - │   │   ├── erasurecode.h --> liberasurecode frontend API header - │   │   └── erasurecode_backend.h --> liberasurecode backend API header - │   └── xor_codes --> headers for the built-in XOR codes - | - ├── src - │   ├── erasurecode.c --> liberasurecode API implementation - | | (frontend + backend) - │   ├── backends - │   │   └── null - │   │   └─── null.c --> 'null' erasure code backend - │   │   └── xor - │   │   └─── flat_xor_hd.c --> 'flat_xor_hd' erasure code backend - │   │   └── jerasure - │   │      ├── jerasure_rs_cauchy.c --> 'jerasure_rs_vand' erasure code backend - │   │      └── jerasure_rs_vand.c --> 'jerasure_rs_cauchy' erasure code backend - | | - │   ├── builtin - │   │   └── xor_codes --> XOR HD code backend, built-in erasure - | | | code implementation (shared library) - │   │   ├── xor_code.c - │   │   └── xor_hd_code.c - | | - │   └── utils - │   └── chksum --> fragment checksum utils for erasure - │   ├── alg_sig.c coded fragments - │   └── crc32.c - | - ├── doc --> API Documentation - │   ├── Doxyfile - │   └── html - | - └─── test --> Test routines - │    ├── builtin - |    │   └── xor_codes - │    ├── liberasurecode_test.c - │    └── utils - | - ├── autogen.sh - ├── configure.ac - ├── Makefile.am - ├── README - ├── NEWS - ├── COPYING - ├── AUTHORS - ├── INSTALL - └── ChangeLog + |-- include + | +-- erasurecode + | | +-- erasurecode.h --> liberasurecode frontend API header + | | +-- erasurecode_backend.h --> liberasurecode backend API header + | +-- xor_codes --> headers for the built-in XOR codes + | + |-- src + | |-- erasurecode.c --> liberasurecode API implementation + | | (frontend + backend) + | |-- backends + | | +-- null + | | +--- null.c --> 'null' erasure code backend + | | +-- xor + | | +--- flat_xor_hd.c --> 'flat_xor_hd' erasure code backend + | | +-- jerasure + | | +-- jerasure_rs_cauchy.c --> 'jerasure_rs_vand' erasure code backend + | | +-- jerasure_rs_vand.c --> 'jerasure_rs_cauchy' erasure code backend + | | + | |-- builtin + | | +-- xor_codes --> XOR HD code backend, built-in erasure + | | | code implementation (shared library) + | | +-- xor_code.c + | | +-- xor_hd_code.c + | | + | +-- utils + | +-- chksum --> fragment checksum utils for erasure + | +-- alg_sig.c coded fragments + | +-- crc32.c + | + |-- doc --> API Documentation + | +-- Doxyfile + | +-- html + | + |--- test --> Test routines + | +-- builtin + | | +-- xor_codes + | +-- liberasurecode_test.c + | +-- utils + | + |-- autogen.sh + |-- configure.ac + |-- Makefile.am + |-- README + |-- NEWS + |-- COPYING + |-- AUTHORS + |-- INSTALL + +-- ChangeLog ``` --- From 2a103711fafd7258420c478130c6e850b23698d2 Mon Sep 17 00:00:00 2001 From: Tushar Gohad Date: Sun, 7 Sep 2014 08:06:01 -0700 Subject: [PATCH 3/4] Turn on Javadoc style brief for comments --- doc/Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index 7a4c36b..08c0a43 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -177,7 +177,7 @@ SHORT_NAMES = NO # description.) # The default value is: NO. -JAVADOC_AUTOBRIEF = NO +JAVADOC_AUTOBRIEF = YES # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If From c85e1bacd36ca83ece37d70ae63409d010aef0cf Mon Sep 17 00:00:00 2001 From: Tushar Gohad Date: Sun, 7 Sep 2014 08:49:05 -0700 Subject: [PATCH 4/4] Integrate doxygen with autoconf infrastructure Signed-off-by: Tushar Gohad --- .gitignore | 5 ++++ Makefile.am | 3 +- aclocal.m4 | 40 ++++++++++++++++++++++++++ configure.ac | 48 ++++++++++++++++++++++++++++++-- doc/Makefile.am | 36 ++++++++++++++++++++++++ doc/{Doxyfile => doxygen.cfg.in} | 8 +++--- 6 files changed, 132 insertions(+), 8 deletions(-) create mode 100644 doc/Makefile.am rename doc/{Doxyfile => doxygen.cfg.in} (99%) diff --git a/.gitignore b/.gitignore index 24fafc3..fb2a4e9 100644 --- a/.gitignore +++ b/.gitignore @@ -44,3 +44,8 @@ config_liberasurecode.h.in .deps config_liberasurecode.h stamp-h1 + +# doxygen documentation +^doc/.*\.doxytag +^doc/html +^doc/doxygen.cfg diff --git a/Makefile.am b/Makefile.am index b7ec5dc..6787508 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,7 +1,8 @@ # Top-level liberasurecode automake configuration ACLOCAL_AMFLAGS = -I m4 -SUBDIRS = src test +SUBDIRS = src test doc + EXTRA_DIST = autogen.sh INCLUDE = -I$(abs_top_builddir)/include \ diff --git a/aclocal.m4 b/aclocal.m4 index 9bbc37a..f338346 100644 --- a/aclocal.m4 +++ b/aclocal.m4 @@ -114,6 +114,46 @@ AC_PREREQ([2.50])dnl am_aux_dir=`cd $ac_aux_dir && pwd` ]) +# AM_COND_IF -*- Autoconf -*- + +# Copyright (C) 2008, 2010 Free Software Foundation, Inc. +# +# This file is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# serial 3 + +# _AM_COND_IF +# _AM_COND_ELSE +# _AM_COND_ENDIF +# -------------- +# These macros are only used for tracing. +m4_define([_AM_COND_IF]) +m4_define([_AM_COND_ELSE]) +m4_define([_AM_COND_ENDIF]) + + +# AM_COND_IF(COND, [IF-TRUE], [IF-FALSE]) +# --------------------------------------- +# If the shell condition COND is true, execute IF-TRUE, otherwise execute +# IF-FALSE. Allow automake to learn about conditional instantiating macros +# (the AC_CONFIG_FOOS). +AC_DEFUN([AM_COND_IF], +[m4_ifndef([_AM_COND_VALUE_$1], + [m4_fatal([$0: no such condition "$1"])])dnl +_AM_COND_IF([$1])dnl +if test -z "$$1_TRUE"; then : + m4_n([$2])[]dnl +m4_ifval([$3], +[_AM_COND_ELSE([$1])dnl +else + $3 +])dnl +_AM_COND_ENDIF([$1])dnl +fi[]dnl +]) + # AM_CONDITIONAL -*- Autoconf -*- # Copyright (C) 1997, 2000, 2001, 2003, 2004, 2005, 2006, 2008 diff --git a/configure.ac b/configure.ac index 80e1ab4..751e588 100644 --- a/configure.ac +++ b/configure.ac @@ -1,3 +1,6 @@ +################################################################################ +# Standard Stuff +################################################################################ AC_INIT(liberasurecode,0.9.10) AC_GNU_SOURCE @@ -25,13 +28,20 @@ AC_PROG_MAKE_SET AX_EXT() +################################################################################ +# System Headers +################################################################################ dnl Check for C library headers AC_HEADER_STDC -AC_CHECK_HEADERS(sys/types.h stdio.h stdlib.h stddef.h stdarg.h malloc.h memory.h \ - string.h strings.h inttypes.h stdint.h ctype.h math.h iconv.h \ - signal.h dlfcn.h pthread.h unistd.h limits.h errno.h syslog.h) +AC_CHECK_HEADERS(sys/types.h stdio.h stdlib.h stddef.h stdarg.h \ + malloc.h memory.h string.h strings.h inttypes.h \ + stdint.h ctype.h math.h iconv.h signal.h dlfcn.h \ + pthread.h unistd.h limits.h errno.h syslog.h) AC_CHECK_FUNCS(malloc calloc realloc free openlog) +################################################################################# +# Debug/coverage Options +################################################################################# AC_ARG_ENABLE([debug], [ --enable-debug Turn on debugging], [case "${enableval}" in @@ -74,15 +84,47 @@ dnl Expand the sources and objects needed to build the library AC_SUBST(ac_aux_dir) AC_SUBST(OBJECTS) +################################################################################# +# Doxygen Documentation +################################################################################# +AC_CHECK_PROG(DOXYGEN, doxygen, true, false) +AM_CONDITIONAL(HAVE_DOXYGEN, $DOXYGEN) +AC_SUBST(HAVE_DOXYGEN) + +dnl Let people disable the doxygen stuff. +AC_ARG_ENABLE(doxygen, [ --enable-doxygen Use doxygen to build documentation (default=auto)], + enable_doxygen="$enableval", + enable_doxygen=auto) + +if test x$enable_doxygen = xauto ; then + if test x$DOXYGEN = xtrue ; then + enable_doxygen=yes + else + enable_doxygen=no + fi +fi + +dnl NOTE: We need to use a separate automake conditional for this +dnl to make this work with the tarballs. +AM_CONDITIONAL(ENABLE_DOXYGEN, test x$enable_doxygen = xyes) + +################################################################################ +# Output Files +################################################################################ AC_CONFIG_FILES([\ src/builtin/null_code/Makefile \ src/builtin/xor_codes/Makefile \ src/Makefile \ test/Makefile \ + doc/Makefile \ Makefile \ erasurecode.pc \ Xorcode.pc ]) +AM_CONDITIONAL([HAVE_DOXYGEN], [test -n "$DOXYGEN"]) +AM_COND_IF([HAVE_DOXYGEN], + [AC_CONFIG_FILES([doc/doxygen.cfg])]) + AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..aea521f --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,36 @@ +DOC_MODULE="liberasurecode" +HTML_DIR=$(datadir)/$(DOC_MODULE)/html +TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) + +all-local: html/index.html + +if ENABLE_DOXYGEN +html/index.html: doxygen.cfg + doxygen doxygen.cfg +else +html/index.html: +endif + +clean-local: + rm -f *~ *.bak + rm -rf html + +install-data-local: html + $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR) + (installfiles=`echo html/*`; \ + if test "$$installfiles" = 'html/*'; \ + then echo '-- Nothing to install' ; \ + else \ + for i in $$installfiles; do \ + echo '-- Installing '$$i ; \ + $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \ + done; \ + fi) + +dist-hook: + mkdir $(distdir)/html + mkdir $(distdir)/man + -cp html/* $(distdir)/html + -cp man/* $(distdir)/man + +.PHONY : html latex man diff --git a/doc/Doxyfile b/doc/doxygen.cfg.in similarity index 99% rename from doc/Doxyfile rename to doc/doxygen.cfg.in index 08c0a43..ec2c87d 100644 --- a/doc/Doxyfile +++ b/doc/doxygen.cfg.in @@ -32,13 +32,13 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "liberasurecode" +PROJECT_NAME = @PACKAGE_NAME@ # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = +PROJECT_NUMBER = @PACKAGE_VERSION@ # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -751,8 +751,8 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = ../include/erasurecode/erasurecode.h \ - ../include/erasurecode/erasurecode_backend.h +INPUT = @top_srcdir@/include/erasurecode/erasurecode.h \ + @top_srcdir@/include/erasurecode/erasurecode_backend.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses