{"id":17633270,"url":"https://github.com/ashermancinelli/cxbqn","last_synced_at":"2025-09-04T15:41:21.224Z","repository":{"id":78571348,"uuid":"420225755","full_name":"ashermancinelli/cxbqn","owner":"ashermancinelli","description":"BQN virtual machine","archived":false,"fork":false,"pushed_at":"2024-02-01T16:23:19.000Z","size":6049,"stargazers_count":31,"open_issues_count":6,"forks_count":4,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-19T12:13:55.784Z","etag":null,"topics":["apl","bqn","cplusplus","cpp20","cuda"],"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/ashermancinelli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2021-10-22T19:55:34.000Z","updated_at":"2024-10-18T22:23:35.000Z","dependencies_parsed_at":"2023-03-03T19:45:33.723Z","dependency_job_id":null,"html_url":"https://github.com/ashermancinelli/cxbqn","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashermancinelli%2Fcxbqn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashermancinelli%2Fcxbqn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashermancinelli%2Fcxbqn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashermancinelli%2Fcxbqn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashermancinelli","download_url":"https://codeload.github.com/ashermancinelli/cxbqn/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252596320,"owners_count":21773842,"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":["apl","bqn","cplusplus","cpp20","cuda"],"created_at":"2024-10-23T01:48:04.053Z","updated_at":"2025-05-05T23:41:54.416Z","avatar_url":"https://github.com/ashermancinelli.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CXBQN\n\n***NOTE: I haven't updated this in a while, so the bytecode for the BQN compiler is out of date.***\n\nVM for [BQN](https://mlochbaum.github.io/BQN/).\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for information on contributing.\n\n## Building\n\nRequires a compiler capable of C++20.\nGCC 9.3.1 is the oldest compiler I have tested it with.\n\n```console\nmkdir build\ncd build\n# Use CXX to choose your compiler\nCXX=g++-11 cmake ..\nmake -j12\n./BQN -v\nCXBQN 0.11.0 compiled on Dec 25 2021\n```\n\nOr if you want to use nix, CXBQN has a flake:\n```\n$ nix shell github:ashermancinelli/cxbqn\n$ BQN -v\nCXBQN 0.11.0 compiled on Jan  1 1980\n```\n\n## Using\n\n```\n$ ./BQN -h\nUsage: BQN [options] args\n\nPositional arguments:\nargs                   \tall remaining arguments are passed into the BQN program as •args [default: {}]\n\nOptional arguments:\n-h --help              \tshows help message and exits [default: false]\n-e --execute           \texecute a string as BQN code\n-v --version           \tprints version information and exits [default: false]\n-p --execute-and-print \texecute a string as BQN code, pretty print the result\n-x --dump-cu           \tdump compilation units after compiling [default: false]\n-r --repl              \tenter REPL [default: false]\n-f --file              \texecute a string as BQN code\n$ ./BQN -e '•Show 5+5'\n10\n$ ./BQN -p ↕10\n⟨ 0 1 2 3 4 5 6 7 8 9 ⟩\n$ ./BQN\n   foo←5\n5\n$ echo '•Show 3‿3⥊↕9' \u003e foo.bqn \u0026\u0026 ./BQN -f foo.bqn\n┌─\n╵ 0 1 2\n  3 4 5\n  6 7 8\n        ┘\n```\n\nSee the values of `•listSys` to see what system functions are available in your build of CXBQN.\n\nThe REPL also has Readline support if you enable that option at configure time.\nWhen you run cmake, pass the argument `-DCXBQN_READLINE=ON` like so:\n```console\nmkdir build \u0026\u0026 cd build\ncmake .. -DCXBQN_READLINE=ON\n```\n\nIf you have a readline library and development headers installed, this will use\nthem and provide a much nicer REPL environment with variable name completion\nlike so:\n\n```\n$ ./BQN -r\n   foo←5\n5\n   foobar←10\n10\n   # Tab once for attempted completion\n   fo\u003cTAB\u003e\n   foo\n\n   # Tab twice for all options if there is no single completion available\n   foo\u003cTAB\u003e\u003cTAB\u003e\nfoo     foobar\n   foo\n```\n\n## Configuring Options\n\n|     CMake Option     |                                                                          Notes                                                                          |\n|:--------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------:|\n| `CXBQN_READLINE`     | Enable Readline support in the BQN repl (recommended)                                                                                                   |\n| `CXBQN_MEM_STRATEGY` | Possible values include \"shared_ptr\", \"leak\", and \"gc\". \"gc\" has not been implemented yet. For best performance, select \"leak\"                          |\n| `CXBQN_BUILD_TESTS`  | Build test suite. Builds take much longer.                                                                                                              |\n| `CXBQN_LOG`          | Enable logging. You will have to set the log level above `level::off` to get output. See log file `cxbqn-debug.log` after running BQN or a test runner. |\n| `CXBQN_LOGLEVEL`     | Wrapper around spdlog's log levels. `level::debug` will produce an extremely large amount of data (~10-15gib for executing \"2+2\").                      |\n| `CXBQN_DEBUG_VM`     | Output VM debugging information, including the opcode being executed, the program counter, and any opcode arguments.                                    |\n| `CXBQN_DEEPCHECKS`   | Enable deeper checks which may produce more helpful errors but will hurt performance.                                                                   |\n| `CXBQN_CUDA`         | Enable CUDA execution via `•_CUDAFor`                                                                                                                   |\n| `CXBQN_FFI`          | Enable loading dynamic libraries and calling user functions from them.                                                                                  |\n| `CXBQN_NATIVE_R0`    | Enable native C++ implementation of some runtime functions from r0.                                                                                     |\n| `CXBQN_NATIVE_R1`    | Enable native C++ implementation of some runtime functions from r1.                                                                                     |\n| `CXBQN_PLOT`    | Enable matplotlib bindings and the namespace `•cxbqn.plot`. See [`doc/plot.md`](doc/plot.md) for more information.                                                                                     |\n\n## Specification Feature Support\n\n| Spec Item          | Compliance      | Notes                                                                                                                                        |\n|--------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------|\n| Bytecode           | Full            |                                                                                                                                              |\n| Runtime            | BQN-native and r0 | Almost all of r0 has a native implementation. We plan to replace elements of r1 with native functions as well                                                                                 |\n| System Functions   | Partial         | See `•listsys` for the supported system values. Good candidate for first contribution.                                                       |\n| Namespaces         | Partial         | Using fields of a namespace and destructuring without aliasing work, however mutable namespace fields are not supported. System-provided namespace `•file` has support for `•file.List` and `•file.Lines`.                    |\n\n## Nonstandard Extensions\n\n### GPU Execution\n\nTo build with CUDA, enable the CMake option `CXBQN_CUDA` at configure time.\nSupport for CUDA execution is limited, but it exists!\nThe primary function for CUDA execution is `•_CUDAFor`, which is a 1-modifier\nthat performs the primitive `𝕗` on array `𝕩` and optionally `𝕨`.\nIf you give this functionality a try, feel free to open an issue for any bugs you encounter (there will be many).\nHere's an example:\n\n```console\n$ cmake .. -DCXBQN_CUDA=ON\n$ make -j 12\n$ ./BQN -r\n   (↕10) × •_CUDAFor ⌽↕10\n⟨ 0 8 14 18 20 20 18 14 8 0 ⟩\n   10 + •_CUDAFor ↕15\n⟨ 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 ⟩\n```\n\n[See the WIP design document for parallel execution here](./doc/GPU.md).\n\n\u003c!--\n|      Extension     | Completion |                                                                     Notes                                                                    |\n|:------------------:|:----------:|:--------------------------------------------------------------------------------------------------------------------------------------------:|\n| GPU Execution      | Partial       | Plan to add support for primitive operations on data values (chars, numbers, strings, and arrays of any of these) on GPUs in the near future |\n| Threaded Execution | None       | Same plan as above. Needs more discussion                                                                                                    |\n| Libraries and Packaging | None       | There has been much discussion on this topic in the Matrix server, but little consensus has been reached. The first library-related feature CXBQN will support will likely look like `strings←•Import \"←strings.bqn\"` where `strings.bqn` is the strings library from Marshall's [bqn-libs repository](https://github.com/mlochbaum/bqn-libs). This will likely become a *standard library* of sorts, once consensus is reached. The first character of the string argument passed to `•Import` will have some special meaning indicating that the BQN VM ought to look in some special location (eg all directories in the environment variable `$BQNPATH`) or perform some operation before importing the specified library. |\n--\u003e\n\n### Plotting\n\nCXBQN supports bindings to matplotlib via [the matplotlib-cpp](https://github.com/lava/matplotlib-cpp) library.\nTo enable plotting, enable the CMake option `CXBQN_PLOT`.\nYou must have Python, matplotlib, and numpy installed.\n\n[See `doc/plot.md` for more information.](doc/plot.md)\n\n```console\nBQN -e '•cxbqn.plot.Plot ↕10⋄•cxbqn.plot.Show@'\n```\n![Simple Plotting Example](doc/img/simple_line_graphs.png)\n\n### FFI\n\n[See the documentation for FFI here.](doc/FFI.md)\n\n### Libraries and Packaging\n\nThere has been discussion on this topic on the Matrix server, but no consensus has been reached.\nCXBQN supports importing from locations defined in the environment variable `BQNPATH`, a `:`-delimited path just like `$PATH`.\n\nThe order in which `•Import` searches for files is:\n\n1. Current working directory\n1. The `BQNPATH` environment variable (`:` delimited)\n1. `\u003cprefix\u003e/share/bqn` where `\u003cprefix\u003e` is the installation prefix of CXBQN\n1. `/usr/share/bqn`\n\n\u003c!--\nThe first character of the string argument passed to `•Import` will have some special meaning indicating that the BQN VM ought to look in some special location (eg all directories in the environment variable `$BQNPATH`) or perform some operation before importing the specified library.\n--\u003e\n\n### Custom Namespace `•cxbqn`\n\nEverything under the namespace `•cxbqn` is specific to the CXBQN implementation of BQN.\nAs of v0.10.4, only the value `•cxbqn.config` is available under this namespace:\n\n```console\n$ ./BQN -p '•cxbqn.config'\n⟨ ⟨ \"CXBQN_READLINE\" 1 ⟩ ⟨ \"CXBQN_CUDA\" 0 ⟩ ⟨ \"CXBQN_FFI\" 0 ⟩ ⟨ \"CXBQN_PLOT\" 0 ⟩ ⟩\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashermancinelli%2Fcxbqn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashermancinelli%2Fcxbqn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashermancinelli%2Fcxbqn/lists"}