Clean up in response to Scott's request to make another pass over my …

…changes.

external/Apr1Lib.cmake

@@ -31,7 +31,7 @@
 include(../src/NupicLibraryUtils) # for MERGE_STATIC_LIBRARIES
 
 
-# Output static library link target name
+# Output static library target for linking and dependencies
 set(APR1_STATIC_LIB_TARGET apr-1-bundle)
 
 

external/AprUtil1Lib.cmake

@@ -31,7 +31,7 @@
 include(../src/NupicLibraryUtils) # for MERGE_STATIC_LIBRARIES
 
 
-# Output static library link target name
+# Output static library target for linking and dependencies
 set(APRUTIL1_STATIC_LIB_TARGET aprutil-1-bundle)
 
 

external/CapnProto.cmake

@@ -23,21 +23,26 @@
 #
 # OUTPUT VARIABLES:
 #
-# CAPNP_STATIC_LIB_TARGET: name of static library target that contains all of
-#                          capnproto library objects.
+#   CAPNP_STATIC_LIB_TARGET: name of static library target that contains all of
+#                            capnproto library objects.
 #
-# CAPNP_INCLUDE_DIRS
-# CAPNP_EXECUTABLE
-# CAPNPC_CXX_EXECUTABLE
-# CAPNP_CMAKE_DEFINITIONS: informational; platform-specific cmake defintions
-#                          used by capnproto build
-# CAPNP_COMPILER_DEFINITIONS: list of -D compiler defintions needed by apps that
-#                             are built against this library (e.g., -DCAPNP_LITE)
+#   CAPNP_INCLUDE_DIRS
+#   CAPNP_EXECUTABLE
+#   CAPNPC_CXX_EXECUTABLE
+#   CAPNP_CMAKE_DEFINITIONS: informational; platform-specific cmake defintions
+#                            used by capnproto build
+#   CAPNP_COMPILER_DEFINITIONS: list of -D compiler defintions needed by apps
+#                               that are built against this library (e.g.,
+#                               -DCAPNP_LITE)
+#
+# EXPORTED FUNCTIONS:
+#
+#   CREATE_CAPNPC_COMMAND: Create a custom command that runs the capnp compiler.
 
 include(../src/NupicLibraryUtils) # for MERGE_STATIC_LIBRARIES
 
 
