{"id":22801696,"url":"https://github.com/pojntfx/hydrun","last_synced_at":"2025-04-19T18:36:35.946Z","repository":{"id":47332808,"uuid":"347344898","full_name":"pojntfx/hydrun","owner":"pojntfx","description":"Execute a command for the current directory on multiple architectures and operating systems.","archived":false,"fork":false,"pushed_at":"2024-07-16T16:58:43.000Z","size":54,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-07-16T20:49:19.698Z","etag":null,"topics":["binfmt","buildx","ci","cross-compilation","docker","github-actions","go","qemu-user-static"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pojntfx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-13T10:54:35.000Z","updated_at":"2024-07-16T16:55:17.000Z","dependencies_parsed_at":"2024-06-19T17:41:21.597Z","dependency_job_id":"1a68db12-96be-41a6-899d-dae1d7130d16","html_url":"https://github.com/pojntfx/hydrun","commit_stats":{"total_commits":38,"total_committers":1,"mean_commits":38.0,"dds":0.0,"last_synced_commit":"3c62f7743fac266f94431f24e4110f59c8089b03"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fhydrun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fhydrun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fhydrun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fhydrun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pojntfx","download_url":"https://codeload.github.com/pojntfx/hydrun/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229352375,"owners_count":18059493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["binfmt","buildx","ci","cross-compilation","docker","github-actions","go","qemu-user-static"],"created_at":"2024-12-12T08:12:28.204Z","updated_at":"2024-12-12T08:12:28.805Z","avatar_url":"https://github.com/pojntfx.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hydrun (\"Hydra Run\")\n\nExecute a command for the current directory on multiple architectures and operating systems.\n\n[![hydrun CI](https://github.com/pojntfx/hydrun/actions/workflows/hydrun.yaml/badge.svg)](https://github.com/pojntfx/hydrun/actions/workflows/hydrun.yaml)\n[![Matrix](https://img.shields.io/matrix/hydrun:matrix.org)](https://matrix.to/#/#hydrun:matrix.org?via=matrix.org)\n\n## Overview\n\nHydra Run, or hydrun, is a thin (\u003c200 SLOC) layer atop [Docker buildx](https://github.com/docker/buildx) and [qemu-user-static](https://github.com/multiarch/qemu-user-static). It allows one to easily execute a command on different processor architectures and operating systems than the host.\n\nIt can, for example, be used for ...\n\n- **Cross-compilation that \"just works\"**, without having to set up a cross-compiler (at the cost of longer build times)\n- **Multi-architecture testing**\n- **Building arm64 binaries on GitHub actions**, which doesn't support arm64 runners or Linux distros other than Ubuntu\n- Quickly getting an **interactive arm64 shell for the current directory on an amd64 host** or the other way round\n- Running binaries built against **glibc on an Alpine Linux host**\n- Making **CI release builds locally reproducable and testable**, without having to `git push` and wait\n\n## Installation\n\nStatic binaries are also available on [GitHub releases](https://github.com/pojntfx/hydrun/releases).\n\nOn Linux, you can install them like so:\n\n```shell\n$ curl -L -o /tmp/hydrun \"https://github.com/pojntfx/hydrun/releases/latest/download/hydrun.linux-$(uname -m)\"\n$ sudo install /tmp/hydrun /usr/local/bin\n```\n\nOn macOS, you can use the following:\n\n```shell\n$ curl -L -o /tmp/hydrun \"https://github.com/pojntfx/hydrun/releases/latest/download/hydrun.darwin-$(uname -m)\"\n$ sudo install /tmp/hydrun /usr/local/bin\n```\n\nOn Windows, the following should work (using PowerShell as administrator):\n\n```shell\nPS\u003e Invoke-WebRequest https://github.com/pojntfx/hydrun/releases/latest/download/hydrun.windows-x86_64.exe -OutFile \\Windows\\System32\\hydrun.exe\n```\n\nYou can find binaries for more operating systems and architectures on [GitHub releases](https://github.com/pojntfx/hydrun/releases).\n\n## Tutorial\n\nBefore continuing, please ensure that you have both [Docker buildx](https://github.com/docker/buildx) and [qemu-user-static](https://github.com/multiarch/qemu-user-static) installed on the host.\n\n### To Get an Interactive Shell\n\nAs described in the [Reference](#Reference), you can get an interactive shell by using the `-i` flag. The `-a` parameter corresponds to an [architecture](https://www.docker.com/blog/multi-platform-docker-builds/) such as `amd64`, `arm64` or `ppc64le`; the `-o` flag corresponds to a [Docker image](https://hub.docker.com/search?q=\u0026type=image) such as `debian`, `alpine` or `fedora`. To for example run arm64 Debian on an amd64 host, you can do the following:\n\n```shell\n$ uname -a\nLinux dev-tmp 4.19.0-10-cloud-amd64 #1 SMP Debian 4.19.132-1 (2020-07-24) x86_64 GNU/Linux\n$ hydrun -a arm64 -o debian -i \"bash\"\nroot@81647bd6aa02:/data# uname -a\nLinux 81647bd6aa02 4.19.0-10-cloud-amd64 #1 SMP Debian 4.19.132-1 (2020-07-24) aarch64 GNU/Linux\nroot@81647bd6aa02:/data# ldd $(which ls)\n        libselinux.so.1 =\u003e /lib/aarch64-linux-gnu/libselinux.so.1 (0x0000005501868000)\n        libc.so.6 =\u003e /lib/aarch64-linux-gnu/libc.so.6 (0x000000550189e000)\n        /lib/ld-linux-aarch64.so.1 (0x0000005500000000)\n        libpcre.so.3 =\u003e /lib/aarch64-linux-gnu/libpcre.so.3 (0x0000005501a10000)\n        libdl.so.2 =\u003e /lib/aarch64-linux-gnu/libdl.so.2 (0x0000005501a83000)\n        libpthread.so.0 =\u003e /lib/aarch64-linux-gnu/libpthread.so.0 (0x0000005501a97000)\n```\n\n### As an Alternative to Cross-Compilation\n\nIt is very easy to use hydrun to get binaries for many platforms, without having to set up cross-compilation. Consider the following C hello world program:\n\n```c\n/* main.c */\n#include \u003cstdio.h\u003e\n\nint main()\n{\n  printf(\"Hello, world!\\n\");\n\n  return 0;\n}\n```\n\nUsing hydrun, we can now compile it for multiple architectures:\n\n```shell\n$ ls\nls\nmain.c\n$ hydrun -a amd64,arm64 -o gcc 'gcc -static -o hello-world.linux-$(uname -m) main.c'\n$ ls\nhello-world.linux-aarch64  hello-world.linux-x86_64  main.c\n$ file *\nhello-world.linux-aarch64: ELF 64-bit LSB executable, ARM aarch64, version 1 (GNU/Linux), statically linked, for GNU/Linux 3.7.0, with debug_info, not stripped\nhello-world.linux-x86_64:  ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked, for GNU/Linux 3.2.0, with debug_info, not stripped\nmain.c:                    C source, ASCII text\n```\n\nIt is also possible to run/test the compiled binaries with it:\n\n```shell\n$ ls\nhello-world.linux-aarch64  hello-world.linux-x86_64  main.c\n$ hydrun -i -a arm64 \"./hello-world.linux-aarch64\"\nHello, world!\n$ hydrun -i -a amd64 \"./hello-world.linux-x86_64\"\nHello, world!\n```\n\nWhen building larger projects or requiring dependencies, it is recommended to put the commands used into a shell script, conventionally named the `Hydrunfile`:\n\n```\n$ cat \u003c\u003cEOT\u003eHydrunfile\n#!/bin/bash\napt update\napt install -y build-essentials\n\ngcc -static -o hello-world.linux-$(uname -m) main.c\nEOT\n$ chmod +x ./Hydrunfile\n```\n\nYou can now easily build like so:\n\n```shell\n$ hydrun -a amd64,arm64 \"./Hydrunfile\"\n$ ls\nhello-world.linux-aarch64  hello-world.linux-x86_64  Hydrunfile  main.c\n```\n\nMost of the time you'll probably want to use the `Hydrunfile` to install toolchains/dependencies and then call your `Makefile`, the Go compiler, `cargo` etc.\n\nFor an example, check out [pojntfx/panrpc](https://github.com/pojntfx/panrpc).\n\n### Usage in GitHub Actions\n\nIt is also possible to use hydrun to build multi-architecture binaries in a CI/CD system such as GitHub actions. Continuing with the C example from above, we could automatically build and release amd64 and arm64 binaries to GitHub releases using GitHub actions with the following workflow:\n\n```yaml\nname: hydrun CI\n\non:\n  push:\n  pull_request:\n\njobs:\n  build-linux:\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v2\n      - name: Set up QEMU\n        uses: docker/setup-qemu-action@v1\n      - name: Set up Docker Buildx\n        uses: docker/setup-buildx-action@v1\n      - name: Set up hydrun\n        run: |\n          curl -L -o /tmp/hydrun https://github.com/pojntfx/hydrun/releases/latest/download/hydrun.linux-$(uname -m)\n          sudo install /tmp/hydrun /usr/local/bin\n      - name: Build with hydrun\n        run: hydrun -a amd64,arm64 ./Hydrunfile\n      - name: Publish to GitHub releases\n        if: ${{ github.ref == 'refs/heads/main' }}\n        uses: marvinpinto/action-automatic-releases@latest\n        with:\n          repo_token: \"${{ secrets.GITHUB_TOKEN }}\"\n          automatic_release_tag: \"latest\"\n          prerelease: false\n          files: |\n            *.linux*\n```\n\nFor an example, check out [pojntfx/panrpc](https://github.com/pojntfx/panrpc).\n\n## Reference\n\n```shell\n$ hydrun --help\nExecute a command for the current directory on multiple architectures and operating systems.\n\nSee https://github.com/pojntfx/hydrun for more information.\n\nUsage: hydrun [OPTION...] \"\u003cCOMMAND...\u003e\"\n  -a, --arch string         Comma-separated list of architectures to run on (default \"amd64\")\n  -c, --context string      Directory to use in the container (default is the current working directory)\n  -e, --extra-args string   Extra arguments to pass to the Docker command\n  -i, --it                  Attach stdin and setup a TTY\n  -j, --jobs int            Maximum amount of parallel jobs (default 1)\n  -m, --mount               Enable mounting the directory specified with the context flag (default true)\n  -o, --os string           Comma-separated list of operating systems (Docker images) to run on (default \"debian\")\n  -p, --pull                Always pull the specified tags of the operating systems (Docker images)\n  -q, --quiet               Disable logging executed commands\n  -r, --readyOnly           Mount the directory specified as read-only\n```\n\n## Contributing\n\nTo contribute, please use the [GitHub flow](https://guides.github.com/introduction/flow/) and follow our [Code of Conduct](./CODE_OF_CONDUCT.md).\n\nTo build hydrun locally, run:\n\n```shell\n$ git clone https://github.com/pojntfx/hydrun.git\n$ cd hydrun\n$ go run main.go --help\n```\n\nHave any questions or need help? Chat with us [on Matrix](https://matrix.to/#/#hydrun:matrix.org?via=matrix.org)!\n\n## Related Projects\n\nIf you want to quickly cross-compile your Go app, check out [bagop](https://github.com/pojntfx/bagop)!\n\n## License\n\nhydrun (c) 2024 Felicitas Pojtinger and contributors\n\nSPDX-License-Identifier: AGPL-3.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpojntfx%2Fhydrun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpojntfx%2Fhydrun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpojntfx%2Fhydrun/lists"}