docs: give the clone command and size for packs

This commit is contained in:
Abdessamad Derraz committed 2026-11-06 14:47:47 +01:00
1 parent 7657d4aa02
commit 747d40e988
4 files changed
+47 -3

No files matched your search

+1 -1
View File
@@ -124,7 +124,7 @@ Checked by is the test your platform runs on its own, replicated here from its s
## Build your own pack ## Build your own pack
Clone the repo and generate packs for any platform, emulator, or system: Packs are built from a clone, and the clone carries the collection: its checkout alone is over 7.7 GB. `git clone --depth 1 https://github.com/Abdess/retrobios.git` leaves the history out. Files kept as release assets are downloaded when a pack needs them. Then generate packs for any platform, emulator, or system:
```bash ```bash
# The pack of a platform, as released # The pack of a platform, as released
+25 -1
View File
@@ -40,6 +40,7 @@ from nativemode import check_label
import release_record import release_record
from siteguides import install_command from siteguides import install_command
from validate_pr import LARGE_FILE_ISSUE_URL from validate_pr import LARGE_FILE_ISSUE_URL
from largefiles import load_registered_paths
from verify import verify_platform from verify import verify_platform
@@ -447,6 +448,29 @@ REPO = "Abdess/retrobios"
UPLOAD_URL = f"https://github.com/{REPO}/upload/main/bios" UPLOAD_URL = f"https://github.com/{REPO}/upload/main/bios"
def clone_line(db: dict) -> str:
"""How to get the clone the commands below run in, and its size.
Said bare, "clone the repo" started a multi-gigabyte transfer for a user
after a 20 MB --required-only pack. The size counts the collection files
the repository commits, a floor: release assets are fetched only when a
pack needs them.
"""
assets = set(load_registered_paths())
committed = sum(
entry.get("size", 0) for entry in db.get("files", {}).values()
if entry.get("path") not in assets
)
return (
"Packs are built from a clone, and the clone carries the collection:"
f" its checkout alone is over {format_size(committed)}."
f" `git clone --depth 1 https://github.com/{REPO}.git` leaves the"
" history out. Files kept as release assets are downloaded when a"
" pack needs them. Then generate packs for any platform, emulator,"
" or system:"
)
def _existing_contributor_block(readme_path: str = "README.md") -> list[str]: def _existing_contributor_block(readme_path: str = "README.md") -> list[str]:
"""The contributors already published, read back from the file. """The contributors already published, read back from the file.
@@ -767,7 +791,7 @@ def generate_readme(db: dict, platforms_dir: str, db_path: str = "database.json"
"", "",
"## Build your own pack", "## Build your own pack",
"", "",
"Clone the repo and generate packs for any platform, emulator, or system:", clone_line(db),
"", "",
"```bash", "```bash",
"# The pack of a platform, as released", "# The pack of a platform, as released",
+19
View File
@@ -2031,3 +2031,22 @@ class RegionFreeRuleNamesWhereItDoesNotHold(unittest.TestCase):
if drops: if drops:
with self.subTest(platform=platform, file=name): with self.subTest(platform=platform, file=name):
self.assertRegex(bullet, rf"(?i)\b{re.escape(platform)}\b") self.assertRegex(bullet, rf"(?i)\b{re.escape(platform)}\b")
class BuildYourOwnPackSaysWhatTheCloneCosts(unittest.TestCase):
"""The README sent a user after a minimal pack to "Clone the repo", with no
command and no size, and the clone runs to several gigabytes."""
def test_readme_gives_the_clone_command_and_its_size(self):
import generate_readme
db = json.loads((ROOT / "database.json").read_text(encoding="utf-8"))
line = generate_readme.clone_line(db)
self.assertIn("git clone --depth 1", line)
self.assertRegex(line, r"over \d+(\.\d)? GB")
section = _section((ROOT / "README.md").read_text(encoding="utf-8"),
"Build your own pack")
self.assertIn("git clone --depth 1", section)
def test_advanced_usage_names_the_shallow_clone(self):
self.assertIn("--depth 1", _page("advanced-usage.md").split("## Custom packs")[0])
+2 -1
View File
@@ -19,7 +19,8 @@ boot, with no message saying why. It is not a guarantee either: source
profiles can document files nobody has dumped or that only the user can profiles can document files nobody has dumped or that only the user can
provide, all of them visible in the [gap analysis](../gaps.md). provide, all of them visible in the [gap analysis](../gaps.md).
From a clone of the repository, `python scripts/generate_pack.py --platform A clone carries the whole collection, several gigabytes, and `git clone
--depth 1` leaves its history out. From that clone, `python scripts/generate_pack.py --platform
retroarch --region us` builds a narrower pack, `--required-only` the bare retroarch --region us` builds a narrower pack, `--required-only` the bare
minimum each core needs to start, and `--no-game-data` keeps the firmware and minimum each core needs to start, and `--no-game-data` keeps the firmware and
leaves out the files a game reads. `--help` lists every way to build your own, leaves out the files a game reads. `--help` lists every way to build your own,