-# Output static library link target name
+# Output static library target for linking and dependencies
 set(CAPNP_STATIC_LIB_TARGET capnp-bundle)
 
 set(capnp_lib_url
@@ -122,8 +127,8 @@ endif()
 
 function(CREATE_CAPNPC_COMMAND
          SPEC_FILES SRC_PREFIX INCLUDE_DIR TARGET_DIR OUTPUT_FILES)
-  # Creates the custom command that runs the capnp compiler
-  # on ${SPEC_FILES} and generates ${OUTPUT_FILES} in directory ${TARGET_DIR}
+  # Create a custom command that runs the capnp compiler on ${SPEC_FILES} and
+  # generates ${OUTPUT_FILES} in directory ${TARGET_DIR}
 
   set(dependencies ${SPEC_FILES} CapnProto)
 

external/YamlCppLib.cmake

@@ -30,7 +30,7 @@
 include(../src/NupicLibraryUtils) # for MERGE_STATIC_LIBRARIES
 
 
-# Output static library link target name
+# Output static library target for linking and dependencies
 set(YAML_CPP_STATIC_LIB_TARGET yaml-cpp-bundle)
 
 

external/YamlLib.cmake

@@ -29,7 +29,7 @@
 include(../src/NupicLibraryUtils) # for MERGE_STATIC_LIBRARIES
 
 
-# Output static library link target name
+# Output static library target for linking and dependencies
 set(YAML_STATIC_LIB_TARGET yaml-bundle)
 
 

external/Zlib.cmake

@@ -30,7 +30,7 @@
 include(../src/NupicLibraryUtils) # for MERGE_STATIC_LIBRARIES
 
 
-# Output static library link target name
+# Output static library target for linking and dependencies
 set(Z_STATIC_LIB_TARGET z-bundle)
 
 

src/CMakeLists.txt

@@ -535,7 +535,7 @@ set_target_properties(${src_executable_hellosptp}
 
 
 #
-# Setup gtest-based unit tests
+# Setup gtests
 #
 set(src_executable_gtests unit_tests)
 add_executable(${src_executable_gtests}
@@ -677,14 +677,13 @@ if (${NUPIC_BUILD_PYEXT_MODULES})
   # symbols should be available automatically when python loads the extension.
   #
   # NOTE We don't link our non-Windows python extensions with capnproto static
-  # lib to force runtime linkage to pycapnp's capnproto symbols in order to
-  # avoid the conflict of executing the methods in our own
+  # lib in order to force runtime linkage to pycapnp's capnproto symbols thus
+  # avoiding the conflict of executing the methods in our own
   # compilation of capnproto (different compiler/STL/version, flags, etc.) on
-  # objects created by pycapnp's. Instead, we force dynamic linkage to pycapnp's
+  # objects created by pycapnp's. We force runtime linking to pycapnp's
   # capnproto symbols by preloading the pycapnp extension in our extension
   # python proxy modules, thus avoiding the conflict from executing the methods
-  # in our own compilation of capnproto (different compiler, flags, etc.) on
-  # objects created by pycapnp's.
+  # in our own compilation of capnproto on objects created by pycapnp's.
   set(src_swig_link_libraries
       ${src_lib_static_nupiccore_combined}
       ${src_common_os_libs})
@@ -699,8 +698,8 @@ if (${NUPIC_BUILD_PYEXT_MODULES})
   #
   # NOTE On Windows nupic.bindings builds, we include capnproto because we
   # presently build self-contained CAPNP_LITE on Windows, and Windows
-  # nupic/nupic.bindings presently have no dependency on pycapnp; however, all
-  # symbols have to resolve locally within each Windows Python extension DLL.
+  # nupic/nupic.bindings presently have no dependency on pycapnp. We also inclue
+  # PYTHON_LIBRARIES because all symbols have to resolve when building a DLL.
   if("${PLATFORM}" STREQUAL "windows")
     list(APPEND src_swig_link_libraries
          ${PYTHON_LIBRARIES}
@@ -882,9 +881,6 @@ foreach(directory ${CAPNP_INCLUDE_DIRS})
           DESTINATION include)
 endforeach()
 
-#install(FILES ${src_lib_static_nupiccore_combined}
-#        DESTINATION lib)
-
 install(DIRECTORY nupic/py_support DESTINATION include/nupic
         FILES_MATCHING PATTERN "*.c*")
 install(DIRECTORY nupic DESTINATION include/nupic

src/CombineUnixArchives.cmake

@@ -19,15 +19,18 @@
 # http://numenta.org/licenses/
 # -----------------------------------------------------------------------------
 
-# Combine multiple Unix static libraries into a single static library
+# Combine multiple Unix static libraries into a single static library.
+#
+# This script is intended to be invoked via `${CMAKE_COMMAND} -DLIB_TARGET= ...`.
 #
 # ARGS:
 #
 #   LIB_TARGET: target name of resulting static library (passed to add_library)
 #   TARGET_LOCATION: Full path to the target library
 #   SRC_LIB_LOCATIONS: List of source static library paths
 #   LIST_SEPARATOR: separator string that separates paths in
-#     SRC_LIB_LOCATIONS; NOTE with cmake 2.8.11+, caller could use "$<SEMICOLON>"
+#     SRC_LIB_LOCATIONS; NOTE with cmake 2.8.11+, caller could use the generator
+#     "$<SEMICOLON>" in SRC_LIB_LOCATIONS, and this arg would be unnecessary.
 #   BINARY_DIR: The value of ${CMAKE_CURRENT_BINARY_DIR} from caller
 #   CMAKE_AR: The value of ${CMAKE_AR} from caller
 

src/ConcatTwoFiles.cmake

@@ -22,11 +22,13 @@
 # Concatenates two files into a target file, overwriting target file if already
 # exists; either of the source files may be the same path as the target file.
 
+# This script is intended to be invoked via `${CMAKE_COMMAND} -DSRC_FILE_1= ...`.
+
 # ARGS:
 #
-#  SRC_FILE_1: path of first source file
-#  SRC_FILE_2: path of second source file
-#  TARGET_FILE: path of target file
+#  SRC_FILE_1: path of first source file; may be same as TARGET_FILE.
+#  SRC_FILE_2: path of second source file; may be same as TARGET_FILE.
+#  TARGET_FILE: path of target file.
 
 
 function(CONCAT_TWO_FILES SRC_FILE_1 SRC_FILE_2 TARGET_FILE)

src/NupicLibraryUtils.cmake

@@ -138,4 +138,3 @@ function(MERGE_STATIC_LIBRARIES LIB_TARGET STATIC_LIBS)
   endif()
 
 endfunction(MERGE_STATIC_LIBRARIES)
-