From 5adf542ef39ca27d8a37aa5207c722a2f5c62f05 Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Sun, 29 Mar 2026 20:02:26 -0600 Subject: [PATCH 1/7] Added AGENTS.md; minor chages to jhrg/settings.json --- .gitignore | 2 +- .vscode/jhrg/settings.json | 18 ++++++- AGENTS.md | 104 +++++++++++++++++++++++++++++++++++++ agents-needs-work.md | 94 --------------------------------- 4 files changed, 121 insertions(+), 97 deletions(-) create mode 100644 AGENTS.md delete mode 100644 agents-needs-work.md diff --git a/.gitignore b/.gitignore index 6bbc474648..2a9b873cb1 100644 --- a/.gitignore +++ b/.gitignore @@ -176,4 +176,4 @@ timing/*/*.dtps /bw-output/ ## IDE configuration -.vscode/** +.vscode/*.json diff --git a/.vscode/jhrg/settings.json b/.vscode/jhrg/settings.json index 9ec8ed642f..a00f09a687 100644 --- a/.vscode/jhrg/settings.json +++ b/.vscode/jhrg/settings.json @@ -1,7 +1,8 @@ { // For Hyrax, prefix and PATH need to be set. jhrg 3/11/26 - "prefix": "/Users/jimg/src/opendap/hyrax/build", + "prefix": "/Users/jimg/src/opendap/hyrax_git/build", "PATH": "${config:prefix}/bin:${config:prefix}/deps/bin:${env:PATH}", + // C/C++ extensionsettings. jhrg 3/11/26 "C_Cpp.default.configurationProvider": "ms-vscode.makefile-tools", "C_Cpp.default.compileCommands": "${workspaceFolder}/compile_commands.json", "C_Cpp.default.includePath": [ @@ -18,11 +19,24 @@ "${workspaceFolder}/server/**", "${workspaceFolder}/standalone/**", "${workspaceFolder}/xmlcommand/**", - "${workspaceFolder}/modules/**", + "${workspaceFolder}/modules/**" ], "C_Cpp.default.cppStandard": "c++14", "C_Cpp.default.intelliSenseMode": "macos-clang-arm64", "C_Cpp.vcFormat.indent.namespaceContents": false, + // Makefile settings. jhrg 3/11/26 + "files.associations": { + "*.am": "makefile" + }, + "[makefile]": { + "editor.insertSpaces": false + }, + // Exclude object files from the file explorer. jhrg 3/29/26 + "files.exclude": { + "**/*.o": true, + "**/*.lo": true + }, + // Terminal environment settings. jhrg 3/11/26 "terminal.integrated.env.osx": { "prefix": "${config:prefix}", "PATH": "${config:PATH}" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..fcf30abed6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,104 @@ +# AGENTS.md + +## Scope + +These instructions apply to the entire `bes` repository. + +## Project Context + +- `bes` is the Back-End Server for Hyrax and is a long-lived C++ codebase with downstream users who depend on stable behavior. +- Prefer compatibility, behavioral stability, and small reviewable diffs over broad cleanup or refactoring. +- Treat changes to protocol behavior, server startup/configuration, packaging, and installed layout as high risk. + +## Primary Build System + +- Use autotools for normal development work in this repository. +- A top-level `CMakeLists.txt` exists, but ignore that since it is a relic. + +## Autotools Workflow + +For a fresh git checkout: + +```sh +autoreconf --force --install --verbose +./configure --prefix="$prefix" --with-dependencies="$prefix/deps" --enable-developer +make -j +make check +``` + +For a source-distribution style build: + +```sh +./configure +make -j +make check +``` + +Notes: + +- Check that `prefix` is defined before using commands that rely on it. +- Use `--with-dependencies=` when BES dependencies are installed outside standard system paths. +- `--enable-developer` is the normal developer-mode configure option in this repo. +- Useful configure toggles defined at the top level include `--enable-asan`, `--enable-coverage`, `--without-cmr`, `--without-ngap`, and `--without-s3`. +- `make distcheck` is a supported validation path here; top-level build files already carry `AM_DISTCHECK_CONFIGURE_FLAGS` logic for dependency-aware distcheck runs. + +## Testing Expectations + +- For code changes, run focused validation first, then broaden test scope when the risk warrants it. +- Default autotools validation is `make check`. +- Parallel test runs are used in CI, but `INSTALL` notes that some tests may object to parallel execution; if `-j` causes issues, retry serially and mention that in your summary. +- If you change build, packaging, or install behavior, consider whether `make distcheck` or the Docker build path should also be exercised. + +## CI And Container Workflows + +- CI is defined in [`.travis.yml`](/Users/jimg/src/opendap/hyrax_git/bes/.travis.yml) and uses autotools, `make check`, `make distcheck`, coverage builds, and Docker image builds. +- Docker builds are driven by [`Dockerfile`](/Users/jimg/src/opendap/hyrax_git/bes/Dockerfile) and [`travis/build-rhel-docker.sh`](/Users/jimg/src/opendap/hyrax_git/bes/travis/build-rhel-docker.sh). +- CI commonly configures with `--disable-dependency-tracking`, `--with-dependencies=$prefix/deps`, and `--enable-developer`. +- Docker and CI assume external dependency artifacts such as hyrax-dependencies and libdap builds; do not hardcode local-only assumptions into those paths. + +## Generated Files And Build Artifacts + +- Prefer editing source inputs such as [`configure.ac`](/Users/jimg/src/opendap/hyrax_git/bes/configure.ac) and [`Makefile.am`](/Users/jimg/src/opendap/hyrax_git/bes/Makefile.am), not generated outputs like `configure`, `Makefile.in`, or `config.h.in`, unless the task explicitly requires regenerating them. +- This repository may contain checked-in generated files and local build artifacts. Do not delete or revert unrelated generated files just to make the tree look clean. +- If you regenerate autotools outputs, keep the resulting changes tightly scoped and mention that regeneration was performed. + +## Documentation + +- Top-level API docs are built with `make docs`. +- Doc inputs are generated from top-level templates such as `doxy.conf.in` and `main_page.doxygen.in`; keep template/generated relationships consistent with the chosen build workflow. + +## Configuration Awareness + +- BES is not just a library build; installation layout and runtime configuration matter. +- `INSTALL` and `README.md` both assume post-install configuration under `etc/bes`, including `bes.conf` and module configuration files. +- When changing defaults, installed paths, service scripts, or startup behavior, call out runtime configuration impact explicitly. + +## Legacy C++ Constraints + +- Match local style in touched files; avoid unrelated formatting sweeps. +- Avoid API or ABI-impacting changes unless explicitly requested. +- Be conservative with ownership, lifetime, and assertion behavior in older pointer-heavy code. +- Developer mode and release mode differ here (`--enable-developer` vs. `NDEBUG` builds), so consider both when changing assertions, debug-only behavior, or diagnostics. + +## Change Discipline + +- Do not revert unrelated local changes in a dirty worktree. +- Keep edits narrowly scoped to the request. +- If you encounter unexpected repository changes that conflict with the task, stop and ask how to proceed. +- Do not run destructive git commands unless explicitly requested. + +## Review Priorities + +When asked to review, prioritize: + +1. Behavioral regressions in server responses, protocol handling, and installed/runtime behavior +2. Memory/resource safety and ownership lifetime issues +3. Build-system or packaging regressions in autotools, distcheck, CI, or Docker flows +4. Configuration/install-layout regressions that would affect deployed BES instances +5. Missing or weak regression coverage + +## Communication + +- State assumptions and environment details explicitly, especially configure flags and dependency locations. +- If full validation was not run, say exactly what was run and what was not. +- If a change depends on external prerequisites such as `libdap`, hyrax-dependencies, AWS-fetched artifacts, or system packages, note that clearly. diff --git a/agents-needs-work.md b/agents-needs-work.md deleted file mode 100644 index 0ebc27f5eb..0000000000 --- a/agents-needs-work.md +++ /dev/null @@ -1,94 +0,0 @@ -# AGENTS.md - -## Scope - -These instructions apply to the entire `bes` repository. - -## Project Context - -- `bes` is a legacy C++ implementation of the Hyrax data server long-lived downstream consumers. -- Prioritize compatibility, behavioral stability, and small, reviewable diffs. -- Prefer minimal, targeted changes over broad refactors. - -## Primary Build Systems - -- Prefer autotools for day-to-day work. - - -## Autotools Workflow (preferred) - -For a fresh git checkout: - -```sh -autoreconf --force --install --verbose -./configure --prefix=$prefix --with-dependencies=$prefix/deps --enable-developer -make -j -make -j check -``` - -For release-tarball style builds: - -```sh -./configure -make -j -make -j check -``` - -Notes: - -- Check that the environment variable 'prefix' is defined before running any command that uses it. -- Use `--prefix=` when installation path matters. -- Use `TESTSUITEFLAGS=-j` with `make check` when parallelizing tests. -- If `make check` fails due to missing `config.guess`, link `conf/config.guess` into `tests/` per `tests/README`. - -## Testing Expectations - -- For code changes, run focused tests in affected areas first, then broader suites when risk is higher. -- Autotools default: `make -j check` -- If tests are flaky or expected-fail in legacy areas, call that out explicitly in your summary. - -## Documentation And Doxygen - -- Doxygen docs are built with: - -```sh -make docs -``` - -- Inputs are `doxy.conf` and `main_page.doxygen` (generated from `.in` templates by configure). -- When updating doc config/templates, keep generated and template files consistent with the chosen build workflow. - -## Legacy C++ Constraints - -- Match local style in touched files; do not perform unrelated formatting sweeps. -- Avoid API/ABI-impacting changes unless explicitly requested. -- Be conservative with ownership/lifetime changes in pointer-heavy code. -- Parser/scanner sources are generated (`*.tab.cc`, `*.tab.hh`, `lex.*.cc`); edit `*.yy`/`*.lex` sources, not generated outputs, unless the task explicitly requires generated-file updates. - -## Tooling And Quality - -- `clang-format` and pre-commit are configured (`README.pre-commit.md`, `.pre-commit-config.yaml`). -- Prefer running formatting/hooks only on changed files relevant to the task. -- Address sanitizer is supported (`--enable-asan` in autotools, `asan` preset in CMake) for memory-safety debugging. - -## Change Discipline - -- Do not revert unrelated local changes in a dirty worktree. -- Keep edits tightly scoped to the request. -- If you encounter unexpected repository changes during work, stop and ask how to proceed. -- Do not run destructive git commands unless explicitly requested. - -## Review Priorities - -When asked to review: - -1. Behavioral regressions in protocol/data-model behavior -2. Memory/resource safety and ownership lifetime issues -3. Parser/serialization correctness and edge cases -4. Build-system regressions (autotools and CMake) -5. Missing or weak regression coverage - -## Communication - -- State assumptions and environment details explicitly (build system, preset/configure flags, test scope). -- If full validation is not run, say exactly what was run and what was not. From 14522b61ed0c4b51e2fe891cbb88fd0559259b31 Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Sun, 29 Mar 2026 20:37:33 -0600 Subject: [PATCH 2/7] Some questions added to the DOckerfile as comments. --- Dockerfile | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Dockerfile b/Dockerfile index 6d21af7627..ee2052d939 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,8 +1,17 @@ # Dockerfile for bes_core images + +# I think we might want to explain here that this Dockerfile is intended to build a base image +# that will be used to build subsequent images for our production BES/Hyrax images. Also, +# we might want to explain that the build process is split into two stages, with the first stage +# building the BES and the second stage copying over the built BES and its dependencies to a +# slimmer base image. jhrg 3/29/26 + ARG BUILDER_BASE_IMAGE ARG FINAL_BASE_IMAGE FROM ${BUILDER_BASE_IMAGE:-"rockylinux:8"} AS builder +# Sanity check that the required build argument is provided and non-empty, evn though +# a default value is provided above. We want to enforce that the value is always specified. jhrg 3/29/26 ARG BUILDER_BASE_IMAGE RUN if [ -z "$BUILDER_BASE_IMAGE" ]; then \ echo "Error: Non-empty BUILDER_BASE_IMAGE must be specified. Exiting."; \ @@ -59,6 +68,9 @@ COPY . ./bes RUN sudo chown -R $BES_USER:$BES_USER bes WORKDIR bes +# *** Note that since this is going to be used in production, the --enable-developer +# configure option should not be used. This is the only change that I think we need +# to make to the build process for production images. jhrg 3/29/26 RUN autoreconf -fiv RUN echo "Sanity check: CPPFLAGS=$CPPFLAGS LDFLAGS=$LDFLAGS prefix=$PREFIX" \ && ./configure --disable-dependency-tracking \ @@ -173,6 +185,8 @@ USER root # Adapted from bes/spec.all_static.in in RPM creation. # The four *.pem substitutions may be unnecessary, as those *.pem files may be # vestigial substitutions for a build process past. +# +# Yes, I believe they are vestigial. Let's try to find time to test removing them. jhrg 3/29/26 RUN sed -i.dist \ -e 's:=.*/bes.log:=/var/log/bes/bes.log:' \ -e 's:=.*/lib/bes:=/usr/lib/bes:' \ @@ -189,6 +203,8 @@ RUN sed -i.dist \ && touch "/var/log/bes/bes.log" \ && chown -R $BES_USER:$BES_USER "/var/log/bes/" +# We have some contributed scripts that work with systemctl, is it worth trying to set up +# systemctl in this image? jhrg 3/29/26 # Start besd service at boot RUN chkconfig --add besd \ && ldconfig \ From 596be15a83b8bd8ed6daf699916a36299db4b6cb Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Mon, 30 Mar 2026 15:26:06 -0600 Subject: [PATCH 3/7] Update Dockerfile Co-authored-by: Hannah Robertson --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index ee2052d939..1b917cfe9f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -11,7 +11,7 @@ ARG FINAL_BASE_IMAGE FROM ${BUILDER_BASE_IMAGE:-"rockylinux:8"} AS builder # Sanity check that the required build argument is provided and non-empty, evn though -# a default value is provided above. We want to enforce that the value is always specified. jhrg 3/29/26 +# a default value is provided above. We want to enforce that the value is always specified. ARG BUILDER_BASE_IMAGE RUN if [ -z "$BUILDER_BASE_IMAGE" ]; then \ echo "Error: Non-empty BUILDER_BASE_IMAGE must be specified. Exiting."; \ From ef712071fe8a06ca59025671dbffb56b9ffec76c Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Mon, 30 Mar 2026 15:30:59 -0600 Subject: [PATCH 4/7] Update links in AGENTS.md for relative paths --- AGENTS.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fcf30abed6..593b7acaa9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,14 +51,15 @@ Notes: ## CI And Container Workflows -- CI is defined in [`.travis.yml`](/Users/jimg/src/opendap/hyrax_git/bes/.travis.yml) and uses autotools, `make check`, `make distcheck`, coverage builds, and Docker image builds. -- Docker builds are driven by [`Dockerfile`](/Users/jimg/src/opendap/hyrax_git/bes/Dockerfile) and [`travis/build-rhel-docker.sh`](/Users/jimg/src/opendap/hyrax_git/bes/travis/build-rhel-docker.sh). +- CI is defined in [`.travis.yml`](.travis.yml) and uses autotools, `make check`, `make distcheck`, coverage builds, and Docker image builds. +- Additional CI in [`.github/workflows`](.github/workflows) for OSX Intel and ARM64. +- Docker builds are driven by [`Dockerfile`](Dockerfile) and [`travis/build-rhel-docker.sh`](travis/build-rhel-docker.sh). - CI commonly configures with `--disable-dependency-tracking`, `--with-dependencies=$prefix/deps`, and `--enable-developer`. - Docker and CI assume external dependency artifacts such as hyrax-dependencies and libdap builds; do not hardcode local-only assumptions into those paths. ## Generated Files And Build Artifacts -- Prefer editing source inputs such as [`configure.ac`](/Users/jimg/src/opendap/hyrax_git/bes/configure.ac) and [`Makefile.am`](/Users/jimg/src/opendap/hyrax_git/bes/Makefile.am), not generated outputs like `configure`, `Makefile.in`, or `config.h.in`, unless the task explicitly requires regenerating them. +- Prefer editing source inputs such as [`configure.ac`](configure.ac) and [`Makefile.am`](Makefile.am), not generated outputs like `configure`, `Makefile.in`, or `config.h.in`, unless the task explicitly requires regenerating them. - This repository may contain checked-in generated files and local build artifacts. Do not delete or revert unrelated generated files just to make the tree look clean. - If you regenerate autotools outputs, keep the resulting changes tightly scoped and mention that regeneration was performed. From 3e73cc308398aa460df070c825425b55b3bd0e62 Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Tue, 31 Mar 2026 10:22:27 -0600 Subject: [PATCH 5/7] Apply suggestion from @hannahilea Co-authored-by: Hannah Robertson --- Dockerfile | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Dockerfile b/Dockerfile index 1b917cfe9f..31428ce862 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,10 +1,9 @@ # Dockerfile for bes_core images -# I think we might want to explain here that this Dockerfile is intended to build a base image -# that will be used to build subsequent images for our production BES/Hyrax images. Also, -# we might want to explain that the build process is split into two stages, with the first stage +# This Dockerfile is intended to build a base image +# that will be used to build subsequent images for our production BES/Hyrax images. # The build process is split into two stages, with the first stage # building the BES and the second stage copying over the built BES and its dependencies to a -# slimmer base image. jhrg 3/29/26 +# slimmer base image. ARG BUILDER_BASE_IMAGE ARG FINAL_BASE_IMAGE From 09c53d8cedf1910b15d7a1404d1a440057fb63db Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Tue, 31 Mar 2026 10:22:40 -0600 Subject: [PATCH 6/7] Apply suggestion from @hannahilea Co-authored-by: Hannah Robertson --- Dockerfile | 2 -- 1 file changed, 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 31428ce862..9efe76cb0b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -184,8 +184,6 @@ USER root # Adapted from bes/spec.all_static.in in RPM creation. # The four *.pem substitutions may be unnecessary, as those *.pem files may be # vestigial substitutions for a build process past. -# -# Yes, I believe they are vestigial. Let's try to find time to test removing them. jhrg 3/29/26 RUN sed -i.dist \ -e 's:=.*/bes.log:=/var/log/bes/bes.log:' \ -e 's:=.*/lib/bes:=/usr/lib/bes:' \ From 7c97317d56388f22797573a278e4de54b24c6c6c Mon Sep 17 00:00:00 2001 From: James Gallagher Date: Wed, 1 Apr 2026 09:51:40 -0600 Subject: [PATCH 7/7] Removed questions from Dockerfile --- Dockerfile | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/Dockerfile b/Dockerfile index 1b917cfe9f..d07c7bc5c8 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,17 +1,17 @@ # Dockerfile for bes_core images -# I think we might want to explain here that this Dockerfile is intended to build a base image -# that will be used to build subsequent images for our production BES/Hyrax images. Also, -# we might want to explain that the build process is split into two stages, with the first stage -# building the BES and the second stage copying over the built BES and its dependencies to a -# slimmer base image. jhrg 3/29/26 +# This Dockerfile is intended to build a base image that will be used to build +# subsequent images for our production BES/Hyrax images. The build process is +# split into two stages, with the first stage building the BES and the second +# stage copying over the built BES and its dependencies to a slimmer base image. ARG BUILDER_BASE_IMAGE ARG FINAL_BASE_IMAGE FROM ${BUILDER_BASE_IMAGE:-"rockylinux:8"} AS builder -# Sanity check that the required build argument is provided and non-empty, evn though -# a default value is provided above. We want to enforce that the value is always specified. +# Sanity check that the required build argument is provided and non-empty, evn +# though a default value is provided above. We want to enforce that the value is +# always specified. ARG BUILDER_BASE_IMAGE RUN if [ -z "$BUILDER_BASE_IMAGE" ]; then \ echo "Error: Non-empty BUILDER_BASE_IMAGE must be specified. Exiting."; \ @@ -68,9 +68,10 @@ COPY . ./bes RUN sudo chown -R $BES_USER:$BES_USER bes WORKDIR bes -# *** Note that since this is going to be used in production, the --enable-developer -# configure option should not be used. This is the only change that I think we need -# to make to the build process for production images. jhrg 3/29/26 +# *** Note that since this is going to be used in production, the +# --enable-developer configure option should not be used. This is the only +# change that I think we need to make to the build process for production +# images. jhrg 3/29/26 RUN autoreconf -fiv RUN echo "Sanity check: CPPFLAGS=$CPPFLAGS LDFLAGS=$LDFLAGS prefix=$PREFIX" \ && ./configure --disable-dependency-tracking \ @@ -146,7 +147,7 @@ COPY --from=builder /home/$BES_USER/bes/bes_VERSION bes_VERSION COPY --from=builder /home/$BES_USER/bes/libdap_VERSION libdap_VERSION COPY --from=builder $DEPS_PREFIX $DEPS_PREFIX -# Copy over everything installed in the builder image +# Copy over everything installed in the builder image. # This is a little ham-fisted, but seems to be at least sufficient # (if not particularly elegant!). COPY --from=builder /etc/bes /etc/bes @@ -184,9 +185,7 @@ USER root # Adapted from bes/spec.all_static.in in RPM creation. # The four *.pem substitutions may be unnecessary, as those *.pem files may be -# vestigial substitutions for a build process past. -# -# Yes, I believe they are vestigial. Let's try to find time to test removing them. jhrg 3/29/26 +# vestigial substitutions for a build process past. See HYRAX-2075. RUN sed -i.dist \ -e 's:=.*/bes.log:=/var/log/bes/bes.log:' \ -e 's:=.*/lib/bes:=/usr/lib/bes:' \ @@ -203,8 +202,6 @@ RUN sed -i.dist \ && touch "/var/log/bes/bes.log" \ && chown -R $BES_USER:$BES_USER "/var/log/bes/" -# We have some contributed scripts that work with systemctl, is it worth trying to set up -# systemctl in this image? jhrg 3/29/26 # Start besd service at boot RUN chkconfig --add besd \ && ldconfig \