romfs 0.0.1__py3-none-any.whl

romfs/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Junbo Zheng
+"""romfs: pure-Python reader and writer for Linux romfs (-rom1fs-) images."""
+
+from .errors import (
+    BadMagicError,
+    ChecksumMismatchError,
+    RomFSError,
+    TruncatedImageError,
+    UnsupportedTypeError,
+)
+from .format import EntryType
+from .nodes import RomFSNode
+from .reader import RomFSReader
+from .writer import RomFSWriter
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "RomFSReader",
+    "RomFSWriter",
+    "RomFSNode",
+    "EntryType",
+    "RomFSError",
+    "BadMagicError",
+    "ChecksumMismatchError",
+    "TruncatedImageError",
+    "UnsupportedTypeError",
+    "__version__",
+]

romfs/cli.py

@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Junbo Zheng
+"""Command-line interface for the romfs package."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from .errors import RomFSError
+from .format import EntryType
+from .nodes import RomFSNode
+from .reader import RomFSReader
+from .writer import RomFSWriter
+
+_TYPE_LABEL = {
+    EntryType.REGULAR: "f",
+    EntryType.DIRECTORY: "d",
+    EntryType.SYMLINK: "l",
+}
+
+
+def _version() -> str:
+    try:
+        return version("romfs")
+    except PackageNotFoundError:
+        from . import __version__
+
+        return __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="romfs",
+        description=f"romfs {_version()} — read and write Linux romfs images.",
+    )
+    p.add_argument("-V", "--version", action="version", version=f"romfs {_version()}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_list = sub.add_parser("list", help="list the file tree in an image")
+    p_list.add_argument("image")
+
+    p_extract = sub.add_parser("extract", help="extract files from an image")
+    p_extract.add_argument("image")
+    p_extract.add_argument(
+        "path", nargs="?", help="extract a single entry to stdout (else all)"
+    )
+    p_extract.add_argument(
+        "-o", "--outdir", help="output directory for full extraction"
+    )
+
+    p_pack = sub.add_parser("pack", help="build an image from a directory tree")
+    p_pack.add_argument("srcdir")
+    p_pack.add_argument("-o", "--out", required=True, help="output image path")
+    p_pack.add_argument("-n", "--name", default="", help="volume name")
+
+    p_info = sub.add_parser("info", help="print image header info")
+    p_info.add_argument("image")
+    p_info.add_argument(
+        "--verify", action="store_true", help="verify the superblock checksum"
+    )
+
+    args = p.parse_args(argv)
+
+    try:
+        if args.cmd == "list":
+            return _cmd_list(args)
+        if args.cmd == "extract":
+            return _cmd_extract(args)
+        if args.cmd == "pack":
+            return _cmd_pack(args)
+        if args.cmd == "info":
+            return _cmd_info(args)
+    except RomFSError as e:
+        print(f"romfs: error: {e}", file=sys.stderr)
+        return 1
+    except FileNotFoundError as e:
+        print(f"romfs: error: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    with RomFSReader(args.image) as r:
+        for path, node in r.walk():
+            label = _TYPE_LABEL.get(node.type, "?")
+            print(f"{label} {node.size:>10}  {path}")
+    return 0
+
+
+def _cmd_extract(args: argparse.Namespace) -> int:
+    with RomFSReader(args.image) as r:
+        if args.path:
+            node = _find(r, args.path)
+            if node is None:
+                print(f"romfs: error: path not found: {args.path}", file=sys.stderr)
+                return 1
+            if node.type is EntryType.DIRECTORY:
+                print(
+                    f"romfs: error: cannot extract a directory: {args.path}",
+                    file=sys.stderr,
+                )
+                return 1
+            sys.stdout.buffer.write(r.read(node))
+            return 0
+        outdir = args.outdir or Path(args.image).stem + ".extracted"
+        r.extract(outdir)
+        print(f"extracted to {outdir}")
+    return 0
+
+
+def _cmd_pack(args: argparse.Namespace) -> int:
+    RomFSWriter.from_directory(args.srcdir, volume_name=args.name).write(args.out)
+    print(f"packed {args.srcdir} -> {args.out}")
+    return 0
+
+
+def _cmd_info(args: argparse.Namespace) -> int:
+    with RomFSReader(args.image, verify=args.verify) as r:
+        print(f"image:      {args.image}")
+        print("magic:      -rom1fs-")
+        print(f"full_size:  {r.full_size} bytes")
+        print(f"volume:     {r.volume_name!r}")
+        n_files = sum(1 for _, n in r.walk() if n.type is EntryType.REGULAR)
+        n_dirs = sum(1 for _, n in r.walk() if n.type is EntryType.DIRECTORY)
+        n_links = sum(1 for _, n in r.walk() if n.type is EntryType.SYMLINK)
+        print(f"entries:    {n_files} file, {n_dirs} dir, {n_links} symlink")
+        if args.verify:
+            print("checksum:   OK")
+    return 0
+
+
+def _find(reader: RomFSReader, path: str) -> RomFSNode | None:
+    path = path.lstrip("/")
+    for p, node in reader.walk():
+        if p == path:
+            return node
+    return None
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

romfs/errors.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Junbo Zheng
+"""romfs exception hierarchy."""
+
+from __future__ import annotations
+
+
+class RomFSError(Exception):
+    """Base class for all romfs errors."""
+
+
+class BadMagicError(RomFSError):
+    """The image does not start with the ``-rom1fs-`` magic."""
+
+
+class TruncatedImageError(RomFSError):
+    """The image is shorter than the bytes a header claims to occupy."""
+
+
+class UnsupportedTypeError(RomFSError):
+    """The image contains an entry type this library does not handle."""
+
+
+class ChecksumMismatchError(RomFSError):
+    """The superblock checksum region does not sum to zero."""
+
+
+__all__ = [
+    "RomFSError",
+    "BadMagicError",
+    "TruncatedImageError",
+    "UnsupportedTypeError",
+    "ChecksumMismatchError",
+]

romfs/format.py

@@ -0,0 +1,175 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Junbo Zheng
+"""romfs on-disk format primitives.
+
+Byte-exact per the Linux kernel sources:
+  - fs/romfs/super.c            (superblock parse, root offset, checksum)
+  - include/uapi/linux/romfs_fs.h  (struct + constant definitions)
+  - Documentation/filesystems/romfs.rst
+
+All multi-byte integers are big-endian. Every header and payload begins on a
+16-byte boundary. The superblock checksum covers the first
+``min(full_size, 512)`` bytes; the file-header checksum covers the whole header
+(fixed 16 bytes + padded name). Both are stored as the two's complement of the
+sum of the remaining words so that summing every word in the covered region
+(including the checksum word) yields zero.
+"""
+
+from __future__ import annotations
+
+import struct
+from enum import IntEnum
+
+# --- Superblock ------------------------------------------------------------
+
+# "-rom1fs-" as two big-endian words: '-','r','o','m' and '1','f','s','-'.
+ROMFS_MAGIC_WORD0 = b"-rom"
+ROMFS_MAGIC_WORD1 = b"1fs-"
+ROMFS_MAGIC = ROMFS_MAGIC_WORD0 + ROMFS_MAGIC_WORD1  # b"-rom1fs-"
+
+# The superblock checksum window: the first min(full_size, 512) bytes.
+ROMFS_SUPERBLOCK_CHECK_WINDOW = 512
+
+# Whole-image padding to a 1024-byte boundary (block-device mount requirement,
+# per Documentation/filesystems/romfs.rst).
+ROMFS_IMAGE_ALIGN = 1024
+
+# --- File header -----------------------------------------------------------
+
+ROMFH_SIZE = 16  # fixed part of a file header (next, spec, size, checksum)
+ROMFH_PAD = 15  # low 4 bits carry type + exec, so offsets are 16-aligned
+ROMFH_MASK = ~ROMFH_PAD & 0xFFFFFFFF  # next/spec offset mask (clear low 4 bits)
+ROMFH_TYPE = 7  # low 3 bits: entry type
+ROMFH_EXEC = 8  # bit 3: executable
+
+# 16-byte alignment for every header and payload.
+ALIGN = 16
+
+
+class EntryType(IntEnum):
+    """romfs entry type codes (low 3 bits of the ``next`` field)."""
+
+    HARDLINK = 0
+    DIRECTORY = 1
+    REGULAR = 2
+    SYMLINK = 3
+    BLOCKDEV = 4
+    CHARDEV = 5
+    SOCKET = 6
+    FIFO = 7
+
+
+# --- Structs ---------------------------------------------------------------
+
+# Superblock fixed part: magic0, magic1, full_size, checksum (name[] follows).
+_superblock_head = struct.Struct(">4s4sII")
+# File header fixed part: next, spec, size, checksum (name[] follows).
+_file_head = struct.Struct(">IIII")
+
+
+def align_up(n: int, alignment: int = ALIGN) -> int:
+    """Round ``n`` up to the next multiple of ``alignment``."""
+    return (n + alignment - 1) & ~(alignment - 1)
+
+
+def align16(n: int) -> int:
+    """Round ``n`` up to the next 16-byte boundary."""
+    return align_up(n, ALIGN)
+
+
+def name_field_size(name_len: int) -> int:
+    """Padded size of a null-terminated name field of ``name_len`` bytes.
+
+    The name is stored null-terminated and the whole field (name + NUL +
+    padding) is rounded up to 16 bytes. Minimum field size is 16.
+    """
+    return align16(name_len + 1)
+
+
+def header_meta_size(name_len: int) -> int:
+    """Total metadata size of a file header: fixed 16 bytes + padded name."""
+    return ROMFH_SIZE + name_field_size(name_len)
+
+
+def _sum_words(buf: bytes) -> int:
+    """Sum every big-endian uint32 word in ``buf`` (length must be a multiple of 4)."""
+    if len(buf) % 4 != 0:
+        raise ValueError(f"buffer length {len(buf)} is not a multiple of 4")
+    total = 0
+    for i in range(0, len(buf), 4):
+        total += struct.unpack_from(">I", buf, i)[0]
+    return total & 0xFFFFFFFF
+
+
+def superblock_checksum(first_block: bytes) -> int:
+    """Compute the superblock checksum word for ``first_block``.
+
+    ``first_block`` is the first ``min(full_size, 512)`` bytes of the image
+    with the checksum field (offset 12) set to 0. The returned value, when
+    stored at offset 12, makes the sum of every word in ``first_block`` equal
+    to zero.
+    """
+    return (-_sum_words(first_block)) & 0xFFFFFFFF
+
+
+def header_checksum(header: bytes) -> int:
+    """Compute the file-header checksum word for ``header``.
+
+    ``header`` is the full header (16 fixed bytes + padded name) with the
+    checksum field (offset 12) set to 0. Same convention as the superblock:
+    the stored value makes the whole header sum to zero.
+    """
+    return (-_sum_words(header)) & 0xFFFFFFFF
+
+
+def verify_superblock_checksum(first_block: bytes, stored: int) -> bool:
+    """Return True if the superblock checksum region sums to zero."""
+    return (_sum_words(first_block[:ROMFS_SUPERBLOCK_CHECK_WINDOW]) & 0xFFFFFFFF) == 0
+
+
+# --- Pack / unpack helpers -------------------------------------------------
+
+
+def pack_superblock_head(full_size: int, checksum: int) -> bytes:
+    """Pack the 16-byte superblock fixed head (magic + size + checksum)."""
+    return _superblock_head.pack(
+        ROMFS_MAGIC_WORD0, ROMFS_MAGIC_WORD1, full_size, checksum
+    )
+
+
+def unpack_superblock_head(buf: bytes) -> tuple[bytes, bytes, int, int]:
+    """Unpack the 16-byte superblock fixed head.
+
+    Returns ``(magic0, magic1, full_size, checksum)``.
+    """
+    return _superblock_head.unpack(buf[:ROMFH_SIZE])
+
+
+def pack_file_head(next_off: int, spec: int, size: int, checksum: int) -> bytes:
+    """Pack the 16-byte file header fixed part."""
+    return _file_head.pack(
+        next_off & 0xFFFFFFFF,
+        spec & 0xFFFFFFFF,
+        size & 0xFFFFFFFF,
+        checksum & 0xFFFFFFFF,
+    )
+
+
+def unpack_file_head(buf: bytes) -> tuple[int, int, int, int]:
+    """Unpack the 16-byte file header fixed part -> (next, spec, size, checksum)."""
+    return _file_head.unpack(buf[:ROMFH_SIZE])
+
+
+def encode_name(name: str) -> bytes:
+    """Encode a name to its null-terminated, 16-byte-padded field bytes."""
+    raw = name.encode("utf-8")
+    field = name_field_size(len(raw))
+    return raw + b"\x00" * (field - len(raw))
+
+
+def decode_name(field: bytes) -> str:
+    """Decode a padded name field up to its NUL terminator."""
+    nul = field.find(b"\x00")
+    if nul >= 0:
+        field = field[:nul]
+    return field.decode("utf-8")

romfs/nodes.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Junbo Zheng
+"""In-memory node tree shared by reader and writer."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .format import EntryType
+
+if TYPE_CHECKING:
+    from .reader import RomFSReader
+
+
+@dataclass
+class RomFSNode:
+    """A single romfs entry (regular file, directory, or symlink).
+
+    Reader and writer share this representation:
+      - ``data_offset``: absolute byte offset of the payload in the image
+        (regular/symlink). ``None`` until laid out / parsed.
+      - ``header_offset``: absolute byte offset of this entry's header.
+      - ``children`` / ``parent``: tree links (directories carry children).
+      - ``src_path``: writer-side source path to copy payload from.
+      - ``_reader``: reader-side back-reference for lazy content reads.
+    """
+
+    name: str
+    type: EntryType
+    size: int = 0
+    spec_info: int = 0
+    header_offset: int | None = None
+    data_offset: int | None = None
+    children: list[RomFSNode] = field(default_factory=list)
+    parent: RomFSNode | None = None
+    src_path: str | None = None
+    _reader: RomFSReader | None = field(default=None, repr=False)
+    # symlink target string (writer-side convenience; reader fills it on demand)
+    target: str | None = None
+
+    @property
+    def is_dir(self) -> bool:
+        return self.type is EntryType.DIRECTORY
+
+    @property
+    def is_regular(self) -> bool:
+        return self.type is EntryType.REGULAR
+
+    @property
+    def is_symlink(self) -> bool:
+        return self.type is EntryType.SYMLINK
+
+    def walk(self, prefix: str = "") -> Iterator[tuple[str, RomFSNode]]:
+        """Yield ``(path, node)`` for this node and all descendants (pre-order)."""
+        path = f"{prefix}/{self.name}" if prefix else self.name
+        yield path, self
+        for child in self.children:
+            yield from child.walk(path)
+
+
+__all__ = ["RomFSNode"]

