esp32-installer 1.0.0__py3-none-any.whl

esp32_installer/__init__.py

@@ -0,0 +1,43 @@
+"""
+Install embedded C libraries into an ESP-IDF project.
+
+Installed with pip, it is the esp32-installer command. It takes a library from
+GitHub, from a downloaded zip, or from a folder, and makes it a component of
+the project: its own CMakeLists.txt and Kconfig, the ESP-IDF components it
+uses, and the settings it needs in sdkconfig.defaults.
+
+The work that is the same for any project is the shared core, in core/, from
+github.com/nimaltd/core-installer. What an ESP-IDF project is, is in esp32.py.
+
+See https://github.com/nimaltd/esp32-installer
+"""
+
+__version__ = "1.0.0"
+
+# Before anything of the core is used: it asks the target for every answer
+# that depends on the kind of project.
+from .core import target as _target  # noqa: E402
+from .esp32 import Esp32  # noqa: E402
+
+_target.use(Esp32(__version__))
+
+from .core.installer import InstallError, Result, install_in_place, install_to  # noqa: E402
+from .core.manifest import Manifest, ManifestError, load  # noqa: E402
+
+__all__ = [
+    "InstallError",
+    "Manifest",
+    "ManifestError",
+    "Result",
+    "install_in_place",
+    "install_to",
+    "load",
+    "main",
+]
+
+
+def main(argv=None):
+    """Run the command line interface. Imported lazily to keep start-up cheap."""
+    from .cli import main as _main
+
+    return _main(argv=argv)

esp32_installer/__main__.py

@@ -0,0 +1,8 @@
+"""Lets the package be run directly: python -m esp32_installer owner/example"""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

esp32_installer/cli.py

@@ -0,0 +1,14 @@
+"""
+The esp32-installer command: the core's command line, with the ESP-IDF target.
+
+The target is chosen when the package is imported, before this runs.
+"""
+
+import sys
+
+from .core.cli import main
+
+__all__ = ["main"]
+
+if __name__ == "__main__":
+    sys.exit(main())

esp32_installer/component.py

