Merge branch 'main' into sgmoore/update_qmake_plugin

canonical · Mar 8, 2024 · 494ea32 · 494ea32
2 parents aa98fc5 + 3e1d1b2
commit 494ea32
Show file tree

Hide file tree

Showing 42 changed files with 381 additions and 83 deletions.
diff --git a/.gitignore b/.gitignore
@@ -14,6 +14,7 @@ docs/reference.md
 docs/reference/commands
 docs/.sphinx
 docs/_build
+docs/common
 *.egg-info
 .eggs/
 .envrc

diff --git a/docs/common/.gitkeep b/docs/common/.gitkeep
diff --git a/docs/conf.py b/docs/conf.py
@@ -3,6 +3,8 @@
 import pathlib
 import sys
 
+import craft_parts_docs
+
 project_dir = pathlib.Path("..").resolve()
 sys.path.insert(0, str(project_dir.absolute()))
 
@@ -60,7 +62,12 @@
 
 myst_enable_extensions = ["substitution", "deflist"]
 
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "sphinx-resources"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "sphinx-resources",
+]
 
 rst_epilog = """
 .. include:: /reuse/links.txt
@@ -161,6 +168,34 @@
 # For example: "explanation/old-name.html": "../how-to/prettify.html",
 # redirects = {}
 
+extensions.extend(
+    (
+        "sphinx.ext.ifconfig",
+        "sphinxcontrib.details.directive",
+    )
+)
+
+exclude_patterns.extend(
+    (
+        # Excluded because Snapcraft doesn't use overlays
+        "common/craft-parts/overlay_parameters.rst",
+        # Excluded here because they are included explicitly in other documents;
+        # if we don't exclude them, they generate "duplicate label" errors.
+        "common/craft-parts/dump_plugin.rst",
+        "common/craft-parts/part_properties.rst",
+        "common/craft-parts/python_plugin.rst",
+        "common/craft-parts/rust_plugin.rst",
+        "common/craft-parts/step_execution_environment.rst",
+        "common/craft-parts/step_output_directories.rst",
+        "common/craft-parts/explanation/filesets.rst",
+        "common/craft-parts/explanation/lifecycle.rst",
+        "common/craft-parts/explanation/parts.rst",
+        "common/craft-parts/explanation/how_parts_are_built.rst",
+        "common/craft-parts/reference/parts_steps.rst",
+        # Extra non-craft-parts exclusions can be added after this comment
+    )
+)
+
 
 def generate_cli_docs(nil):
     gen_cli_docs_path = (project_dir / "tools" / "docs" / "gen_cli_docs.py").resolve()
@@ -169,3 +204,12 @@ def generate_cli_docs(nil):
 
 def setup(app):
     app.connect("builder-inited", generate_cli_docs)
+
+
+# Setup libraries documentation snippets for use in snapcraft docs.
+common_docs_path = pathlib.Path(__file__).parent / "common"
+craft_parts_docs_path = pathlib.Path(craft_parts_docs.__file__).parent
+(common_docs_path / "craft-parts").unlink(missing_ok=True)
+(common_docs_path / "craft-parts").symlink_to(
+    craft_parts_docs_path, target_is_directory=True
+)
diff --git a/docs/explanation/filesets.rst b/docs/explanation/filesets.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/explanation/filesets.rst
diff --git a/docs/explanation/how_parts_are_built.rst b/docs/explanation/how_parts_are_built.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/explanation/how_parts_are_built.rst
diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst
@@ -7,3 +7,6 @@ Explanation
    :maxdepth: 1
 
    architectures
+   filesets
+   parts
+   lifecycle
diff --git a/docs/explanation/lifecycle.rst b/docs/explanation/lifecycle.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/explanation/lifecycle.rst
diff --git a/docs/explanation/parts.rst b/docs/explanation/parts.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/explanation/parts.rst
diff --git a/docs/images/lifecycle_logic.png b/docs/images/lifecycle_logic.png
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -8,6 +8,9 @@ Reference
 
    architectures
    commands
+   plugins
+   part_properties
+   parts_steps
 
 Indices and tables
 ==================

diff --git a/docs/reference/part_properties.rst b/docs/reference/part_properties.rst
@@ -0,0 +1,6 @@
+.. _ref_parts:
+
+Part properties
+===============
+
+.. include:: /common/craft-parts/part_properties.rst
diff --git a/docs/reference/parts_steps.rst b/docs/reference/parts_steps.rst
@@ -0,0 +1,6 @@
+
+.. include:: /common/craft-parts/reference/parts_steps.rst
+
+.. include:: /common/craft-parts/step_execution_environment.rst
+
+.. include:: /common/craft-parts/step_output_directories.rst
diff --git a/docs/reference/plugins.rst b/docs/reference/plugins.rst
@@ -0,0 +1,15 @@
+.. _plugins:
+
+*****************
+Snapcraft plugins
+*****************
+
+This section contains an in-depth description of the plugins available in
+Snapcraft.
+
+.. toctree::
+   :maxdepth: 1
+
+   plugins/dump_plugin
+   plugins/python_plugin
+   plugins/rust_plugin
diff --git a/docs/reference/plugins/dump_plugin.rst b/docs/reference/plugins/dump_plugin.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/dump_plugin.rst
diff --git a/docs/reference/plugins/python_plugin.rst b/docs/reference/plugins/python_plugin.rst
@@ -0,0 +1,23 @@
+
+.. include:: /common/craft-parts/python_plugin.rst
+   :end-before: .. _python-details-begin:
+
+Dependencies
+------------
+
+Whether the Python interpreter needs to be included in the snap depends on its
+``confinement``. Specifically:
+
+- Projects with ``strict`` or ``devmode`` confinement can safely use the base
+  snap's interpreter, so they typically do **not** need to include Python.
+- Projects with ``classic`` confinement **cannot** use the base snap's
+  interpreter and thus must always bundle it (typically via ``stage-packages``).
+- In both cases, a specific/custom Python installation can always be included
+  in the snap. This can be useful, for example, when using a different Python
+  version or building an interpreter with custom flags.
+
+Snapcraft will prefer an included interpreter over the base's, even for projects
+with ``strict`` and ``devmode`` confinement.
+
+.. include:: /common/craft-parts/python_plugin.rst
+   :start-after: .. _python-details-end:
diff --git a/docs/reference/plugins/rust_plugin.rst b/docs/reference/plugins/rust_plugin.rst
@@ -0,0 +1,2 @@
+
+.. include:: /common/craft-parts/rust_plugin.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,10 +1,11 @@
 attrs==23.1.0
 catkin-pkg==0.5.2
 click==8.1.7
+craft-application==1.2.1
 craft-archives==1.1.3
 craft-cli==2.5.1
 craft-grammar==1.1.1
-craft-parts==1.26.2
+craft-parts==1.27.0
 craft-providers==1.23.0
 craft-store==2.5.0
 Deprecated==1.2.14
@@ -40,6 +41,7 @@ simplejson==3.19.2
 snap-helpers==0.4.2
 spdx==2.5.1
 spdx-lookup==0.3.3
+sphinxcontrib-details-directive==0.1.0
 tabulate==0.8.10
 types-Deprecated==1.2.9.2
 typing_extensions==4.5.0

diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt
@@ -1,13 +1,15 @@
 .. _AppStream: https://www.freedesktop.org/software/appstream/docs/
 .. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en
 .. _Canonical website: https://canonical.com/
+.. _`Charmcraft`: https://juju.is/docs/sdk/charmcraft
 .. _`Create a brand account`: https://snapcraft.io/docs/t/creating-snap-store-brand-accounts/6271
 .. _`Kernel connector`: https://www.kernel.org/doc/Documentation/connector/connector.txt
 .. _managing-snap-configuration: https://snapcraft.io/docs/configuration-in-snaps
 .. _`Markdown`: https://commonmark.org/help/
 .. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
 .. _ROS: https://www.ros.org/
 .. _setuptools: https://setuptools.readthedocs.io/en/latest/
+.. _`Snapcraft`: https://snapcraft.io/docs/snapcraft
 .. _`snap-channels`: https://snapcraft.io/docs/channels
 .. _`Snap Store desktop app`: https://snapcraft.io/snap-store
 .. _`Snap Store`: https://snapcraft.io/store
@@ -16,3 +18,4 @@
 .. _`Ubuntu Core`: https://ubuntu.com/core/
 .. _vscode: https://code.visualstudio.com/
 .. _`YAML specification`: https://yaml.org/spec/
+
diff --git a/requirements-devel.txt b/requirements-devel.txt
@@ -15,7 +15,7 @@ craft-application==1.2.1
 craft-archives==1.1.3
 craft-cli==2.5.1
 craft-grammar==1.1.2
-craft-parts==1.26.2
+craft-parts==1.27.0
 craft-providers==1.23.0
 craft-store==2.6.0
 cryptography==42.0.4

diff --git a/requirements.txt b/requirements.txt
@@ -9,7 +9,7 @@ craft-application==1.2.1
 craft-archives==1.1.3
 craft-cli==2.5.1
 craft-grammar==1.1.2
-craft-parts==1.26.2
+craft-parts==1.27.0
 craft-providers==1.23.0
 craft-store==2.6.0
 cryptography==42.0.4

diff --git a/snapcraft/extensions/_ros2_humble_meta.py b/snapcraft/extensions/_ros2_humble_meta.py
@@ -54,9 +54,9 @@ def is_experimental(base: Optional[str]) -> bool:
     def get_root_snippet(self) -> Dict[str, Any]:
         root_snippet = super().get_root_snippet()
         root_snippet["plugs"] = {
-            "ros-humble": {
+            self.ros2_humble_snaps.content: {
                 "interface": "content",
-                "content": "ros-humble",
+                "content": self.ros2_humble_snaps.content,
                 "target": "$SNAP/opt/ros/underlay_ws",
                 "default-provider": self.ros2_humble_snaps.content,
             }

diff --git a/snapcraft/meta/appstream.py b/snapcraft/meta/appstream.py
@@ -100,6 +100,13 @@ def extract(relpath: str, *, workdir: str) -> Optional[ExtractedMetadata]:
     description = _get_value_from_xml_element(dom, "description")
     title = _get_value_from_xml_element(dom, "name")
     version = _get_latest_release_from_nodes(dom.findall("releases/release"))
+    project_license = _get_value_from_xml_element(dom, "project_license")
+    contact = _get_value_from_xml_element(dom, "update_contact")
+
+    issues = _get_urls_from_xml_element(dom.findall("url"), "bugtracker")
+    donation = _get_urls_from_xml_element(dom.findall("url"), "donation")
+    website = _get_urls_from_xml_element(dom.findall("url"), "homepage")
+    source_code = _get_source_code_from_xml_element(dom.findall("url"))
 
     desktop_file_paths = []
     desktop_file_ids = _get_desktop_file_ids_from_nodes(dom.findall("launchable"))
@@ -125,6 +132,12 @@ def extract(relpath: str, *, workdir: str) -> Optional[ExtractedMetadata]:
         description=description,
         version=version,
         icon=icon,
+        license=project_license,
+        contact=contact,
+        issues=issues,
+        donation=donation,
+        website=website,
+        source_code=source_code,
         desktop_file_paths=desktop_file_paths,
     )
 
@@ -161,6 +174,23 @@ def _get_value_from_xml_element(tree, key) -> Optional[str]:
     return None
 
 
+def _get_urls_from_xml_element(nodes, url_type) -> Optional[List[str]]:
+    urls = []  # type: List[str]
+    for node in nodes:
+        if node is not None and node.attrib["type"] == url_type:
+            urls.append(node.text.strip())
+    if urls:
+        return urls
+    return None
+
+
+def _get_source_code_from_xml_element(nodes) -> Optional[str]:
+    for node in nodes:
+        if node is not None and node.attrib["type"] == "vcs-browser":
+            return node.text.strip()
+    return None
+
+
 def _get_latest_release_from_nodes(nodes) -> Optional[str]:
     for node in nodes:
         if "version" in node.attrib:

diff --git a/snapcraft/meta/extracted_metadata.py b/snapcraft/meta/extracted_metadata.py
@@ -47,3 +47,21 @@ class ExtractedMetadata:
 
     desktop_file_paths: List[str] = field(default_factory=list)
     """The extracted application desktop file paths."""
+
+    license: Optional[str] = None
+    """The extracted package license"""
+
+    contact: Optional[str] = None
+    """The extracted package contact"""
+
+    donation: Optional[List[str]] = None
+    """The extracted package donation"""
+
+    issues: Optional[List[str]] = None
+    """The extracted package issues"""
+
+    source_code: Optional[str] = None
+    """The extracted package source code"""
+
+    website: Optional[List[str]] = None
+    """The extracted package website"""
diff --git a/snapcraft/models/project.py b/snapcraft/models/project.py
@@ -570,14 +570,14 @@ def _validate_grade_and_build_base(cls, values):
             raise ValueError("grade must be 'devel' when build-base is 'devel'")
         return values
 
-    @pydantic.validator("base", always=True)
+    @pydantic.root_validator()
     @classmethod
-    def _validate_base(cls, base, values):
+    def _validate_base(cls, values):
         """Not allowed to use unstable base without devel build-base."""
         if values.get("base") == "core24" and values.get("build_base") != "devel":
             raise ValueError("build-base must be 'devel' when base is 'core24'")
 
-        return base
+        return values
 
     @pydantic.validator("build_base", always=True)
     @classmethod

diff --git a/snapcraft_legacy/internal/project_loader/_extensions/_ros1_noetic_meta.py b/snapcraft_legacy/internal/project_loader/_extensions/_ros1_noetic_meta.py
@@ -53,10 +53,10 @@ def __init__(self, *, extension_name: str, yaml_data: Dict[str, Any]) -> None:
         self.part_snippet_extra = dict()
 
         self.root_snippet["plugs"] = {
-            "ros-noetic":
+            self.ros_noetic_snaps.content:
                 {
                     "interface": "content",
-                    "content": "ros-noetic",
+                    "content": self.ros_noetic_snaps.content,
                     "target": "$SNAP/opt/ros/underlay_ws",
                     "default-provider": self.ros_noetic_snaps.content,
                 }

diff --git a/snapcraft_legacy/internal/project_loader/_extensions/_ros2_foxy_meta.py b/snapcraft_legacy/internal/project_loader/_extensions/_ros2_foxy_meta.py
@@ -61,10 +61,10 @@ def __init__(self, *, extension_name: str, yaml_data: Dict[str, Any]) -> None:
         ]
 
         self.root_snippet["plugs"] = {
-            "ros-foxy":
+            self.ros2_foxy_snaps.content:
                 {
                     "interface": "content",
-                    "content": "ros-foxy",
+                    "content": self.ros2_foxy_snaps.content,
                     "target": "$SNAP/opt/ros/underlay_ws",
                     "default-provider": self.ros2_foxy_snaps.content,
                 }

diff --git a/tests/legacy/unit/project_loader/extensions/test_ros1_noetic_meta.py b/tests/legacy/unit/project_loader/extensions/test_ros1_noetic_meta.py
@@ -92,9 +92,9 @@ def test_extension(self, extension_name, extension_class, meta, meta_dev):
                 }
             ],
             "plugs": {
-                "ros-noetic": {
+                meta: {
                     "interface": "content",
-                    "content": "ros-noetic",
+                    "content": meta,
                     "target": "$SNAP/opt/ros/underlay_ws",
                     "default-provider": meta,
                 }

diff --git a/tests/legacy/unit/project_loader/extensions/test_ros2_foxy_meta.py b/tests/legacy/unit/project_loader/extensions/test_ros2_foxy_meta.py
@@ -72,9 +72,9 @@ def test_extension(self, extension_name, extension_class, meta, meta_dev):
                 }
             ],
             "plugs": {
-                "ros-foxy": {
+                meta: {
                     "interface": "content",
-                    "content": "ros-foxy",
+                    "content": meta,
                     "target": "$SNAP/opt/ros/underlay_ws",
                     "default-provider": meta,
                 }
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@

		.. include:: /common/craft-parts/explanation/filesets.rst
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@

		.. include:: /common/craft-parts/dump_plugin.rst
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@

		.. include:: /common/craft-parts/rust_plugin.rst