Merge pull request nasa#566 from nasa/integration-candidate

Integration Candidate 2020-03-18

README.md

@@ -5,6 +5,11 @@ This repository contains NASA's Core Flight Executive (cFE), which is a framewor
 This is a collection of services and associated framework to be located in the `cfe` subdirectory of a cFS Mission Tree.  The Core Flight System is bundled at https://github.com/nasa/cFS, which includes build and execution instructions.
 
 ## Version Notes
+
+- 6.7.11: DEVELOPMENT
+  - Improve documentation
+  - Update makefile to report branch coverage
+  - Minor other updates (see https://github.com/nasa/cFE/pull/566)
 - 6.7.10: DEVELOPMENT
   - Fix potential unit test problems with name collisions
   - Improve documentation

cmake/Makefile.sample

@@ -16,33 +16,33 @@
 # repository which is why it cannot be delivered directly in place.
 # To use it, simply copy it to the top directory.  As this just contains
 # wrappers for the CMake targets, it is unlikely to change.  Projects
-# are also free to customize this file and add their own targets after 
+# are also free to customize this file and add their own targets after
 # copying it to the top of the source tree.
 #
-# For _ALL_ targets defined in this file the build tree location may 
-# be specified via the "O" variable (i.e. make O=<my-build-dir> all).  
-# If not specified then the "build" subdirectory will be assumed. 
+# For _ALL_ targets defined in this file the build tree location may
+# be specified via the "O" variable (i.e. make O=<my-build-dir> all).
+# If not specified then the "build" subdirectory will be assumed.
 #
 # This wrapper defines the following major targets:
 #  prep -- Runs CMake to create a new or re-configure an existing build tree
 #    Note that multiple build trees can exist from a single source
-#    Other control options (such as "SIMULATION") may be passed to CMake via 
+#    Other control options (such as "SIMULATION") may be passed to CMake via
 #    make variables depending on the mission build scripts.  These will be
-#    cached in the build tree so they do not need to be set again thereafter. 
+#    cached in the build tree so they do not need to be set again thereafter.
 #
 #  all -- Build all targets in the CMake build tree
-#          
+#
 #  install -- Copy all files to the installation tree and run packaging scripts
-#     The "DESTDIR" environment variable controls where the files are copied        
+#     The "DESTDIR" environment variable controls where the files are copied
 #
 #  clean -- Clean all targets in the CMake build tree, but not the build tree itself.
 #
-#  distclean -- Entirely remove the build directory specified by "O" 
+#  distclean -- Entirely remove the build directory specified by "O"
 #      Note that after this the "prep" step must be run again in order to build.
 #      Use caution with this as it does an rm -rf - don't set O to your home dir!
 #
 #  doc -- Build all doxygen source documentation.  The HTML documentation will be
-#      generated under the build tree specified by "O". 
+#      generated under the build tree specified by "O".
 #
 #  usersguide -- Build all API/Cmd/Tlm doxygen documentation.  The HTML documentation
 #      will be generated under the build tree specified by "O".
@@ -53,7 +53,7 @@
 #  test -- Run all unit tests defined in the build.  Unit tests will typically only
 #      be executable when building with the "SIMULATION=native" option.  Otherwise
 #      it is up to the user to copy the executables to the target and run them.
-#  
+#
 #  lcov -- Runs the "lcov" tool on the build tree to collect all code coverage
 #      analysis data and build the reports.  Code coverage data may be output by
 #      the "make test" target above.
@@ -91,7 +91,7 @@ $(DIRTGTS):
 endif
 
 # For any other goal that is not one of the known local targets, pass it to the arch build
-# as there might be a target by that name.  For example, this is useful for rebuilding 
+# as there might be a target by that name.  For example, this is useful for rebuilding
 # single unit test executable files while debugging from the IDE
 FILETGTS := $(filter-out $(DIRTGTS),$(OTHERTGTS))
 ifneq ($(FILETGTS),)
@@ -103,7 +103,7 @@ endif
 # Certain special ones should be passed via cache (-D) options to CMake.
 # These are only needed for the "prep" target but they are computed globally anyway.
 PREP_OPTS :=
- 
+
 ifneq ($(INSTALLPREFIX),)
 PREP_OPTS += -DCMAKE_INSTALL_PREFIX=$(INSTALLPREFIX)
 endif
@@ -125,7 +125,7 @@ install:
 prep $(O)/.prep:
 	mkdir -p "$(O)"
 	(cd "$(O)/$(BUILDDIR)" && cmake $(PREP_OPTS) "$(CURDIR)/cfe")
-	echo "$(PREP_OPTS)" > "$(O)/.prep"  
+	echo "$(PREP_OPTS)" > "$(O)/.prep"
 
 clean:
 	$(MAKE) --no-print-directory -C "$(O)" mission-clean
@@ -139,10 +139,9 @@ test:
 	(cd $(O)/$(ARCH) && ctest -O ctest.log)
 
 lcov:
-	lcov --capture --directory $(O)/$(ARCH) --output-file $(O)/$(ARCH)/coverage_test.info
-	lcov --add-tracefile $(O)/$(ARCH)/coverage_base.info --add-tracefile $(O)/$(ARCH)/coverage_test.info --output-file $(O)/$(ARCH)/coverage_total.info
-	lcov --remove $(O)/$(ARCH)/coverage_total.info 'unit-test/*' --output-file $(O)/$(ARCH)/coverage_filtered.info
-	genhtml $(O)/$(ARCH)/coverage_filtered.info --output-directory $(O)/$(ARCH)/lcov
+	lcov --capture --rc lcov_branch_coverage=1 --directory $(O)/$(ARCH) --output-file $(O)/$(ARCH)/coverage_test.info
+	lcov --rc lcov_branch_coverage=1 --add-tracefile $(O)/$(ARCH)/coverage_base.info --add-tracefile $(O)/$(ARCH)/coverage_test.info --output-file $(O)/$(ARCH)/coverage_total.info
+	genhtml $(O)/$(ARCH)/coverage_total.info --output-directory $(O)/$(ARCH)/lcov
 	@/bin/echo -e "\n\nCoverage Report Link: file:$(CURDIR)/$(O)/$(ARCH)/lcov/index.html\n"
 
 doc:
@@ -155,11 +154,10 @@ usersguide:
 
 osalguide:
 	$(MAKE) --no-print-directory -C "$(O)" osalguide
-	@/bin/echo -e "\n\nOsal Users Guide: \nfile://$(CURDIR)/$(O)/doc/osal_guide/html/index.html\n"
+	@/bin/echo -e "\n\nOsal Users Guide: \nfile://$(CURDIR)/$(O)/doc/osalguide/html/index.html\n"
 
 # Make all the commands that use the build tree depend on a flag file
 # that is used to indicate the prep step has been done.  This way
 # the prep step does not need to be done explicitly by the user
 # as long as the default options are sufficient.
-$(filter-out prep distclean,$(LOCALTGTS)): $(O)/.prep 
-
+$(filter-out prep distclean,$(LOCALTGTS)): $(O)/.prep

cmake/cfe-common.doxyfile.in

@@ -7,7 +7,7 @@ CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
 OUTPUT_DIRECTORY       = .
 BRIEF_MEMBER_DESC      = YES
-REPEAT_BRIEF           = NO
+REPEAT_BRIEF           = YES
 ABBREVIATE_BRIEF       = "The $name class " \
                          "The $name widget " \
                          "The $name file " \
@@ -30,13 +30,6 @@ INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 8
 ALIASES               += "event=\xrefitem cfeevents \"Event Message\" \"cFE Event Message Cross Reference\" " \
-                         "retdesc=<TD WIDTH=\"80%\"> " \
-                         "retcode=<TR><TD WIDTH=\"20%\" VALIGN=TOP> " \
-                         endcode=</TR> \
-                         "returns=\return <TABLE BORDER=\"0\" CELLPADDING=\"2\" WIDTH=\"100%\"> " \
-                         endreturns=</TABLE> \
-                         "retstmt=<TR><TD COLSPAN=2 WIDTH=\"100%\"> " \
-                         endstmt=</TR> \
                          "cfeescfg=\xrefitem cfeescfg \"Purpose\" \"cFE Executive Services Configuration Parameters\" " \
                          "cfeevscfg=\xrefitem cfeevscfg \"Purpose\" \"cFE Event Services Configuration Parameters\" " \
                          "cfetblcfg=\xrefitem cfetblcfg \"Purpose\" \"cFE Table Services Configuration Parameters\" " \
@@ -54,8 +47,8 @@ ALIASES               += "event=\xrefitem cfeevents \"Event Message\" \"cFE Even
                          "cfeevstlm=\xrefitem cfeevstlm \"Name\" \"cFE Event Services Telemetry\" " \
                          "cfesbtlm=\xrefitem cfesbtlm \"Name\" \"cFE Software Bus Telemetry\" " \
                          "cfetimetlm=\xrefitem cfetimetlm \"Name\" \"cFE Time Services Telemetry\" " \
-                         "cfecmdmnemonic=\xrefitem cfecmdmnems \"Command Mnemonic(s)\" \"cFE Command Mnemonic Cross Reference\" \b \c " \
-                         "cfetlmmnemonic=\xrefitem cfetlmmnems \"Telemetry Mnemonic(s)\" \"cFE Telemetry Mnemonic Cross Reference\" \b \c "
+                         "cfecmdmnemonic=\xrefitem cfecmdmnems \"Command Mnemonic(s)\" \"cFE Command Mnemonic Cross Reference\" " \
+                         "cfetlmmnemonic=\xrefitem cfetlmmnems \"Telemetry Mnemonic(s)\" \"cFE Telemetry Mnemonic Cross Reference\" "
 OPTIMIZE_OUTPUT_FOR_C  = YES
 OPTIMIZE_OUTPUT_JAVA   = NO
 BUILTIN_STL_SUPPORT    = NO

cmake/cfe-usersguide.doxyfile.in

@@ -2,8 +2,10 @@
 # Doxygen Configuration options to generate the "cFE Users Guide"
 #---------------------------------------------------------------------------
 
-# Start with the common definitions, some of which are extended or overridden here.
+# Start with the main page so document ordering is established
+INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox
 
+# Common definitions, some of which are extended or overridden here.
 @INCLUDE               = @MISSION_BINARY_DIR@/doc/cfe-common.doxyfile
 PROJECT_NAME           = "Core Flight Executive Users Guide"
 OUTPUT_DIRECTORY       = users_guide
@@ -15,10 +17,6 @@ GENERATE_LATEX         = YES
 STRIP_FROM_PATH       += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs
 INPUT                 += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs
 
-# Main page for the users guide
-INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox 
-INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_usersguide.dox
-
 #PREDEFINED
 PREDEFINED            += @USERGUIDE_PREDEFINED@
 

cmake/osal-common.doxyfile.in

@@ -7,7 +7,7 @@ CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
 OUTPUT_DIRECTORY       = .
 BRIEF_MEMBER_DESC      = YES
-REPEAT_BRIEF           = NO
+REPEAT_BRIEF           = YES
 ABBREVIATE_BRIEF       = "The $name class " \
                          "The $name widget " \
                          "The $name file " \

cmake/osalguide.doxyfile.in

@@ -2,21 +2,17 @@
 # Doxygen Configuration options to generate the "OSAL API Guide"
 #---------------------------------------------------------------------------
 
-# Start with the common definitions, some of which are extended or overridden here.
+# Start with the main page so document ordering is established
+INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/osalmain.dox
 
+# Common definitions, some of which are extended or overridden here.
 @INCLUDE               = @MISSION_BINARY_DIR@/doc/osal-common.doxyfile
-PROJECT_NAME           = "Core Flight Executive OSAL API Guide"
+PROJECT_NAME           = "OSAL User's Guide"
 OUTPUT_DIRECTORY       = osalguide
 GENERATE_LATEX         = YES
 
-# Main page for the osal guide
-INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/osalmain.dox 
-INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/osalguide.dox
-
 #PREDEFINED
 PREDEFINED            += @OSALGUIDE_PREDEFINED@
 
 # Bring in the cFE header files for the documentation of the various API calls
-INPUT                 += \
-@MISSION_OSAL_HEADERFILES@ \
-@OSAL_MISC_ADDITION@                
+INPUT                 += @MISSION_OSAL_HEADERFILES@

cmake/sample_defs/cpu1_platform_cfg.h

@@ -126,8 +126,8 @@
 **       Dictates the size of the SB memory pool. For each message the SB
 **       sends, the SB dynamically allocates from this memory pool, the memory needed
 **       to process the message. The memory needed to process each message is msg
-**       size + msg descriptor(#CFE_SB_BufferD_t). This memory pool is also used
-**       to allocate destination descriptors (#CFE_SB_DestinationD_t) during the
+**       size + msg descriptor(CFE_SB_BufferD_t). This memory pool is also used
+**       to allocate destination descriptors (CFE_SB_DestinationD_t) during the
 **       subscription process.
 **       To see the run-time, high-water mark and the current utilization figures
 **       regarding this parameter, send an SB command to 'Send Statistics Pkt'.
@@ -788,7 +788,7 @@
 **       log ER Log and critical reset variables. This is 4 of 4 of the memory areas
 **       that are preserved during a processor reset.
 **       Note: This area must be sized large enough to hold all of the data
-**       structures. It should be automatically sized based on the #CFE_ES_ResetData_t
+**       structures. It should be automatically sized based on the CFE_ES_ResetData_t
 **       type, but circular dependancies in the headers prevent it from being defined
 **       this way.
 **       NOTE: Changing this value changes memory allocation, and may