holoscan-cli 2.9.0__py3-none-any.whl

holoscan_cli/packager/manifest_files.py

@@ -0,0 +1,217 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from pathlib import Path
+from typing import Any
+
+
+class ApplicationManifest:
+    def __init__(self):
+        self._data = {}
+        self._data["apiVersion"] = None
+        self._data["command"] = None
+        self._data["environment"] = None
+        self._data["input"] = None
+        self._data["liveness"] = None
+        self._data["output"] = None
+        self._data["readiness"] = None
+        self._data["sdk"] = None
+        self._data["sdkVersion"] = None
+        self._data["timeout"] = None
+        self._data["version"] = None
+        self._data["workingDirectory"] = None
+
+    @property
+    def api_version(self) -> str:
+        return self._data["apiVersion"]
+
+    @api_version.setter
+    def api_version(self, value: str):
+        self._data["apiVersion"] = value
+
+    @property
+    def command(self) -> str:
+        return self._data["command"]
+
+    @command.setter
+    def command(self, value: str):
+        self._data["command"] = value
+
+    @property
+    def environment(self) -> dict[str, str]:
+        return self._data["environment"]
+
+    @environment.setter
+    def environment(self, value: dict[str, str]):
+        self._data["environment"] = value
+
+    @property
+    def input(self) -> dict[str, str]:  # noqa: A003
+        return self._data["input"]
+
+    @input.setter
+    def input(self, value: dict[str, str]):  # noqa: A003
+        self._data["input"] = value
+
+    @property
+    def liveness(self) -> Any:
+        return self._data["liveness"]
+
+    @liveness.setter
+    def liveness(self, value: Any):
+        self._data["liveness"] = value
+
+    @property
+    def output(self) -> dict[str, str]:
+        return self._data["output"]
+
+    @output.setter
+    def output(self, value: dict[str, str]):
+        self._data["output"] = value
+
+    @property
+    def readiness(self) -> Any:
+        return self._data["readiness"]
+
+    @readiness.setter
+    def readiness(self, value: Any):
+        self._data["readiness"] = value
+
+    @property
+    def sdk(self) -> str:
+        return self._data["sdk"]
+
+    @sdk.setter
+    def sdk(self, value: str):
+        self._data["sdk"] = value
+
+    @property
+    def sdk_version(self) -> str:
+        return self._data["sdkVersion"]
+
+    @sdk_version.setter
+    def sdk_version(self, value: str):
+        self._data["sdkVersion"] = value
+
+    @property
+    def timeout(self) -> int:
+        return self._data["timeout"]
+
+    @timeout.setter
+    def timeout(self, value: int):
+        self._data["timeout"] = value
+
+    @property
+    def version(self) -> str:
+        return self._data["version"]
+
+    @version.setter
+    def version(self, value: str):
+        self._data["version"] = value
+
+    @property
+    def working_directory(self) -> str:
+        return self._data["workingDirectory"]
+
+    @working_directory.setter
+    def working_directory(self, value: str):
+        if isinstance(value, Path):
+            self._data["workingDirectory"] = str(value)
+        else:
+            self._data["workingDirectory"] = value
+
+    @property
+    def data(self) -> dict[str, Any]:
+        """Returns all values for serializing to JSON"""
+        return self._data
+
+
+class PackageManifest:
+    def __init__(self):
+        self._data = {}
+        self._data["apiVersion"] = None
+        self._data["applicationRoot"] = None
+        self._data["modelRoot"] = None
+        self._data["models"] = None
+        self._data["resources"] = None
+        self._data["version"] = None
+        self._data["platformConfig"] = None
+
+    @property
+    def platform_config(self) -> str:
+        return self._data["platformConfig"]
+
+    @platform_config.setter
+    def platform_config(self, value: str):
+        self._data["platformConfig"] = value
+
+    @property
+    def api_version(self) -> str:
+        return self._data["apiVersion"]
+
+    @api_version.setter
+    def api_version(self, value: str):
+        self._data["apiVersion"] = value
+
+    @property
+    def application_root(self) -> str:
+        return self._data["applicationRoot"]
+
+    @application_root.setter
+    def application_root(self, value: str):
+        if isinstance(value, Path):
+            self._data["applicationRoot"] = str(value)
+        else:
+            self._data["applicationRoot"] = value
+
+    @property
+    def model_root(self) -> str:
+        return self._data["modelRoot"]
+
+    @model_root.setter
+    def model_root(self, value: str):
+        if isinstance(value, Path):
+            self._data["modelRoot"] = str(value)
+        else:
+            self._data["modelRoot"] = value
+
+    @property
+    def models(self) -> dict[str, str]:
+        return self._data["models"]
+
+    @models.setter
+    def models(self, value: dict[str, str]):
+        self._data["models"] = value
+
+    @property
+    def resources(self) -> Any:
+        return self._data["resources"]
+
+    @resources.setter
+    def resources(self, value: Any):
+        """Resources are copied from application configuration file directly."""
+        self._data["resources"] = value
+
+    @property
+    def version(self) -> str:
+        return self._data["version"]
+
+    @version.setter
+    def version(self, value: str):
+        self._data["version"] = value
+
+    @property
+    def data(self) -> dict[str, Any]:
+        """Returns all values for serializing to JSON"""
+        return self._data

