{"id":15220454,"url":"https://github.com/jaseemabid/inc","last_synced_at":"2025-10-03T12:30:26.292Z","repository":{"id":62440817,"uuid":"102759897","full_name":"jaseemabid/inc","owner":"jaseemabid","description":"An incremental approach to compiler construction","archived":false,"fork":true,"pushed_at":"2020-05-29T14:17:09.000Z","size":4600,"stargazers_count":80,"open_issues_count":7,"forks_count":6,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-01-01T10:33:16.451Z","etag":null,"topics":["assembly","chez-scheme","compiler","scheme-compiler","x86"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"namin/inc","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaseemabid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-07T16:21:42.000Z","updated_at":"2024-09-03T06:26:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jaseemabid/inc","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/jaseemabid%2Finc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaseemabid%2Finc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaseemabid%2Finc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaseemabid%2Finc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaseemabid","download_url":"https://codeload.github.com/jaseemabid/inc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235122343,"owners_count":18939286,"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":["assembly","chez-scheme","compiler","scheme-compiler","x86"],"created_at":"2024-09-28T13:10:06.756Z","updated_at":"2025-10-03T12:30:25.398Z","avatar_url":"https://github.com/jaseemabid.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌱 A tiny scheme compiler [![Build Status][tbadge]][travis] [![Docs][dbadge]][docs] [![](https://meritbadge.herokuapp.com/inc)](https://crates.io/crates/inc)\n\n🐳 A tiny educational [Scheme][wiki] compiler written in Rust that generates\nreadable x86 assembly. Implements the paper [An Incremental Approach to Compiler\nConstruction][paper] by Abdulaziz Ghuloum. We aim to be complete, correct and fast,\nin that order of importance.\n\n## Getting started\n\n    $ cargo build\n    $ cargo test\n\nRunning simple programs is straight forward.\n\n    $ echo \"(define (twice x) (* x 2)) (twice 21)\" | cargo run -q\n    42\n\n## How does this work?\n\nThe previous step generates x86 assembly that gets compiled to a very tiny\n(~13KB) native executable binary along with some runtime written in Rust and\nsome glue code in C.\n\n    $ ./inc\n    42\n\n    $ file inc\n    inc: Mach-O 64-bit executable x86_64\n\n    $ stat -f \"%z\" inc\n    13556\n\nThe generated assembly is usually easy to read, and if you squint hard enough\nkinda looks like the source code 😉\n\n     $ echo \"(define (twice x) (* x 2)) (twice 21)\" | cargo run -q -- -S\n\n```asm\n    .section __TEXT,__text\n    .intel_syntax noprefix\n\n    .globl \"_init\"\n\"_init\":\n    push rbp\n    mov rbp, rsp\n    mov r12, rdi        # Store heap index to R12\n    mov rax, 168\n    mov qword ptr [rbp - 24], rax\n    call \"twice\"\n    pop rbp\n    ret\n\n    .globl \"twice\"\n\"twice\":\n    push rbp\n    mov rbp, rsp\n    mov rax, [rbp - 8]\n    mov qword ptr [rbp - 16], rax\n    mov rax, 16\n    sar rax, 3\n    mul qword ptr [rbp - 16]\n    pop rbp\n    ret\n```\n\nUnder the hood, inc compiles scheme to x86 assembly and uses Clang (or GCC on\nLinux) to generate machine executable binaries.\n\nGenerate the asm\n\n    $ echo \"(define (twice x) (* x 2)) (twice 21)\" | cargo run -q -- -S \u003e inc.s\n\nCompile the runtime as well the generated assembly into shared object files\n\n    $ clang -c inc.s     # Generates inc.o\n    $ clang -c runtime.c # Generates runtime.o\n    $ cargo build        # Generates ./target/debug/libinc.dylib\n\nLink it all together with a linker\n\n    $ ld -L./target/debug runtime.o inc.o -linc -ldl -lpthread -o inc\n\nThe same binary is generated again\n\n    $ ./inc\n    42\n\nConveniently clang can do it all in one step if you prefer it that way.\n\n    $ clang -L./target/debug inc.s runtime.c  -linc -ldl -lpthread -o inc\n\n## Docs\n\nInc is reasonably well documented and is preferably read with Cargo docs. Build\ndocs locally or [read online][docs] (⚠ Could be outdated)\n\n    $ cargo doc --document-private-items --open\n\n## Where can I learn more?\n\n1. Read the [paper] for an overview\n2. Watch a [talk about this project][talk] if that works better.\n3. [Ask HN: What's the best resource for learning modern x64 assembly?][hn]\n\n## Colophon\n\nThis project started in [Chez], later [ported it to Racket][rkt] and then again\nto [rust]. The old project still lives at [rkt](./rkt).\n\n[book]:    https://doc.rust-lang.org/book/#the-rust-programming-language\n[chez]:    https://www.scheme.com\n[dbadge]:  https://docs.rs/inc/badge.svg\n[docs]:    https://docs.rs/inc\n[iter]:    https://hermanradtke.com/2015/06/22/effectively-using-iterators-in-rust.html\n[paper]:   docs/paper.pdf?raw=true\n[rkt]:     https://github.com/jaseemabid/inc/commit/a8ab1e6c7506023e59ddcf11cfabe53fbaa5c00a\n[rust]:    https://github.com/jaseemabid/inc/commit/cc333332a5f20dc9de168954808d363621bd0c97\n[talk]:    https://www.youtube.com/watch?v=WBWRkUuyuE0\n[tbadge]:  https://travis-ci.org/jaseemabid/inc.svg?branch=master\n[travis]:  https://travis-ci.org/jaseemabid/inc\n[wiki]:    https://en.wikipedia.org/wiki/Scheme_(programming_language)\n[hn]:      https://news.ycombinator.com/item?id=22279051\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaseemabid%2Finc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaseemabid%2Finc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaseemabid%2Finc/lists"}