{"id":13505475,"url":"https://github.com/lalten/rules_appimage","last_synced_at":"2025-09-25T21:40:26.548Z","repository":{"id":38823515,"uuid":"430368975","full_name":"lalten/rules_appimage","owner":"lalten","description":"Bazel rules to create portable Linux applications by bundling a binary target and all its runfiles into a self-contained AppImage binary.","archived":false,"fork":false,"pushed_at":"2025-03-28T22:45:02.000Z","size":402,"stargazers_count":28,"open_issues_count":7,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T23:28:41.292Z","etag":null,"topics":["appimage","bazel"],"latest_commit_sha":null,"homepage":"","language":"Starlark","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lalten.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-11-21T13:06:40.000Z","updated_at":"2025-03-14T16:21:20.000Z","dependencies_parsed_at":"2023-11-20T10:36:34.416Z","dependency_job_id":"64a5c057-4b60-42c0-bc86-a0eb5ce5b7b3","html_url":"https://github.com/lalten/rules_appimage","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalten%2Frules_appimage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalten%2Frules_appimage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalten%2Frules_appimage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lalten%2Frules_appimage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lalten","download_url":"https://codeload.github.com/lalten/rules_appimage/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246262490,"owners_count":20749170,"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":["appimage","bazel"],"created_at":"2024-08-01T00:01:08.725Z","updated_at":"2025-09-25T21:40:26.539Z","avatar_url":"https://github.com/lalten.png","language":"Starlark","funding_links":[],"categories":["AppImage developer tools"],"sub_categories":["Build systems"],"readme":"# rules_appimage\n\n[![CI status](https://img.shields.io/github/actions/workflow/status/lalten/rules_appimage/ci.yaml?branch=main)](https://github.com/lalten/rules_appimage/actions)\n[![MIT License](https://img.shields.io/github/license/lalten/rules_appimage)](https://github.com/lalten/rules_appimage/blob/main/LICENSE)\n[![Awesome](https://awesome.re/badge.svg)](https://awesomebazel.com/)\n\nCreate portable Linux applications by bundling a binary target and all its runfiles into a self-contained [AppImage](https://github.com/AppImage/AppImageKit) binary.\n\nAppImages are a great match for Bazel because the runfiles structure and launcher stub (where applicable) can be packaged into an AppRun structure relatively easily.\nNo application source modifications are required.\nNo existing Bazel targets have to be modified.\n\nThe `appimage` rule has been used successfully with `py_binary`, `ruby_binary`, `sh_binary`, and `cc_binary`.\nIn fact, any _lang_\\_binary should be compatible.\n\nAppImages are executable ELF format files with a static runtime at the front and a compressed SquashFS image containing the application files at the back.\nWhen run, the runtime will use FUSE to mount the SquashFS image and run the application from there.\nAlternatively, the runtime can extract the files into a temporary directory and run the application from there.\nThere is no extra extraction or installation step.\n\nSee also [Alternatives](#alternatives) below.\n\n## Getting Started\n\n### Installation\n\nSee the [latest release notes](https://github.com/lalten/rules_appimage/releases/latest) for a snippet to add to your `MODULE.bazel` or `WORKSPACE`.\n\nrules_appimage aims to be compatible and test with the last two [Bazel LTS releases](https://bazel.build/release) but is likely to work with older versions as well.\n\n### Usage\n\nSee the [rule documentation](docs/defs.md).\n\nThere is an example workspace in [`examples/`](https://github.com/lalten/rules_appimage/blob/main/examples/README.md).\n\nTo package a binary target into an AppImage, add an `appimage` rule in a `BUILD` file and point it at the target.\n\n```py\nload(\"@rules_appimage//appimage:appimage.bzl\", \"appimage\")\n\nappimage(\n    name = \"program.appimage\",\n    binary = \":program\",\n)\n```\n\nThere is also a `appimage_test` rule that takes the same arguments but runs the appimage as a Bazel test target.\n\n## How to run the appimage artifact\n\n### Via Bazel\n\nYou can `bazel run` AppImages directly:\n\n```sh\n❯ bazel run -- //tests:appimage_py\n(...)\nHello, world!\n```\n\n```sh\n❯ bazel run -- //tests:appimage_py --name TheAssassin\n(...)\nHello, TheAssassin!\n```\n\n### Directly\n\nThe resulting AppImage file is a portable standalone executable (which is kind of the point of the whole thing!)\n\n```sh\n❯ file bazel-bin/tests/appimage_py\nbazel-bin/tests/appimage_py: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, stripped\n\n❯ bazel-bin/tests/appimage_py --name GitHub\nHello, GitHub!\n```\n\n```sh\n❯ rsync bazel-bin/tests/appimage_py my-server:. \u0026\u0026 ssh my-server ./appimage_py\nHello, world!\n```\n\n### AppImage CLI args\n\nThere are certain [AppImage CLI args](https://github.com/AppImage/AppImageKit#command-line-arguments).\nThey'll still work. Try `--appimage-help`.\n\n```sh\n❯ bazel run -- //tests:appimage_py --appimage-version\n(...)\nAppImage runtime version: https://github.com/lalten/type2-runtime/releases/tag/build-2022-10-03-c5c7b07\n```\n\n## Troubleshooting\n\n### `$PWD` is a `Read-only file system`\n\nWhen the AppImage is run, it will mount contained the SquashFS image via FUSE as read-only file system.\n\nIf this causes problems, you can:\n\n- Write to `$BUILD_WORKING_DIRECTORY` instead, which is set by Bazel when running `bazel run`, and set by `rules_appimage` when running as pure AppImage.\n- Set the `APPIMAGE_EXTRACT_AND_RUN` env var or pass the `--appimage-extract-and-run` CLI arg to extract the AppImage into a temporary directory and run it from there.\n\n### Missing `fusermount`\n\nrules_appimage builds `type-2 AppImages` using a statically-linked appimage runtime.\nThe only runtime dependency is either `fusermount` (from fuse2) or `fusermount3` (from fuse3).\nIf neither is not available, you'll get an error like this:\n\n```sh\nfuse: failed to exec fusermount3: No such file or directory\n\nCannot mount AppImage, please check your FUSE setup.\nYou might still be able to extract the contents of this AppImage\nif you run it with the --appimage-extract option.\nSee https://github.com/AppImage/AppImageKit/wiki/FUSE\nfor more information\nopen dir error: No such file or directory\n```\n\nIn this case, you can:\n\n- Install [libfuse3](https://pkgs.org/search/?q=libfuse3): `sudo apt install libfuse3`\n- Run the application with `--appimage-extract-and-run` as the first command-line argument.\n- Set the `APPIMAGE_EXTRACT_AND_RUN` environment variable.\n\nThe latter two options will cause the appimage to extract the files instead of mounting them directly.\nThis may take slightly longer and consume more disk space.\n\n### Missing runtime deps\n\nThe AppImage will only be as portable/hermetic/reproducible as the rest of your Bazel build is.\n\nExample: Without a hermetic Python toolchain your target will use the system's Python interpreter.\nIf your program needs Python \u003e=3.8 but you run the appimage on a host that uses Python 3.6 by default, you might get an error like this:\n\n```sh\n  File \"/tmp/appimage_extracted_544993ad2a5919e445b618f1fe009e53/test_py.runfiles/rules_appimage/tests/test.py\", line 10\n    assert (s := DATA_DEP.stat().st_size) == 591, f\"{DATA_DEP} has wrong size {s}\"\n              ^\nSyntaxError: invalid syntax\n```\n\nCheck \u003chttps://thundergolfer.com/bazel/python/2021/06/25/a-basic-python-bazel-toolchain/\u003e if you would like to know more.\n\n### Something isn't right about my appimage, how can I debug?\n\nAn easy way to understand what is happening inside the appimage is to run the application with the `--appimage-extract` cli arg.\nThis will extract the bundled squashfs blob into a `squashfs-root` dir in the current working directory.\n\nYou can look at those files and see exactly what's going on.\nIn fact, you can even run `squashfs-root/AppRun` and it will run exactly the same as with the packaged appimage.\nThis can be very handy when rebuilding the Bazel target is not the best option but you need to modify a file inside.\n\n## Alternatives\n\nThere are a few other good ways to get you application and all its runfiles into a single portable executable.\n\n- python_zip / par_binary / subpar: Only applicable to Python. Needs system Python to extract contained zip on startup, which can be slow for large apps. Bazel's builtin ijar zipper will segfault on very large (multiple GB) runfiles.\n- [Kickoff Launcher](https://github.com/nimbus-build/kickoff):\n  Very similar idea to appimages, but works also for Windows and macOS.\n  Will always extract runfiles, no way to mount them like appimages do with squashfuse.\n  No Bazel rules, but a CLI tool that could be used in a `genrule`.\n  Check out @alloveras's talk at BazelCon 2023!\n\n## Contributing\n\nIssue reports and pull requests are welcome.\n\nPlease test your changes:\n\n```sh\nbazel test //...\n```\n\nAnd run the [linters/formatters](.github/workflows/ci.yaml):\n\n```sh\npre-commit run --all-files\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flalten%2Frules_appimage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flalten%2Frules_appimage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flalten%2Frules_appimage/lists"}