holoscan_cli/packager/models.py

@@ -0,0 +1,90 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger("packager")
+
+
+class Models:
+    """
+    Builds model list from a given path where the path could be a model file, a directory that
+    contains a model or a directory with multiple models where each model contains within its own
+    subdirectory.
+    """
+
+    def build(self, models_path: Path) -> Optional[dict[str, Path]]:
+        """Checks if the given path is a file or a directory.
+
+        Args:
+            models_path (Path): A user given path that contains one or more models.
+        Returns:
+            Optional[Dict[str, Path]]: Returns None if no path is given.  Otherwise, returns a
+            dictionary where the key is the name of the model and the value contains the path
+            to the model.
+        """
+        if models_path is not None:
+            logger.info(f"Scanning for models in {models_path}...")
+            models: dict[str, Path] = {}
+            if models_path.is_file():
+                self._configure_model_file(models_path, models)
+            elif models_path.is_dir():
+                self._configure_model_dir(models_path, models)
+
+            return models
+        else:
+            return None
+
+    def _configure_model_dir(self, models_path: Path, models: dict[str, Path]):
+        """
+        Iterate through the given directory to scan for models.
+        If files are found within the directory, we simply assume that all files within the given
+        directory contains a model and sets the name of the model to the name of the given
+        directory.
+
+        Any subdirectories found within the given directory are treated as a separate model and the
+        name of the subdirectory is set to be the name of the model.
+
+        Args:
+            models_path (Path): Path to the model file.
+            models (Dict[str, Path]): Where models are added to.
+        """
+        model_dirs = os.listdir(models_path)
+
+        for model_dir in model_dirs:
+            if os.path.isfile(models_path / model_dir):
+                model_name = models_path.resolve().stem
+                models[model_name] = models_path
+                logger.debug(f"Model {model_name}={models_path} added.")
+            elif os.path.isdir(models_path / model_dir):
+                model_path = models_path / model_dir
+                model_name = model_dir
+                models[model_name] = model_path
+                logger.debug(f"Model {model_name}={model_path} added.")
+
+    def _configure_model_file(self, models_path: Path, models: dict[str, Path]):
+        """
+        Adds a new model to 'models' object where the model name is the name of the given file,
+        and the value is the path to the given model file.
+
+        Args:
+            models_path (Path): Path to the model file.
+            models (Dict[str, Path]): Where the model is added to.
+        """
+        model_name = models_path.stem
+        models[model_name] = models_path
+        logger.debug(f"Model file {model_name}={models[model_name]} added.")

holoscan_cli/packager/package_command.py

