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
- 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.
- Note
- If you are using custom installations of HDF5 or BOOST that are not being detected automatically by CMake, you should set the CMAKE_PREFIX_PATH variable to include the install directories of HDF5 and BOOST. 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:/path/to/boost_install
cmake --preset=dev
# Option 2: Pass as a CMake variable (semicolon-separated)
cmake --preset=dev -DCMAKE_PREFIX_PATH=/path/to/hdf5_install;/path/to/boost_install
This ensures CMake can find the necessary config files for both HDF5 and Boost.
The use of HDF5_ROOT and BOOST_ROOT environment variables is deprecated for modern CMake and may not work reliably with recent CMake versions.
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
- 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.15.0 