(axis-axis2-c-core) 08/08: Say that make install replaces axis2.xml

[ro...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

robertlazarski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/axis-axis2-c-core.git

commit 81f034732a0ebddf501b104574f9ad0826874bed
Author: Robert Lazarski <ro...@gmail.com>
AuthorDate: Tue Sep 1 10:54:20 2026 -1000

    Say that make install replaces axis2.xml
    
    $(prefix)/axis2.xml is a symlink into share/axis2c, and that file is
    reinstalled every time, so an enabled transport or an attachmentDIR set
    before installing is silently gone afterwards. Nothing said so at the
    point it bites. The install now says it, and the testing guide gives
    the ordering -- configure after the last install, samples build
    included, since that installs again.
    
    Co-Authored-By: Claude Opus 5 (1M context) <no...@anthropic.com>
---
 Makefile.am              |  5 +++++
 docs/HTTP2_UNIT_TESTS.md | 27 +++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/Makefile.am b/Makefile.am
index d150fc735..1f7669e6c 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -116,6 +116,11 @@ install-data-hook:
 	@rm -f $(DESTDIR)$(prefix)/axis2.xml 2>/dev/null || true
 	@cd $(DESTDIR)$(prefix) && $(LN_S) share/axis2c/axis2.xml axis2.xml 2>/dev/null || \
 		echo "Note: Could not create axis2.xml symlink (may already exist or different filesystem)"
+	@echo "Note: axis2.xml has just been REPLACED with the shipped default."
+	@echo "      $(DESTDIR)$(prefix)/axis2.xml is a symlink to share/axis2c/axis2.xml,"
+	@echo "      and that file is reinstalled by every 'make install' -- so any local"
+	@echo "      edits (enabled transports, attachmentDIR, ports) are gone. Reapply"
+	@echo "      them after installing, or keep the configuration outside the prefix."
 	@echo ""
 	@echo "========================================================================"
 	@echo "CRITICAL: Complete Apache Module & Library Deployment Required!"
diff --git a/docs/HTTP2_UNIT_TESTS.md b/docs/HTTP2_UNIT_TESTS.md
index 9bd69d997..9e870c1bd 100644
--- a/docs/HTTP2_UNIT_TESTS.md
+++ b/docs/HTTP2_UNIT_TESTS.md
@@ -203,6 +203,33 @@ run happily against code you did not build. Results then depend on what each
 machine happens to have installed, which is a good way to spend an afternoon on
 a "platform-specific" failure that is nothing of the kind.
 
+#### **Issue: `axis2.xml` edits disappear after `make install`**
+
+**Problem:** you enable a transport or set `attachmentDIR`, rebuild, and the
+server behaves as though you changed nothing — or refuses to start because the
+transport you enabled is commented out again.
+
+**Cause:** `$(prefix)/axis2.xml` is a symlink to `share/axis2c/axis2.xml`, and
+that file is reinstalled from `samples/server/axis2.xml` by *every*
+`make install`. Editing through the symlink edits the install's copy, and the
+next install overwrites it. Nothing warns you at the point of use; the
+behaviour just reverts.
+
+**Solution:** reapply the configuration after installing, not before — or keep
+a configured copy outside the prefix and point `AXIS2C_HOME` at that. When
+scripting a test run, put the edit *after* the last `make install` step, which
+is the ordering mistake that is easy to make and hard to see:
+
+```bash
+make && make install
+(cd samples && sh build.sh)     # installs again
+# only now is it safe to configure
+python3 configure_axis2_xml.py "$AXIS2C_HOME/axis2.xml"
+```
+
+Note `samples/build.sh` runs its own install, so an edit made between `make
+install` and the samples build is also lost.
+
 ---
 
 ## 🔍 **Test Verification Commands**