Merge pull request #1502 from LLNL/docs/han12/local_docker

Docs for local Axom Docker container

src/docs/sphinx/dev_guide/continuous_integration.rst

@@ -29,6 +29,107 @@ Axom's GitHub project is also configured to require pull requests to pass checks
 from our LC GitLab CI (as described below).
 
 
+Build and Test Axom in a Docker Container
+-----------------------------------------
+
+1. Install Docker Desktop
+
+	* You can look at `dockerdocs <https://docs.docker.com/>`_ for tutorials on installing and using Docker.
+
+2. Ensure the Docker Desktop application is running on your computer
+3. Open Terminal/Powershell/Command Line prompt of choice
+4. Pull the Docker image
+
+	.. code-block:: bash
+
+		docker pull <image name>
+
+	* Checkout Azure Pipelines `configuration file <https://github.com/LLNL/axom/blob/develop/azure-pipelines.yml>`_ for latest images (denoted by ``<Compiler>_IMAGENAME``).
+
+	.. code-block:: bash
+
+		docker images
+
+	* Verify you can see your image
+
+5. Create a Docker volume to save your work
+
+	.. code-block:: bash
+
+		docker volume create <volume name>
+
+	* This allows you to save your progress once you exit the container
+
+	.. code-block:: bash
+
+		docker volume ls
+
+	* Verify you can see your volume
+
+6. Run the Docker container with the volume mounted
+
+	.. code-block:: bash
+
+		docker run -it --mount source=<volume name>,target=/home/axom --name <name you want to give container> <image id>
+
+	* You can get the ``<image id>`` through the ``docker images`` command.
+	* This will mount/attach your volume to the Docker image. When you exit your running Docker container, you will want to rerun this command to restart the container with your current progress.
+
+	.. note::
+
+		If you exit the container and attempt to restart, sometimes Docker will return a warning stating the initial container has not fully closed. Just run ``docker container prune`` command to cleanup the container and then you can reissue the run command.
+
+7. In the running Docker container, clone the axom github repository
+
+	.. code-block:: bash
+
+		git clone https://github.com/LLNL/axom.git
+		cd axom
+
+8. (optional) Checkout your branch
+
+	.. code-block:: bash
+
+		git checkout <name of your branch>
+
+9. Setup submodules
+
+	.. code-block:: bash
+
+		git submodule update --init
+
+10. Configure Axom
+
+	.. code-block:: bash
+
+		python3 ./config-build.py -hc host-configs/docker/<CMake host-config for container> -bt Release -DENABLE_GTEST_DEATH_TESTS=ON -DBUILD_SHARED_LIBS=ON -DAXOM_QUEST_ENABLE_EXTRA_REGRESSION_TESTS:BOOL=ON -DENABLE_BENCHMARKS:BOOL=ON
+
+	* The host-config for your Docker container can be found in the ``host-configs/docker/`` directory.
+	* The CMake flags (marked with ``-D``) are derived from a job in the Azure Pipelines `configuration file <https://github.com/LLNL/axom/blob/develop/azure-pipelines.yml>`_. The CMake flags are for mimicking a specific job setup, but are not required to configure Axom.
+
+11. Build Axom
+
+	.. code-block:: bash
+
+		cd <build-* directory>
+		make -j 8
+
+12. Run unit tests
+
+You have several potential options:
+
+	.. code-block:: bash
+
+		# Run tests with verbose output using make
+		make VERBOSE=1 test
+
+		# Run tests with verbose output using ctest
+		ctest -VV
+
+		# Run specific tests with verbose output using ctest, filtering for tests that have a specific prefix
+		ctest -VV -R  "<some_test_prefix>*"
+
+
 .. _gitlab-label:
 
 ==========