{"id":22394591,"url":"https://github.com/redraiment/brainfuck","last_synced_at":"2025-10-15T14:32:00.271Z","repository":{"id":56999717,"uuid":"523032957","full_name":"redraiment/brainfuck","owner":"redraiment","description":"Brainfuck Compiler and Interpreter with LLVM in C","archived":false,"fork":false,"pushed_at":"2023-04-23T10:45:44.000Z","size":373,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-05T05:10:45.732Z","etag":null,"topics":["brainfuck","c","compiler","interpreter","jit","llvm","llvm-frontend"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redraiment.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}},"created_at":"2022-08-09T16:46:02.000Z","updated_at":"2024-10-23T07:54:01.000Z","dependencies_parsed_at":"2022-08-21T13:20:49.637Z","dependency_job_id":null,"html_url":"https://github.com/redraiment/brainfuck","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redraiment%2Fbrainfuck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redraiment%2Fbrainfuck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redraiment%2Fbrainfuck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redraiment%2Fbrainfuck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redraiment","download_url":"https://codeload.github.com/redraiment/brainfuck/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236618064,"owners_count":19177998,"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":["brainfuck","c","compiler","interpreter","jit","llvm","llvm-frontend"],"created_at":"2024-12-05T05:11:03.334Z","updated_at":"2025-10-15T14:31:54.919Z","avatar_url":"https://github.com/redraiment.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Brainfuck Interpreters and Compilers\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\nThis is my learning project to practice building compiler and interpreter with LLVM C API.\n\nThe project is too complext for someone, who just want to implement a simple interpreter for Brainfuck. This [snippet](https://gist.github.com/redraiment/87413e5edc5c33458812492b5358ed61) is a better alternative, which implements the interpreter with one C file only.\n\n# About the Project\n\nThere are so many LLVM tutorials in C++, however, I'd like to build a compiler and interpreter with LLVM in C. Therefore, I created this project to build a compiler and JIT interpreter for [Brainfuck](https://en.wikipedia.org/wiki/Brainfuck). Brainfuck language is simple enough, and it designed for implementing the smallest possible compiler.\n\n# Roadmap\n\n* [x] ~~Generating Makefile with [GNU Autoconf](https://www.gnu.org/software/autoconf/).~~\n* [x] Generating Makefile with [CMake](https://cmake.org/).\n* [x] Building project with [GNU Make](https://www.gnu.org/software/make/).\n* [x] Parsing Command line options with [getopt](https://www.gnu.org/software/libc/manual/html_node/Getopt.html).\n* [x] Lexical analysis with [flex](https://github.com/westes/flex).\n* [x] Syntax analysis with [bison](https://www.gnu.org/software/bison/).\n* [x] Creating LLVM IR file with [LLVM C API](https://llvm.org/doxygen/group__LLVMC.html).\n* [x] Creating native object file with [LLVM C API](https://llvm.org/doxygen/group__LLVMC.html).\n* [x] Creating executable file with linker.\n* [x] Running script file with [LLVM MCJIT](https://llvm.org/doxygen/group__LLVMCExecutionEngine.html).\n* [x] Deploying with [docker](https://hub.docker.com/).\n* [x] Linking with [lld](https://lld.llvm.org/).\n* [x] Static linking with [musl](https://musl.libc.org/).\n* [x] Embedding C runtime library.\n\n# Getting Started\n\nThe program can only working on Linux for now.\n\n## Download pre-build binary file (Recommended)\n\n```sh\nwget https://github.com/redraiment/brainfuck/releases/download/v0.5.0/brainfuck-0.5.0-x86_64.gz\ngunzip brainfuck-0.5.0.x86_64.gz\nsudo mv brainfuck-0.5.0.x86_64 /usr/local/bin/brainfuck\nbrainfuck -v\n```\n\nYou can see below version information if the above command run success.\n\n```\nbrainfuck v0.5.0\n\nHome page: \u003chttps://github.com/redraiment/brainfuck/\u003e.\nE-mail bug reports to: \u003credraiment@gmail.com\u003e.\n```\n\nExample for creating executable file and run it then:\n\n```sh\nbrainfuck hello-world.bf\n./hello-world\n```\n\nYou can find the `hello-world.bf` in [test](https://github.com/redraiment/brainfuck/tree/main/test) folder.\n\n## Install with Source Code\n\nAn example on Ubuntu:\n\n```sh\nsudo apt install --no-install-recommends -y flex bison clang-15 lld-15 liblld-15-dev llvm-15 llvm-15-dev llvm-15-tools zlib1g-dev libtinfo-dev binutils-dev musl-dev xxd make cmake\ngit clone --depth=1 https://github.com/redraiment/brainfuck.git\ncd brainfuck\ncmake 'Unix Makefiles' -B build .\ncmake --build build\n```\n\n# Usage\n\n```sh\nbrainfuck [OPTIONS] \u003csource-file\u003e\n```\n\nIt will create an executable file default.\n\n## Options\n\n* `-c/--compile`: only run preprocess, compile and assemble steps, then emit native object (`.o`) to output file. By default, the object file name for a source file is made by replacing the extension with `.o`.\n* `-r/--representation`: emit LLVM representation (`.ll`) to standard output.\n* `-s/--script`: run source file as Brainfuck script.\n* `-m/--enable-single-line-comment`: enable single line comment command `#`. It's useful used with Shebang.\n* `-o/--output \u003coutput-file\u003e`: write output to file. This applies to whatever sort of output is being produced, whether it be an executable file, an object file, an IR file. If `-o` is not specified, the default executable file name for a source file is made by removing the extension.\n* `-h/--help`: show this help and exit.\n* `-v/--version`: show version and exit.\n\n## Examples\n\n1. Creating an executable file: `brainfuck helloworld.bf`\n2. Running a file as scripting: `brainfuck -s helloworld.bf`\n3. Using with Shebang: `#!/usr/local/bin/brainfuck -ms`\n4. Creating native object file: `brainfuck -c helloworld.bf`\n5. Creating LLVM representation file: `brainfuck -p helloworld.bf`\n\n# Language Specification\n\nHere are some key behaviors:\n\n* Memory size: 30,000 bytes, and initialized to zero.\n* Data pointer initialized to point to the leftmost byte of the array.\n* Two streams of bytes for input and output.\n* End-of-file behavior: setting the cell to 0.\n* Use \"\\n\" for end-of-line.\n\n## Commands\n\n| Character | Meaning |\n| -- | -- |\n| `\u003e` | Increment the data pointer (to point to the next cell to the right). |\n| `\u003c` | Decrement the data pointer (to point to the next cell to the left). |\n| `+` | Increment (increase by one) the byte at the data pointer. |\n| `-` | Decrement (decrease by one) the byte at the data pointer. |\n| `.` | Output the byte at the data pointer. |\n| `,` | Accept one byte of input, storing its value in the byte at the data pointer. |\n| `[` | If the byte at the data pointer is zero, then instead of moving the instruction pointer forward to the next command, jump it forward to the command after the matching `]` command. |\n| `]` | If the byte at the data pointer is nonzero, then instead of moving the instruction pointer forward to the next command, jump it back to the command after the matching `[` command. |\n| `#` | Single line comment. **Disabled default**. |\n| others | Comments |\n\n**HINT**: Single line comment command (`#`) is an extra command to ignore the text until end-of-line. It was added to avoid command of shebang conflict with Brainfuck commands. For example, there is `-` in `#!/bin/brainfuck -s`, which is backward command of Brainfuck.\n\n## Snippets\n\nHere some Brainfuck snippets for testing.\n\n### Hello World\n\nFrom [Wikipedia](https://en.wikipedia.org/wiki/Brainfuck#Hello_World!). It will write \"Hello world\" to standard output.\n\n```brainfuck\n++++++++++\n[\u003e+++++++\u003e++++++++++\u003e+++\u003e+\u003c\u003c\u003c\u003c-]\n\u003e++.\u003e+.+++++++..+++.\u003e++.\u003c\u003c+++++++++++++++.\n\u003e.+++.------.--------.\u003e+.\u003e.\n```\n\n### cat\n\nIt will read data from standard input and write to standard output directly, until end of file.\n\n```brainfuck\n,[.,]\n```\n\n### wc\n\nfrom [brainfuck.org](http://brainfuck.org/wc.b). the standard (line and) word (and character) count utility.\n\n```brainfuck\n\u003e\u003e\u003e+\u003e\u003e\u003e\u003e\u003e+\u003e\u003e+\u003e\u003e+[\u003c\u003c],[\n    -[-[-[-[-[-[-[-[\u003c+\u003e-[\u003e+\u003c-[\u003e-\u003c-[-[-[\u003c++[\u003c++++++\u003e-]\u003c\n        [\u003e\u003e[-\u003c]\u003c[\u003e]\u003c-]\u003e\u003e[\u003c+\u003e-[\u003c-\u003e[-]]]]]]]]]]]]]]]]\n    \u003c[-\u003c\u003c[-]+\u003e]\u003c\u003c[\u003e\u003e\u003e\u003e\u003e\u003e+\u003c\u003c\u003c\u003c\u003c\u003c-]\u003e[\u003e]\u003e\u003e\u003e\u003e\u003e\u003e\u003e+\u003e[\n        \u003c+[\n            \u003e+++++++++\u003c-[\u003e-\u003c-]++\u003e[\u003c+++++++\u003e-[\u003c-\u003e-]+[+\u003e\u003e\u003e\u003e\u003e\u003e]]\n            \u003c[\u003e+\u003c-]\u003e[\u003e\u003e\u003e\u003e\u003e++\u003e[-]]+\u003c\n        ]\u003e[-\u003c\u003c\u003c\u003c\u003c\u003c]\u003e\u003e\u003e\u003e\n    ],\n]+\u003c++\u003e\u003e\u003e[[+++++\u003e\u003e\u003e\u003e\u003e\u003e]\u003c+\u003e+[[\u003c++++++++\u003e-]\u003c.\u003c\u003c\u003c\u003c\u003c]\u003e\u003e\u003e\u003e\u003e\u003e\u003e\u003e]\n```\n\n# Contributing\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\". Don't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n1. Create your Feature Branch (git checkout -b feature/AmazingFeature)\n1. Commit your Changes (git commit -m 'Add some AmazingFeature')\n1. Push to the Branch (git push origin feature/AmazingFeature)\n1. Open a Pull Request\n\n# License\n\nDistrubuted under the GPLv3 License. See `LICENSE` for more information.\n\n# Contact\n\n* Zhang, Zepeng - [@redraiment](https://twitter.com/redraiment) - [redraiment@gmail.com](mailto:redraiment@gmail.com)\n\n# Acknowledgments\n\n* [Wikipedia](https://en.wikipedia.org/)\n* [brainfuck.org](http://brainfuck.org/)\n* [LLVM.org](https://llvm.org/)\n* [CMake](https://cmake.org/)\n* [GNU](https://www.gnu.org/)\n  * ~~[GNU Autoconf](https://www.gnu.org/software/autoconf/)~~\n  * [GNU Make](https://www.gnu.org/software/make/)\n  * [GNU getopt](https://www.gnu.org/software/libc/manual/html_node/Getopt.html)\n  * [GNU bison](https://www.gnu.org/software/bison/).\n* [flex](https://github.com/westes/flex).\n* [Docker](https://www.docker.com/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredraiment%2Fbrainfuck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredraiment%2Fbrainfuck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredraiment%2Fbrainfuck/lists"}