romfs/reader.py

@@ -0,0 +1,225 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Junbo Zheng
+"""Parse a romfs image into a node tree with lazy content reads."""
+
+from __future__ import annotations
+
+import mmap
+from collections.abc import Iterator
+from pathlib import Path
+
+from .errors import (
+    BadMagicError,
+    ChecksumMismatchError,
+    TruncatedImageError,
+    UnsupportedTypeError,
+)
+from .format import (
+    ROMFH_MASK,
+    ROMFS_MAGIC,
+    ROMFS_SUPERBLOCK_CHECK_WINDOW,
+    EntryType,
+    _sum_words,
+    decode_name,
+    header_meta_size,
+    unpack_file_head,
+    unpack_superblock_head,
+)
+from .nodes import RomFSNode
+
+_MAX_NAME = 128  # ROMFS_MAXFN
+
+
+class RomFSReader:
+    """Read a romfs image from a file, building a node tree.
+
+    File contents are not loaded eagerly: the image is memory-mapped and
+    :meth:`read` slices the payload on demand.
+    """
+
+    def __init__(self, path: str | Path, *, verify: bool = True) -> None:
+        self._path = Path(path)
+        self._fd = open(self._path, "rb")
+        self._mm = mmap.mmap(self._fd.fileno(), 0, access=mmap.ACCESS_READ)
+
+        magic0, magic1, full_size, checksum = unpack_superblock_head(self._mm[:16])
+        if magic0 + magic1 != ROMFS_MAGIC:
+            raise BadMagicError(f"not a romfs image: bad magic {magic0 + magic1!r}")
+
+        self.full_size = full_size
+        self._checksum = checksum
+
+        if verify:
+            self._verify_checksum()
+
+        self.volume_name = self._read_volume_name()
+        self.root = self._build_root()
+
+    # --- public API --------------------------------------------------------
+
+    def walk(self) -> Iterator[tuple[str, RomFSNode]]:
+        """Yield ``(path, node)`` for every node under root (root itself excluded)."""
+        for child in self.root.children:
+            yield from child.walk()
+
+    def read(self, node: RomFSNode) -> bytes:
+        """Return the payload bytes of a regular file or symlink target."""
+        if node.type is EntryType.DIRECTORY:
+            raise TypeError(f"{node.name!r}: directories have no payload")
+        if node.data_offset is None:
+            raise TypeError(f"{node.name!r}: node has no data offset")
+        return bytes(self._mm[node.data_offset : node.data_offset + node.size])
+
+    def extract(self, outdir: str | Path) -> None:
+        """Write the whole tree to ``outdir`` (created if missing)."""
+        out = Path(outdir)
+        out.mkdir(parents=True, exist_ok=True)
+        for path, node in self.walk():
+            rel = Path(path)
+            if node.type is EntryType.DIRECTORY:
+                (out / rel).mkdir(parents=True, exist_ok=True)
+            elif node.type is EntryType.SYMLINK:
+                target = self.read(node).decode("utf-8")
+                (out / rel).parent.mkdir(parents=True, exist_ok=True)
+                (out / rel).symlink_to(target)
+            elif node.type is EntryType.REGULAR:
+                (out / rel).parent.mkdir(parents=True, exist_ok=True)
+                (out / rel).write_bytes(self.read(node))
+
+    def close(self) -> None:
+        self._mm.close()
+        self._fd.close()
+
+    def __enter__(self) -> RomFSReader:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # --- internals ---------------------------------------------------------
+
+    def _read_volume_name(self) -> str:
+        # Volume name starts at offset 16, NUL-terminated (capped at ROMFS_MAXFN).
+        end = 16
+        limit = min(16 + _MAX_NAME, len(self._mm))
+        while end < limit and self._mm[end] != 0:
+            end += 1
+        return bytes(self._mm[16:end]).decode("utf-8", errors="replace")
+
+    def _verify_checksum(self) -> None:
+        # The kernel sums EVERY word in the first min(full_size, 512) bytes
+        # (including the checksum field) and requires the total to be zero:
+        # stored_checksum == -(sum of all other words). So we sum the raw
+        # block as-is and check for zero — no zeroing of the checksum field.
+        window = min(self.full_size, ROMFS_SUPERBLOCK_CHECK_WINDOW)
+        if window > len(self._mm):
+            raise TruncatedImageError(
+                f"image is {len(self._mm)} bytes but checksum window needs {window}"
+            )
+        if _sum_words(bytes(self._mm[:window])) & 0xFFFFFFFF != 0:
+            raise ChecksumMismatchError("superblock checksum does not sum to zero")
+
+    def _build_root(self) -> RomFSNode:
+        # Root header offset = align16(16 + len(volume_name) + 1), matching the
+        # kernel's `(ROMFH_SIZE + len + 1 + ROMFH_PAD) & ROMFH_MASK`.
+        root_off = header_meta_size(len(self.volume_name.encode("utf-8")))
+        root = self._parse_node(root_off)
+        if root.type is not EntryType.DIRECTORY:
+            raise BadMagicError(f"root entry at offset {root_off} is not a directory")
+        # The on-disk root entry is named "." (genromfs convention); expose it
+        # as a nameless root so child paths are clean ("watchface", not "./watchface").
+        root.name = ""
+        return root
+
+    def _parse_node(self, offset: int) -> RomFSNode:
+        if offset + 16 > len(self._mm):
+            raise TruncatedImageError(
+                f"file header at offset {offset} is out of bounds"
+            )
+
+        next_off, spec, size, _checksum = unpack_file_head(
+            self._mm[offset : offset + 16]
+        )
+        type_code = next_off & 0x07
+        try:
+            etype = EntryType(type_code)
+        except ValueError as e:
+            raise UnsupportedTypeError(
+                f"unknown entry type {type_code} at offset {offset}"
+            ) from e
+
+        name_len = self._strnlen(offset + 16)
+        name = decode_name(self._mm[offset + 16 : offset + 16 + name_len])
+        meta = header_meta_size(name_len)
+
+        node = RomFSNode(
+            name=name,
+            type=etype,
+            size=size,
+            spec_info=spec & ROMFH_MASK,
+            header_offset=offset,
+            _reader=self,
+        )
+        if etype is EntryType.HARDLINK:
+            # A hardlink's spec points at its destination header. genromfs uses
+            # hardlinks both for ".." (skipped in _parse_children) and for
+            # deduplicating identical files. Resolve file/symlink targets so
+            # read()/extract() see the linked content; directory targets are
+            # left unresolved to avoid cycles in the tree.
+            self._resolve_hardlink(node, spec & ROMFH_MASK)
+        elif etype in (EntryType.REGULAR, EntryType.SYMLINK):
+            node.data_offset = offset + meta
+        elif etype is EntryType.DIRECTORY:
+            self._parse_children(node, spec & ROMFH_MASK)
+
+        return node
+
+    def _resolve_hardlink(self, node: RomFSNode, target_off: int) -> None:
+        """Mirror a hardlink's file/symlink target so its content is readable."""
+        if not target_off or target_off == node.header_offset:
+            return
+        if target_off + 16 > len(self._mm):
+            return
+        t_next, _t_spec, t_size, _ = unpack_file_head(
+            self._mm[target_off : target_off + 16]
+        )
+        try:
+            t_type = EntryType(t_next & 0x07)
+        except ValueError:
+            return
+        if t_type not in (EntryType.REGULAR, EntryType.SYMLINK):
+            return
+        t_name_len = self._strnlen(target_off + 16)
+        t_meta = header_meta_size(t_name_len)
+        node.type = t_type
+        node.size = t_size
+        node.data_offset = target_off + t_meta
+
+    def _parse_children(self, parent: RomFSNode, first_off: int) -> None:
+        offset = first_off
+        while offset and offset + 16 <= len(self._mm):
+            # Peek the name first to skip the "." / ".." self/parent entries
+            # that genromfs emits at the head of every directory. "." is a DIR
+            # whose spec points back at the directory itself, so recursing into
+            # it would loop forever; ".." is a hardlink to the parent.
+            name_len = self._strnlen(offset + 16)
+            name = decode_name(self._mm[offset + 16 : offset + 16 + name_len])
+            if name not in (".", ".."):
+                child = self._parse_node(offset)
+                child.parent = parent
+                parent.children.append(child)
+            # Advance to the next sibling via this entry's `next` field. The
+            # offset lives in the high 28 bits; the low 4 bits carry type+exec.
+            next_raw = unpack_file_head(self._mm[offset : offset + 16])[0]
+            offset = next_raw & ROMFH_MASK
+
+    def _strnlen(self, offset: int) -> int:
+        """Length of the NUL-terminated name at ``offset`` (capped at ROMFS_MAXFN)."""
+        end = offset
+        limit = min(offset + _MAX_NAME, len(self._mm))
+        while end < limit and self._mm[end] != 0:
+            end += 1
+        return end - offset
+
+
+__all__ = ["RomFSReader"]