@@ -0,0 +1,318 @@
+"""
+The library as an ESP-IDF component: its CMakeLists.txt, and a Kconfig for its settings.
+
+ESP-IDF builds a folder of the project's components folder when it holds a
+CMakeLists.txt that calls idf_component_register(). A library written for any
+project has none, so it is written here, from installer.yml, into the folder
+the library was installed in. It is written again on every install and update,
+so a source file the new version adds is built without anyone editing anything.
+
+A library that ships a CMakeLists.txt of its own knows its build better than
+this does, and is left alone.
+
+The component is named after its folder, as ESP-IDF names every component:
+components/ee24 is the component ee24, which other components list in their
+REQUIRES. A folder named like one of ESP-IDF's own components takes its place
+in the build, which the target warns about before the library goes in.
+"""
+
+import re
+from pathlib import Path
+
+from .core import usercode
+from .core.files import backup
+from .core.target import ALREADY, CHANGED, MANUAL, Outcome
+
+NAME = "ESP-IDF component"
+CMAKELISTS = "CMakeLists.txt"
+KCONFIG = "Kconfig"
+
+# The first line of each file written here, so a file of the library's own is
+# never mistaken for one this wrote.
+MARK = "# Generated by esp32-installer"
+
+# How far the lines inside idf_component_register() and Kconfig are indented,
+# the way ESP-IDF's own components write them.
+INDENT = "    "
+
+
+def symbol_of(name):
+    """The Kconfig prefix for a library name: EE24 for ee24, ONE_WIRE for one-wire."""
+    return re.sub(r"[^A-Za-z0-9]", "_", str(name)).upper()
+
+
+def component_name(destination):
+    """The component's name, which is its folder's: ee24 for components/ee24."""
+    return Path(destination).name
+
+
+def cmake_quote(text):
+    """
+    Text as one quoted CMake argument.
+
+    A file name lands in CMakeLists.txt as it stands, so a quote, a dollar or a
+    semicolon in it could otherwise end the argument, expand a variable or
+    split it into two.
+    """
+    escaped = str(text).replace("\\", "\\\\").replace('"', '\\"').replace("$", "\\$").replace(";", "\\;")
+
+    return f'"{escaped}"'
+
+
+def section(library):
+    """The name of the USER CODE section in the component's CMakeLists.txt: EXAMPLE_CMAKE."""
+    return f"{symbol_of(library.name)}_CMAKE"
+
+
+def _label(library):
+    return f"{library.name} {library.version}".strip()
+
+
+def _argument(keyword, values):
+    """One keyword of idf_component_register() and its values, a line each."""
+    return [f"{INDENT}{keyword}"] + [f"{INDENT}{INDENT}{value}" for value in values]
+
+
+def cmakelists(library, requires):
+    """
+    The component's CMakeLists.txt: the library's files, and the components it uses.
+
+    requires is every component the library needs, ESP-IDF's own and the
+    libraries it depends on, by the names their folders give them.
+    """
+    lines = [
+        f"{MARK} for {_label(library)}.",
+        "#",
+        "# ESP-IDF builds this folder as a component, since it sits in the project's",
+        "# components folder or in EXTRA_COMPONENT_DIRS. Written again on every install",
+        "# and update, so a change made here does not last, except between the USER",
+        "# CODE lines at the end. The files come from the library's installer.yml.",
+        "",
+        "idf_component_register(",
+    ]
+
+    if library.build_sources:
+        lines += _argument("SRCS", [cmake_quote(name) for name in library.build_sources])
+
+    lines += _argument("INCLUDE_DIRS", [cmake_quote(folder) for folder in library.include_dirs])
+
+    if requires:
+        lines += _argument("REQUIRES", requires)
+
+    lines.append(")")
+
+    # For every component that uses the library, not only its own files: a
+    # define can change what the library's header declares, and every file
+    # including it has to agree. A component of headers only is an interface
+    # library, and takes nothing but INTERFACE.
+    if library.defines:
+        scope = "PUBLIC" if library.build_sources else "INTERFACE"
+        lines.append("")
+        lines.append(f"target_compile_definitions(${{COMPONENT_LIB}} {scope}")
+        lines.extend(f"{INDENT}{define}" for define in library.defines)
+        lines.append(")")
+
+    if library.esp32.cmake:
+        lines.append("")
+        lines.append(f"# From {library.name}'s installer.yml.")
+        lines.extend(library.esp32.cmake)
+
+    # The user's own lines, which every install carries over. Empty to start
+    # with, so anything in it on an uninstall is the user's.
+    scope = "PRIVATE" if library.build_sources else "INTERFACE"
+    lines += [
+        "",
+        f"# Lines of your own for {library.name}, such as",
+        f"# target_compile_options(${{COMPONENT_LIB}} {scope} -O2), go between these",
+        "# two, and every install keeps them.",
+        f"# USER CODE BEGIN {section(library)}",
+        f"# USER CODE END {section(library)}",
+    ]
+
+    return "\n".join(lines) + "\n"
+
+
+def _help(lines):
+    """A Kconfig help block, each line indented under it."""
+    out = [f"{INDENT}help"]
+    out.extend(f"{INDENT}{INDENT}{line}" if line.strip() else "" for line in lines)
+
+    return out
+
+
+def one_line(text):
+    """Text for a Kconfig prompt: one line, its quotes and backslashes escaped."""
+    flat = " ".join(str(text).split())
+
+    return flat.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def kconfig(library):
+    """
+    The component's Kconfig: a menu of the library's settings in menuconfig.
+
+    None when the library has no settings. ESP-IDF reads a Kconfig file at the
+    top of any component on its own, so nothing else has to name it.
+    """
+    settings = library.esp32.settings
+
+    if not settings:
+        return None
+
+    title = library.name + (f": {library.description}" if library.description else "")
+    lines = [
+        f"{MARK} for {_label(library)}. Written again on",
+        "# every install and update, so a change made here does not last.",
+        "",
+        f'menu "{one_line(title)}"',
+    ]
+
+    for setting in settings:
+        lines.append("")
+        lines.append(f"{INDENT}config {setting.name}")
+        lines.append(f'{INDENT}{INDENT}{setting.type} "{setting.prompt}"')
+        lines.append(f"{INDENT}{INDENT}default {setting.default}")
+
+        if setting.range:
+            lines.append(f"{INDENT}{INDENT}range {setting.format(setting.range[0])} "
+                         f"{setting.format(setting.range[1])}")
+
+        if setting.help:
+            lines.extend(f"{INDENT}{line}" if line else "" for line in _help(setting.help))
+
+    lines.append("")
+    lines.append("endmenu")
+
+    return "\n".join(lines) + "\n"
+
+
+def _ours(path):
+    """Whether a file is one this wrote, by its first line."""
+    try:
+        return path.read_text(encoding="utf-8").startswith(MARK)
+    except (OSError, UnicodeDecodeError):
+        return False
+
+
+def ships_its_own(destination):
+    """Whether the library brought a CMakeLists.txt of its own."""
+    path = Path(destination) / CMAKELISTS
+
+    return path.is_file() and not _ours(path)
+
+
+def write(library, destination, requires):
+    """Write the component's files, each only when it changed. Returns an Outcome."""
+    folder = Path(destination)
+    name = component_name(destination)
+
+    if ships_its_own(destination):
+        return Outcome(NAME, ALREADY, f"{library.name} has its own CMakeLists.txt, used as it is.")
+
+    wanted = {CMAKELISTS: cmakelists(library, requires), KCONFIG: kconfig(library)}
+    written = []
+    removed = []
+    steps = []
+    saved = None
+
+    try:
+        for file_name, text in wanted.items():
+            path = folder / file_name
+
+            # A Kconfig an earlier version wrote, for settings this one no
+            # longer has. One of the library's own is never touched.
+            if text is None:
+                if path.is_file() and _ours(path):
+                    path.unlink()
+                    removed.append(file_name)
+
+                continue
+
+            data = text.encode("utf-8")
+            old = path.read_bytes() if path.is_file() else None
+
+            # What the user wrote between the USER CODE lines of the last copy
+            # goes into the new one. Markers that no longer pair leave nothing
+            # to carry, so the copy is put aside first, whole.
+            if old is not None and file_name == CMAKELISTS:
+                merged = usercode.merge(data, old)
+
+                if merged.broken or merged.lost:
+                    saved = backup(path)
+                    steps.append(f"Your lines in {file_name} could not be carried over: they are in {saved.name}.")
+                else:
+                    data = merged.data
+
+                if merged.kept:
+                    steps.append(f"Kept your USER CODE {', '.join(merged.kept)} in {file_name}.")
+
+            # Left alone when nothing changed, so the build does not see a
+            # newer file and configure again for nothing.
+            if old == data:
+                continue
+
+            path.write_bytes(data)
+            written.append(file_name)
+    except OSError as error:
+        return Outcome(NAME, MANUAL, f"Could not write {folder}: {error}")
+
+    if not written and not removed:
+        return Outcome(NAME, ALREADY, f"The component {name} is up to date.", steps)
+
+    done = [f"wrote {', '.join(written)}"] if written else []
+    done += [f"removed its {', '.join(removed)}, as {library.name} has no settings now"] if removed else []
+
+    return Outcome(NAME, CHANGED, f"The component {name}: {'; '.join(done)}.", steps, saved)
+
+
+def _holds_yours(path):
+    """Whether a CMakeLists.txt write() made has anything between its USER CODE lines."""
+    try:
+        lines, sections = usercode.parse(path.read_bytes())
+    except usercode.MarkerError:
+        return True
+
+    return any(b"".join(lines[first:last]).strip() for first, last in sections.values())
+
+
+def remove(destination):
+    """
+    Delete the files write() made. A library's own CMakeLists.txt is not touched.
+
+    Returns the copy put aside of a CMakeLists.txt that had the user's lines
+    in it, or None.
+    """
+    folder = Path(destination)
+    saved = None
+
+    for file_name in (CMAKELISTS, KCONFIG):
+        path = folder / file_name
+
+        try:
+            if not (path.is_file() and _ours(path)):
+                continue
+
+            if file_name == CMAKELISTS and _holds_yours(path):
+                saved = backup(path)
+
+            path.unlink()
+        except OSError:
+            continue
+
+    return saved
+
+
+# A symbol the Kconfig defines: config NAME, or menuconfig NAME.
+_DEFINED = re.compile(r"^[ \t]*(?:menu)?config[ \t]+([A-Za-z0-9_]+)", re.MULTILINE)
+
+
+def symbols(destination):
+    """Every symbol the Kconfig write() made defines, read before it is removed."""
+    path = Path(destination) / KCONFIG
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+
+    return _DEFINED.findall(text) if text.startswith(MARK) else []

esp32_installer/core/__init__.py

@@ -0,0 +1,12 @@
+"""
+The shared core of the installers: stm32-installer, zephyr-installer.
+
+It fetches a library from GitHub, a zip or a folder, reads its installer.yml,
+installs what it needs first, copies its files and keeps what the user wrote
+between USER CODE markers. What a project looks like, and how a library is
+registered with it, comes from the installer through target.use().
+
+Kept in its own repository, github.com/nimaltd/core-installer, and built into
+each installer's wheel, so an installer still installs from one file with no
+internet.
+"""