From 17f566c55e1891715c122cfb839ed18a27b841e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cezary=20Skrzy=C5=84ski?= Date: Mon, 11 Nov 2024 16:18:53 +0100 Subject: [PATCH 1/7] #371: update defaults in .env --- .env | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.env b/.env index 6836da5d..b8cef152 100644 --- a/.env +++ b/.env @@ -1,8 +1,8 @@ REPO=lifflander1/checkpoint ARCH=amd64 -UBUNTU=18.04 +UBUNTU=22.04 ULIMIT_CORE=0 -COMPILER=gcc-8 +COMPILER=gcc-11 COMPILER_TYPE=gnu PROXY= CACHE= From aa4760c6ec4b54f961eded45520d21c16be584f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cezary=20Skrzy=C5=84ski?= Date: Mon, 11 Nov 2024 16:25:20 +0100 Subject: [PATCH 2/7] #371: docs: use doxygen v1.8.16 --- ci/deps/doxygen.sh | 18 +++++++++ ci/docker/ubuntu-20.04-gnu-docs.dockerfile | 47 +++++++++++----------- 2 files changed, 42 insertions(+), 23 deletions(-) create mode 100755 ci/deps/doxygen.sh diff --git a/ci/deps/doxygen.sh b/ci/deps/doxygen.sh new file mode 100755 index 00000000..eff7a54f --- /dev/null +++ b/ci/deps/doxygen.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash + +set -exo pipefail + +if test $# -ne 1 +then + echo "usage: ./$0 " + exit 1 +fi + +doxygen_version=$1 +doxygen_tar_name=doxygen-"${doxygen_version}".linux.bin.tar.gz + +echo "${doxygen_tar_name}" + +wget https://sourceforge.net/projects/doxygen/files/rel-"${doxygen_version}"/"${doxygen_tar_name}" + +tar xzf "${doxygen_tar_name}" --one-top-level=doxygen --strip-components=1 diff --git a/ci/docker/ubuntu-20.04-gnu-docs.dockerfile b/ci/docker/ubuntu-20.04-gnu-docs.dockerfile index 76dc885d..8ea2af0c 100644 --- a/ci/docker/ubuntu-20.04-gnu-docs.dockerfile +++ b/ci/docker/ubuntu-20.04-gnu-docs.dockerfile @@ -1,6 +1,6 @@ ARG arch=amd64 -FROM ${arch}/ubuntu:20.04 as base +FROM ${arch}/ubuntu:20.04 AS base ARG proxy="" ARG compiler=gcc-8 @@ -13,33 +13,33 @@ ENV DEBIAN_FRONTEND=noninteractive RUN apt-get update -y -q && \ apt-get install -y -q --no-install-recommends \ - ca-certificates \ - curl \ - cmake \ - git \ - mpich \ - libmpich-dev \ - wget \ - ${compiler} \ - zlib1g \ - zlib1g-dev \ - ninja-build \ - doxygen \ - unzip \ - python3 \ - python3-jinja2 \ - python3-pygments \ - texlive-font-utils \ - ghostscript \ - ccache && \ + ${compiler} \ + ca-certificates \ + ccache \ + curl \ + ghostscript \ + git \ + libmpich-dev \ + mpich \ + ninja-build \ + python3 \ + python3-jinja2 \ + python3-pygments \ + texlive-font-utils \ + unzip \ + wget \ + zlib1g \ + zlib1g-dev &&\ apt-get clean && \ rm -rf /var/lib/apt/lists/* COPY ./ci/deps/cmake.sh cmake.sh RUN ./cmake.sh 3.23.4 ${arch} - ENV PATH=/cmake/bin/:$PATH -ENV LESSCHARSET=utf-8 + +COPY ./ci/deps/doxygen.sh doxygen.sh +RUN ./doxygen.sh 1.8.16 +ENV PATH=/doxygen/bin/:$PATH COPY ./ci/deps/gtest.sh gtest.sh RUN ./gtest.sh 1.8.1 /pkgs @@ -57,9 +57,10 @@ ENV MPI_EXTRA_FLAGS="" \ CMAKE_PREFIX_PATH="/lib/x86_64-linux-gnu/" \ CC=mpicc \ CXX=mpicxx \ + LESSCHARSET=utf-8 \ PATH=/usr/lib/ccache/:$PATH -FROM base as build +FROM base AS build COPY . /checkpoint ARG token From f3ce84a1290c09f53ec108891afcf68d417a1609 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cezary=20Skrzy=C5=84ski?= Date: Tue, 12 Nov 2024 20:12:42 +0100 Subject: [PATCH 3/7] #371: docs: update GitHub links --- docs/Doxyfile.in-mcss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Doxyfile.in-mcss b/docs/Doxyfile.in-mcss index 5c47e7c3..e592715c 100644 --- a/docs/Doxyfile.in-mcss +++ b/docs/Doxyfile.in-mcss @@ -14,7 +14,7 @@ XML_NS_MEMB_FILE_SCOPE = YES ##! M_LINKS_NAVBAR2 = \ ##! "annotated" \ ##! "files" \ -##! "GitHub Checkpoint Checkpoint Analyzer Detector" +##! "GitHub magistrate Serialization Sanitizer" ##! ALIASES += \ ##! "m_div{1}=@xmlonly@endxmlonly" \ From 9e220637f078820f495f3476a87737fdbbed9d56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cezary=20Skrzy=C5=84ski?= Date: Tue, 12 Nov 2024 20:21:00 +0100 Subject: [PATCH 4/7] #371: docs: use `magistrate` and C++17 --- docs/md/checkpoint_learn.md | 4 +- docs/md/checkpoint_learn_build.md | 62 +++++++++---------- docs/md/checkpoint_learn_example_2.md | 2 +- ...checkpoint_learn_example_2_nonintrusive.md | 2 +- docs/md/checkpoint_learn_example_3.md | 2 +- ...checkpoint_learn_example_3_nonintrusive.md | 2 +- ..._example_polymorphic_macro_nonintrusive.md | 2 +- ..._learn_example_polymorphic_nonintrusive.md | 2 +- docs/md/checkpoint_learn_example_traversal.md | 2 +- ...nt_learn_example_traversal_nonintrusive.md | 2 +- docs/md/mainpage.md | 8 +-- docs/shared/README.txt | 2 +- docs/shared/checkpoint_learn_example_1.md | 2 +- ...checkpoint_learn_example_1_nonintrusive.md | 2 +- .../checkpoint_learn_example_polymorphic.md | 2 +- ...ckpoint_learn_example_polymorphic_macro.md | 2 +- docs/shared/checkpoint_learn_serialize.md | 20 +++--- 17 files changed, 59 insertions(+), 61 deletions(-) diff --git a/docs/md/checkpoint_learn.md b/docs/md/checkpoint_learn.md index 999a8416..f4b5f13e 100644 --- a/docs/md/checkpoint_learn.md +++ b/docs/md/checkpoint_learn.md @@ -1,9 +1,9 @@ \page ckpt_learn Learn -To learn how to use *checkpoint*, several resources are available. +To learn how to use *magistrate*, several resources are available. - Learn \subpage ckpt_learn_build - Read the small example programs - Read the \subpage ckpt_learn_examples walk-through - - Examine `checkpoint/examples/*` + - Examine `magistrate/examples/*` - Learn \subpage ckpt_learn_serialize diff --git a/docs/md/checkpoint_learn_build.md b/docs/md/checkpoint_learn_build.md index b2c12a97..f45b593c 100644 --- a/docs/md/checkpoint_learn_build.md +++ b/docs/md/checkpoint_learn_build.md @@ -1,21 +1,21 @@ \page ckpt_learn_build How to Build -checkpoint can be built with `cmake`. +magistrate can be built with `cmake`. \section ckpt_how-to-build Building -To build *checkpoint*, one must obtain the following dependencies: +To build *magistrate*, one must obtain the following dependencies: \subsection ckpt_optional-deps Optional - - gtest, (if testing *checkpoint* is enabled) + - gtest, (if testing *magistrate* is enabled) - MPI, (if MPI tests are enabled) - [Kokkos](https://github.com/kokkos/kokkos), (if Kokkos views need to be serialized) - [KokkosKernels](https://github.com/kokkos/kokkos-kernels), (if Kokkos kernel data structures need to be serialized) \subsection ckpt_use-cmake-directly-vars Using cmake directly -One may use `cmake` to build *checkpoint* once the dependencies are installed. +One may use `cmake` to build *magistrate* once the dependencies are installed. The following are some options that can be provided to `cmake` to change the build configuration: @@ -24,22 +24,22 @@ build configuration: | `gtest_DIR` | | Install directory for googletest | | `Kokkos_DIR` | | Install directory for kokkos | | `KokkosKernels_DIR` | | Install directory for kokkoskernels | -| `checkpoint_tests_enabled` | 0 | Build *checkpoint* tests | -| `checkpoint_mpi_enabled` | 0 | Build *checkpoint* with MPI for tests | -| `checkpoint_examples_enabled` | 0 | Build *checkpoint* examples | -| `checkpoint_warnings_as_errors` | 0 | Make all warnings errors during build | -| `checkpoint_doxygen_enabled` | 0 | Enable doxygen generation | -| `checkpoint_asan_enabled` | 0 | Enable address sanitizer | -| `checkpoint_ubsan_enabled` | 0 | Enable undefined behavior sanitizer | -| `checkpoint_serialization_error_checking_enabled(*)` | 0 | Enable extensive serialization error checking | +| `magistrate_tests_enabled` | 0 | Build *magistrate* tests | +| `magistrate_mpi_enabled` | 0 | Build *magistrate* with MPI for tests | +| `magistrate_examples_enabled` | 0 | Build *magistrate* examples | +| `magistrate_warnings_as_errors` | 0 | Make all warnings errors during build | +| `magistrate_doxygen_enabled` | 0 | Enable doxygen generation | +| `magistrate_asan_enabled` | 0 | Enable address sanitizer | +| `magistrate_ubsan_enabled` | 0 | Enable undefined behavior sanitizer | +| `magistrate_serialization_error_checking_enabled(*)` | 0 | Enable extensive serialization error checking | | `CODE_COVERAGE` | 0 | Generate code coverage report | -* note that if `checkpoint_serialization_error_checking_enabled` is not explicitly enabled or disabled, it will be **enabled** for `Debug` and `RelWithDebInfo` builds and disabled for others. +* note that if `magistrate_serialization_error_checking_enabled` is not explicitly enabled or disabled, it will be **enabled** for `Debug` and `RelWithDebInfo` builds and disabled for others. \subsection using-the-build-script Using the Build Script -Instead of running `cmake`, one may invoke the `checkpoint/ci/build_cpp.sh` -script which will run `cmake` for *checkpoint* with environment variables for +Instead of running `cmake`, one may invoke the `magistrate/ci/build_cpp.sh` +script which will run `cmake` for *magistrate* with environment variables for most configuration parameters. \subsubsection building-environment-variables Build Script Environment Variables @@ -54,27 +54,27 @@ most configuration parameters. | `MAGISTRATE_DOXYGEN_ENABLED` | 0 | Enable doxygen generation | | `MAGISTRATE_ASAN_ENABLED` | 0 | Enable building with address sanitizer | | `MAGISTRATE_UBSAN_ENABLED` | 0 | Enable building with undefined behavior sanitizer | -| `MAGISTRATE_TESTS_ENABLED` | 1 | Enable checkpoint tests | -| `MAGISTRATE_EXAMPLES_ENABLED` | 1 | Enable checkpoint examples | +| `MAGISTRATE_TESTS_ENABLED` | 1 | Enable magistrate tests | +| `MAGISTRATE_EXAMPLES_ENABLED` | 1 | Enable magistrate examples | | `MAGISTRATE_WARNINGS_AS_ERRORS` | 0 | Make all warnings errors during build | | `MAGISTRATE_SERIALIZATION_ERROR_CHECKING_ENABLED` | 0 | Enable extensive error checking of serialization | -| `MAGISTRATE_MPI_ENABLED` | 1 | Enable checkpoint MPI for testing | +| `MAGISTRATE_MPI_ENABLED` | 1 | Enable magistrate MPI for testing | * note that if `MAGISTRATE_SERIALIZATION_ERROR_CHECKING_ENABLED` is not explicitly enabled or disabled, it will be **enabled** for `Debug` and `RelWithDebInfo` builds and disabled for others. With these set, invoke the script with two arguments: the path to the -*checkpoint* root directory and the build path. Here's an example assuming that -*checkpoint* is cloned into `/usr/src/checkpoint` with trace enabled in debug mode. +*magistrate* root directory and the build path. Here's an example assuming that +*magistrate* is cloned into `/usr/src/magistrate` with trace enabled in debug mode. **Usage for building:** ```bash -$ checkpoint/ci/build_cpp.sh +$ magistrate/ci/build_cpp.sh ``` \subsection docker-build Building with docker containerization -The easiest way to build *checkpoint* is by using `docker` with the available +The easiest way to build *magistrate* is by using `docker` with the available containers that contain the proper compilers, MPI, and all other dependencies. First, install `docker` on the system. On some systems, `docker-compose` might also need to be installed. @@ -88,7 +88,7 @@ Nvidia) and compiler version, Linux distro (ubuntu or alpine), and distro version. The default set of the docker configuration options is located in -`checkpoint/.env`, which `docker-compose` will read. +`magistrate/.env`, which `docker-compose` will read. ``` # Variables: @@ -103,10 +103,10 @@ The default set of the docker configuration options is located in # UBUNTU={18.04, 20.04} # ULIMIT_CORE=0 # -# DARMA/checkpoint Configuration Variables: -# MAGISTRATE_TESTS=1 # Enable checkpoint tests -# MAGISTRATE_EXAMPLES=1 # Enable checkpoint examples -# MAGISTRATE_MPI=1 # Enable checkpoint MPI tests +# DARMA/magistrate Configuration Variables: +# MAGISTRATE_TESTS=1 # Enable magistrate tests +# MAGISTRATE_EXAMPLES=1 # Enable magistrate examples +# MAGISTRATE_MPI=1 # Enable magistrate MPI tests # MAGISTRATE_WARNINGS_AS_ERRORS=0 # Treat warnings as errors in compilation # MAGISTRATE_ASAN=0 # Enable address sanitizer in build # MAGISTRATE_UBSAN=0 # Enable undefined behavior sanitizer in build @@ -121,7 +121,7 @@ ubuntu. Or, to speed up the build process, the base container can be pulled for many of the common configurations: `docker-compose pull ubuntu-cpp`. ```bash -$ cd checkpoint +$ cd magistrate $ docker-compose run -e BUILD_TYPE=debug ubuntu-cpp ``` @@ -129,8 +129,8 @@ For an interactive build with ubuntu, where one can build, debug, and run `valgrind`, etc: ```bash -$ cd checkpoint +$ cd magistrate $ docker-compose run -e BUILD_TYPE=debug ubuntu-cpp-interactive -# /checkpoint/ci/build_cpp.sh /checkpoint /build -# /checkpoint/ci/test_cpp.sh /checkpoint /build +# /magistrate/ci/build_cpp.sh /magistrate /build +# /magistrate/ci/test_cpp.sh /magistrate /build ``` diff --git a/docs/md/checkpoint_learn_example_2.md b/docs/md/checkpoint_learn_example_2.md index 3cce924f..508499ac 100644 --- a/docs/md/checkpoint_learn_example_2.md +++ b/docs/md/checkpoint_learn_example_2.md @@ -1,6 +1,6 @@ \page ckpt_learn_ex2 Program Example 2 -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_2.cc` \subsubsection ex2 Example source code: diff --git a/docs/md/checkpoint_learn_example_2_nonintrusive.md b/docs/md/checkpoint_learn_example_2_nonintrusive.md index 1178d948..b5dd6744 100644 --- a/docs/md/checkpoint_learn_example_2_nonintrusive.md +++ b/docs/md/checkpoint_learn_example_2_nonintrusive.md @@ -2,7 +2,7 @@ \attention All Non-Intrusive serialize methods MUST be placed in the namespace of type which they serialize. -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_2_nonintrusive.cc` \subsubsection ex2 Example source code: diff --git a/docs/md/checkpoint_learn_example_3.md b/docs/md/checkpoint_learn_example_3.md index 1378b365..a18bf25f 100644 --- a/docs/md/checkpoint_learn_example_3.md +++ b/docs/md/checkpoint_learn_example_3.md @@ -1,6 +1,6 @@ \page ckpt_learn_ex3 Program Example 3 -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_3.cc` \subsubsection ex3 Example source code: diff --git a/docs/md/checkpoint_learn_example_3_nonintrusive.md b/docs/md/checkpoint_learn_example_3_nonintrusive.md index 46c95b6d..3b35c8ed 100644 --- a/docs/md/checkpoint_learn_example_3_nonintrusive.md +++ b/docs/md/checkpoint_learn_example_3_nonintrusive.md @@ -2,7 +2,7 @@ \attention All Non-Intrusive serialize methods MUST be placed in the namespace of type which they serialize. -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_3_nonintrusive.cc` \subsubsection ex3 Example source code: diff --git a/docs/md/checkpoint_learn_example_polymorphic_macro_nonintrusive.md b/docs/md/checkpoint_learn_example_polymorphic_macro_nonintrusive.md index b1a7b7a0..0bc5899b 100644 --- a/docs/md/checkpoint_learn_example_polymorphic_macro_nonintrusive.md +++ b/docs/md/checkpoint_learn_example_polymorphic_macro_nonintrusive.md @@ -2,7 +2,7 @@ \attention All Non-Intrusive serialize methods MUST be placed in the namespace of type which they serialize. -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_polymorphic_macro_nonintrusive.cc` \subsubsection ex6 Example source code: diff --git a/docs/md/checkpoint_learn_example_polymorphic_nonintrusive.md b/docs/md/checkpoint_learn_example_polymorphic_nonintrusive.md index 28c57395..8b7d08e4 100644 --- a/docs/md/checkpoint_learn_example_polymorphic_nonintrusive.md +++ b/docs/md/checkpoint_learn_example_polymorphic_nonintrusive.md @@ -2,7 +2,7 @@ \attention All Non-Intrusive serialize methods MUST be placed in the namespace of type which they serialize. -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_polymorphic_nonintrusive.cc` \subsubsection ex5 Example source code: diff --git a/docs/md/checkpoint_learn_example_traversal.md b/docs/md/checkpoint_learn_example_traversal.md index 132948c7..4e967a56 100644 --- a/docs/md/checkpoint_learn_example_traversal.md +++ b/docs/md/checkpoint_learn_example_traversal.md @@ -1,6 +1,6 @@ \page ckpt_learn_ex7_traversal Program Example Traversal -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_traversal.cc` \subsubsection ex7 Example source code: diff --git a/docs/md/checkpoint_learn_example_traversal_nonintrusive.md b/docs/md/checkpoint_learn_example_traversal_nonintrusive.md index 59dea49b..70d175cf 100644 --- a/docs/md/checkpoint_learn_example_traversal_nonintrusive.md +++ b/docs/md/checkpoint_learn_example_traversal_nonintrusive.md @@ -2,7 +2,7 @@ \attention All Non-Intrusive serialize methods MUST be placed in the namespace of type which they serialize. -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_traversal_nonintrusive.cc` \subsubsection ex7 Example source code: diff --git a/docs/md/mainpage.md b/docs/md/mainpage.md index ea33c5ae..a237a6a0 100644 --- a/docs/md/mainpage.md +++ b/docs/md/mainpage.md @@ -1,14 +1,12 @@ \mainpage Introduction -\tableofcontents +\section ckpt_what_is What is magistrate? -\section ckpt_what_is What is checkpoint? - -\checkpoint is a serialization and checkpointing library written in C++14. It +`magistrate` is a serialization and checkpointing library written in C++17. It allows any C++ type that has a serialize method or free function associated with it to be recursively traversed and transformed by the library. For instance, if the user wants to send over the network, the traversal will create a byte buffer -that contains all the data for a message. `DARMA/checkpoint` is a general +that contains all the data for a message. `DARMA/magistrate` is a general library that can also be used for other purposes such as I/O---creating snapshots of objects to disk. diff --git a/docs/shared/README.txt b/docs/shared/README.txt index 2e69c228..443eb894 100644 --- a/docs/shared/README.txt +++ b/docs/shared/README.txt @@ -3,5 +3,5 @@ with the VT documentation. - These Markdown files should not include any reference to -Markdown files in the directory `checkpoint/docs/md` +Markdown files in the directory `magistrate/docs/md` diff --git a/docs/shared/checkpoint_learn_example_1.md b/docs/shared/checkpoint_learn_example_1.md index 7229af39..53d3f698 100644 --- a/docs/shared/checkpoint_learn_example_1.md +++ b/docs/shared/checkpoint_learn_example_1.md @@ -1,6 +1,6 @@ \page ckpt_learn_ex1 Program Example 1 -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_1.cc` \snippet examples/checkpoint_example_1.cc Serialize structure built-in types diff --git a/docs/shared/checkpoint_learn_example_1_nonintrusive.md b/docs/shared/checkpoint_learn_example_1_nonintrusive.md index 57e693de..d93f1f7e 100644 --- a/docs/shared/checkpoint_learn_example_1_nonintrusive.md +++ b/docs/shared/checkpoint_learn_example_1_nonintrusive.md @@ -2,7 +2,7 @@ \attention All Non-Intrusive serialize methods MUST be placed in the namespace of type which they serialize. -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_1_nonintrusive.cc` \subsubsection ex1 Example source code: diff --git a/docs/shared/checkpoint_learn_example_polymorphic.md b/docs/shared/checkpoint_learn_example_polymorphic.md index 29c79394..58318d31 100644 --- a/docs/shared/checkpoint_learn_example_polymorphic.md +++ b/docs/shared/checkpoint_learn_example_polymorphic.md @@ -1,6 +1,6 @@ \page ckpt_learn_ex5_polymorphic Polymorphic Serialization Example -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_polymorphic.cc` \snippet examples/checkpoint_example_polymorphic.cc Serialize polymorphic diff --git a/docs/shared/checkpoint_learn_example_polymorphic_macro.md b/docs/shared/checkpoint_learn_example_polymorphic_macro.md index 98c6c103..09f80b5c 100644 --- a/docs/shared/checkpoint_learn_example_polymorphic_macro.md +++ b/docs/shared/checkpoint_learn_example_polymorphic_macro.md @@ -1,6 +1,6 @@ \page ckpt_learn_ex6_polymorphic_macro Polymorphic Serialization Example w/Macros -The full code for this *checkpoint* example can be found here: +The full code for this *magistrate* example can be found here: `examples/checkpoint_example_polymorphic_macro.cc` \snippet examples/checkpoint_example_polymorphic_macro.cc Serialize polymorphic macro diff --git a/docs/shared/checkpoint_learn_serialize.md b/docs/shared/checkpoint_learn_serialize.md index 24fcbda5..a1e149b3 100644 --- a/docs/shared/checkpoint_learn_serialize.md +++ b/docs/shared/checkpoint_learn_serialize.md @@ -2,7 +2,7 @@ *Serialization* is the process of recursively traversing C++ objects into a simple format that can be stored or transmitted and reconstructed later. -*checkpoint* translates the object into a set of contiguous bits and provides +*magistrate* translates the object into a set of contiguous bits and provides the steps to reverse the process, i.e. to reconstitute the object from the set of bits. @@ -55,15 +55,15 @@ to actually perform the serialization. \subsection reconstruct_class Class reconstruction -There are several ways to allow *checkpoint* to reconstruct a -class. *checkpoint* will try to detect a reconstruction strategy in the +There are several ways to allow *magistrate* to reconstruct a +class. *magistrate* will try to detect a reconstruction strategy in the following resolution order: - 1. Tagged constructor: `MyClass(checkpoint::SERIALIZE_CONSTRUCT_TAG) {}` + 1. Tagged constructor: `MyClass(magistrate::SERIALIZE_CONSTRUCT_TAG) {}` 1. Reconstruction `MyClass::reconstruct(buf)` or `reconstruct(MyClass, buf)` 1. Default constructor: `MyClass()` -If no reconstruct strategy is detected with type traits, *checkpoint* will fail -at compile-time with a static assertion indicating that *checkpoint* can't +If no reconstruct strategy is detected with type traits, *magistrate* will fail +at compile-time with a static assertion indicating that *magistrate* can't reconstruct the class. The example in \ref ckpt_learn_ex1 illustrates the reconstruct method. @@ -83,10 +83,10 @@ serialization of the class state. To serialize polymorphic class hierarchies, one must write serializers for each class in the hierarchy. Then, the user should either insert macros `checkpoint_virtual_serialize_root()` and -`checkpoint_virtual_serialize_derived_from(T)` to inform *checkpoint* of the +`checkpoint_virtual_serialize_derived_from(T)` to inform *magistrate* of the hierarchy so it can automatically traverse the hierarchy. Alternatively, the -user may use the inheritance wrappers `checkpoint::SerializableBase` and -`checkpoint::SerializableDerived` to achieve the same effect. +user may use the inheritance wrappers `magistrate::SerializableBase` and +`magistrate::SerializableDerived` to achieve the same effect. The example in \ref ckpt_learn_ex6_polymorphic_macro illustrates the approach uses the macros. The example in \ref ckpt_learn_example_polymorphic @@ -99,6 +99,6 @@ illustrates this approach. type. - If one has a raw pointer, `Teuchos::RCP`, or `std::shared_ptr`, - `checkpoint::allocateConstructForPointer(s, ptr)` can be + `magistrate::allocateConstructForPointer(s, ptr)` can be invoked to properly allocate and construct the concrete class depending on runtime type. From 7458ca502821f3cebf6e3a10d3cb377c475c6f8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cezary=20Skrzy=C5=84ski?= Date: Tue, 12 Nov 2024 20:29:05 +0100 Subject: [PATCH 5/7] #371: docs: misc fixes --- cmake/load_doxygen.cmake | 6 +++--- docs/Doxyfile.in-mcss | 22 +++++++++++----------- docs/md/mainpage.md | 6 ++---- 3 files changed, 16 insertions(+), 18 deletions(-) diff --git a/cmake/load_doxygen.cmake b/cmake/load_doxygen.cmake index fe39822c..b7e359c2 100644 --- a/cmake/load_doxygen.cmake +++ b/cmake/load_doxygen.cmake @@ -5,7 +5,7 @@ if (${magistrate_doxygen_enabled}) set(doxygen_in ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in) set(doxygen_out ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) - set(DOXYGEN_PROJECT_NAME "checkpoint") + set(DOXYGEN_PROJECT_NAME "magistrate") set(VERSION_MAJOR "1") set(VERSION_MINOR "0") set(VERSION_PATCH "0") @@ -18,13 +18,13 @@ if (${magistrate_doxygen_enabled}) configure_file(${doxygen_in} ${doxygen_out} @ONLY) configure_file(${doxygen_in}-mcss ${doxygen_out}-mcss @ONLY) - message(STATUS "checkpoint doxygen build started") + message(STATUS "magistrate doxygen build started") add_custom_target( docs ALL COMMAND ${DOXYGEN_EXECUTABLE} ${doxygen_out} WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "checkpoint generating API documentation with Doxygen" + COMMENT "magistrate generating API documentation with Doxygen" VERBATIM ) diff --git a/docs/Doxyfile.in-mcss b/docs/Doxyfile.in-mcss index e592715c..320a8964 100644 --- a/docs/Doxyfile.in-mcss +++ b/docs/Doxyfile.in-mcss @@ -16,14 +16,14 @@ XML_NS_MEMB_FILE_SCOPE = YES ##! "files" \ ##! "GitHub magistrate Serialization Sanitizer" -##! ALIASES += \ -##! "m_div{1}=@xmlonly@endxmlonly" \ -##! "m_enddiv=@xmlonly@endxmlonly" \ -##! "m_span{1}=@xmlonly@endxmlonly" \ -##! "m_endspan=@xmlonly@endxmlonly" \ -##! "m_class{1}=@xmlonly@endxmlonly" \ -##! "m_footernavigation=@xmlonly@endxmlonly" \ -##! "m_examplenavigation{2}=@xmlonly@endxmlonly" \ -##! "m_keywords{1}=@xmlonly@endxmlonly" \ -##! "m_keyword{3}=@xmlonly@endxmlonly" \ -##! "m_enum_values_as_keywords=@xmlonly@endxmlonly" +ALIASES += \ + "m_div{1}=@xmlonly@endxmlonly" \ + "m_enddiv=@xmlonly@endxmlonly" \ + "m_span{1}=@xmlonly@endxmlonly" \ + "m_endspan=@xmlonly@endxmlonly" \ + "m_class{1}=@xmlonly@endxmlonly" \ + "m_footernavigation=@xmlonly@endxmlonly" \ + "m_examplenavigation{2}=@xmlonly@endxmlonly" \ + "m_keywords{1}=@xmlonly@endxmlonly" \ + "m_keyword{3}=@xmlonly@endxmlonly" \ + "m_enum_values_as_keywords=@xmlonly@endxmlonly" diff --git a/docs/md/mainpage.md b/docs/md/mainpage.md index a237a6a0..8a295159 100644 --- a/docs/md/mainpage.md +++ b/docs/md/mainpage.md @@ -1,4 +1,4 @@ -\mainpage Introduction +\mainpage DARMA/magistrate => serialization and checkpointing library \section ckpt_what_is What is magistrate? @@ -12,9 +12,7 @@ snapshots of objects to disk. \section License -@m_class{m-note m-dim} - -@parblock +@m_class{m-note m-dim} @parblock Copyright 2021 National Technology & Engineering Solutions of Sandia, LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software. From eb28b90a675a27862b50dfeb433cd3eedab95213 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cezary=20Skrzy=C5=84ski?= Date: Tue, 12 Nov 2024 20:57:40 +0100 Subject: [PATCH 6/7] #371: docs: update m.css version --- ci/build_cpp.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ci/build_cpp.sh b/ci/build_cpp.sh index 6fd81a31..2e7fc084 100755 --- a/ci/build_cpp.sh +++ b/ci/build_cpp.sh @@ -60,7 +60,7 @@ then git clone --depth=1 "https://${token}@github.com/DARMA-tasking/DARMA-tasking.github.io" git clone https://github.com/mosra/m.css cd m.css - git checkout 5235066 + git checkout 699abdd5 cd ../ "$MCSS/documentation/doxygen.py" Doxyfile-mcss CKPT_NAME=checkpoint_docs @@ -70,7 +70,7 @@ then git config --global user.email "jliffla@sandia.gov" git config --global user.name "Jonathan Lifflander" git add "$CKPT_NAME" - git commit -m "Update checkpoint_docs (auto-build)" + git commit -m "Update magistrate_docs (auto-build)" git push origin master else time cmake --build . --target "${target}" From 45fb0a4c562b9a546e4455f393fdc3c015754b51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cezary=20Skrzy=C5=84ski?= Date: Wed, 13 Nov 2024 22:57:50 +0100 Subject: [PATCH 7/7] #371: docs: use correct syntax for @m_class --- docs/md/mainpage.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/md/mainpage.md b/docs/md/mainpage.md index 8a295159..5478c4cc 100644 --- a/docs/md/mainpage.md +++ b/docs/md/mainpage.md @@ -12,7 +12,9 @@ snapshots of objects to disk. \section License -@m_class{m-note m-dim} @parblock +@m_class{m-note m-dim} + +@parblock Copyright 2021 National Technology & Engineering Solutions of Sandia, LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software.