# SICP: JavaScript, Python, and Scheme Editions
This repository contains processing scripts and sources for *Structure and Interpretation of Computer Programs* (SICP), adapted from the original Scheme edition (SICP) into JavaScript (SICP JS) and Python (SICPy), and also publishing the original Scheme edition on its own. See the [SICP JS preface](https://sourceacademy.org/sicpjs/prefaces03) for background on the JavaScript adaptation.
## Editions
### SICP JS
* [PDF edition](https://sicp.sourceacademy.org/sicpjs.pdf)
* [Interactive SICP JS](https://sourceacademy.org/sicpjs), backed by structured per-section JSON textbook content, e.g. [json/1.1.1.json](https://sicp.sourceacademy.org/json/1.1.1.json)
* [Comparison edition](https://sicp.sourceacademy.org), Scheme vs. JavaScript
* Search support: the [frontend](https://github.com/source-academy/frontend)'s Text Search and Index Search buttons fetch [json/searchData.json](https://sicp.sourceacademy.org/json/searchData.json) from this public static host (not the Source Academy backend) and filter it locally; generated by `yarn json` (`javascript/search.ts`), which runs as part of `deploy-pages.yml` on every push to `master`
* Table of contents and prev/next navigation: the frontend fetches [json/toc.json](https://sicp.sourceacademy.org/json/toc.json) and [json/toc-navigation.json](https://sicp.sourceacademy.org/json/toc-navigation.json) at runtime, the same way it fetches section content and search data above — it must not snapshot these into its own repo, since the published chapter range can shrink or grow (e.g. `SICP_PUBLISHED_CHAPTERS`) independently of a frontend release; generated by `yarn json`/`yarn split` (`javascript/generateTocJson.js`)
* Source code archive ([sicpjs.zip](https://sicp.sourceacademy.org/sicpjs.zip)), the `programs_js` extracted from the book, one file per snippet
* Single-file Markdown export ([sicpjs.md](https://sicp.sourceacademy.org/sicpjs.md)), mirroring the PDF's content selection, for reading or feeding to tools that don't handle HTML/PDF/XML
### SICPy
* [PDF edition](https://sicp.sourceacademy.org/sicpy.pdf)
* [Interactive SICPy](https://sourceacademy.org/sicpy), backed by structured per-section JSON textbook content, e.g. [json_py/1.1.1.json](https://sicp.sourceacademy.org/json_py/1.1.1.json)
* [Comparison edition](https://sicp.sourceacademy.org/split_py), Scheme vs. Python
* Search support: same mechanism as SICP JS above, via [json_py/searchData.json](https://sicp.sourceacademy.org/json_py/searchData.json)
* Table of contents and prev/next navigation: same mechanism as SICP JS above, via [json_py/toc.json](https://sicp.sourceacademy.org/json_py/toc.json) and [json_py/toc-navigation.json](https://sicp.sourceacademy.org/json_py/toc-navigation.json)
* AI support: [SICPy chatbot knowledge base](https://sicp.sourceacademy.org/chatbot_notes_py) (see [details](#sicpy-chatbot-knowledge-base) below)
* Source code archive ([sicpy.zip](https://sicp.sourceacademy.org/sicpy.zip)), the `programs_py` extracted from the book, one file per snippet
* Single-file Markdown export ([sicpy.md](https://sicp.sourceacademy.org/sicpy.md)), mirroring the PDF's content selection
### Scheme (the original)
* [PDF edition](https://sicp.sourceacademy.org/sicp.pdf)
* Structured per-section JSON textbook content, e.g. [json_scm/1.1.1.json](https://sicp.sourceacademy.org/json_scm/1.1.1.json), including generated search data ([json_scm/searchData.json](https://sicp.sourceacademy.org/json_scm/searchData.json)) — not yet wired up to a live interactive frontend, unlike JS/Python above
* Source code archive ([sicp.zip](https://sicp.sourceacademy.org/sicp.zip)), the `programs_scm` extracted from the book, one file per snippet
* Single-file Markdown export ([sicp.md](https://sicp.sourceacademy.org/sicp.md)), mirroring the PDF's content selection
No comparison edition: Scheme is the comparison anchor the other two editions are diffed against, so a Scheme-vs-Scheme comparison would be nonsensical.
Details on how to generate these versions are in the [repo wiki](https://github.com/source-academy/sicp/wiki).
**Platform requirement:** Generating the JSON edition and extracting the programs (`yarn json`, `yarn programs`) works on any platform with Node.js. Generating the PDF edition and running the full build require Unix/macOS; Windows users can use [WSL](https://learn.microsoft.com/en-us/windows/wsl/) to run the shell scripts involved.
Check out our [Resources for Learners, Educators and Researchers](https://about.sourceacademy.org/), and read more [About the SICP JS Project](https://sourceacademy.org/sicpjs/making-of) in Interactive SICP JS.
## SICPy chatbot knowledge base
[`chatbot_notes_py/`](chatbot_notes_py) is a knowledge base for retrieval-augmented-generation (RAG) Q&A bots over SICPy, published alongside the other editions at [chatbot_notes_py](https://sicp.sourceacademy.org/chatbot_notes_py) (an `index.html` there lists and links every file). Unlike the editions above, it is not autogenerated by the XML build pipeline: it's AI-generated on demand — not by any pipeline in this repo — and checked into git directly, regenerated only for major revisions of the book.
For each chapter there are two files:
* `sicpy_notes_chapter<N>.ex`, an Elixir module (`Cadet.Chatbot.SicpyNotesWithIndex.Chapter<N>`) with one `@summary_<section>` module attribute per section/subsection. Each is an original bullet-point summary of that section, followed by a "Key terms" line drawn from the book's own back-of-book index.
* `sicpy_index_terms_chapter<N>.json`, a term-to-section-numbers lookup built from the same index entries, for keyword-based retrieval alongside embedding-based search.
## Testing the example programs
Each edition's example programs (`programs_js` / `programs_py` / `programs_scm`) can be tested automatically against their expected outputs, via `scripts/test.js`. CI (`.github/workflows/ci.yml`) runs all three on every push/PR; only SICPy chapters 1–3 against CPython are a required check today (see below) — everything else runs informationally (`continue-on-error`), either because the interpreter itself is unproven infrastructure (native JS, Scheme) or because the content isn't finished yet (SICPy chapters 4–5, py-slang).
### SICP JS
```bash
yarn test
# scoped to a folder:
yarn test -- programs_js/chapter1
```
By default this runs through **js-slang**. Set `JS_SLANG=0` (`yarn test:native`) to instead run natively on Node, using the [`sicp`](https://www.npmjs.com/package/sicp) npm package — the JS analogue of `sourceacademy-sicp` below: it re-exports js-slang's predeclared primitives (`pair`, `head`, `tail`, `math_*`, ...) as plain functions, generated from the [js-slang](https://github.com/source-academy/js-slang) repo. Unlike js-slang there's no chapter/variant gating; `sicp` exposes everything unconditionally.
### SICPy (Python)
First, generate the programs from the XML sources:
```bash
SICP_EDITION=py npx tsx ./javascript/index.js programs_py
```
Then run the tests:
```bash
yarn test:py
# Or scope to one chapter/section by passing a folder, same as `yarn test`:
yarn test:py -- programs_py/chapter1
yarn test:py -- programs_py/chapter1/section1/subsection4
```
By default the programs are run through **py-slang**, the Source Academy Python interpreter, which is installed as the [`@sourceacademy/py-slang`](https://www.npmjs.com/package/@sourceacademy/py-slang) dependency (run `yarn install` first). To test against a local py-slang build instead, set the `PY_SLANG` environment variable to its `dist/index.cjs` (e.g. `PY_SLANG=../py-slang/dist/index.cjs`).
To run against **CPython** instead (useful for comparison or as a ground truth — this is what `scripts/run_py.py` does, and what `test.js` shells out to when `PY_SLANG=0`):
```bash
yarn test:py:cpython
# scoped to a folder, same as above:
yarn test:py:cpython -- programs_py/chapter1
```
The CPython path needs the `sicp` runtime (published as [`sourceacademy-sicp`](https://pypi.org/project/sourceacademy-sicp/), maintained in the [py-slang](https://github.com/source-academy/py-slang) repo under `python/`) importable from wherever `python3` runs. `scripts/run_py.py` looks for it in this order:
1. An installed copy — `pip install sourceacademy-sicp`.
2. A sibling `py-slang` checkout — if this repo and `py-slang` sit next to each other on disk (e.g. both under the same parent directory), `pip install -e ../py-slang/python` (or nothing at all — `run_py.py` also falls back to importing straight out of that checkout without an install).
If neither is available, `run_py.py` exits with an error naming both options rather than failing with a raw `ModuleNotFoundError`.
Chapters 1–3 currently pass in full against CPython. Chapter 4 (the meta-circular evaluator) has a number of known, pre-existing failures unrelated to the `sicp` runtime itself — mostly program fragments that reference names like `parse` that only exist in the Source/JS edition, or that are intentionally incomplete snippets extracted from the book.
### Scheme
```bash
SICP_EDITION=scm npx tsx ./javascript/index.js programs_scm
SICP_EDITION=scm yarn test:scm
# scoped to a folder, same as above:
SICP_EDITION=scm yarn test:scm -- programs_scm/chapter1
```
This runs through [MIT/GNU Scheme](https://www.gnu.org/software/mit-scheme/) (`mit-scheme` on `PATH`; on Ubuntu, `sudo apt-get install mit-scheme`), the only interpreter wired up for this edition — there's no ground truth to compare against the way CPython grounds SICPy. Currently well under half the suite passes; most failures trace back to `programs_scm` snippets not yet having their `REQUIRES` (cross-snippet prerequisites, e.g. a helper `define`d in an earlier snippet) wired up for the Scheme edition, so a snippet ends up incomplete on its own — not to actual content bugs. This is new, previously-untested infrastructure, so treat it as informational rather than authoritative for now.
## Licenses
[![CC BY-SA 4.0][cc-by-nc-sa-image]][cc-by-nc-sa]
The [print version of SICP JS](https://mitpress.mit.edu/books/structure-and-interpretation-computer-programs-1) and the [ebook version](https://www.amazon.com/Structure-Interpretation-Computer-Programs-Engineering-ebook-dp-B094X8316F/dp/B094X8316F/ref=mt_other?_encoding=UTF8&me=&qid=) will be published in 2022 by The MIT Press under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](cc-by-nc-sa) (CC BY-NC-SA).
[![CC BY-SA 4.0][cc-by-sa-image]][cc-by-sa]
The text of SICP JS and SICPy is derived from the book *Structure and Interpretation of Computer Programs*, Second Edition, 1996, (SICP) by Harold Abelson and Gerald Jay Sussman, and is licensed by these original authors under a [Creative Commons Attribution-ShareAlike 4.0 International License](cc-by-sa) (CC BY-SA). SICP JS is licensed by adapters Martin Henz and Tobias Wrigstad under CC BY-SA; SICPy is licensed by adapter Martin Henz under CC BY-SA. The Scheme edition republishes the original SICP text and programs unmodified under the same CC BY-SA license, with no additional adaptation layer. A [comparison edition](https://sicp.sourceacademy.org) indicates the changes that were made to SICP for the JavaScript edition; a [Scheme/Python comparison edition](https://sicp.sourceacademy.org/split_py) does the same for the Python edition. [Interactive SICP JS](https://sourceacademy.org/sicpjs) is licensed by Martin Henz, Tobias Wrigstad, and Samuel Fang under CC BY-SA; [Interactive SICPy](https://sourceacademy.org/sicpy) is licensed by Martin Henz and Samuel Fang under CC BY-SA. The figures in all versions are derived from figures created by Andres Raba in 2015, and are licensed by Martin Henz and Tobias Wrigstad under CC BY-SA.
[<img src="static/img_original/gpl-v3.svg" alt="GPL 3" width="50">][gpl3]
The JavaScript programs in SICP JS and the Python programs in SICPy are derived from the Scheme programs in SICP and are licensed by their respective adapters (Martin Henz and Tobias Wrigstad for JavaScript; Martin Henz for Python) under the [GNU General Public License v3.0](gpl3).
[](https://opensource.org/licenses/Apache-2.0)
All JavaScript and TypeScript programs that generate the SICP JS, SICPy, and Scheme versions are licensed by the contributors under the [Apache License Version 2][apache2].
[cc-by-sa]: http://creativecommons.org/licenses/by-sa/4.0/
[cc-by-sa-image]: https://licensebuttons.net/l/by-sa/4.0/88x31.png
[cc-by-nc-sa]: http://creativecommons.org/licenses/by-nc-sa/4.0/
[cc-by-nc-sa-image]: https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png
[gpl3]: https://www.gnu.org/licenses/gpl-3.0.en.html
[apache2]: https://www.apache.org/licenses/LICENSE-2.0.txt