{"id":13393299,"url":"https://github.com/munificent/craftinginterpreters","last_synced_at":"2025-05-12T13:23:41.936Z","repository":{"id":38326178,"uuid":"79055279","full_name":"munificent/craftinginterpreters","owner":"munificent","description":"Repository for the book \"Crafting Interpreters\"","archived":false,"fork":false,"pushed_at":"2024-08-07T12:07:07.000Z","size":23405,"stargazers_count":9662,"open_issues_count":130,"forks_count":1123,"subscribers_count":173,"default_branch":"master","last_synced_at":"2025-04-23T15:59:40.557Z","etag":null,"topics":["book","bytecode","c","compiler","interpreter","java","language","lox","markdown","parser","scripting-language"],"latest_commit_sha":null,"homepage":"http://www.craftinginterpreters.com/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/munificent.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":"2017-01-15T19:46:57.000Z","updated_at":"2025-04-23T14:29:34.000Z","dependencies_parsed_at":"2023-02-10T08:30:20.209Z","dependency_job_id":"a561bfb7-4a70-4658-9802-5bb410a1ce3e","html_url":"https://github.com/munificent/craftinginterpreters","commit_stats":{"total_commits":1466,"total_committers":135,"mean_commits":10.85925925925926,"dds":"0.13710777626193726","last_synced_commit":"4a840f70f69c6ddd17cfef4f6964f8e1bcd8c3d4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/munificent%2Fcraftinginterpreters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/munificent%2Fcraftinginterpreters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/munificent%2Fcraftinginterpreters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/munificent%2Fcraftinginterpreters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/munificent","download_url":"https://codeload.github.com/munificent/craftinginterpreters/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745526,"owners_count":21957391,"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":["book","bytecode","c","compiler","interpreter","java","language","lox","markdown","parser","scripting-language"],"created_at":"2024-07-30T17:00:49.589Z","updated_at":"2025-05-12T13:23:41.916Z","avatar_url":"https://github.com/munificent.png","language":"HTML","readme":"This is the repo used for the in-progress book \"[Crafting Interpreters][]\". It\ncontains the Markdown text of the book, full implementations of both\ninterpreters, as well as the build system to weave the two together into the\nfinal site.\n\n[crafting interpreters]: http://craftinginterpreters.com\n\nIf you find an error or have a suggestion, please do file an issue here. Thank\nyou!\n\n## Contributing\n\nOne of the absolute best things about writing a book online and putting it out\nthere before it's done is that people like you have been kind enough to give me\nfeedback, point out typos, and find other errors or unclear text.\n\nIf you'd like to do that, great! You can just file bugs here on the repo, or\nsend a pull request if you're so inclined. If you want to send a pull request,\nbut don't want to get the build system set up to regenerate the HTML too, don't\nworry about it. I'll do that when I pull it in.\n\n## Ports and implementations\n\nAnother way to get involved is by sharing your own implementation of Lox. Ports\nto other languages are particularly useful since not every reader likes Java and\nC. Feel free to add your Lox port or implementation to the wiki:\n\n* [Lox implementations][]\n\n[lox implementations]: https://github.com/munificent/craftinginterpreters/wiki/Lox-implementations\n\n## Building Stuff\n\nI am a terribly forgetful, error-prone mammal, so I automated as much as I\ncould.\n\n### Prerequisites\n\nI develop on an OS X machine, but any POSIX system should work too. With a\nlittle extra effort, you should be able to get this working on Windows as well,\nthough I can't help you out much.\n\nMost of the work is orchestrated by make. The build scripts, test runner, and\nother utilities are all written in [Dart][]. Instructions to install Dart are\n[here][install]. Once you have Dart installed and on your path, run:\n\n```sh\n$ make get\n```\n\n[dart]: https://dart.dev/\n[install]: https://dart.dev/get-dart\n\nThis downloads all of the packages used by the build and test scripts.\n\nIn order to compile the two interpreters, you also need a C compiler on your\npath as well as `javac`.\n\n### Building\n\nOnce you've got that setup, try:\n\n```sh\n$ make\n```\n\nIf everything is working, that will generate the site for the book as well as\ncompiling the two interpreters clox and jlox. You can run either interpreter\nright from the root of the repo:\n\n```sh\n$ ./clox\n$ ./jlox\n```\n\n### Hacking on the book\n\nThe Markdown and snippets of source code are woven together into the final HTML\nusing a hand-written static site generator that started out as a [single tiny\nPython script][py] for [my first book][gpp] and somehow grew into something\napproximating a real program.\n\n[py]: https://github.com/munificent/game-programming-patterns/blob/master/script/format.py\n[gpp]: http://gameprogrammingpatterns.com/\n\nThe generated HTML is committed in the repo under `site/`. It is built from a\ncombination of Markdown for prose, which lives in `book/`, and snippets of code\nthat are weaved in from the Java and C implementations in `java/` and `c/`. (All\nof those funny looking comments in the source code are how it knows which\nsnippet goes where.)\n\nThe script that does all the magic is `tool/bin/build.dart`. You can run that\ndirectly, or run:\n\n```sh\n$ make book\n```\n\nThat generates the entire site in one batch. If you are incrementally working\non it, you'll want to run the development server:\n\n```sh\n$ make serve\n```\n\nThis runs a little HTTP server on localhost rooted at the `site/` directory.\nAny time you request a page, it regenerates any files whose sources have been\nchanged, including Markdown files, interpreter source files, templates, and\nassets. Just let that keep running, edit files locally, and refresh your\nbrowser to see the changes.\n\n### Building the interpreters\n\nYou can build each interpreter like so:\n\n```sh\n$ make clox\n$ make jlox\n```\n\nThis builds the final version of each interpreter as it appears at the end of\nits part in the book.\n\nYou can also see what the interpreters look like at the end of each chapter. (I\nuse this to make sure they are working even in the middle of the book.) This is\ndriven by a script, `tool/bin/split_chapters.dart` that uses the same comment\nmarkers for the code snippets to determine which chunks of code are present in\neach chapter. It takes only the snippets that have been seen by the end of each\nchapter and produces a new copy of the source in `gen/`, one directory for each\nchapter's code. (These are also an easier way to view the source code since they\nhave all of the distracting marker comments stripped out.)\n\nThen, each of those can be built separately. Run:\n\n```sh\n$ make c_chapters\n```\n\nAnd in the `build/` directory, you'll get an executable for each chapter, like\n`chap14_chunks`, etc. Likewise:\n\n```sh\n$ make java_chapters\n```\n\nThis compiles the Java code to classfiles in `build/gen/` in a subdirectory for\neach chapter.\n\n## Testing\n\nI have a full Lox test suite that I use to ensure the interpreters in the book\ndo what they're supposed to do. The test cases live in `test/`. The Dart\nprogram `tool/bin/test.dart` is a test runner that runs each of those test\nfiles on a Lox interpreter, parses the result, and validates that that the test\ndoes what it's expected to do.\n\nThere are various interpreters you can run the tests against:\n\n```sh\n$ make test       # The final versions of clox and jlox.\n$ make test_clox  # The final version of clox.\n$ make test_jlox  # The final version of jlox.\n$ make test_c     # Every chapter's version of clox.\n$ make test_java  # Every chapter's version of jlox.\n$ make test_all   # All of the above.\n```\n\n### Testing your implementation\n\nYou are welcome to use the test suite and the test runner to test your own Lox\nimplementation. The test runner is at `tool/bin/test.dart` and can be given a\ncustom interpreter executable to run using `--interpreter`. For example, if you\nhad an interpreter executable at `my_code/boblox`, you could test it like:\n\n```sh\n$ dart tool/bin/test.dart clox --interpreter my_code/boblox\n```\n\nYou still need to tell it which suite of tests to run because that determines\nthe test expectations. If your interpreter should behave like jlox, use \"jlox\"\nas the suite name. If it behaves like clox, use \"clox\". If your interpreter is\nonly complete up to the end of one of the chapters in the book, you can use\nthat chapter as the suite, like \"chap10_functions\". See the Makefile for the\nnames of all of the chapters.\n\nIf your interpreter needs other command line arguments passed to use, pass them\nto the test runner using `--arguments` and it will forward to your interpreter.\n\n## Repository Layout\n\n*   `asset/` – Sass files and jinja2 templates used to generate the site.\n*   `book/` - Markdown files for the text of each chapter.\n*   `build/` - Intermediate files and other build output (except for the site\n    itself) go here. Not committed to Git.\n*   `c/` – Source code of clox, the interpreter written in C. Also contains an\n    XCode project, if that's your thing.\n*   `gen/` – Java source files generated by GenerateAst.java go here. Not\n    committed.\n*   `java/` – Source code of jlox, the interpreter written in Java.\n*   `note/` – Various research, notes, TODOs, and other miscellanea.\n*   `note/answers` – Sample answers for the challenges. No cheating!\n*   `site/` – The final generated site. The contents of this directory directly\n    mirror craftinginterpreters.com. Most content here is generated by build.py,\n    but fonts, images, and JS only live here. Everything is committed, even the\n    generated content.\n*   `test/` – Test cases for the Lox implementations.\n*   `tool/` – Dart package containing the build, test, and other scripts.\n","funding_links":[],"categories":["HTML","Learning","Uncategorized","c","Scripting"],"sub_categories":["Books","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmunificent%2Fcraftinginterpreters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmunificent%2Fcraftinginterpreters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmunificent%2Fcraftinginterpreters/lists"}