{"id":50440828,"url":"https://github.com/nicholaswilde/sys-fetch","last_synced_at":"2026-05-31T19:01:57.553Z","repository":{"id":340641588,"uuid":"1166963544","full_name":"nicholaswilde/sys-fetch","owner":"nicholaswilde","description":"Learning GNU assembly by building a lightweight, bare-metal alternative to system fetchers","archived":false,"fork":false,"pushed_at":"2026-03-05T12:26:45.000Z","size":153,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T05:14:50.875Z","etag":null,"topics":["amd64","arm64","assembly","gnu-assembler","learning-by-doing"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicholaswilde.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"nicholaswilde"}},"created_at":"2026-02-25T19:56:48.000Z","updated_at":"2026-03-02T15:02:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nicholaswilde/sys-fetch","commit_stats":null,"previous_names":["nicholaswilde/zero-sys-fetch","nicholaswilde/sys-fetch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nicholaswilde/sys-fetch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicholaswilde%2Fsys-fetch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicholaswilde%2Fsys-fetch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicholaswilde%2Fsys-fetch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicholaswilde%2Fsys-fetch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicholaswilde","download_url":"https://codeload.github.com/nicholaswilde/sys-fetch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicholaswilde%2Fsys-fetch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33744447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amd64","arm64","assembly","gnu-assembler","learning-by-doing"],"created_at":"2026-05-31T19:01:57.459Z","updated_at":"2026-05-31T19:01:57.539Z","avatar_url":"https://github.com/nicholaswilde.png","language":"Assembly","funding_links":["https://github.com/sponsors/nicholaswilde"],"categories":[],"sub_categories":[],"readme":"# :rocket: sys-fetch :zap:\n\n[![task](https://img.shields.io/badge/Task-Enabled-brightgreen?style=for-the-badge\u0026logo=task\u0026logoColor=white)](https://taskfile.dev/#/)\n\n**`sys-fetch`** is a project dedicated to learning assembly language—specifically the **GNU Assembler (GAS)**—by building a lightweight, bare-metal alternative to system fetchers. Bypassing standard libraries entirely, this project interacts directly with the Linux kernel using native system calls to extract and display real-time system metrics. \n\nBy reading directly from virtual files like `/proc/loadavg` and parsing the data in pure [GNU Assembler (GAS)](https://sourceware.org/binutils/docs/as/), this tool provides a hyper-optimized way to monitor server health without the overhead of heavy scripts or subshells.\n\n## :sparkles: Key Features\n* **Multi-Architecture Support:** Written strictly in assembly for both `x86_64` (amd64) and `aarch64` (arm64) architectures.\n* **Pure Assembly:** Gives absolute control over memory and CPU registers using the GNU Assembler.\n* **Zero Dependencies:** Runs natively without the C standard library (libc) or any external package requirements.\n* **Direct Kernel I/O:** Utilizes native Linux system calls (via `syscall` on x86_64 and `svc` on aarch64) for all file operations and terminal output.\n* **Low Overhead:** Executes instantly, making it a perfectly lightweight monitoring tool for headless servers.\n\n## :package: Installation\n\nThis project requires the **GNU Assembler (as)** and standard build tools. \n\n### amd64 (x86_64)\nOn Debian/Ubuntu:\n```bash\nsudo apt update\nsudo apt install binutils build-essential\n```\n\n### arm64 (aarch64)\nFor cross-compilation on an amd64 host:\n```bash\nsudo apt update\nsudo apt install binutils-aarch64-linux-gnu build-essential\n```\n\nIf you have [Task](https://taskfile.dev/) installed, you can also run:\n```bash\ntask deps:amd64  # or task deps:arm64\n```\n\n## :hammer_and_wrench: Development\n\n### Using Task (Recommended)\n\nTo build and run the tool for your architecture:\n\n```bash\ntask build-run:amd64\n# or\ntask build-run:arm64\n```\n\n### Manual Build\n\n#### amd64 (x86_64)\n1. **Assemble:** `as src/x86_64/main.S -o src/x86_64/main.o`\n2. **Link:** `ld src/x86_64/main.o -o bin/x86_64/sys-fetch`\n\n#### arm64 (aarch64)\n1. **Assemble:** `aarch64-linux-gnu-as src/aarch64/main.S -o src/aarch64/main.o`\n2. **Link:** `aarch64-linux-gnu-ld src/aarch64/main.o -o bin/aarch64/sys-fetch`\n\n### Debugging (amd64)\n\nTo build with debug symbols and start a [GDB](https://www.sourceware.org/gdb/) session:\n\n```bash\ntask dbg:amd64\n```\n\nOnce inside the GDB session, you can use the following commands to step through the program:\n\n```gdb\n(gdb) break _start   # Set a breakpoint at the entry point\n(gdb) run            # Start execution\n(gdb) stepi          # Step one instruction at a time\n(gdb) \u003center\u003e        # Repeat the previous command (stepi)\n(gdb) info registers # Show all register values\n(gdb) print $rax     # Print the value of a specific register (e.g., rax)\n(gdb) x/s \u0026filepath  # Examine the filepath as a string\n(gdb) x/16xb \u0026filepath # Examine 16 bytes of memory at filepath in hex\n(gdb) x/64xb \u0026buffer # Examine 64 bytes of the buffer in hex\n(gdb) x/s \u0026buffer    # Examine the buffer as a string\n```\n\n### Inspection\n\nTo disassemble and inspect the machine code, you can use `objdump`:\n\n```bash\n# amd64\ntask inspect:bin:amd64\n# arm64\ntask inspect:bin:arm64\n```\n\n### System Call Tracing\n\nTo trace the system calls made by the binary in real-time, use `strace`:\n\n```bash\ntask strace:amd64\n# or (on arm64 host)\ntask strace:arm64\n```\n\n## :books: Learning \u0026 Reference\n\nTo support the transition from C to assembly, this project includes a reference snippet from the [Rosetta Stone](https://github.com/lowleveltv/rosetta-stone) project.\n\n*   **Reference File:** `ref/rosetta.c` contains common C constructs (loops, function calls, syscalls).\n*   **Build Task:** Run `task rosetta-amd64` to compile the reference file and generate an assembly listing (`ref/rosetta-amd64.s`).\n\n## :computer: System Call Reference\n\n### Register Usage\n\n| Role | x86_64 | aarch64 |\n| :--- | :--- | :--- |\n| **Syscall Number** | `rax` | `x8` |\n| **Argument 1** | `rdi` | `x0` |\n| **Argument 2** | `rsi` | `x1` |\n| **Argument 3** | `rdx` | `x2` |\n| **Argument 4** | `r10` | `x3` |\n| **Argument 5** | `r8` | `x4` |\n| **Argument 6** | `r9` | `x5` |\n| **Return Value** | `rax` | `x0` |\n\n### Common Syscalls\n\n| Name | x86_64 (%rax) | aarch64 (%x8) | Description |\n| :--- | :--- | :--- | :--- |\n| `read` | **0** | **63** | Read data from a file descriptor. |\n| `write` | **1** | **64** | Write data to a file descriptor. |\n| `open` | **2** | **-** | Open a file (x86_64). |\n| `openat` | **257** | **56** | Open a file relative to dir FD (modern standard). |\n| `close` | **3** | **57** | Close an open file descriptor. |\n| `exit` | **60** | **93** | Terminate the calling process. |\n\n## :file_folder: GAS Section Reference\n\n*   **`.text`**: Contains the actual executable code.\n*   **`.data`**: Used for declaring initialized data or constants.\n*   **`.bss`**: Used for declaring uninitialized variables (Block Started by Symbol).\n\n## :memo: GAS Data Declaration Directives\n\n| Directive | Purpose | Standard Size |\n| :--- | :--- | :--- |\n| **`.byte`** | Define Byte | 1 byte |\n| **`.short`** | Define Short (Word) | 2 bytes |\n| **`.long`** | Define Long (Doubleword) | 4 bytes |\n| **`.quad`** | Define Quadword | 8 bytes |\n| **`.octa`** | Define Octoword | 16 bytes |\n\n## :balance_scale: License\n\n​[​Apache License 2.0](./LICENSE)\n\n---\n\n## :pencil: Author\n\nThis project was started in 2026 by [Nicholas Wilde](https://github.com/nicholaswilde/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicholaswilde%2Fsys-fetch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicholaswilde%2Fsys-fetch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicholaswilde%2Fsys-fetch/lists"}