@@ -0,0 +1,197 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import argparse
+import logging
+from argparse import ArgumentParser, _SubParsersAction
+
+from packaging.version import Version
+
+from ..common.argparse_types import (
+    valid_dir_path,
+    valid_existing_dir_path,
+    valid_existing_path,
+    valid_platform_config,
+    valid_platforms,
+    valid_sdk_type,
+)
+from ..common.constants import SDK
+
+logger = logging.getLogger("packager")
+
+
+def create_package_parser(
+    subparser: _SubParsersAction, command: str, parents: list[ArgumentParser]
+) -> ArgumentParser:
+    parser: ArgumentParser = subparser.add_parser(
+        command, formatter_class=argparse.HelpFormatter, parents=parents, add_help=False
+    )
+
+    parser.add_argument(
+        "application",
+        type=valid_existing_path,
+        help="Holoscan application path: Python application directory with __main__.py, "
+        "Python file, C++ source directory with CMakeLists.txt, or path to an executable.",
+    )
+    parser.add_argument(
+        "--config",
+        "-c",
+        required=True,
+        type=valid_existing_path,
+        help="Holoscan application configuration file (.yaml)",
+    )
+    parser.add_argument(
+        "--docs",
+        "-d",
+        type=valid_existing_dir_path,
+        help="path to a directory containing user documentation and/or licenses.",
+    )
+    parser.add_argument(
+        "--models",
+        "-m",
+        type=valid_existing_path,
+        help="path to a model file or a directory containing all models as subdirectories",
+    )
+    parser.add_argument(
+        "--platform",
+        type=valid_platforms,
+        required=True,
+        help="target platform(s) for the build output separated by comma. "
+        f"Valid values: {str.join(', ', SDK.PLATFORMS)}.",
+    )
+    parser.add_argument(
+        "--platform-config",
+        type=valid_platform_config,
+        help="target platform configuration for the build output. "
+        f"Valid values: {str.join(', ', SDK.PLATFORM_CONFIGS)}.",
+    )
+    parser.add_argument(
+        "--add",
+        action="append",
+        dest="additional_libs",
+        type=valid_existing_dir_path,
+        help="include additional library files, python files into the application directory.",
+    )
+    parser.add_argument(
+        "--timeout", type=int, help="override default application timeout"
+    )
+    parser.add_argument(
+        "--version", type=Version, help="set the version of the application"
+    )
+
+    advanced_group = parser.add_argument_group(title="advanced build options")
+    advanced_group.add_argument(
+        "--base-image",
+        type=str,
+        help="base image name for the packaged application.",
+    )
+    advanced_group.add_argument(
+        "--build-image",
+        type=str,
+        help="container image name for building the C++ application.",
+    )
+    advanced_group.add_argument(
+        "--includes",
+        nargs="*",
+        default=[],
+        choices=["debug", "holoviz", "torch", "onnx"],
+        help="additional packages to include in the container.",
+    )
+    advanced_group.add_argument(
+        "--build-cache",
+        type=valid_dir_path,
+        default="~/.holoscan_build_cache",
+        help="path of the local directory where build cache gets stored.",
+    )
+    advanced_group.add_argument(
+        "--cmake-args",
+        type=str,
+        help='additional CMAKE build arguments. E.g. "-DCMAKE_BUILD_TYPE=DEBUG -DCMAKE_ARG=VALUE"',
+    )
+    advanced_group.add_argument(
+        "--holoscan-sdk-file",
+        type=valid_existing_path,
+        help="path to the Holoscan SDK Debian or PyPI package. "
+        "If not specified, the packager downloads "
+        "the SDK file from the internet based on the SDK version.",
+    )
+    advanced_group.add_argument(
+        "--monai-deploy-sdk-file",
+        type=valid_existing_path,
+        help="path to the MONAI Deploy App SDK PyPI package. "
+        "If not specified, the packager downloads "
+        "the SDK file from the internet based on the SDK version.",
+    )
+    advanced_group.add_argument(
+        "--no-cache",
+        "-n",
+        dest="no_cache",
+        action="store_true",
+        help="do not use cache when building image",
+    )
+    advanced_group.add_argument(
+        "--sdk",
+        type=valid_sdk_type,
+        help="SDK for building the application: Holoscan or MONAI-Deploy. "
+        f"Valid values: {str.join(', ', SDK.SDKS)}.",
+    )
+    advanced_group.add_argument(
+        "--source",
+        type=str,
+        help="override Debian package, build container image and run container image from a "
+        "JSON formatted file or a secured web server (HTTPS).",
+    )
+    advanced_group.add_argument(
+        "--sdk-version",
+        type=Version,
+        help="set the version of the SDK that is used to build and package the application. "
+        "If not specified, the packager attempts to detect the installed version.",
+    )
+
+    output_group = parser.add_argument_group(title="output options")
+    output_group.add_argument(
+        "--output",
+        "-o",
+        type=valid_existing_dir_path,
+        help="output directory where result images will be written.",
+    )
+    output_group.add_argument(
+        "--tag",
+        "-t",
+        required=True,
+        type=str,
+        help="name of the image and a optional tag (format: name[:tag]).",
+    )
+
+    user_group = parser.add_argument_group(title="security options")
+    user_group.add_argument(
+        "--username",
+        type=str,
+        default="holoscan",
+        help="username to be created in the container execution context.",
+    )
+    user_group.add_argument(
+        "--uid",
+        type=str,
+        default=1000,
+        help="UID associated with the username.  (default:1000)",
+    )
+    user_group.add_argument(
+        "--gid",
+        type=str,
+        default=1000,
+        help="GID associated with the username. (default:1000)",
+    )
+    parser.set_defaults(no_cache=False)
+    return parser

