{"id":18783996,"url":"https://github.com/u-root/mkuimage","last_synced_at":"2025-08-05T15:34:41.905Z","repository":{"id":217991803,"uuid":"745244549","full_name":"u-root/mkuimage","owner":"u-root","description":"Create small Go-based root file systems -- with support for CPIOs and (TBD) Docker images","archived":false,"fork":false,"pushed_at":"2024-02-28T02:24:53.000Z","size":183,"stargazers_count":8,"open_issues_count":3,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-06-21T18:56:29.497Z","etag":null,"topics":["go","initramfs","kernel","linux","linuxboot","system"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/u-root.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":"2024-01-18T23:21:31.000Z","updated_at":"2024-04-24T12:13:40.000Z","dependencies_parsed_at":"2024-01-19T04:31:46.775Z","dependency_job_id":"08d9c28c-98ec-4177-bd71-3d9dc9f69453","html_url":"https://github.com/u-root/mkuimage","commit_stats":null,"previous_names":["u-root/mkuimage"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-root%2Fmkuimage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-root%2Fmkuimage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-root%2Fmkuimage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-root%2Fmkuimage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/u-root","download_url":"https://codeload.github.com/u-root/mkuimage/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223588504,"owners_count":17169877,"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":["go","initramfs","kernel","linux","linuxboot","system"],"created_at":"2024-11-07T20:41:34.486Z","updated_at":"2025-04-13T12:28:29.759Z","avatar_url":"https://github.com/u-root.png","language":"Go","readme":"# uimage\n\n[![GoDoc](https://pkg.go.dev/badge/github.com/u-root/mkuimage)](https://pkg.go.dev/github.com/u-root/mkuimage)\n[![codecov](https://codecov.io/gh/u-root/mkuimage/graph/badge.svg?token=5Z9B3OyVYi)](https://codecov.io/gh/u-root/mkuimage)\n[![Slack](https://slack.osfw.dev/badge.svg)](https://slack.osfw.dev)\n[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/u-root/mkuimage/blob/main/LICENSE)\n\nuimage builds initramfs images composed of arbitrary Go commands and files.\n\nuimage optimizes for space by utilizing\n[gobusybox](https://github.com/u-root/gobusybox) to compile many arbitrary Go\ncommands into one binary.\n\nuimage can be easily used with [u-root](https://github.com/u-root/u-root),\nwhich contains many Go coreutils-like commands as well as bootloaders. However,\nuimage supports compilation of any Go command, and the use of u-root is not\nrequired.\n\n## Getting Started\n\nMake sure your Go version is \u003e= 1.21. If your Go version is lower,\n\n```shell\n$ go install golang.org/dl/go1.21.5@latest\n$ go1.21.5 download\n$ go1.21.5 version\n# Now use go1.21.5 in place of go\n```\n\nDownload and install mkuimage either via git:\n\n```shell\ngit clone https://github.com/u-root/mkuimage\ncd mkuimage/cmd/mkuimage\ngo install\n```\n\nOr install directly with go:\n\n```shell\ngo install github.com/u-root/mkuimage/cmd/mkuimage@latest\n```\n\n\u003e [!NOTE]\n\u003e The `mkuimage` command will end up in `$GOPATH/bin/mkuimage`, so you may\n\u003e need to add `$GOPATH/bin` to your `$PATH`.\n\n## Examples\n\nHere are some examples of using the `mkuimage` command to build an initramfs.\n\n```shell\ngit clone https://github.com/u-root/u-root\n```\n\nBuild gobusybox binaries of these two commands and add to initramfs:\n\n```shell\n$ cd ./u-root\n$ mkuimage ./cmds/core/{init,gosh}\n\n$ cpio -ivt \u003c /tmp/initramfs.linux_amd64.cpio\n...\n-rwxr-x---   0 root     root      4542464 Jan  1  1970 bbin/bb\nlrwxrwxrwx   0 root     root            2 Jan  1  1970 bbin/gosh -\u003e bb\nlrwxrwxrwx   0 root     root            2 Jan  1  1970 bbin/init -\u003e bb\n...\n```\n\nAdd symlinks for shell and init:\n\n```shell\n$ mkuimage -initcmd=init -defaultsh=gosh ./cmds/core/{init,gosh}\n\n$ cpio -ivt \u003c /tmp/initramfs.linux_amd64.cpio\n...\nlrwxrwxrwx   0 root     root           12 Jan  1  1970 bin/defaultsh -\u003e ../bbin/gosh\nlrwxrwxrwx   0 root     root           12 Jan  1  1970 bin/sh -\u003e ../bbin/gosh\n...\nlrwxrwxrwx   0 root     root            9 Jan  1  1970 init -\u003e bbin/init\n...\n```\n\n### Builds with globs and exclusion\n\nBuild everything from core without ls and losetup:\n\n```shell\n$ mkuimage ./cmds/core/* -./cmds/core/{ls,losetup}\n```\n\n### Multi-module workspace builds\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e `mkuimage` works when `go build` and `go list` work as well.\n\nThere are 2 ways to build multi-module command images using standard Go tooling.\n\n```shell\n$ mkdir workspace\n$ cd workspace\n$ git clone https://github.com/u-root/u-root\n$ git clone https://github.com/u-root/cpu\n\n$ go work init ./u-root\n$ go work use ./cpu\n\n$ mkuimage ./u-root/cmds/core/{init,gosh} ./cpu/cmds/cpud\n\n$ cpio -ivt \u003c /tmp/initramfs.linux_amd64.cpio\n...\n-rwxr-x---   0 root     root      6365184 Jan  1  1970 bbin/bb\nlrwxrwxrwx   0 root     root            2 Jan  1  1970 bbin/cpud -\u003e bb\nlrwxrwxrwx   0 root     root            2 Jan  1  1970 bbin/gosh -\u003e bb\nlrwxrwxrwx   0 root     root            2 Jan  1  1970 bbin/init -\u003e bb\n...\n\n# Works for offline vendored builds as well.\n$ go work vendor # Go 1.22 feature.\n\n$ mkuimage ./u-root/cmds/core/{init,gosh} ./cpu/cmds/cpud\n```\n\n`GBB_PATH` is a place that mkuimage will look for commands. Each colon-separated\n`GBB_PATH` element is concatenated with patterns from the command-line and\nchecked for existence. For example:\n\n```shell\nGBB_PATH=$(pwd)/u-root:$(pwd)/cpu mkuimage \\\n    cmds/core/{init,gosh} \\\n    cmds/cpud\n\n# Matches\n#   ./u-root/cmds/core/{init,gosh}\n#   ./cpu/cmds/cpud\n```\n\nTo ease usability, the `goanywhere` tool can create one Go workspaces the fly.\nThis works **only with local file system paths**:\n\n```shell\n$ go install github.com/u-root/gobusybox/src/cmd/goanywhere@latest\n\n$ goanywhere ./u-root/cmds/core/{init,gosh} ./cpu/cmds/cpud -- go build -o $(pwd)\n$ goanywhere ./u-root/cmds/core/{init,gosh} ./cpu/cmds/cpud -- mkuimage\n```\n\n`goanywhere` creates a workspace in a temporary directory with the given\nmodules, and then execs `u-root` in the workspace passing along the command\nnames.\n\n`goanywhere` supports `GBB_PATH`, exclusions, globs, and curly brace expansions\nas well.\n\n\u003e [!CAUTION]\n\u003e\n\u003e While workspaces are good for local compilation, they are not meant to be\n\u003e checked in to version control systems. See below for the recommended way.\n\n### Multi-module go.mod builds\n\nYou may also create a go.mod with the commands you intend to compile.\n\nTo depend on commands outside of ones own repository, the easiest way to depend\non Go commands is the following:\n\n```sh\nmkdir mydistro\ncd mydistro\ngo mod init mydistro\n```\n\nCreate a file with some unused build tag like this to create dependencies on\ncommands:\n\n```go\n//go:build tools\n\npackage something\n\nimport (\n        _ \"github.com/u-root/u-root/cmds/core/ip\"\n        _ \"github.com/u-root/u-root/cmds/core/init\"\n        _ \"github.com/hugelgupf/p9/cmd/p9ufs\"\n)\n```\n\nYou can generate this file for your repo with the `gencmddeps` tool from\ngobusybox:\n\n```\ngo install github.com/u-root/gobusybox/src/cmd/gencmddeps@latest\n\ngencmddeps -o deps.go -t tools -p something \\\n    github.com/u-root/u-root/cmds/core/{ip,init} \\\n    github.com/hugelgupf/p9/cmd/p9ufs\n```\n\nThe unused build tag keeps it from being compiled, but its existence forces `go\nmod tidy` to add these dependencies to `go.mod`:\n\n```sh\ngo mod tidy\n\nmkuimage \\\n  github.com/u-root/u-root/cmds/core/ip \\\n  github.com/u-root/u-root/cmds/core/init \\\n  github.com/hugelgupf/p9/cmd/p9ufs\n\n# Works for offline vendored builds as well.\ngo mod vendor\n\nmkuimage \\\n  github.com/u-root/u-root/cmds/core/ip \\\n  github.com/u-root/u-root/cmds/core/init \\\n  github.com/hugelgupf/p9/cmd/p9ufs\n```\n\n## Extra Files\n\nYou may also include additional files in the initramfs using the `-files` flag.\n\nIf you add binaries with `-files` are listed, their ldd dependencies will be\nincluded as well.\n\n```shell\n$ mkuimage -files /bin/bash\n\n$ cpio -ivt \u003c /tmp/initramfs.linux_amd64.cpio\n...\n-rwxr-xr-x   0 root     root      1277936 Jan  1  1970 bin/bash\n...\ndrwxr-xr-x   0 root     root            0 Jan  1  1970 lib/x86_64-linux-gnu\n-rwxr-xr-x   0 root     root       210792 Jan  1  1970 lib/x86_64-linux-gnu/ld-linux-x86-64.so.2\n-rwxr-xr-x   0 root     root      1926256 Jan  1  1970 lib/x86_64-linux-gnu/libc.so.6\nlrwxrwxrwx   0 root     root           15 Jan  1  1970 lib/x86_64-linux-gnu/libtinfo.so.6 -\u003e libtinfo.so.6.4\n-rw-r--r--   0 root     root       216368 Jan  1  1970 lib/x86_64-linux-gnu/libtinfo.so.6.4\ndrwxr-xr-x   0 root     root            0 Jan  1  1970 lib64\nlrwxrwxrwx   0 root     root           42 Jan  1  1970 lib64/ld-linux-x86-64.so.2 -\u003e /lib/x86_64-linux-gnu/ld-linux-x86-64.so.2\n...\n```\n\nYou can determine placement with colons:\n\n```shell\n$ mkuimage -files \"/bin/bash:sbin/sh\"\n\n$ cpio -ivt \u003c /tmp/initramfs.linux_amd64.cpio\n...\n-rwxr-xr-x   0 root     root      1277936 Jan  1  1970 sbin/sh\n...\n```\n\nFor example on Debian, if you want to add two kernel modules for testing,\nexecuting your currently booted kernel:\n\n```shell\n$ mkuimage -files \"$HOME/hello.ko:etc/hello.ko\" -files \"$HOME/hello2.ko:etc/hello2.ko\" ./u-root/cmds/core/*\n$ qemu-system-x86_64 -kernel /boot/vmlinuz-$(uname -r) -initrd /tmp/initramfs.linux_amd64.cpio\n```\n\n## AMD64 Architecture Level\n\nBefore building for AMD64, verify that the command\n\n```shell\ngo env GOAMD64\n```\n\nprints `v1`. A [`GOAMD64` setting](https://go.dev/wiki/MinimumRequirements#amd64)\nof any higher version may produce such binaries that don't execute on old AMD64\nprocessors (including the default CPU model of QEMU).\n\n`GOAMD64` can be reset to `v1` with one of the following methods:\n\n*   through the `GOAMD64` environment variable:\n\n    ```shell\n    export GOAMD64=v1\n    ```\n\n*   through `go env` (only takes effect if the `GOAMD64` environment variable\n    is not set):\n\n    ```shell\n    go env -w GOAMD64=v1\n    ```\n\n## Cross Compilation (targeting different architectures and OSes)\n\nJust like standard Go tooling, cross compilation is easy and supported.\n\nTo cross compile for an ARM, on Linux:\n\n```shell\nGOARCH=arm mkuimage ./u-root/cmds/core/*\n```\n\nIf you are on OS X, and wish to build for Linux on AMD64:\n\n```shell\nGOOS=linux GOARCH=amd64 ./u-root/cmds/core/*\n```\n\n## Testing in QEMU\n\nA good way to test the initramfs generated by u-root is with qemu:\n\n```shell\nqemu-system-x86_64 -nographic -kernel path/to/kernel -initrd /tmp/initramfs.linux_amd64.cpio\n```\n\nNote that you do not have to build a special kernel on your own, it is\nsufficient to use an existing one. Usually you can find one in `/boot`.\n\nIf you don't have a kernel handy, you can also get the one we use for VM testing:\n\n```shell\ngo install github.com/hugelgupf/vmtest/tools/runvmtest@latest\n\nrunvmtest -- bash -c \"cp \\$VMTEST_KERNEL ./kernel\"\n```\n\nIt may not have all features you require, however.\n\nTo automate testing, you may use the same\n[vmtest](https://github.com/hugelgupf/vmtest) framework that we use as well. It\nhas native uimage support.\n\n## Build Modes\n\nmkuimage can create an initramfs in two different modes, specified by `-build`:\n\n*   `bb` mode: One busybox-like binary comprising all the Go tools you ask to\n    include.\n    See [the gobusybox README for how it works](https://github.com/u-root/gobusybox).\n    In this mode, mkuimage copies and rewrites the source of the tools you asked\n    to include to be able to compile everything into one busybox-like binary.\n\n*   `binary` mode: each specified binary is compiled separately and all binaries\n    are added to the initramfs.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu-root%2Fmkuimage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fu-root%2Fmkuimage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu-root%2Fmkuimage/lists"}