Merge pull request #81 from NeurodataWithoutBorders/plugin-related-up…

…dates

integration related updates

.codespellrc

@@ -2,6 +2,6 @@
 builtin = clear,rare,en-GB_to_en-US,names,informal,code
 check-filenames =
 check-hidden =
-skip = */.git,*/build,*/prefix,*/resources,*/.vscode,*/libs
+skip = */.git,*/build,*/prefix,*/resources,*/.vscode,*/libs,*/spec,
 quiet-level = 2
 ignore-words=./.codespell_ignore

CMakeLists.txt

@@ -6,7 +6,7 @@ endif()
 include(cmake/prelude.cmake)
 
 project(
-    aq-nwb
+    aqnwb
     VERSION 0.1.0
     DESCRIPTION "An API to acquire neurophysiology data in the NWB format"
     LANGUAGES CXX
@@ -18,7 +18,7 @@ include(cmake/variables.cmake)
 # ---- Declare library ----
 
 add_library(
-    aq-nwb_lib OBJECT
+    aqnwb_aqnwb
     src/BaseIO.cpp
     src/Channel.cpp
     src/hdf5/HDF5IO.cpp
@@ -29,20 +29,53 @@ add_library(
     src/nwb/ecephys/ElectricalSeries.cpp
     src/nwb/file/ElectrodeGroup.cpp
     src/nwb/file/ElectrodeTable.cpp
-    src/nwb/hdmf/base/Data.hpp
     src/nwb/hdmf/base/Container.cpp
     src/nwb/hdmf/table/DynamicTable.cpp
-    src/nwb/hdmf/table/ElementIdentifiers.hpp
-    src/nwb/hdmf/table/VectorData.hpp
+)
+
+add_library(aqnwb::aqnwb ALIAS aqnwb_aqnwb)
+
+include(GenerateExportHeader)
+generate_export_header(
+    aqnwb_aqnwb
+    BASE_NAME aqnwb
+    EXPORT_FILE_NAME export/aqnwb/aqnwb_export.hpp
+    CUSTOM_CONTENT_FROM_VARIABLE pragma_suppress_c4251
+)
+
+if(NOT BUILD_SHARED_LIBS)
+  target_compile_definitions(aqnwb_aqnwb PUBLIC SHARED_STATIC_DEFINE)
+endif()
+
+set_target_properties(
+    aqnwb_aqnwb PROPERTIES
+    CXX_VISIBILITY_PRESET hidden
+    VISIBILITY_INLINES_HIDDEN YES
+    VERSION "${PROJECT_VERSION}"
+    SOVERSION "${PROJECT_VERSION_MAJOR}"
+    EXPORT_NAME aqnwb
+    OUTPUT_NAME aqnwb
+)
+
+target_include_directories(
+    aqnwb_aqnwb ${warning_guard}
+    PUBLIC
+    "\$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>"
+)
+
+target_include_directories(
+    aqnwb_aqnwb ${warning_guard}
+    PUBLIC
+    "\$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/src>"
 )
 
 target_include_directories(
-    aq-nwb_lib ${warning_guard}
+    aqnwb_aqnwb SYSTEM
     PUBLIC
-    "$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/src>"
+    "\$<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/export>"
 )
 
-target_compile_features(aq-nwb_lib PUBLIC cxx_std_17)
+target_compile_features(aqnwb_aqnwb PUBLIC cxx_std_17)
 
 # ---- Additional libraries needed ----
 find_package(HDF5 REQUIRED COMPONENTS CXX)
@@ -51,7 +84,7 @@ include_directories(${HDF5_INCLUDE_DIRS})
 find_package(Boost REQUIRED)
 include_directories(${Boost_INCLUDE_DIRS})
 
-target_link_libraries(aq-nwb_lib ${HDF5_CXX_LIBRARIES} ${Boost_LIBRARIES})
+target_link_libraries(aqnwb_aqnwb ${HDF5_CXX_LIBRARIES} ${Boost_LIBRARIES})
 
 # ---- Install rules ----
 
@@ -61,12 +94,12 @@ endif()
 
 # ---- Developer mode ----
 
-if(NOT aq-nwb_DEVELOPER_MODE)
+if(NOT aqnwb_DEVELOPER_MODE)
   return()
 elseif(NOT PROJECT_IS_TOP_LEVEL)
   message(
       AUTHOR_WARNING
-      "Developer mode is intended for developers of aq-nwb"
+      "Developer mode is intended for developers of aqnwb"
   )
 endif()
 

CMakePresets.json

@@ -26,7 +26,7 @@
       "hidden": true,
       "inherits": "cmake-pedantic",
       "cacheVariables": {
-        "aq-nwb_DEVELOPER_MODE": "ON"
+        "aqnwb_DEVELOPER_MODE": "ON"
       }
     },
     {

cmake/install-config.cmake

@@ -0,0 +1 @@
+include("${CMAKE_CURRENT_LIST_DIR}/aqnwbTargets.cmake")

cmake/install-rules.cmake

@@ -1,3 +1,71 @@
 if(PROJECT_IS_TOP_LEVEL)
-  include(CPack)
+  set(
+      CMAKE_INSTALL_INCLUDEDIR "include/aqnwb-${PROJECT_VERSION}"
+      CACHE STRING ""
+  )
+  set_property(CACHE CMAKE_INSTALL_INCLUDEDIR PROPERTY TYPE PATH)
 endif()
+
+include(CMakePackageConfigHelpers)
+include(GNUInstallDirs)
+
+set(package aqnwb)
+
+install(
+    DIRECTORY
+    src/
+    "${PROJECT_BINARY_DIR}/export/"
+    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+    COMPONENT aqnwb_Development
+)
+
+install(
+    TARGETS aqnwb_aqnwb
+    EXPORT aqnwbTargets
+    RUNTIME #
+    COMPONENT aqnwb_Runtime
+    LIBRARY #
+    COMPONENT aqnwb_Runtime
+    NAMELINK_COMPONENT aqnwb_Development
+    ARCHIVE #
+    COMPONENT aqnwb_Development
+    INCLUDES #
+    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+)
+
+write_basic_package_version_file(
+    "${package}ConfigVersion.cmake"
+    COMPATIBILITY SameMajorVersion
+)
+
+# Allow package maintainers to freely override the path for the configs
+set(
+    aqnwb_INSTALL_CMAKEDIR "${CMAKE_INSTALL_LIBDIR}/cmake/${package}"
+    CACHE STRING "CMake package config location relative to the install prefix"
+)
+set_property(CACHE aqnwb_INSTALL_CMAKEDIR PROPERTY TYPE PATH)
+mark_as_advanced(aqnwb_INSTALL_CMAKEDIR)
+
+install(
+    FILES cmake/install-config.cmake
+    DESTINATION "${aqnwb_INSTALL_CMAKEDIR}"
+    RENAME "${package}Config.cmake"
+    COMPONENT aqnwb_Development
+)
+
+install(
+    FILES "${PROJECT_BINARY_DIR}/${package}ConfigVersion.cmake"
+    DESTINATION "${aqnwb_INSTALL_CMAKEDIR}"
+    COMPONENT aqnwb_Development
+)
+
+install(
+    EXPORT aqnwbTargets
+    NAMESPACE aqnwb::
+    DESTINATION "${aqnwb_INSTALL_CMAKEDIR}"
+    COMPONENT aqnwb_Development
+)
+
+if(PROJECT_IS_TOP_LEVEL)
+  include(CPack)
+endif()

cmake/variables.cmake

@@ -1,11 +1,12 @@
 # ---- Developer mode ----
 
 # Developer mode enables targets and code paths in the CMake scripts that are
-# only relevant for the developer(s) of aq-nwb
+# only relevant for the developer(s) of aqnwb
 # Targets necessary to build the project must be provided unconditionally, so
 # consumers can trivially build and package the project
 if(PROJECT_IS_TOP_LEVEL)
-  option(aq-nwb_DEVELOPER_MODE "Enable developer mode" OFF)
+  option(aqnwb_DEVELOPER_MODE "Enable developer mode" OFF)
+  option(BUILD_SHARED_LIBS "Build shared libs." OFF)
 endif()
 
 # ---- Warning guard ----
@@ -17,12 +18,12 @@ endif()
 set(warning_guard "")
 if(NOT PROJECT_IS_TOP_LEVEL)
   option(
-      aq-nwb_INCLUDES_WITH_SYSTEM
-      "Use SYSTEM modifier for aq-nwb's includes, disabling warnings"
+      aqnwb_INCLUDES_WITH_SYSTEM
+      "Use SYSTEM modifier for aqnwb's includes, disabling warnings"
       ON
   )
-  mark_as_advanced(aq-nwb_INCLUDES_WITH_SYSTEM)
-  if(aq-nwb_INCLUDES_WITH_SYSTEM)
+  mark_as_advanced(aqnwb_INCLUDES_WITH_SYSTEM)
+  if(aqnwb_INCLUDES_WITH_SYSTEM)
     set(warning_guard SYSTEM)
   endif()
 endif()

docs/pages/2_devdocs.dox

@@ -6,6 +6,7 @@
  * - \subpage dev_install_page
  * - \subpage testing
  * - \subpage dev_docs_page
+ * - \subpage nwb_schema_page
  * - \subpage code_of_conduct_page
  * - \subpage license_page
  * - \subpage copyright_page

docs/pages/devdocs/install.dox

@@ -23,14 +23,16 @@
  * \section devbuild_sec Developer Build
  *
  * Build system targets that are only useful for developers of AqNWB are
- * hidden if the `aq-nwb_DEVELOPER_MODE` option is disabled. Enabling this
+ * hidden if the `aqnwb_DEVELOPER_MODE` option is disabled. Enabling this
  * option makes \ref testing "tests" and other developer targets and options available. You can enable
- * the option when configuring the build by adding `-Daq-nwb_DEVELOPER_MODE=ON`, e.g.,
+ * the option when configuring the build by adding `-Daqnwb_DEVELOPER_MODE=ON`, e.g.,
  *
  * \code{.sh}
- * cmake -S . -B build -Daq-nwb_DEVELOPER_MODE=ON
+ * cmake -S . -B build -Daqnwb_DEVELOPER_MODE=ON
  * \endcode
  *
+ * Use the flag ``-DBUILD_SHARED_LIBS=ON`` to generate the shared library file.
+ *
  * \note
  * If you are using custom installations of **HDF5** or **BOOST** that are not being detected
  * automatically by cmake, you can specify `HDF5_ROOT` and `BOOST_ROOT` environment variables to

docs/pages/devdocs/nwb_schema.dox

@@ -0,0 +1,25 @@
+/**
+ * @page nwb_schema_page NWB Schema
+ * 
+ * The NWB file format is formally described by the [NWB Format Specification Schema](https://nwb-schema.readthedocs.io/en/latest/). 
+ * The data organization of NWB files and the core NWB format is described by these nwb-schema format specification documents. 
+ *
+ * \section dev_docs_generating_nwb_schema_headers_section Generating the schema header files
+ *
+ * AqNWB is linked to a specific version of the nwb-schema, and the schema version is written to the `nwb_version` field of the NWB File during acquisition.
+ * The full specification documentation for that schema version is also cached in the `specifications` group of the NWB File to facilitate compatibility with 
+ * other NWB-related software.
+ * 
+ * The contents of the `specifications` group are defined using the header files in the `spec` subfolder, which are in turn generated from the nwb-schema documentation files.
+ * To regenerate these header files, developers can run `resources/generate_spec_files.py`. 
+ *
+ * \section dev_docs_updating_nwb_schema_section Updating the schema
+ *
+ * Currently, the version of the schema being used for development is fixed and stored in the `/resources/schema` folder. 
+ * Updating to a newer version of the schema requires:
+ * - Regeneration of the `spec` header files via `resources/generate_spec_files.py`
+ * - Update of existing `Container` classes and unit tests in AqNWB to match changes in the  new schema compared to the previous schema
+ * - Successful completion of all unit-test and round-trip testing with PyNWB and MatNWB
+ *
+ */
+

docs/pages/userdocs/install.dox

@@ -19,6 +19,8 @@
  * cmake --build build --config Release
  * \endcode
  *
+ * Use the flag ``-DBUILD_SHARED_LIBS=ON`` to generate the shared library file.
+ *
  * \note
  * If you are using custom installations of **HDF5** or **BOOST** that are not being detected
  * automatically by cmake, you can specify `HDF5_ROOT` and `BOOST_ROOT` environment variables to

resources/generate_spec_files.py

@@ -1,4 +1,5 @@
 import json
+import os
 
 from pathlib import Path
 from ruamel.yaml import YAML
@@ -17,19 +18,29 @@
         spec_dir = Path(f"./resources/spec/{ns['name']}/{ns['version']}")
         spec_dir.mkdir(parents=True, exist_ok=True)
 
+        # create header file
+        header_file = Path(f"./src/spec/{ns['name'].replace('-', '_')}.hpp").resolve()
+        with open(header_file, 'w') as fo:
+            fo.write('#pragma once\n\n')
+            fo.write('#include <string>\n#include <string_view>\n#include <array>\n\n')
+            fo.write(f'namespace AQNWB::SPEC::{ns['name'].upper().replace('-', '_')}\n{{\n\n')
+            fo.write(f'const std::string version = "{ns["version"]}";\n\n')
+
         # load and convert schema files
+        var_names = []
         for s in ns['schema']:
             if 'source' in s:
                 # load file
                 schema_file = file.parent / s['source']
                 with open(schema_file) as f:
                     spec = yaml.load(schema_file)
-
-                # convert to json
-                spec_file = (spec_dir / s['source']).with_suffix('.json')
-                print(f'Generating file {spec_file}')
-                with open(spec_file, 'w') as fo:
-                    json.dump(spec, fo, separators=(',', ':'),)    
+
+                # convert to cpp string
+                print(f'Generating file {header_file} - {s["source"]}')
+                with open(header_file, 'a') as fo:
+                    var_name = s['source'].replace('.yaml', '').replace('.', '_')
+                    fo.write(f'constexpr std::string_view {var_name} = R"delimiter(\n{json.dumps(spec, separators=(',', ':'))})delimiter";\n\n')
+                    var_names.append(var_name)
 
         # reformat schema sources for namespace file
         schema = list()
@@ -38,10 +49,12 @@
                 s = {'source': s['source'].split('.yaml')[0]}
             schema.append(s)
         ns['schema'] = schema
-
-        # convert namespace json
-        ns_file = (spec_dir / file.name).with_suffix('.json')
+
+        # convert to cpp variables
         ns_output = {'namespaces': [ns]}
-        print(f'Generating file {ns_file}')
-        with open(ns_file, 'w') as fo:
-            json.dump(ns_output, fo, separators=(',', ':'),)
+        with open(header_file, 'a') as fo:
+            fo.write(f'constexpr std::string_view namespaces = R"delimiter(\n{json.dumps(ns_output, separators=(',', ':'))})delimiter";\n\n')
+            fo.write(f'constexpr std::array<std::pair<std::string_view, std::string_view>, {len(var_names) + 1}> specVariables {{{{\n')
+            fo.write(''.join([f'  {{"{name.replace('_', '.')}", {name}}},\n' for name in var_names]))
+            fo.write('  {"namespace", namespaces}\n')
+            fo.write(f'}}}};\n}}  // namespace AQNWB::SPEC::{ns['name'].upper().replace('-', '_')}\n')

src/Channel.cpp

@@ -6,6 +6,7 @@ using namespace AQNWB;
 
 Channel::Channel(const std::string name,
                  const std::string groupName,
+                 const SizeType groupIndex,
                  const SizeType localIndex,
                  const SizeType globalIndex,
                  const float conversion,
@@ -15,6 +16,7 @@ Channel::Channel(const std::string name,
                  const std::string comments)
     : name(name)
     , groupName(groupName)
+    , groupIndex(groupIndex)
     , localIndex(localIndex)
     , globalIndex(globalIndex)
     , position(position)

src/Channel.hpp

@@ -20,6 +20,7 @@ class Channel
    */
   Channel(const std::string name,
           const std::string groupName,
+          const SizeType groupIndex,
           const SizeType localIndex,
           const SizeType globalIndex,
           const float conversion = 1e6f,  // uV to V
@@ -63,6 +64,11 @@ class Channel
    */
   std::string groupName;
 
+  /**
+   * @brief Index of array group the channel belongs to.
+   */
+  SizeType groupIndex;
+
   /**
    * @brief Index of channel within the recording array.
    */

src/hdf5/HDF5IO.cpp

@@ -4,7 +4,7 @@
 #include <memory>
 #include <vector>
 
-#include "HDF5IO.hpp"
+#include "hdf5/HDF5IO.hpp"
 
 #include <H5Cpp.h>
 #include <H5Fpublic.h>