Fix nasa#913, include doxygen targets locally

Add the "doxyfile" templates and various OSAL doxygen pages
locally under the "doc/src" directory.  Add a CMake script
to build the documentation in either a standalone or
integrated build environment.

CMakeLists.txt

@@ -48,10 +48,10 @@ project(OSAL C)
 # part of the open source release.
 # CAUTION: The API between the OSAL and the low level implementation and/or BSP
 # is not stabilized, and may change with every OSAL release.  No attempt is made
-# to provide backward compatibility with to external sources. 
-set(OSAL_EXT_SOURCE_DIR "$ENV{OSAL_EXT_SOURCE_DIR}" 
+# to provide backward compatibility with to external sources.
+set(OSAL_EXT_SOURCE_DIR "$ENV{OSAL_EXT_SOURCE_DIR}"
     CACHE PATH "External source directory to check for additional OS/BSP implementations")
-    
+
 # Read the default compile-time configuration, and update with
 # any mission/project specific options in the OSAL_CONFIGURATION_FILE
 include("${OSAL_SOURCE_DIR}/default_config.cmake")
@@ -170,7 +170,7 @@ if (OSAL_BSP_INCLUDE_DIRECTORIES)
     include_directories(${OSAL_BSP_INCLUDE_DIRECTORIES})
 endif (OSAL_BSP_INCLUDE_DIRECTORIES)
 
-set(BSP_SRCLIST 
+set(BSP_SRCLIST
     src/bsp/shared/src/osapi-bsp.c
     src/bsp/shared/src/bsp_default_app_run.c
     src/bsp/shared/src/bsp_default_app_startup.c
@@ -351,6 +351,10 @@ if (HAS_PARENT)
     # when building code intended for coverage analysis.
     set(UT_COVERAGE_COMPILE_FLAGS "${UT_COVERAGE_COMPILE_FLAGS}" PARENT_SCOPE)
     set(UT_COVERAGE_LINK_FLAGS "${UT_COVERAGE_LINK_FLAGS}" PARENT_SCOPE)
+else(HAS_PARENT)
+    # In a standalone build, also add the documentation target(s)
+    # Note that in a CFE/integrated build, it is expected this will be built separately.
+    add_subdirectory(doc/src doc)
 endif(HAS_PARENT)
 
 

doc/src/CMakeLists.txt

@@ -0,0 +1,88 @@
+########################################################
+#
+# CMake Recipe to build OSAL API guide documentation
+#
+########################################################
+
+#
+# This CMake script currently defines a top-level target "apiguide"
+# to build the OSAL API documentation.  This may be invoked either
+# from the main OSAL CMakeLists.txt as a subdirectory (useful in the
+# case of a self-contained/standalone build) or by a separate script
+# (useful if integrating into a larger project with a separate doc build)
+#
+# To invoke from a separate documentation build, the following vars
+# should be defined by the caller, before adding this subdirectory:
+#
+# OSAL_API_INCLUDE_DIRECTORIES :
+#   The list of directories that have the OSAL API headers
+#   This should include the path to osconfig.h to avoid warnings
+#   about undefined references.
+#
+# OSALDOC_PREDEFINED :
+#   Not used directly, but passed through to the "osal-common.doxyfile"
+#   This may be used to indicate preprocessor definitions that the
+#   documentation generator tool should be aware of
+#
+# Note that OSAL_API_INCLUDE_DIRECTORIES is defined by the parent script
+# in a standalone build environment.
+#
+
+cmake_minimum_required(VERSION 3.5)
+project(OSAL_DOCS NONE)
+
+# List of dox files to include -
+# note that order is relevant here, doxygen processes in the order listed.
+set(OSAL_DOCFILE_LIST
+    ${CMAKE_CURRENT_SOURCE_DIR}/osalmain.dox
+    ${CMAKE_CURRENT_SOURCE_DIR}/osal_fs.dox
+    ${CMAKE_CURRENT_SOURCE_DIR}/osal_timer.dox
+)
+
+# For the generated Doxyfiles, the various paths should be in native form
+set(OSAL_NATIVE_APIGUIDE_SOURCEFILES)
+set(OSAL_NATIVE_INCLUDE_DIRS)
+set(OSAL_DOC_DEPENDENCY_LIST)
+
+foreach(SRC ${OSAL_DOCFILE_LIST})
+    file(TO_NATIVE_PATH "${SRC}" SRC)
+    string(APPEND OSAL_NATIVE_APIGUIDE_SOURCEFILES " \\\n  ${SRC}")
+endforeach()
+
+foreach(DIR ${OSAL_API_INCLUDE_DIRECTORIES})
+    file(GLOB OSAL_HEADERFILE_LIST ${DIR}/*.h)
+    foreach(HDR ${OSAL_HEADERFILE_LIST})
+        list(APPEND OSAL_DOC_DEPENDENCY_LIST ${HDR})
+        file(TO_NATIVE_PATH "${HDR}" HDR)
+        string(APPEND OSAL_NATIVE_APIGUIDE_SOURCEFILES " \\\n  ${HDR}")
+    endforeach()
+    file(TO_NATIVE_PATH "${DIR}" DIR)
+    string(APPEND OSAL_NATIVE_INCLUDE_DIRS " \\\n  ${DIR}")
+endforeach()
+
+file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/apiguide-warnings.log OSAL_NATIVE_LOGFILE)
+file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/osal-common.doxyfile OSAL_NATIVE_COMMON_CFGFILE)
+file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile OSAL_NATIVE_APIGUIDE_CFGFILE)
+
+# generate the configuration files
+configure_file(
+        ${CMAKE_CURRENT_SOURCE_DIR}/osal-common.doxyfile.in
+        ${CMAKE_CURRENT_BINARY_DIR}/osal-common.doxyfile
+        @ONLY
+)
+configure_file(
+        ${CMAKE_CURRENT_SOURCE_DIR}/osal-apiguide.doxyfile.in
+        ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile
+        @ONLY
+)
+
+add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/apiguide/html/index.html"
+    COMMAND doxygen ${OSAL_NATIVE_APIGUIDE_CFGFILE}
+    DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile ${OSAL_DOCFILE_LIST} ${OSAL_DOC_DEPENDENCY_LIST}
+    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+)
+
+add_custom_target(osal-apiguide
+    COMMAND echo "OSAL API Guide: file://${CMAKE_CURRENT_BINARY_DIR}/apiguide/html/index.html"
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/apiguide/html/index.html"
+)

doc/src/osal-apiguide.doxyfile.in

@@ -0,0 +1,16 @@
+#---------------------------------------------------------------------------
+# Doxygen Configuration options to generate the "OSAL API Guide"
+#---------------------------------------------------------------------------
+
+# Complete list of input files
+INPUT += @OSAL_NATIVE_APIGUIDE_SOURCEFILES@
+
+
+# Common definitions, some of which are extended or overridden here.
+@INCLUDE               = @OSAL_NATIVE_COMMON_CFGFILE@
+PROJECT_NAME           = "OSAL User's Guide"
+OUTPUT_DIRECTORY       = apiguide
+GENERATE_LATEX         = YES
+
+# output the warnings to a separate file
+WARN_LOGFILE           = @OSAL_NATIVE_LOGFILE@

doc/src/osal-common.doxyfile.in

@@ -0,0 +1,76 @@
+#---------------------------------------------------------------------------
+# Project related configuration options, shared for all cFE doxygen outputs
+#---------------------------------------------------------------------------
+@INCLUDE_PATH          = @OSAL_NATIVE_INCLUDE_DIRS@
+OUTPUT_DIRECTORY       = .
+ABBREVIATE_BRIEF       = "The $name class " \
+                         "The $name widget " \
+                         "The $name file " \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+TAB_SIZE               = 4
+OPTIMIZE_OUTPUT_FOR_C  = YES
+ALIASES               +=  nonnull="(must not be null)"
+ALIASES               +=  nonzero="(must not be zero)"
+ALIASES               +=  covtest="(return value only verified in coverage test)"
+
+PREDEFINED            += @OSALDOC_PREDEFINED@
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+CASE_SENSE_NAMES       = NO
+GENERATE_TODOLIST      = NO
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+WARN_NO_PARAMDOC       = YES
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+STRIP_FROM_PATH        = @OSAL_SOURCE_NATIVE_DIR@
+FILE_PATTERNS          = *.c *.cpp *.cc *.C *.h *.hh *.hpp *.H *.dox *.md
+RECURSIVE              = YES
+EXAMPLE_PATTERNS       = *
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_CMD_NAME         = latex
+COMPACT_LATEX          = YES
+PAPER_TYPE             = letter
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+COMPACT_RTF            = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = NO
+HAVE_DOT               = YES
+CLASS_GRAPH            = NO
+COLLABORATION_GRAPH    = NO
+INCLUDE_GRAPH          = NO
+INCLUDED_BY_GRAPH      = NO
+CALL_GRAPH             = YES
+GRAPHICAL_HIERARCHY    = NO
+MAX_DOT_GRAPH_DEPTH    = 1000
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine
+#---------------------------------------------------------------------------
+SEARCHENGINE           = NO

doc/src/osal_fs.dox

@@ -0,0 +1,94 @@
+/**
+\page osalfsovr File System Overview
+
+ The File System API is a thin wrapper around a selection of POSIX file APIs.
+ In addition the File System API presents a common directory structure and
+ volume view regardless of the underlying system type. For example, vxWorks
+ uses MS-DOS style volume names and directories where a vxWorks RAM disk might
+ have the volume “RAM:0”. With this File System API, volumes are represented
+ as Unix-style paths where each volume is mounted on the root file system:
+
+ <UL>
+    <LI>RAM:0/file1.dat becomes /mnt/ram/file1.dat
+    <LI>FL:0/file2.dat becomes /mnt/fl/file2.dat
+ </UL>
+
+ This abstraction allows the applications to use the same paths regardless of
+ the implementation and it also allows file systems to be simulated on a desktop
+ system for testing. On a desktop Linux system, the file system abstraction can
+ be set up to map virtual devices to a regular directory. This is accomplished
+ through the OS_mkfs call, OS_mount call, and a BSP specific volume table that
+ maps the virtual devices to real devices or underlying file systems.
+
+ In order to make this file system volume abstraction work, a “Volume Table”
+ needs to be provided in the Board Support Package of the application. The table
+ has the following fields:
+
+ <UL>
+   <LI> Device Name: This is the name of the virtual device that the Application
+        uses. Common names are “ramdisk1”, “flash1”, or “volatile1” etc. But the
+        name can be any unique string.
+   <LI> Physical Device Name: This is an implementation specific field. For
+        vxWorks it is not needed and can be left blank. For a File system based
+        implementation, it is the “mount point” on the root file system where all
+        of the volume will be mounted. A common place for this on Linux could
+        be a user’s home directory, “/tmp”, or even the current working
+        directory “.”. In the example of “/tmp” all of the directories created
+        for the volumes would be under “/tmp” on the Linux file system. For a real
+        disk device in Linux, such as a RAM disk, this field is the device
+        name “/dev/ram0”.
+   <LI> Volume Type: This field defines the type of volume. The types are:
+        FS_BASED which uses the existing file system, RAM_DISK which uses a
+        RAM_DISK device in vxWorks, RTEMS, or Linux, FLASH_DISK_FORMAT which uses
+        a flash disk that is to be formatted before use, FLASH_DISK_INIT which
+        uses a flash disk with an existing format that is just to be initialized
+        before it’s use, EEPROM which is for an EEPROM or PROM based system.
+   <LI> Volatile Flag: This flag indicates that the volume or disk is a volatile
+        disk (RAM disk ) or a non-volatile disk, that retains its contents when
+        the system is rebooted. This should be set to TRUE or FALSE.
+   <LI> Free Flag: This is an internal flag that should be set to FALSE or zero.
+   <LI> Is Mounted Flag: This is an internal flag that should be set to FALSE
+        or zero. Note that a “pre-mounted” FS_BASED path can be set up by setting
+        this flag to one.
+   <LI> Volume Name: This is an internal field and should be set to a space
+        character “ “.
+   <LI> Mount Point Field: This is an internal field and should be set to a space
+        character “ “.
+   <LI> Block Size Field: This is used to record the block size of the device and
+        does not need to be set by the user.
+ </UL>
+**/
+
+/**
+\page osalfsfd File Descriptors In Osal
+
+ The OSAL uses abstracted file descriptors. This means that the file descriptors
+ passed back from the OS_open and OS_creat calls will only work with other OSAL OS_*
+ calls. The reasoning for this is as follows:
+
+ Because the OSAL now keeps track of all file descriptors, OSAL specific information
+ can be associated with a specific file descriptor in an OS independent way. For
+instance, the path of the file that the file descriptor points to can be easily
+  retrieved. Also, the OSAL task ID of the task that opened the file can also be
+ retrieved easily.  Both of these pieces of information are very useful when trying
+ to determine statistics for a task, or the entire system. This information can all
+ be retrieved with a single API, OS_FDGetInfo.
+
+ All of possible file system calls are not implemented.  "Special" files requiring OS
+ specific control/operations are by nature not portable.  Abstraction in this case is
+ is not possible, so the raw OS calls should be used (including open/close/etc).  Mixing
+ with OSAL calls is not supported for such cases.  #OS_TranslatePath is available to
+ support using open directly by an app and maintain abstraction on the file system.
+
+ There are some small drawbacks with the OSAL file descriptors. Because the related
+ information is kept in a table, there is a define called OS_MAX_NUM_OPEN_FILES that
+ defines the maximum number of file descriptors available. This is a configuration
+parameter, and can be changed to fit your needs.
+
+ Also, if you open or create a file not using the OSAL calls (OS_open or OS_creat)
+ then none of the other OS_* calls that accept a file descriptor as a parameter will
+work (the results of doing so are undefined). Therefore, if you open a file with
+ the underlying OS's open call, you must continue to use the OS's calls until you
+ close the file descriptor. Be aware that by doing this your software may no longer
+ be OS agnostic.
+**/

doc/src/osal_timer.dox

@@ -0,0 +1,8 @@
+/**
+ \page osaltimerover Timer Overview
+
+ The timer API is a generic interface to the OS timer facilities. It is
+ implemented using the POSIX timers on Linux and vxWorks and the native timer
+ API on RTEMS. The number of timers supported is controlled by the configuration
+ parameter OS_MAX_TIMERS.
+**/