pw_build_mcuxpresso: Add readme generation support

This commit adds support for generating readme file containing
source description when generating SDK repository.

Change-Id: Iffe3d686837790f1701c75265d15d05dfbe8ea03
Signed-off-by: Mikołaj Rosowski <mrosowski@antmicro.com>
Signed-off-by: Kamil Rakoczy <krakoczy@antmicro.com>
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/255772
Reviewed-by: Rob Mohr <mohrr@google.com>
Reviewed-by: Ted Pudlik <tpudlik@google.com>
Docs-Not-Needed: Ted Pudlik <tpudlik@google.com>
Commit-Queue: Ted Pudlik <tpudlik@google.com>
Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com>

pw_build_mcuxpresso/py/BUILD.bazel

@@ -26,6 +26,7 @@ py_library(
         "pw_build_mcuxpresso/components.py",
         "pw_build_mcuxpresso/consts.py",
         "pw_build_mcuxpresso/gn.py",
+        "pw_build_mcuxpresso/readme_generator.py",
         "pw_build_mcuxpresso/west_wrap.py",
     ],
     imports = ["."],

pw_build_mcuxpresso/py/BUILD.gn

@@ -29,6 +29,7 @@ pw_python_package("py") {
     "pw_build_mcuxpresso/components.py",
     "pw_build_mcuxpresso/consts.py",
     "pw_build_mcuxpresso/gn.py",
+    "pw_build_mcuxpresso/readme_generator.py",
     "pw_build_mcuxpresso/west_wrap.py",
   ]
   tests = [

pw_build_mcuxpresso/py/pw_build_mcuxpresso/__main__.py

@@ -20,12 +20,19 @@
 import sys
 
 try:
-    from pw_build_mcuxpresso import bazel, components, gn, west_wrap
+    from pw_build_mcuxpresso import (
+        bazel,
+        components,
+        gn,
+        readme_generator,
+        west_wrap,
+    )
 except ImportError:
     # Load from this directory if pw_build_mcuxpresso is not available.
     import bazel  # type: ignore
     import components  # type: ignore
     import gn  # type: ignore
+    import readme_generator  # type: ignore
     import west_wrap  # type: ignore
 
 
@@ -61,9 +68,10 @@ def main():
         print("# Removing old output directory...")
         shutil.rmtree(output_path)
 
-    west_wrap.west_manifest(
+    west_wrap.fetch_project(
         output_path, args.mcuxpresso_repo, args.mcuxpresso_rev
     )
+    modules = west_wrap.list_modules(output_path, args.mcuxpresso_repo)
 
     project = components.Project.from_file(
         output_path / 'core' / 'manifests' / args.manifest_filename,
@@ -82,6 +90,12 @@ def main():
     if not args.skip_gn:
         gn.generate_gn_files(project, output_path)
 
+    readme_generator.generate_readme(
+        modules=modules,
+        output_dir=args.output_path,
+        filename="README.md",
+    )
+
     print(f"Output directory: {output_path.resolve().as_posix()}")
 
     sys.exit(0)

pw_build_mcuxpresso/py/pw_build_mcuxpresso/readme_generator.py

@@ -0,0 +1,90 @@
+# Copyright 2024 The Pigweed Authors
+#
+# 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
+#
+#     https://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.
+"""README generation support"""
+
+import shlex
+import sys
+from pathlib import Path
+
+# pylint: disable=line-too-long
+README_TEMPLATE = r'''
+# MCUXpresso-SDK
+
+This repository is auto-generated from the files from
+[NXP SDK code](https://github.com/nxp-mcuxpresso/mcux-sdk) using
+[pw_build_mcuxpresso](https://pigweed.dev/pw_build_mcuxpresso/) pigweed module.
+The purpose of this repository is to be used as a module for
+[Pigweed](https://pigweed.dev) applications targeting the NXP RT595 MCUs.
+The repository includes bazel rules allowing seamless integration into
+Pigweed's build system.
+
+## Used Revisions
+
+| Name | Revision | Source |
+| ---- | -------- | ------ |
+{sources}
+
+## Running generation script locally
+
+The script used to generate this repository is part of
+[Pigweed](https://pigweed.dev).
+To generate this repository locally, you will have to
+[setup Pigweed](https://pigweed.dev/docs/get_started)
+on your machine. After that, you can run this command to generate this
+repository.
+
+```sh
+bazelisk run //pw_build_mcuxpresso/py:mcuxpresso_builder -- {args}
+```
+
+## License
+Files taken from the NXP SDK repository are licensed under the BSD-3-Clause
+license.
+'''
+# pylint: enable=line-too-long
+
+
+def generate_readme(
+    modules: list[tuple[str, str, str]],
+    output_dir: Path,
+    filename: str,
+):
+    """
+    Generate SDK readme file
+
+    Args:
+        src_repo: source repository URL
+        src_version: source repository version,
+        modules: list of west modules
+        output_dir: path to output directory,
+        filename: name for generated file,
+    """
+    readme = output_dir / filename
+
+    args = " \\\n  ".join(
+        shlex.quote(arg) if " " in arg else arg for arg in sys.argv[1:]
+    )
+
+    sources = "\n".join(
+        f"| {name} | [`{version}`]({url}/tree/{version}) | {url} |"
+        for name, version, url in modules
+    )
+
+    with open(readme, "w") as f:
+        f.write(
+            README_TEMPLATE.format(
+                args=args,
+                sources=sources,
+            )
+        )

pw_build_mcuxpresso/py/pw_build_mcuxpresso/west_wrap.py

@@ -13,17 +13,22 @@
 # the License.
 """West manifest output support."""
 
+import io
 import os
+from contextlib import redirect_stdout
 from pathlib import Path
+from subprocess import check_output
 
 from west.app.main import WestApp
 
 
-def west_manifest(
+def fetch_project(
     workdir_path: Path, src_repo: str, src_rev: str | None = None
 ):
-    # save current working directory and restore it after
-    # running west so other relative paths will work
+    """
+    Fetch West project into given directory
+    """
+    # Save cwd to restore it after running west
     current_dir = os.getcwd()
     app = WestApp()
 
@@ -36,3 +41,48 @@ def west_manifest(
     app.run(['update', '-n'])
 
     os.chdir(current_dir)
+
+
+def list_modules(
+    workdir_path: Path, src_repo: str
+) -> list[tuple[str, str, str]]:
+    """
+    Parses manifest to return project's source information
+
+    Args:
+        workdir_path: path to project's working directory
+        src_repo: url of source repository
+
+    Returns:
+        list of (module_name, module_revision, module_url) for all
+        modules
+    """
+    # Save cwd to restore it after running west
+    current_dir = os.getcwd()
+    workdir_path = workdir_path.resolve()
+    os.chdir(workdir_path)
+
+    app = WestApp()
+    with io.StringIO() as buf, redirect_stdout(buf):
+        app.run(['list', '-f', '{name} {sha} {url} {path}'])
+        output_raw = buf.getvalue()
+
+    # First line is core module, rest is submodules
+    core, *submodules = output_raw.splitlines()
+
+    # We have to manually extract core's commit hash
+    core_path = workdir_path / core.split()[3]
+    core_revision = check_output(
+        ['git', 'rev-parse', 'HEAD'],
+        text=True,
+        cwd=core_path,
+    ).strip()
+
+    os.chdir(current_dir)
+
+    modules = [("mcuxpresso-sdk", core_revision, src_repo)]
+    modules.extend(
+        (module[0], module[1], module[2])
+        for module in map(lambda line: line.split(" "), submodules)
+    )
+    return modules