Installing AqNWB
Requirements
Please ensure that the required libraries described in the User Requirements section are installed and clone the latest AqNWB source via:
git clone https://github.com/NeurodataWithoutBorders/aqnwb.git
For developers we also recommend to install the following optional command line tools used for generating the documentation, for code quality checks, and for debugging.
- Documentation: Additional requirements for building the documentation (optional)
- Code checks: Additional command line tools used in developer mode dev
- cppcheck (optional, required for target=cppcheck)
- clang-format (optional, required for target=format-check, target=format-fix)
- codespell (optional, required for target=spell-check, target=spell-fix)
Developer Build
Build system targets that are only useful for developers of AqNWB are hidden if the aqnwb_DEVELOPER_MODE option is disabled. Enabling this option makes tests and other developer targets and options available. You can enable the option when configuring the build by adding -Daqnwb_DEVELOPER_MODE=ON, e.g.,
cmake -S . -B build -Daqnwb_DEVELOPER_MODE=ON
Use the flag -DBUILD_SHARED_LIBS=ON to generate the shared library file.
Using a custom HDF5 installation
If you are using a custom installation of HDF5 that is not being detected automatically by CMake, you should set the CMAKE_PREFIX_PATH variable to include the install directory of HDF5. This can be done either as an environment variable or directly on the CMake command line. For example:
# Option 1: Set as environment variable (colon-separated on Unix/macOS)
export CMAKE_PREFIX_PATH=/path/to/hdf5_install
cmake --preset=dev
# Option 2: Pass as a CMake variable (semicolon-separated)
cmake --preset=dev -DCMAKE_PREFIX_PATH=/path/to/hdf5_install
This ensures CMake can find the necessary config files for HDF5.
The use of the HDF5_ROOT environment variable is deprecated for modern CMake and may not work reliably with recent CMake versions.
Selecting a newer C++ standard version
You can also select the C++ standard to use (minimum 17, default 17) by setting the AQNWB_CXX_STANDARD option when configuring the build. For example, to build with C++23:
cmake --preset=dev -DAQNWB_CXX_STANDARD=23
If not specified, the project will use C++17 by default. Currently, only the values 17, 20, or 23 are accepted.
Developer Presets
As a developer, you can create your own dev preset by making a CMakeUserPresets.json file at the root of the project:
{
"version": 2,
"cmakeMinimumRequired": {
"major": 3,
"minor": 15,
"patch": 0
},
"configurePresets": [
{
"name": "dev",
"binaryDir": "${sourceDir}/build/dev",
"inherits": ["dev-mode", "ci-<os>"],
"cacheVariables": {
"CMAKE_BUILD_TYPE": "Debug"
}
}
],
"buildPresets": [
{
"name": "dev",
"configurePreset": "dev",
"configuration": "Debug"
}
],
"testPresets": [
{
"name": "dev",
"configurePreset": "dev",
"configuration": "Debug",
"output": {
"outputOnFailure": true
}
}
]
}
Replace <os> in the CMakeUserPresets.json file with the name of the operating system you have (win64, linux or darwin).
Configure, Build and Test
You can configure, build and test the project respectively with the following commands from the project root on any operating system with any build system:
cmake --preset=dev
cmake --build --preset=dev
ctest --preset=dev
Developer Install
After build, we can install the developer library into a custom location, by navigating to the build folder and call cmake --install . with a an optional --prefix to specify th install location, e.g.,
cd build/dev
cmake --install . --prefix=../dev/install
Developer Mode Targets
Additional targets can be invoked when in development mode using the commands below
cmake --build --preset=dev --target=<name of the target>
Target options
- format-check: run the clang-format tool on the codebase to check for formatting errors
- format-fix : run the clang-format tool on the codebase with FIX=YES to both check and automatically fix for formatting errors
- spell-check: run the codespell tool on the codebase to check for common spelling errors
- spell-fix : run the codespell tool on the codebase with FIX=YES to both check and automatically fix common spelling errors
- cppcheck : run the cppcheck static analysis tool on the codebase to check for potential bugs, style issues, performance issues, and portability issues
- docs : builds the documentation using Doxygen. (Note: run cmake --preset=dev -DBUILD_DOCS=ON before building to add docs target)
Installing Python Utilities
AqNWB provides a set of Python utilities for developers to help with generating C++ classes from NWB schema files. For details on how to use the utilities, see the README.md in the resources/utils directory.
README.md
# AqNWB Utilities
Command-line utilities for AqNWB development.
## Installation
### Using uv (Recommended)
The utilities use inline script metadata (PEP 723) and can be run directly with `uv`:
```bash
# Install uv if you haven't already
brew install uv
# Run utilities directly without installation
uv run resources/utils/aqnwb_utils.py generate-spec <schema_dir> <output_dir>
uv run resources/utils/aqnwb_utils.py generate-types <namespace_file> <output_dir>
```
### Traditional Installation
You can also install the package if you prefer:
```bash
# Using uv
uv pip install ./resources/utils
# Or using pip
pip install ./resources/utils
# Then use the installed command
aqnwb-utils generate-spec <schema_dir> <output_dir>
```
## Usage
### Direct execution with uv (no installation required)
```bash
# Generate spec files
uv run resources/utils/aqnwb_utils.py generate-spec <schema_dir> <output_dir>
# Generate neurodata types
uv run resources/utils/aqnwb_utils.py generate-types <namespace_file> <output_dir>
# Generate types with test app
uv run resources/utils/aqnwb_utils.py generate-types --generate-test-app <namespace_file> <output_dir>
```
### After installation
```bash
# Generate spec files
aqnwb-utils generate-spec <schema_dir> <output_dir>
# Generate neurodata types
aqnwb-utils generate-types <namespace_file> <output_dir>
# Generate types with test app
aqnwb-utils generate-types --generate-test-app <namespace_file> <output_dir>
```
## Available Commands
- `generate-spec`: Generate C++ header files from NWB schema files
- `generate-types`: Generate C++ classes from neurodata types defined in schema files
## Benefits of using uv
- **No installation required**: Run scripts directly with their dependencies automatically managed
- **Isolated environments**: Each script run uses its own isolated environment
- **Fast**: uv is significantly faster than pip for dependency resolution and installation
- **Reproducible**: Dependencies are specified in the script itself using PEP 723 metadata
1.16.1 