Prefer Podman on Mac, Docker Engine elsewhere...

- Use --mount instead of -v where possible (on Mac, or Ubuntu Docker).
- Don't allow build_docs_to_publish with Podman except on Mac. See #27.

Author: samsrabin

build_docs_to_publish

@@ -19,7 +19,13 @@ from doc_builder.build_docs import (
     main as build_docs,
 )
 from doc_builder.build_docs_shared_args import main as build_docs_shared_args
-from doc_builder.sys_utils import get_git_head_or_branch, check_permanent_file, get_toplevel_git_dir
+from doc_builder.sys_utils import (
+    get_git_head_or_branch,
+    check_permanent_file,
+    get_toplevel_git_dir,
+    is_mac,
+)
+from doc_builder.build_commands import get_container_cli_tool
 
 # Change to the parent director of doc-builder and add to Python path
 os.chdir(os.path.join(os.path.dirname(__file__), os.pardir))
@@ -179,6 +185,15 @@ def main():
     # Check version list for problems
     check_version_list()
 
+    # build_docs_to_publish has trouble on Linux (maybe just Ubuntu?) with Podman. Only allow
+    # Docker. Issue filed: https://github.com/ESMCI/doc-builder/issues/27
+    if args.container_cli_tool is None:
+        args.container_cli_tool = get_container_cli_tool()
+    if args.container_cli_tool == "podman" and not is_mac():
+        raise RuntimeError(
+            "build_docs_to_publish is only supported for Podman on Macs. Use Docker instead."
+        )
+
     # Loop over all documentation versions
     for version in VERSION_LIST:
         # Check that repo is ready and get our current state

doc_builder/build_commands.py

@@ -13,7 +13,12 @@
 _CONTAINER_HOME = "/home/user/mounted_home"
 
 # CLI tools we can try to use to run our container, in decreasing order of preference
-COMPATIBLE_CLI_TOOLS = ["podman", "docker"]
+if sys_utils.is_mac():
+    # Prefer Podman because Docker Desktop isn't always free
+    COMPATIBLE_CLI_TOOLS = ["podman", "docker"]
+else:
+    # On Linux, Docker Engine (free) can be obtained without Docker Desktop, and it works better
+    COMPATIBLE_CLI_TOOLS = ["docker", "podman"]
 
 
 def get_build_dir(build_dir=None, repo_root=None, version=None):
@@ -81,6 +86,24 @@ def get_container_cli_tool():
     raise RuntimeError(f"No compatible container software found: {', '.join(COMPATIBLE_CLI_TOOLS)}")
 
 
+def get_mount_arg(container_mountpoint, container_cli_tool=None):
+    """
+    Get the Podman/Docker mount argument depending on which we're using and whether we're on Mac
+    """
+    if container_cli_tool is None:
+        container_cli_tool = get_container_cli_tool()
+
+    # This is preferred for performance reasons (at least on Mac)
+    mount_option = "--mount"
+    mount_arg = f"type=bind,source={container_mountpoint},target={_CONTAINER_HOME}"
+
+    # This fallback is needed for Podman on Linux machines,
+    if container_cli_tool == "podman" and not sys_utils.is_mac():
+        mount_option = "-v"
+        mount_arg = f"{container_mountpoint}:{_CONTAINER_HOME}:U"
+    return mount_option, mount_arg
+
+
 def get_build_command(
     *,
     build_dir,
@@ -157,15 +180,18 @@ def get_build_command(
     if container_cli_tool is None:
         container_cli_tool = get_container_cli_tool()
 
+    # Get argument for mounting/binding
+    mount_option, mount_arg = get_mount_arg(container_mountpoint, container_cli_tool)
+
     container_command = [
         container_cli_tool,
         "run",
         "--name",
         container_name,
         "--user",
         f"{uid}:{gid}",
-        "-v",
-        f"{container_mountpoint}:{_CONTAINER_HOME}:U",
+        mount_option,
+        mount_arg,
         "--workdir",
         container_workdir,
         "-t",  # "-t" is needed for colorful output

doc_builder/build_docs.py

@@ -8,7 +8,6 @@
 import random
 import string
 import sys
-import platform
 from urllib.parse import urlparse
 import signal
 
@@ -20,6 +19,7 @@
     DEFAULT_IMAGE,
 )
 from doc_builder.build_docs_shared_args import bd_dir_group, bd_parser
+from doc_builder.sys_utils import is_mac
 
 
 def is_web_url(url_string):
@@ -245,7 +245,7 @@ def run_build_command(build_command, version, options):
     # Start container software/VM
     if "podman" in build_command:
         start_container_software("podman machine start")
-    elif "docker" in build_command and platform.system() == "Darwin":  # Darwin means Mac
+    elif "docker" in build_command and is_mac():
         start_container_software("docker desktop start")
 
     print(" ".join(build_command))

doc_builder/sys_utils.py

@@ -4,6 +4,7 @@
 
 import subprocess
 import os
+import platform
 
 
 def check_permanent_file(filepath):
@@ -133,6 +134,11 @@ def git_current_branch():
     return branch_found, branch_name
 
 
+def is_mac():
+    """Returns True if running on a Mac"""
+    return platform.system() == "Darwin"
+
+
 def is_under(child, parent_dir):
     """Check whether child is in parent_dir
 

test/test_unit_get_build_command.py

@@ -5,7 +5,8 @@
 import os
 import unittest
 from unittest.mock import patch
-from doc_builder.build_commands import get_build_command  # pylint: disable=import-error
+# pylint: disable=import-error
+from doc_builder.build_commands import get_build_command, get_mount_arg
 
 # Allow names that pylint doesn't like, because otherwise I find it hard
 # to make readable unit test names
@@ -118,15 +119,16 @@ def test_container(self, mock_get_toplevel_of_doc_builder_parent):
             conf_py_path=conf_py_path,
             container_cli_tool="abc123",
         )
+        mount_option, mount_arg = get_mount_arg("/path/to/username")
         expected = [
             "abc123",
             "run",
             "--name",
             "foo",
             "--user",
             self.uid_gid,
-            "-v",
-            "/path/to/username:/home/user/mounted_home:U",
+            mount_option,
+            mount_arg,
             "--workdir",
             "/home/user/mounted_home/foorepos/foocode/doc",
             "-t",
@@ -157,15 +159,16 @@ def test_container_relpath(self, mock_get_toplevel_of_doc_builder_parent):
             version="None",
             container_cli_tool="abc123",
         )
+        mount_option, mount_arg = get_mount_arg("/path/to/username")
         expected = [
             "abc123",
             "run",
             "--name",
             "foo",
             "--user",
             self.uid_gid,
-            "-v",
-            "/path/to/username:/home/user/mounted_home:U",
+            mount_option,
+            mount_arg,
             "--workdir",
             "/home/user/mounted_home/foorepos/foocode/doc",
             "-t",
@@ -197,14 +200,15 @@ def test_container_no_clitool_given(self, mock_get_toplevel_of_doc_builder_paren
             conf_py_path=conf_py_path,
             container_cli_tool=None,
         )
+        mount_option, mount_arg = get_mount_arg("/path/to/username")
         expected = [
             "run",
             "--name",
             "foo",
             "--user",
             self.uid_gid,
-            "-v",
-            "/path/to/username:/home/user/mounted_home:U",
+            mount_option,
+            mount_arg,
             "--workdir",
             "/home/user/mounted_home/foorepos/foocode/doc",
             "-t",