diff --git a/.gitignore b/.gitignore index 93fcc66837..faf5656619 100644 --- a/.gitignore +++ b/.gitignore @@ -1,352 +1,353 @@ # # Copyright 2011-2024 the Pacemaker project contributors # # The version control history for this file may have further details. # # This source code is licensed under the GNU General Public License version 2 # or later (GPLv2+) WITHOUT ANY WARRANTY. # # Common conventions for files that should be ignored *~ *.bz2 *.diff *.orig *.patch *.rej *.sed *.swp *.tar.gz *.tgz \#* .\#* logs # libtool artifacts *.la *.lo .libs libltdl libtool libtool.m4 ltdl.m4 /m4/argz.m4 /m4/ltargz.m4 /m4/ltoptions.m4 /m4/ltsugar.m4 /m4/ltversion.m4 /m4/lt~obsolete.m4 # autotools artifacts .deps .dirstamp Makefile Makefile.in aclocal.m4 autoconf autoheader autom4te.cache/ automake /confdefs.h config.log config.status configure /conftest* # gettext artifacts /ABOUT-NLS /m4/codeset.m4 /m4/fcntl-o.m4 /m4/gettext.m4 /m4/glibc2.m4 /m4/glibc21.m4 /m4/iconv.m4 /m4/intdiv0.m4 /m4/intl.m4 /m4/intldir.m4 /m4/intlmacosx.m4 /m4/intmax.m4 /m4/inttypes-pri.m4 /m4/inttypes_h.m4 /m4/lcmessage.m4 /m4/lib-ld.m4 /m4/lib-link.m4 /m4/lib-prefix.m4 /m4/lock.m4 /m4/longlong.m4 /m4/nls.m4 /m4/po.m4 /m4/printf-posix.m4 /m4/progtest.m4 /m4/size_max.m4 /m4/stdint_h.m4 /m4/threadlib.m4 /m4/uintmax_t.m4 /m4/visibility.m4 /m4/wchar_t.m4 /m4/wint_t.m4 /m4/xsize.m4 /po/*.gmo /po/*.header /po/*.pot /po/*.sin /po/Makefile.in.in /po/Makevars.template /po/POTFILES /po/Rules-quot /po/stamp-po # configure targets /agents/ocf/ClusterMon /agents/ocf/Dummy /agents/ocf/HealthCPU /agents/ocf/HealthIOWait /agents/ocf/HealthSMART /agents/ocf/Stateful /agents/ocf/SysInfo /agents/ocf/attribute /agents/ocf/controld /agents/ocf/ifspeed /agents/ocf/ping /agents/ocf/remote /agents/stonith/fence_legacy /agents/stonith/fence_watchdog /cts/benchmark/clubench /cts/cluster_test /cts/cts /cts/cts-attrd /cts/cts-cli /cts/cts-exec /cts/cts-fencing /cts/cts-lab /cts/cts-regression /cts/cts-scheduler /cts/cts-schemas /cts/lab/CTS.py /cts/support/LSBDummy /cts/support/cts-support /cts/support/fence_dummy /cts/support/pacemaker-cts-dummyd /cts/support/pacemaker-cts-dummyd@.service /daemons/execd/pacemaker_remote /daemons/execd/pacemaker_remote.service /daemons/fenced/fence_legacy /daemons/fenced/fence_watchdog /daemons/pacemakerd/pacemaker.service /doc/Doxyfile /etc/init.d/pacemaker /etc/logrotate.d/pacemaker /etc/sysconfig/pacemaker /include/config.h /include/config.h.in /include/crm_config.h /maint/bumplibs /python/pacemaker/buildoptions.py /python/setup.py /tools/cluster-clean /tools/cluster-helper /tools/cluster-init /tools/cibsecret /tools/crm_error /tools/crm_failcount /tools/crm_master /tools/crm_mon.service /tools/crm_report /tools/crm_rule /tools/crm_standby /tools/pcmk_simtimes /tools/report.collector /tools/report.common /xml/rng-helper # Compiled targets and intermediary files *.o *.pc *.pyc /daemons/attrd/pacemaker-attrd /daemons/based/pacemaker-based /daemons/controld/pacemaker-controld /daemons/execd/cts-exec-helper /daemons/execd/pacemaker-execd /daemons/execd/pacemaker-remoted /daemons/fenced/cts-fence-helper /daemons/fenced/pacemaker-fenced /daemons/pacemakerd/pacemakerd /daemons/schedulerd/pacemaker-schedulerd /devel/scratch /lib/gnu/stdalign.h /tools/attrd_updater /tools/cibadmin /tools/crmadmin /tools/crm_attribute /tools/crm_diff /tools/crm_mon /tools/crm_node /tools/crm_resource /tools/crm_shadow /tools/crm_simulate /tools/crm_ticket /tools/crm_verify /tools/iso8601 /tools/stonith_admin # Generated XML schema files /xml/crm_mon.rng /xml/pacemaker*.rng /xml/versions.rng /xml/api/api-result*.rng # Working directories for make dist and make export /pacemaker-[a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9][a-f0-9] # Documentation build targets and intermediary files *.7 *.7.xml *.7.html *.8 *.8.xml *.8.html GPATH GRTAGS GTAGS TAGS /daemons/fenced/pacemaker-fenced.xml /daemons/schedulerd/pacemaker-schedulerd.xml -/doc/.ABI-build /doc/HTML -/doc/abi_dumps +/doc/abi/ /doc/abi-check /doc/api/ -/doc/compat_reports /doc/crm_fencing.html /doc/sphinx/*/_build /doc/sphinx/*/conf.py /doc/sphinx/*/generated /doc/sphinx/build-[0-9]*.txt # Test artifacts (from unit tests, regression tests, static analysis, etc.) *.coverity *.gcda *.gcno coverity-* pacemaker_*.info /coverage /cppcheck.out /cts/scheduler/bug-rh-1097457.log /cts/scheduler/bug-rh-1097457.trs /cts/scheduler/shadow.* /cts/schemas/test-*/ref/*.up* /cts/schemas/test-*/ref.err/*.up.err* /cts/test-suite.log /lib/*/fuzzers/*/*_fuzzer /lib/*/tests/*/*.log /lib/*/tests/*/*_test /lib/*/tests/*/*.trs /lib/common/tests/schemas/schemas /test/_test_file.c # Packaging artifacts *.rpm /pacemaker.spec /rpm/[A-LN-Z]* /rpm/build.counter /rpm/mock # Project maintainer artifacts /maint/gnulib /maint/mocked/based /maint/testcc_helper.cc /maint/testcc_*_h # Formerly built files (helps when jumping back and forth in checkout) /.ABI-build /Doxyfile /HTML /abi_dumps /abi-check /agents/ocf/o2cb /build.counter /compat_reports /compile /cts/.regression.failed.diff /attrd /cib /config.guess /config.sub /coverage.sh /crmd /cts/CTS.py /cts/CTSlab.py /cts/CTSvars.py /cts/HBDummy /cts/LSBDummy /cts/OCFIPraTest.py /cts/cts-coverage /cts/cts-log-watcher /cts/cts-support /cts/fence_dummy /cts/lab/CTSlab.py /cts/lab/CTSvars.py /cts/lab/OCFIPraTest.py /cts/lab/cluster_test /cts/lab/cts /cts/lab/cts-log-watcher /cts/lxc_autogen.sh /cts/pacemaker-cts-dummyd /cts/pacemaker-cts-dummyd@.service /daemons/based/cibmon /daemons/fenced/fence_legacy /daemons/fenced/fence_watchdog /daemons/pacemakerd/pacemaker /daemons/pacemakerd/pacemaker.combined.upstart /daemons/pacemakerd/pacemaker.upstart /depcomp /doc/*.build /doc/*/en-US/Ap-*.xml /doc/*/en-US/Ch-*.xml /doc/*/publican.cfg /doc/*/publish /doc/*/tmp/** +/doc/.ABI-build /doc/Clusters_from_Scratch.txt /doc/Pacemaker_Explained.txt +/doc/abi_dumps /doc/acls.html +/doc/compat_reports /doc/publican-catalog* /doc/shared/en-US/*.xml /doc/shared/en-US/images/pcmk-*.png /doc/shared/en-US/images/Policy-Engine-*.png /extra/*/* /fencing /include/stamp-* /install-sh /lib/common/md5.c /lib/common/tests/flags/pcmk__clear_flags_as /lib/common/tests/flags/pcmk__set_flags_as /lib/common/tests/flags/pcmk_all_flags_set /lib/common/tests/flags/pcmk_any_flags_set /lib/common/tests/operations/parse_op_key /lib/common/tests/strings/pcmk__btoa /lib/common/tests/strings/pcmk__parse_ll_range /lib/common/tests/strings/pcmk__scan_double /lib/common/tests/strings/pcmk__str_any_of /lib/common/tests/strings/pcmk__strcmp /lib/common/tests/strings/pcmk__char_in_any_str /lib/common/tests/utils/pcmk_str_is_infinity /lib/common/tests/utils/pcmk_str_is_minus_infinity /lib/gnu/libgnu.a /lib/pengine/tests/rules/ /lrmd /ltmain.sh /mcp /missing /mock /pacemaker-*.spec /pengine /py-compile /scratch /tools/cluster-init /tools/crm_mon.upstart /test-driver /xml/assets /xml/crm.dtd /xml/version-diff.sh ylwrap diff --git a/doc/Makefile.am b/doc/Makefile.am index ad46812f2d..fbfb7dbebe 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,150 +1,150 @@ # -# Copyright 2003-2024 the Pacemaker project contributors +# Copyright 2003-2025 the Pacemaker project contributors # # The version control history for this file may have further details. # # This source code is licensed under the GNU General Public License version 2 # or later (GPLv2+) WITHOUT ANY WARRANTY. # include $(top_srcdir)/mk/common.mk # Define release- and upload-related variables include $(top_srcdir)/mk/release.mk include $(top_srcdir)/mk/uploads.mk # What formats to use for book uploads (i.e. "make www"; # use BOOK_FORMATS in sphinx subdirectory to change local builds) BOOK_FORMATS ?= html \ singlehtml \ pdf \ epub # SNMP MIB mibdir = $(datadir)/snmp/mibs dist_mib_DATA = PCMK-MIB.txt noinst_SCRIPTS = abi-check SUBDIRS = sphinx EXTRA_DIST = clusterlabs-logo-55x55.png if IS_ASCIIDOC ASCIIDOC_HTML_ARGS = --unsafe --backend=xhtml11 ASCIIDOC_DBOOK_ARGS = -b docbook -d book else ASCIIDOC_HTML_ARGS = --backend=html5 ASCIIDOC_DBOOK_ARGS = -b docbook45 -d book endif %.html: %.txt $(AM_V_GEN)$(ASCIIDOC_CONV) $(ASCIIDOC_HTML_ARGS) --out-file=$@ $< $(PCMK_quiet) # For Makefile debugging .PHONY: vars vars: @echo LAST_RELEASE=\'$(LAST_RELEASE)\' @echo TAG=\'$(TAG)\' @echo RSYNC_DEST=\'$(RSYNC_DEST)\' @echo RSYNC_PACKAGE_DEST=\'$(RSYNC_PACKAGE_DEST)\' # Annotated source code as HTML # Cleaning first ensures we don't index unrelated stuff like RPM sources .PHONY: global global: $(MAKE) $(AM_MAKEFLAGS) -C .. clean-generic $(MAKE) $(AM_MAKEFLAGS) -C ../rpm rpm-clean cd .. && gtags -q && htags -sanhIT doc .PHONY: global-upload global-upload: global rsync $(RSYNC_OPTS) HTML/ "$(RSYNC_PACKAGE_DEST)/global/$(TAG)/" .PHONY: global-clean global-clean: -rm -rf HTML # Man pages as HTML MANPAGE_DIRS = ../agents ../daemons ../tools %.8.html: %.8 groff -mandoc `man -w ./$<` -T html > $@ %.7.html: %.7 groff -mandoc `man -w ./$<` -T html > $@ .PHONY: manhtml manhtml: $(MAKE) $(AM_MAKEFLAGS) -C .. all find $(MANPAGE_DIRS) -name "[a-z]*.[78]" \ -exec $(MAKE) $(AM_MAKEFLAGS) \{\}.html \; .PHONY: manhtml-upload manhtml-upload: manhtml find $(MANPAGE_DIRS) -name "[a-z]*.[78].html" -exec \ rsync $(RSYNC_OPTS) \{\} "$(RSYNC_PACKAGE_DEST)/man/" \; .PHONY: manhtml-clean manhtml-clean: -find $(MANPAGE_DIRS) -name "[a-z]*.[78].html" -exec rm \{\} \; # API documentation as HTML .PHONY: doxygen doxygen: Doxyfile doxygen Doxyfile .PHONY: doxygen-upload doxygen-upload: doxygen rsync $(RSYNC_OPTS) api/html/ "$(RSYNC_PACKAGE_DEST)/doxygen/$(TAG)/" .PHONY: doxygen-clean doxygen-clean: -rm -rf api # ABI compatibility report as HTML .PHONY: abi abi: abi-check ./abi-check $(PACKAGE) $(LAST_RELEASE) $(TAG) .PHONY: abi-www abi-www: export RSYNC_PACKAGE_DEST=$(RSYNC_PACKAGE_DEST); \ ./abi-check -u $(PACKAGE) $(LAST_RELEASE) $(TAG) .PHONY: abi-clean abi-clean: - -rm -rf abi_dumps compat_reports + -rm -rf abi # The main documentation books (which are actually in the sphinx subdirectory) .PHONY: books-upload books-upload: $(MAKE) $(AM_MAKEFLAGS) -C sphinx clean $(MAKE) $(AM_MAKEFLAGS) -C sphinx \ RSYNC_DEST="$(RSYNC_DEST)" \ BOOK_FORMATS="$(BOOK_FORMATS)" \ books-upload # All online documentation (except ABI compatibility, which is run separately) .PHONY: www www: clean-local manhtml-upload global-upload doxygen-upload books-upload .PHONY: clean-local clean-local: global-clean manhtml-clean doxygen-clean abi-clean # "make check" will cause "make all" to be run, which means docs will get built # as a part of running tests if they haven't already. That seems unnecessary, so # override the default check-recursive rule with this one that just returns. If # we ever need to add tests to this directory, this rule will have to come out. .PHONY: check-recursive check-recursive: @true diff --git a/doc/abi-check.in b/doc/abi-check.in index 7972248214..ee431510cd 100755 --- a/doc/abi-check.in +++ b/doc/abi-check.in @@ -1,166 +1,175 @@ #!@BASH_PATH@ # -# Copyright 2011-2024 the Pacemaker project contributors +# Copyright 2011-2025 the Pacemaker project contributors # # The version control history for this file may have further details. # # This source code is licensed under the GNU General Public License version 2 # or later (GPLv2+) WITHOUT ANY WARRANTY. # # # abi-check [-u] [...] # # Build ABI dumps for all listed versions. If exactly two are given, # build an ABI compatibility report for them, and if -u is given, # upload it to the website. # +# Where to checkout the source for a version +ABI_CHECKOUT="abi/src" + +# Where to install the checkout build +ABI_INSTALL="abi/install" + +# Where to build ABI dumps +ABI_DUMPS="abi/dumps" + +# Where to build ABI reports +ABI_REPORTS="abi/compat_reports" + # If the argument is of form x.y.z, print Pacemaker-x.y.z, # otherwise print the argument (presumably a commit ID) directly tag() { if [[ "$1" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3} ]]; then echo "Pacemaker-$1" else echo "$1" fi } sed_in_place() { cp -p "$1" "$1.$$" sed -e "$2" "$1" > "$1.$$" mv "$1.$$" "$1" } # Strip anything up to and including a dash from the argument version() { echo "$1" | sed s:.*-:: } # Create configuration file for ABI dumper abi_config() { PACKAGE="$1" VERSION="$2" - BUILD_ROOT="$3" - DESC="$4" + DESC="$3" # Create header - DESC="$BUILD_ROOT/$VERSION.xml" + DESC="${ABI_CHECKOUT}/${VERSION}.xml" cat < "$DESC" $VERSION - $BUILD_ROOT/root/usr/include/$PACKAGE/crm + $(pwd)/${ABI_INSTALL}/usr/include/${PACKAGE}/crm EOF # Build checkout, installing into subdirectory - ( cd "$BUILD_ROOT" && ./autogen.sh && ./configure --disable-fatal-warnings ) - make -C "$BUILD_ROOT" V=0 DESTDIR="${BUILD_ROOT}/root" install + ( cd "$ABI_CHECKOUT" && ./autogen.sh && ./configure --disable-fatal-warnings ) + make -C "$ABI_CHECKOUT" V=0 DESTDIR="$ABI_INSTALL" install if [ $? -ne 0 ]; then echo "Build for $TAG failed. Repair, populate and re-run: " echo " abi-compliance-checker -l $PACKAGE -dump_abi $DESC" echo "" echo "To find libraries after building:" - echo " find $BUILD_ROOT/root -name "*.so" -print" + echo " find $ABI_INSTALL -name "*.so" -print" exit 1 fi # Add library names to configuration file - find $BUILD_ROOT/root -name "*.so" -print >> $DESC + find "$ABI_INSTALL" -name "*.so" -print >> $DESC # Add footer cat <> "$DESC" EOF } # Dump the ABI for a particular version extract_one() { TAG="$1" VERSION="$2" # If dump already exists, remove it if dumping HEAD (which changes), # otherwise use it (a dump for a particular commit stays the same). - TARBALL="abi_dumps/$PACKAGE/${PACKAGE}_$VERSION.abi.tar.gz" + TARBALL="${ABI_DUMPS}/${PACKAGE}_$VERSION.abi.tar.gz" if [ "$VERSION" = HEAD ]; then rm -rf "$TARBALL" elif [ -f "$TARBALL" ]; then return fi echo "Building ABI dump for $*" # Get a clean checkout at the desired commit - BUILD_ROOT=".ABI-build" - rm -rf "$BUILD_ROOT" - ( cd .. ; git archive --prefix "doc/$BUILD_ROOT/" "$TAG" | tar xv ) + rm -rf "$ABI_CHECKOUT" + ( cd .. ; git archive --prefix "doc/${ABI_CHECKOUT}/" "$TAG" | tar xv ) if [ $? -ne 0 ]; then exit fi # Remove "doc" from SUBDIRS in Makefile (but why?) - BUILD_ROOT="$(pwd)/$BUILD_ROOT" - sed_in_place "$BUILD_ROOT/Makefile.am" 's: doc::' + sed_in_place "${ABI_CHECKOUT}/Makefile.am" 's: doc::' # Run ABI dump - abi_config "$PACKAGE" "$VERSION" "$BUILD_ROOT" "$DESC" + abi_config "$PACKAGE" "$VERSION" "$DESC" abi-compliance-checker -l "$PACKAGE" -dump_abi "$DESC" \ - -dump-path "abi_dumps/${PACKAGE}/${PACKAGE}_${VERSION}.abi.tar.gz" + -dump-path "${ABI_DUMPS}/${PACKAGE}_${VERSION}.abi.tar.gz" # Clean up - rm -rf "$BUILD_ROOT" + rm -rf "$ABI_CHECKOUT" "$ABI_INSTALL" } extract_all() { for arg in $*; do T=$(tag "$arg") V=$(version "$T") extract_one "$T" "$V" done } die() { echo "$@" 1>&2 exit 1 } which git 2>/dev/null || die "abi-check: git must be installed" git rev-parse --git-dir >/dev/null 2>/dev/null \ || die "abi-check: must be run from git checkout" UPLOAD=0 if [ "$1" = "-u" ]; then UPLOAD=1; shift fi PACKAGE="$1"; shift extract_all "$@" if [ $# -eq 2 ]; then V1=$(version "$1") V2=$(version "$2") - abi-compliance-checker -l ${PACKAGE} \ - -d1 abi_dumps/${PACKAGE}/${PACKAGE}_${V1}.abi.tar.gz \ - -d2 abi_dumps/${PACKAGE}/${PACKAGE}_${V2}.abi.tar.gz + (cd abi && abi-compliance-checker -l ${PACKAGE} \ + -d1 "${ABI_DUMPS#abi/}/${PACKAGE}_${V1}.abi.tar.gz" \ + -d2 "${ABI_DUMPS#abi/}/${PACKAGE}_${V2}.abi.tar.gz") if [ $? -ne 0 ]; then echo "WARNING: compliance checker exited $?" fi # Top-level rsync destination for package's file uploads (no trailing slash) : ${RSYNC_PACKAGE_DEST:=sites.clusterlabs.org:/var/www/html/projects/$PACKAGE} - COMPAT_REPORT="compat_reports/${PACKAGE}/${V1}_to_${V2}" - if [ $UPLOAD -eq 1 ] && [ -d "$COMPAT_REPORT" ]; then - rsync -azxlSD --progress "$COMPAT_REPORT" "${RSYNC_PACKAGE_DEST}/abi/" + REPORT="${ABI_REPORTS}/${PACKAGE}/${V1}_to_${V2}" + if [ $UPLOAD -eq 1 ] && [ -d "$REPORT" ]; then + rsync -azxlSD --progress "$REPORT" "${RSYNC_PACKAGE_DEST}/abi/" fi fi # vim: set expandtab tabstop=8 softtabstop=4 shiftwidth=4 textwidth=80: