Review Axom's config options and associated documentation

[kennyweiss]

In #706, @bmhan12 observed that Axom has several config options that are not documented.

These include:

• AXOM_QUEST_ENABLE_EXTRA_REGRESSION_TESTS, a developer option
• AXOM_ENABLE_MFEM_SIDRE_DATACOLLECTION a stopgap solution until we can fully switch over to using axom's MFEMSidreDataCollection instead of mfem's SidreDataCollection
• AXOM_MINT_USE_SIDRE a component-specific option. I'm not sure if this is still needed

It might be worthwhile to review and discuss these as a team.

[rhornung67]

It seems like we need to have some discussion about how we want to document Axom options and what we want to expose to users and developers vs. developers only.

Currently, we document the following CMake options in our quickstart guide:

OPTION	Default	Description
AXOM_DEBUG_DEFINE	DEFAULT	Controls whether the AXOM_DEBUG compiler define is enabled By DEFAULT, it is enabled for Debug and RelWithDebInfo configs but this can be overridden by setting AXOM_DEBUG_DEFINE to ON or OFF
AXOM_ENABLE_ALL_COMPONENTS	ON	Enable all components by default
AXOM_ENABLE_	ON	Enables the axom component named ‘foo’ (e.g. AXOM_ENABLE_SIDRE) for the sidre component
AXOM_ENABLE_DOCS	ON	Builds documentation
AXOM_ENABLE_EXAMPLES	ON	Builds examples
AXOM_ENABLE_TESTS	ON	Builds unit tests
AXOM_ENABLE_TOOLS	ON	Builds tools
BUILD_SHARED_LIBS	OFF	Build shared libraries. Default is Static libraries
ENABLE_ALL_WARNINGS	ON	Enable extra compiler warnings in all build targets
ENABLE_BENCHMARKS	OFF	Enable google benchmark
ENABLE_CODECOV	ON	Enable code coverage via gcov
ENABLE_FORTRAN	ON	Enable Fortran compiler support
ENABLE_MPI	OFF	Enable MPI
ENABLE_OPENMP	OFF	Enable OpenMP
ENABLE_WARNINGS_AS_ERRORS	OFF	Compiler warnings treated as errors errors.

We also have other CMake variables sprinkled thoughout the code, but may not be treated consistently. It seems that we should document in the user guide what we want users to be aware of and be able to set. We should document options intended for developers only someplace else.

Not included in the quickstart guide table above, but in the AxomOptions.cmake file are (which are for users and developers vs. developers only?):
AXOM_ENABLE_ANNOTATIONS
AXOM_ENABLE_SPARSEHASH
AXOM_USE_64BIT_INDEXTYPE
AXOM_ENABLE_MFEM_SIDRE_DATACOLLECTION
AXOM_ENABLE_MPI3

It also seems inconsistent that we don't have ENABLE_CUDA or ENABLE_HIP in the table. I think this is because those are set based on things like user specified CUDA_DIR, check that with find-cuda, etc.

Other variables we use in the code to control compilation (i.e., #define guards), but it's not completely obvious how they get set. These include:

language features....
AXOM_USE_CUDA
AXOM_USE_HIP
AXOM_USE_OPENMP

built-in TPLS....
AXOM_USE_CLI11
AXOM_USE_FMT
AXOM_USE_SOL
AXOM_ENABLE_SPARSEHASH

external TPLS....
AXOM_USE_C2C
AXOM_USE_CAMP
AXOM_USE_CONDUIT
AXOM_USE_HDF5
AXOM_USE_LUA
AXOM_USE_MFEM
AXOM_USE_RAJA
AXOM_USE_SCR
AXOM_USE_UMPIRE

We also have a couple that are intended to be used for component-specific usage or developer internals...
AXOM_MINT_USE_SIDRE (eventually go away)
AXOM_QUEST_ENABLE_EXTRA_REGRESSION_TESTS

To make things clear for users and developers, it seems like we need:

• Make sure we include all user options that are specified via cmake variable settings in the table above and correctly documented.

• For TPL dependency enablement, include in user docs that these are enabled by specifying a valid DIR directory location. Then, in a portion of the dev guide explain how this gets translated into a RAJA_USE macro contant that should be used in the source code.

• Sparsehash seems like an outlier. Remove the entry in the table?

• What else?