{"id":13436582,"url":"https://github.com/icculus/fatelf","last_synced_at":"2025-04-13T19:09:28.795Z","repository":{"id":106919502,"uuid":"381151317","full_name":"icculus/fatelf","owner":"icculus","description":"Universal binaries for Linux.","archived":false,"fork":false,"pushed_at":"2023-11-04T03:37:50.000Z","size":114,"stargazers_count":121,"open_issues_count":3,"forks_count":6,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-27T09:46:19.545Z","etag":null,"topics":["elf","universal-binary"],"latest_commit_sha":null,"homepage":"https://icculus.org/fatelf/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/icculus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":["icculus"],"patreon":"icculus"}},"created_at":"2021-06-28T20:17:12.000Z","updated_at":"2025-02-17T03:01:31.000Z","dependencies_parsed_at":"2023-11-04T05:30:44.358Z","dependency_job_id":null,"html_url":"https://github.com/icculus/fatelf","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icculus%2Ffatelf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icculus%2Ffatelf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icculus%2Ffatelf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icculus%2Ffatelf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icculus","download_url":"https://codeload.github.com/icculus/fatelf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248766734,"owners_count":21158301,"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":["elf","universal-binary"],"created_at":"2024-07-31T03:00:50.420Z","updated_at":"2025-04-13T19:09:28.766Z","avatar_url":"https://github.com/icculus.png","language":"C","funding_links":["https://github.com/sponsors/icculus","https://patreon.com/icculus"],"categories":["C","others"],"sub_categories":[],"readme":"# FatELF\n\nThe latest information about FatELF can be found at https://icculus.org/fatelf/\n\n## What is this?\n\nFatELF is a simple file format that allows you to package several ELF binaries\nin one file. The most obvious use for this is supplying a single executable\nthat will run on different processors; a common scenario would be to pack\nboth an amd64 and an x86 binary into one file, and let the operating system\nchoose the correct one at runtime. FatELF can be used with both executable\nfiles and shared libraries.\n\nAt this time, this documentation assumes a GNU/Linux system, but FatELF could\ntheoretically be of use to most modern Unix systems that use ELF binaries.\nFatELF is of no use to Windows, as its EXE files are not ELF format. Mac OS X,\nwhile it has a Unix heritage, does not use ELF either, but their Mach-O\nformat provides something similar to FatELF (Apple refers to this technology\nas \"Universal Binaries.\" It is incompatible with FatELF.) Systems like\nFreeBSD and OpenSolaris use ELF binaries, and could theoretically be made\nto support FatELF as well.\n\n\n## Source code licensing information:\n\nPatches are contributed under their original licenses. For example, the Linux\nkernel patch is GPLv2, the binutils patch is GPLv3, and the glibc patch is\nLGPL.\n\nThe command line utilities (fatelf-glue, etc) are public domain.\n\n\n## Using FatELF as an end-user:\n\nIf you're an end-user that just wants to run a FatELF binary that someone\ngave you, you have two options. If you want everything to run smoothly, so\nyou run the FatELF files like any other binary, you need to patch your\nsystem if it doesn't already have FatELF support. It's possible your Linux\ndistribution already did this for you. If not, GNU/Linux systems will need\nthe patches for the Linux kernel and glibc. Once you have these in place,\nif you just want to run FatELF binaries, you're done. Have fun!\n\nIf you want file(1) to recognize FatELF binaries instead of calling them\n\"data\", you'll want that patch, too.\n\nIf you can't patch your system, you can use the command line tools to extract\nthe specific ELF file you need, and run that instead. See the \"building the\ncommand line tools\" section, then try running this:\n\n    fatelf-split my_fatelf_binary\n\nIf the FatELF file contained x86 and amd64 binaries, you'll end up with files\nnamed \"my_fatelf_binary-i386\" and \"my_fatelf_binary-x86_64\". Use whichever\nyou need at this point like any other program. Another option is to extract\njust the binary you need, like this...\n\n    fatelf-extract my_elf_binary my_fatelf_binary x86_64\n\n...this will extract the amd64 ELF binary from my_fatelf_binary, and place it\nin the file \"my_elf_binary\".\n\n\n## Using FatELF as a developer:\n\nIf you're a developer that wants to work with FatELF files, you will want to\nhave your system patched (Linux kernel, glibc), so that you can run FatELF\nbinaries directly. You may want to patch binutils and gdb, too, but this is\nonly necessary if you want to link directly against a FatELF library or\ndebug a FatELF binary/library. In many cases, you can get away\nwithout this functionality. You'll want to get the command line tools\ninstalled (see the \"Building the command line tools\" section).\n\nThe most common workflow is usually to build your software for all platforms,\nseparately, and then use fatelf-glue to create FatELF files out of the\nseparate ELF binaries. So long as the soname doesn't change, it is safe to\nlink against an ELF shared library and then later turn that shared library\ninto a FatELF file. The system loaders will still do the right thing.\nAlternately, if you patched binutils, you can create the FatELF shared\nlibrary first, and then link against it as normal.\n\nIn many cases, you only care about FatELF when you are ready to ship your\nbinaries to the outside world, so it's possible to simply use fatelf-glue at\nthe end of the process and never patch a single thing on your development box.\n\n\n## Using FatELF as a system/tool developer:\n\nIf you are bringing FatELF support to a new platform or development tool, you\nshould probably examine include/fatelf.h for the data structures, and read\nfatelf-specification.txt. The format is not particularly complex. The only\nrequirement is that your platform support ELF binaries, as that is where\nmost of the complexity lies. FatELF is just a simple wrapper around\ntraditional ELF files. The existing command line tools will probably Just\nWork on your platform out of the box.\n\nPlease drop Ryan a line at icculus@icculus.org if you add FatELF support to\nyour software, so he can post a link to it on the FatELF website.\n\n\n## Building the command line tools:\n\nYou will need to have a system set up for compiling C code, and you will need\n[CMake](https://www.cmake.org/). If you are looking for the latest and\ngreatest version of the tools, you'll need git to download them. If you're\ninstalling from a source tarball, git isn't necessary.\n\nIf you're on a Debian or Ubuntu system, you can probably run this to prepare:\n\n    sudo apt-get install build-essential cmake git\n\nOnce you are ready, you should get the source code. If downloading via git,\nthis command line should do:\n\n    git clone https://github.com/icculus/fatelf\n\nIf you are using a source tarball, just extract it.\n\nNow make a build directory, configure the build, and compile the sources:\n\n    mkdir fatelf-build\n    cd fatelf-build\n    cmake ../fatelf\n    make\n\nYou should end up with a pile of binaries, with names like \"fatelf-glue\" and\n\"fatelf-info\", etc. If you want to install them system-wide, you can do so\nnow:\n\n    sudo make install\n\n(`sudo make install DESTDIR=/some/other/path` also works.)\n\n\n## Using the command line tools:\n\nMost of the tools expect command line arguments in some form like...\n\n    fatelf-COMMAND OUTPUT INPUT TARGET\n\n...where `COMMAND` is the tool to run, `OUTPUT` is the file you want to create\nwith the results of the operation, `INPUT` is the file you want to process,\nand `TARGET` is the target platform. Please note that output files will\noverwrite existing files of the same name without warning.\n\n`TARGET` takes the form of either a specific record number in the form\n\"recordX\" where X is the index of the record in the FatELF file (\"record0\" is\nthe first record, \"record1\" the next, etc), or a formal target name. Formal\nnames look like this: \"x86_64:64bits:le:sysv:osabiver0\" ... that's a real\nmouthful! All of the fields in a target name are optional. The only\nrequirement is that the name be unique enough to only refer to a single\nrecord in a given FatELF file. In most cases, you'll only need the machine\narchitecture; if you have a FatELF file with x86 and amd64 ELF binaries, your\ntarget names can be, simply, \"i386\" and \"x86_64\". If you have two SPARC\nbinaries that are only separated by word size, you could do \"32bits\" and\n\"64bits\", but if you added an amd64 binary to that FatELF file, you'd need\nto do \"sparc:64bits\" to stay unique. Two PowerPC binaries, one for bigendian\nmode and one for little endian, could say \"le\" or \"be\" to be unique. If you\nwant the full target name for a given record, fatelf-info will list them for\nyou.\n\n\n\nThe actual tools are:\n\n    fatelf-glue OUTPUT INPUT1 INPUT2 [... INPUTn]\n\nThis takes the ELF binaries listed on the command line (as `INPUT*`), and\nglues them together into a FatELF binary named `OUTPUT`. The files' ELF\nheaders are read to construct the proper FatELF data structures. It is an\nerror to try to glue two ELF binaries with the same target together, and\nfatelf-glue will refuse to do so.\n\n\n    fatelf-info INPUT\n\nReport interesting information about FatELF file `INPUT`. This will list\nall fields of all FatELF records, and the full formal target name for\neach.\n\n\n    fatelf-extract OUTPUT INPUT TARGET\n\nExtract a copy of the ELF binary that matches `TARGET` from FatELF file `INPUT`,\nand write it to `OUTPUT`. If `TARGET` is ambiguous, this operation fails.\n\n\n    fatelf-remove OUTPUT INPUT TARGET\n\nRemove the ELF binary that matches `TARGET` from FatELF file INPUT`,\nand write a new FatELF file that lacks that ELF binary to `OUTPUT`.\nIf `TARGET` is ambiguous, this operation fails.\n\n\n    fatelf-replace OUTPUT INPUT NEWELF\n\nReplace an ELF binary in FatELF file `INPUT` with the one in file `NEWELF`,\nand write a new FatELF file with the replacement made. This tool figures\nout which binary to replace by reading the headers in `NEWELF`.\n\n\n    fatelf-split INPUT\n\nSplit FatELF file `INPUT` into multiple ELF files, one per included target.\nThe files will be named `INPUT-targetname`, where `targetname` is a formal\ntarget name in the shortest form possible that prevents ambiguity between\nincluded targets. This can overwrite existing files in the same directory\nas `INPUT` without warning, so use with caution. fatelf-extract can be a\nsafer alternative.\n\n\n    fatelf-verify INPUT TARGET\n\nCheck if there is an ELF binary in FatELF file `INPUT` that matches the\ntarget name `TARGET`, and set the process exit code appropriately. This\nreports zero if `TARGET` was found, and non-zero if not. If `TARGET` is\nambiguous, this is considered an error, and non-zero is reported.\n\n\n    fatelf-validate INPUT\n\nRun several tests on FatELF file `INPUT` to make sure the data is consistent\nand sane. This will return non-zero if there are problems detected, or\nzero if the tool believes that the FatELF file is correctly formed. Please\nnote that this is meant to be a sanity check and debugging aid, but will\nnot detect most forms of file corruption, either intentional or accidental.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficculus%2Ffatelf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficculus%2Ffatelf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficculus%2Ffatelf/lists"}