holoscan_cli/packager/packager.py

@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import json
+import logging
+import os
+import sys
+import tempfile
+from argparse import Namespace
+
+from ..common.enum_types import ApplicationType
+from ..common.utils import print_manifest_json
+from .arguments import PackagingArguments
+from .container_builder import CppAppBuilder, PythonAppBuilder
+from .manifest_files import ApplicationManifest, PackageManifest
+from .parameters import PlatformBuildResults
+
+logger = logging.getLogger("packager")
+
+
+def _build_image(args: PackagingArguments, temp_dir: str) -> list[PlatformBuildResults]:
+    """Creates dockerfile and builds HAP/MONAI Application Package (HAP/MAP) image
+    Args:
+        args (dict): Input arguments for Packager
+        temp_dir (str): Temporary directory to build MAP
+    """
+    if (
+        args.build_parameters.application_type == ApplicationType.PythonFile
+        or args.build_parameters.application_type == ApplicationType.PythonModule
+    ):
+        builder = PythonAppBuilder(args.build_parameters, temp_dir)
+    elif (
+        args.build_parameters.application_type == ApplicationType.Binary
+        or args.build_parameters.application_type == ApplicationType.CppCMake
+    ):
+        builder = CppAppBuilder(args.build_parameters, temp_dir)
+
+    results = [builder.build(platform) for platform in args.platforms]
+    return results
+
+
+def _create_app_manifest(manifest: ApplicationManifest, temp_dir: str):
+    """Creates Application manifest .json file
+    Args:
+        manifest (Dict): Input arguments for Packager
+        temp_dir (str): Temporary directory to build MAP
+    """
+    map_folder_path = os.path.join(temp_dir, "map")
+    os.makedirs(map_folder_path, exist_ok=True)
+    with open(os.path.join(map_folder_path, "app.json"), "w") as app_manifest_file:
+        app_manifest_file.write(json.dumps(manifest.data))
+
+    print_manifest_json(manifest.data, "app.json")
+
+
+def _create_package_manifest(manifest: PackageManifest, temp_dir: str):
+    """Creates package manifest .json file
+    Args:
+        manifest (Dict): Input arguments for Packager
+        temp_dir (str): Temporary directory to build MAP
+    """
+    map_folder_path = os.path.join(temp_dir, "map")
+    os.makedirs(map_folder_path, exist_ok=True)
+    with open(os.path.join(temp_dir, "map", "pkg.json"), "w") as package_manifest_file:
+        package_manifest_file.write(json.dumps(manifest.data))
+
+    print_manifest_json(manifest.data, "pkg.json")
+
+
+def _package_application(args: Namespace):
+    """Driver function for invoking all functions for creating and
+    building the Holoscan Application package image
+    Args:
+        args (Namespace): Input arguments for Packager from CLI
+    """
+    # Initialize arguments for package
+    with tempfile.TemporaryDirectory(
+        prefix="holoscan_tmp", dir=tempfile.gettempdir()
+    ) as temp_dir:
+        packaging_args = PackagingArguments(args, temp_dir)
+
+        # Create Manifest Files
+        _create_app_manifest(packaging_args.application_manifest, temp_dir)
+        _create_package_manifest(packaging_args.package_manifest, temp_dir)
+
+        results = _build_image(packaging_args, temp_dir)
+
+        logger.info("Build Summary:")
+        for result in results:
+            if result.succeeded:
+                print(
+                    f"""\nPlatform: {result.parameters.platform.value}/{result.parameters.platform_config.value}
+    Status:     Succeeded
+    Docker Tag: {result.docker_tag if result.docker_tag is not None else "N/A"}
+    Tarball:    {result.tarball_filenaem}"""  # noqa: E501
+                )
+            else:
+                print(
+                    f"""\nPlatform: {result.parameters.platform.value}/{result.parameters.platform_config.value}
+    Status: Failure
+    Error:  {result.error}
+    """  # noqa: E501
+                )
+                sys.exit(1)
+
+
+def execute_package_command(args: Namespace):
+    try:
+        _package_application(args)
+    except Exception as e:
+        logger.debug(e, exc_info=True)
+        logger.error(f"Error packaging application:\n\n{str(e)}")
+        sys.exit(1)