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.