{"id":14991177,"url":"https://github.com/lifting-bits/remill","last_synced_at":"2025-05-15T14:06:23.812Z","repository":{"id":37318400,"uuid":"44748533","full_name":"lifting-bits/remill","owner":"lifting-bits","description":"Library for lifting machine code to LLVM bitcode","archived":false,"fork":false,"pushed_at":"2025-05-13T16:47:08.000Z","size":10431,"stargazers_count":1391,"open_issues_count":74,"forks_count":149,"subscribers_count":60,"default_branch":"master","last_synced_at":"2025-05-13T17:56:20.858Z","etag":null,"topics":["aarch64","armv7","armv8","instruction-semantics","llvm","llvm-ir","sparcv8","sparcv9","thumb2","x86","x86-64"],"latest_commit_sha":null,"homepage":"","language":"C++","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/lifting-bits.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-22T13:54:19.000Z","updated_at":"2025-05-13T16:47:14.000Z","dependencies_parsed_at":"2023-10-12T21:48:16.141Z","dependency_job_id":"a74de1cd-0aef-4dc1-9831-0455fa067fb0","html_url":"https://github.com/lifting-bits/remill","commit_stats":{"total_commits":999,"total_committers":75,"mean_commits":13.32,"dds":0.5525525525525525,"last_synced_commit":"7f091d4256060c254fcd15f35fd8b9bd6abd157f"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lifting-bits%2Fremill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lifting-bits%2Fremill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lifting-bits%2Fremill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lifting-bits%2Fremill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lifting-bits","download_url":"https://codeload.github.com/lifting-bits/remill/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355335,"owners_count":22057354,"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":["aarch64","armv7","armv8","instruction-semantics","llvm","llvm-ir","sparcv8","sparcv9","thumb2","x86","x86-64"],"created_at":"2024-09-24T14:21:40.164Z","updated_at":"2025-05-15T14:06:18.804Z","avatar_url":"https://github.com/lifting-bits.png","language":"C++","funding_links":[],"categories":["Starchart"],"sub_categories":[],"readme":"# Remill [![Slack Chat](http://slack.empirehacking.nyc/badge.svg)](https://slack.empirehacking.nyc/)\n\n\u003cp align=\"center\"\u003e\n     \u003cimg src=\"docs/images/remill_logo.png\" /\u003e\n\u003c/p\u003e\n\nRemill is a static binary translator that translates machine code instructions into [LLVM bitcode](http://llvm.org/docs/LangRef.html). It translates AArch64 (64-bit ARMv8), SPARC32 (SPARCv8), SPARC64 (SPARCv9), x86 and amd64 machine code (including AVX and AVX512) into LLVM bitcode. AArch32 (32-bit ARMv8 / ARMv7) support is underway.\n\nRemill focuses on accurately lifting instructions. It is meant to be used as a library for other tools, e.g. [McSema](https://github.com/lifting-bits/mcsema).\n\n## Build Status\n\n[![Build Status](https://img.shields.io/github/workflow/status/lifting-bits/remill/CI/master)](https://github.com/lifting-bits/remill/actions?query=workflow%3ACI)\n\n## Documentation\n\nTo understand how Remill works you can take a look at the following resources:\n\n - [Step-by-step guide on how Remill lifts an instruction](docs/LIFE_OF_AN_INSTRUCTION.md)\n - [How to implement the semantics of an instruction](docs/ADD_AN_INSTRUCTION.md)\n - [The design and architecture of Remill](docs/DESIGN.md)\n\nIf you would like to contribute you can check out: [How to contribute](docs/CONTRIBUTING.md)\n\n## Getting Help\n\nIf you are experiencing undocumented problems with Remill then ask for help in the `#binary-lifting` channel of the [Empire Hacking Slack](https://slack.empirehacking.nyc/).\n\n## Supported Platforms\n\nRemill is supported on Linux platforms and has been tested on Ubuntu 22.04. Remill also works on macOS, and has experimental support for Windows.\n\nRemill's Linux version can also be built via Docker for quicker testing.\n\n## Dependencies\n\nMost of Remill's dependencies can be provided by the [cxx-common](https://github.com/lifting-bits/cxx-common) repository. Trail of Bits hosts downloadable, pre-built versions of cxx-common, which makes it substantially easier to get up and running with Remill. Nonetheless, the following table represents most of Remill's dependencies.\n\n| Name | Version |\n| ---- | ------- |\n| [Git](https://git-scm.com/) | Latest |\n| [CMake](https://cmake.org/) | 3.14+ |\n| [Google Flags](https://github.com/google/glog) | Latest |\n| [Google Log](https://github.com/google/glog) | Latest |\n| [Google Test](https://github.com/google/googletest) | Latest |\n| [LLVM](http://llvm.org/) | 15+ |\n| [Clang](http://clang.llvm.org/) | 15 |\n| [Intel XED](https://software.intel.com/en-us/articles/xed-x86-encoder-decoder-software-library) | Latest |\n| [Python](https://www.python.org/) | 2.7 |\n| Unzip | Latest |\n| [ccache](https://ccache.dev/) | Latest |\n\n## Getting and Building the Code\n\n### Docker Build\n\nRemill now comes with a Dockerfile for easier testing. This Dockerfile references the [cxx-common](https://github.com/lifting-bits/cxx-common) container to have all pre-requisite libraries available.\n\nThe Dockerfile allows for quick builds of multiple supported LLVM, and Ubuntu configurations.\n\n\u003e [!IMPORTANT]\n\u003e Not all LLVM and Ubuntu configurations are supported---Please refer to the CI results to get an idea about configurations that are tested and supported. The Docker image should build on both x86_64 and ARM64, but we only test x86_64 in CI. ARM64 _should build_, but if it doesn't, please open an issue.\n\nQuickstart (builds Remill against LLVM 17 on Ubuntu 22.04).\n\nClone Remill:\n\n```shell\ngit clone https://github.com/lifting-bits/remill.git\ncd remill\n```\n\nBuild Remill Docker container:\n\n```shell\ndocker build . -t remill \\\n     -f Dockerfile \\\n     --build-arg UBUNTU_VERSION=22.04 \\\n     --build-arg LLVM_VERSION=17\n```\n\nEnsure remill works:\n\nDecode some AMD64 instructions to LLVM:\n\n```shell\ndocker run --rm -it remill \\\n     --arch amd64 --ir_out /dev/stdout --bytes c704ba01000000\n```\n\nDecode some AArch64 instructions to LLVM:\n\n```shell\ndocker run --rm -it remill \\\n     --arch aarch64 --address 0x400544 --ir_out /dev/stdout \\\n     --bytes FD7BBFA90000009000601891FD030091B7FFFF97E0031F2AFD7BC1A8C0035FD6\n```\n\n### On Linux\n\nFirst, update aptitude and get install the baseline dependencies.\n\n```shell\nsudo dpkg --add-architecture i386\nsudo apt-get update\nsudo apt-get upgrade\n\nsudo apt-get install \\\n     git \\\n     python3 \\\n     wget \\\n     curl \\\n     build-essential \\\n     lsb-release \\\n     ccache \\\n     libc6-dev:i386 \\\n     'libstdc++-*-dev:i386' \\\n     g++-multilib \\\n     rpm\n```\n\nNext, clone the repository. This will clone the code into the `remill` directory.\n\n```shell\ngit clone https://github.com/lifting-bits/remill.git\n```\n\nNext, we build Remill. This script will create another directory, `remill-build`,\nin the current working directory. All remaining dependencies needed\nby Remill will be built in the `remill-build` directory.\n\n```shell\n./remill/scripts/build.sh\n```\n\nNext, we can install Remill. Remill itself is a library, and so there is no real way\nto try it. However, you can head on over to the [McSema](https://github.com/lifting-bits/mcsema) repository, which uses Remill for lifting instructions.\n\n```shell\ncd ./remill-build\nsudo make install\n```\n\nWe can also build and run Remill's test suite.\n\n```shell\ncd ./remill-build\nmake test_dependencies\nmake test\n```\n\n### Full Source Builds\n\nSometimes, you want to build everything from source, including the [cxx-common](https://github.com/lifting-bits/cxx-common) libraries remill depends on. To build against a custom cxx-common location, you can use the following `cmake` invocation:\n\n```sh\nmkdir build\ncd build\ncmake  \\\n  -DCMAKE_INSTALL_PREFIX=\"\u003cpath where remill will install\u003e\" \\\n  -DCMAKE_TOOLCHAIN_FILE=\"\u003cpath to cxx-common directory\u003e/vcpkg/scripts/buildsystems/vcpkg.cmake\"  \\\n  -G Ninja  \\\n  ..\ncmake --build .\ncmake --build . --target install\n```\n\nThe output may produce some CMake warnings about policy CMP0003. These warnings are safe to ignore.\n\n### Common Build Issues\n\nIf you see errors similar to the following:\n\n```\nfatal error: 'bits/c++config.h' file not found\n```\n\nThen you need to install 32-bit libstdc++ headers and libraries. On a Debian/Ubuntu based distribution, You would want to do something like this:\n\n```sh\nsudo dpkg --add-architecture i386\nsudo apt-get update\nsudo apt-get install libc6-dev:i386 libstdc++-10-dev:i386 g++-multilib\n```\n\nThis error happens because the SPARC32 runtime semantics (the bitcode library which lives in `\u003cinstall directory\u003e/share/remill/\u003cversion\u003e/semantics/sparc32.bc`) are built as 32-bit code, but 32-bit development libraries are not installed by default.\n\nA similar situation occurs when building remill on arm64 Linux. In that case, you want to follow a similar workflow, except the architecture used in `dpkg` and `apt-get` commands  would be `armhf` instead of `i386`.\n\nAnother alternative is to disable SPARC32 runtime semantics. To do that, use the `-DREMILL_BUILD_SPARC32_RUNTIME=False` option when invoking `cmake`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flifting-bits%2Fremill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flifting-bits%2Fremill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flifting-bits%2Fremill/lists"}