romfs/writer.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Junbo Zheng
+"""Build a romfs image from a node tree or a local directory tree."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import BinaryIO
+
+from .format import (
+    ALIGN,
+    ROMFS_IMAGE_ALIGN,
+    ROMFS_SUPERBLOCK_CHECK_WINDOW,
+    EntryType,
+    align_up,
+    encode_name,
+    header_checksum,
+    header_meta_size,
+    pack_file_head,
+    pack_superblock_head,
+    superblock_checksum,
+)
+from .nodes import RomFSNode
+
+
+class RomFSWriter:
+    """Assemble a romfs image from a root :class:`RomFSNode` tree.
+
+    Build a tree with :meth:`from_directory` (or by hand), then call
+    :meth:`write` to emit the image.
+    """
+
+    def __init__(self, root: RomFSNode, volume_name: str = "") -> None:
+        if root.type is not EntryType.DIRECTORY:
+            raise ValueError("root node must be a directory")
+        self.root = root
+        self.volume_name = volume_name
+
+    # --- construction ------------------------------------------------------
+
+    @classmethod
+    def from_directory(cls, root_dir: str | Path, volume_name: str = "") -> RomFSWriter:
+        """Build a writer from a local directory tree.
+
+        - directories  -> DIRECTORY nodes (recursed)
+        - symlinks     -> SYMLINK nodes (target stored as payload)
+        - regular files-> REGULAR nodes (payload copied from disk)
+        Other entry types (devices, fifos, sockets) are skipped with a warning.
+        """
+        root_dir = Path(root_dir)
+        if not root_dir.is_dir():
+            raise NotADirectoryError(f"not a directory: {root_dir}")
+        root = RomFSNode(name="", type=EntryType.DIRECTORY)
+        cls._scan(root_dir, root)
+        return cls(root, volume_name=volume_name)
+
+    @classmethod
+    def _scan(cls, dir_path: Path, node: RomFSNode) -> None:
+        for entry in sorted(dir_path.iterdir(), key=lambda p: p.name):
+            child = cls._make_node(entry)
+            if child is not None:
+                child.parent = node
+                node.children.append(child)
+
+    @classmethod
+    def _make_node(cls, path: Path) -> RomFSNode | None:
+        if path.is_symlink():
+            target = os.readlink(path)
+            tgt_bytes = target.encode("utf-8")
+            return RomFSNode(
+                name=path.name,
+                type=EntryType.SYMLINK,
+                size=len(tgt_bytes),
+                target=target,
+            )
+        if path.is_dir():
+            node = RomFSNode(name=path.name, type=EntryType.DIRECTORY)
+            cls._scan(path, node)
+            return node
+        if path.is_file():
+            return RomFSNode(
+                name=path.name,
+                type=EntryType.REGULAR,
+                size=path.stat().st_size,
+                src_path=str(path),
+            )
+        # Skip devices / fifos / sockets — out of scope for this writer.
+        return None
+
+    # --- emission ----------------------------------------------------------
+
+    def write(self, out: str | Path | BinaryIO) -> None:
+        """Write the romfs image to a path or open binary stream."""
+        image = self._build_image()
+        if isinstance(out, (str, os.PathLike)):
+            Path(out).write_bytes(image)
+        else:
+            out.write(image)
+
+    def _build_image(self) -> bytes:
+        # 1. Assign header offsets via pre-order DFS.
+        root_off = header_meta_size(len(self.volume_name.encode("utf-8")))
+        content_end = self._layout(self.root, root_off)
+        total = align_up(content_end, ROMFS_IMAGE_ALIGN)
+
+        # 2. Render into a zeroed buffer of the final size.
+        buf = bytearray(total)
+        self._render(self.root, buf)
+
+        # 3. Fill the superblock (magic + size + checksum) last.
+        self._render_superblock(buf, total)
+
+        return bytes(buf)
+
+    # --- layout ------------------------------------------------------------
+
+    def _layout(self, node: RomFSNode, offset: int) -> int:
+        """Assign ``header_offset``/``data_offset``; return the next free offset."""
+        node.header_offset = offset
+        meta = header_meta_size(len(node.name.encode("utf-8")))
+
+        if node.type is EntryType.DIRECTORY:
+            cursor = offset + meta
+            for child in node.children:
+                cursor = self._layout(child, cursor)
+            if node.children:
+                first = node.children[0].header_offset
+                assert first is not None
+                node.spec_info = first
+            else:
+                node.spec_info = 0
+            return cursor
+
+        # Regular file or symlink: payload follows the (padded) header.
+        node.data_offset = offset + meta
+        return offset + meta + align_up(node.size, ALIGN)
+
+    # --- rendering ---------------------------------------------------------
+
+    def _render(self, node: RomFSNode, buf: bytearray) -> None:
+        offset = node.header_offset
+        assert offset is not None
+
+        next_off = self._next_sibling_offset(node)
+        type_bits = int(node.type) & 0x07
+        next_field = (next_off | type_bits) & 0xFFFFFFFF
+
+        # Pack the header with checksum=0, then fix up the checksum.
+        name_field = encode_name(node.name)
+        head = pack_file_head(next_field, node.spec_info, node.size, 0) + name_field
+        checksum = header_checksum(head)
+        head = (
+            pack_file_head(next_field, node.spec_info, node.size, checksum) + name_field
+        )
+        buf[offset : offset + len(head)] = head
+
+        if node.type is EntryType.REGULAR:
+            assert (
+                node.src_path is not None
+            ), f"regular node {node.name!r} has no src_path"
+            data = Path(node.src_path).read_bytes()
+            self._write_payload(buf, node, data)
+        elif node.type is EntryType.SYMLINK:
+            assert node.target is not None, f"symlink node {node.name!r} has no target"
+            data = node.target.encode("utf-8")
+            self._write_payload(buf, node, data)
+        elif node.type is EntryType.DIRECTORY:
+            for child in node.children:
+                self._render(child, buf)
+
+    def _write_payload(self, buf: bytearray, node: RomFSNode, data: bytes) -> None:
+        assert node.data_offset is not None
+        buf[node.data_offset : node.data_offset + len(data)] = data
+        # Trailing padding stays zero (buffer is pre-zeroed).
+
+    def _next_sibling_offset(self, node: RomFSNode) -> int:
+        if node.parent is None:
+            # Root has no siblings.
+            return 0
+        siblings = node.parent.children
+        idx = siblings.index(node)
+        if idx + 1 < len(siblings):
+            nxt = siblings[idx + 1].header_offset
+            assert nxt is not None
+            return nxt
+        return 0
+
+    # --- superblock --------------------------------------------------------
+
+    def _render_superblock(self, buf: bytearray, total: int) -> None:
+        # Magic + full_size + checksum(=0 placeholder) + volume name field.
+        head = pack_superblock_head(total, 0)
+        name_field = encode_name(self.volume_name)
+        buf[0 : len(head)] = head
+        buf[len(head) : len(head) + len(name_field)] = name_field
+
+        # Checksum covers the first min(total, 512) bytes with the checksum
+        # field (offset 12) zeroed.
+        window = min(total, ROMFS_SUPERBLOCK_CHECK_WINDOW)
+        block = bytes(buf[:window])
+        checksum = superblock_checksum(block)
+        final_head = pack_superblock_head(total, checksum)
+        buf[0 : len(final_head)] = final_head
+
+
+__all__ = ["RomFSWriter"]

romfs-0.0.1.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: romfs
+Version: 0.0.1
+Summary: Pure-Python reader and writer for Linux romfs (-rom1fs-) filesystem images.
+Project-URL: Homepage, https://github.com/Junbo-Zheng/romfs
+Project-URL: Issues, https://github.com/Junbo-Zheng/romfs/issues
+Author-email: Junbo Zheng <Junbo-Zheng@users.noreply.github.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: embedded,filesystem,image,initrd,rom1fs,romfs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Filesystems
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# romfs
+
+[![PyPI](https://img.shields.io/pypi/v/romfs.svg)](https://pypi.org/project/romfs/)
+[![CI](https://github.com/Junbo-Zheng/romfs/actions/workflows/ci.yml/badge.svg)](https://github.com/Junbo-Zheng/romfs/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/romfs.svg)](https://pypi.org/project/romfs/)
+[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
+
+> Pure-Python reader and writer for Linux romfs (`-rom1fs-`) filesystem images.
+> Standard library only, no runtime dependencies.
+
+`romfs` lets you build, inspect, and extract the small read-only filesystem
+images the Linux kernel uses for initrds and embedded root filesystems. Images
+produced by the writer are byte-compatible with `mount -t romfs` and
+interchangeable with `genromfs`; the reader parses any such image, including
+real `genromfs` output with `.`/`..` self-links and dedup hardlinks.
+
+## Features
+
+- **Read** an image into a node tree; list entries and read file contents
+  lazily via `mmap` — large images don't blow up memory.
+- **Write** an image from a local directory tree, preserving the structure,
+  regular files, and symbolic links.
+- **CLI** with `list`, `extract`, `pack`, and `info` subcommands.
+- **Importable library** API for embedding in other tools.
+- Byte-exact conformance with the kernel romfs format: 16-byte alignment,
+  big-endian, superblock + header checksums.
+- Entries sorted by name for a deterministic, diff-friendly layout.
+
+> [!NOTE]
+> The writer lays out entries sorted by name, so two versions of the same
+> resource tree produce byte-stable images — keeping binary diffs (delta
+> packages) small.
+
+## Installation
+
+```bash
+pip install romfs
+```
+
+Run from source with no install:
+
+```bash
+./main.py <args>
+```
+
+## Quick start
+
+```bash
+# Pack a folder tree into a single romfs image
+romfs pack ./rootfs -o rootfs.img -n myvol
+
+# List the file tree (type, size, path)
+romfs list rootfs.img
+
+# Extract one file to stdout, or everything to a directory
+romfs extract rootfs.img etc/init.d/rcS
+romfs extract rootfs.img -o ./out
+
+# Show header info and verify the superblock checksum
+romfs info rootfs.img --verify
+```
+
+## CLI reference
+
+```text
+romfs list   <image>                     list the file tree (path, type, size)
+romfs extract <image> [-o OUTDIR] [PATH] extract all, or one entry to stdout
+romfs pack <srcdir> -o <image> [-n NAME] build an image from a directory tree
+romfs info <image> [--verify]            print header info + checksum check
+```
+
+`romfs -V` prints the version; `romfs -h` shows help.
+
+## Library API
+
+```python
+from romfs import RomFSReader, RomFSWriter, EntryType
+
+# Read an image
+with RomFSReader("rootfs.img") as r:
+    print(r.volume_name, r.full_size)
+    for path, node in r.walk():
+        print(f"{node.type.name:9} {node.size:>8}  {path}")
+    # File contents are sliced from the mmap on demand
+    data = r.read(r.root.children[0])
+
+# Build an image from a directory tree
+RomFSWriter.from_directory("./rootfs", volume_name="myvol").write("out.img")
+```
+
+## Supported entry types
+
+| Type                                | Read | Write |
+|-------------------------------------|:----:|:-----:|
+| Regular file                        | yes  | yes   |
+| Directory                           | yes  | yes   |
+| Symlink                             | yes  | yes   |
+| Hardlink / device / socket / fifo   | yes  | no    |
+
+> [!NOTE]
+> romfs does not store per-file Unix mode bits in the standard format, so the
+> kernel assigns fixed default modes. Permissions are not preserved on write.
+> Hardlinks and special files are parsed on read but not emitted on write.
+
+## Development
+
+```bash
+pip install -e ".[dev]"        # pytest, black, ruff, mypy, build, twine
+pytest                          # runs against src/ directly, no install needed
+black src tests main.py         # format
+ruff check src tests            # lint
+mypy src                        # type check
+python -m build                 # build sdist + wheel into dist/
+```
+
+CI runs black + ruff + mypy + pytest across Python 3.10-3.13, plus a packaging
+job that builds the wheel and tests the installed package. Releases publish to
+PyPI automatically on a GitHub Release via Trusted Publishing (OIDC).

romfs-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+romfs/__init__.py,sha256=BGahrbhMkm18wv3GS0EXnuq5RsXDlUvYTm4YoxSuEIw,662
+romfs/cli.py,sha256=ThdNdJlNFk-H5HZKfAyRlTZpT5SliQj-ipfglPAsSzQ,4574
+romfs/errors.py,sha256=1jElx2KkY2RAXVyu-D2dyOWcHhhkm3QWN159UU0WN2o,787
+romfs/format.py,sha256=H9xXDgqNGVOB47J-s-BbhNUd1NNpSbm-rpg0l31XYRg,5980
+romfs/nodes.py,sha256=L9-qqQFZyeUyNYzKOxGqGEJ2Mp9Z_Puxt5SrmwbLVBA,2023
+romfs/reader.py,sha256=uOvWUh_aEy1rx7uEgbSenTeD6ZJbGRzli6vbPYeRLNo,8866
+romfs/writer.py,sha256=2QpBzQmJaxJVNsbOuIumSPPPsmcutGNXeybx05kV_G0,7614
+romfs-0.0.1.dist-info/METADATA,sha256=6H304Et4CgIipnDR6sWpGXuj7hvN_8w7QHvLimX00JM,5606
+romfs-0.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+romfs-0.0.1.dist-info/entry_points.txt,sha256=1rIx7DcYmcxf80k0zUv6N4FnJsgBNRy4eCTEuMJsg-M,41
+romfs-0.0.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+romfs-0.0.1.dist-info/RECORD,,

romfs-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

romfs-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+romfs = romfs.cli:main

romfs-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.