diff --git a/README.rst b/README.rst index 4f2c189..9889f6f 100644 --- a/README.rst +++ b/README.rst @@ -70,6 +70,7 @@ from scratch the latest version is recommended. .. csv-table:: :header: "LittleFS Version", "Package Version", "LittleFS File System Version" + 2.9.0, v0.11.X, 2.0 / 2.1 [#f1]_ 2.9.0, v0.10.X, 2.0 / 2.1 [#f1]_ 2.8.0, 0.8.X-0.9.X, 2.0 / 2.1 [#f1]_ 2.7.0, 0.7.X, 2.0 / 2.1 [#f1]_ @@ -92,6 +93,44 @@ on other platforms the source package is used and a compiler is required: + MacOS: Python 3.8 - 3.12 / x86_64, arm64 + Windows: Python 3.8 - 3.12 / 32- & 64-bit +CLI +=== +littlefs-python comes bundled with a command-line tool, ``littlefs-python``, that can be used to create and extract littlefs binary images. + +.. code:: console + + $ littlefs-python --help + usage: littlefs-python [-h] [--version] {create,extract,list} ... + + Create, extract and inspect LittleFS filesystem images. Use one of the + commands listed below, the '-h' / '--help' option can be used on each command + to learn more about the usage. + + optional arguments: + -h, --help show this help message and exit + --version show program's version number and exit + + Available Commands: + {create,extract,list} + create Create LittleFS image from file/directory contents. + extract Extract LittleFS image contents to a directory. + list List LittleFS image contents. + +To create a littlefs binary image: + +.. code:: console + + # Creates a 1-megabyte "lfs.bin" containing README.rst + $ littlefs-python create README.rst lfs.bin --fs-size=1mb --block-size=4096 + + # Creates a 1-megabyte "lfs.bin" containing the contents of the examples/ folder + $ littlefs-python create examples lfs.bin --fs-size=1mb --block-size=4096 + +To extract the contents of a littlefs binary image: + +.. code:: console + + $ littlefs-python extract lfs.bin output/ --block-size=4096 Development Setup ================= diff --git a/src/littlefs/__main__.py b/src/littlefs/__main__.py index 26dc98d..65bae3e 100644 --- a/src/littlefs/__main__.py +++ b/src/littlefs/__main__.py @@ -50,7 +50,7 @@ def size_parser(size_str): def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int: - """Create LittleFS image from directory content""" + """Create LittleFS image from file/directory contents.""" # fs_size OR block_count may be populated; make them consistent. if args.block_count is None: block_count = args.fs_size // args.block_size @@ -69,9 +69,16 @@ def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int: print(f" Image: {args.destination}") source = Path(args.source).absolute() + if source.is_dir(): + sources = source.rglob("*") + root = source + else: + sources = [source] + root = source.parent + fs = _fs_from_args(args) - for path in source.rglob("*"): - rel_path = path.relative_to(source) + for path in sources: + rel_path = path.relative_to(root) if path.is_dir(): if args.verbose: print("Adding Directory:", rel_path) @@ -88,7 +95,7 @@ def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int: def _list(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int: - """List LittleFS image content""" + """List LittleFS image contents.""" fs = _fs_from_args(args, mount=False) fs.context.buffer = bytearray(args.source.read_bytes()) fs.mount() @@ -112,8 +119,8 @@ def _list(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int: return 0 -def unpack(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int: - """Unpack LittleFS image to directory""" +def extract(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int: + """Extract LittleFS image contents to a directory.""" fs = _fs_from_args(args, mount=False) fs.context.buffer = bytearray(args.source.read_bytes()) fs.mount() @@ -197,7 +204,7 @@ def add_command(handler, name="", help=""): parser_create.add_argument( "source", type=Path, - help="Source directory of files to encode into a littlefs filesystem.", + help="Source file/directory-of-files to encode into a littlefs filesystem.", ) parser_create.add_argument( "destination", @@ -224,20 +231,20 @@ def add_command(handler, name="", help=""): help="LittleFS filesystem size. Accepts byte units; e.g. 1MB and 1048576 are equivalent.", ) - parser_unpack = add_command(unpack) - parser_unpack.add_argument( + parser_extract = add_command(extract) + parser_extract.add_argument( "source", type=Path, help="Source LittleFS filesystem binary.", ) - parser_unpack.add_argument( + parser_extract.add_argument( "destination", default=Path("."), nargs="?", type=Path, help="Destination directory. Defaults to current directory.", ) - parser_unpack.add_argument( + parser_extract.add_argument( "--block-size", type=size_parser, required=True,