From dd7badf140157f86581870626f68bd1a1a0fcc8c Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Wed, 30 Nov 2022 19:00:09 -0500 Subject: Cut outdated or duplicated parts from running.md and improve explanations --- docs/running.html | 35 ++++++++++++----------------------- 1 file changed, 12 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/running.html b/docs/running.html index 55f78056..cb54f53f 100644 --- a/docs/running.html +++ b/docs/running.html @@ -5,7 +5,7 @@
(github) / BQN

How to run BQN

-

CBQN is the primary offline implementation. Scripts in this repository start with #! /usr/bin/env bqn in order to look up the user's bqn executable, which is expected to be CBQN.

+

CBQN is the primary offline implementation, and has build instructions in its own repository. Here and elsewhere it's expected to be installed as bqn. For Windows, build in WSL or see WinBQN below.

Third-party packages are available for Windows and a few Linux distributions. Because they run on an unknown target system, none of these packages are built with the highest-performance settings. If you need top speed (you probably don't!) you should compile CBQN for the target hardware instead.

@@ -39,7 +39,7 @@

For tools related to running BQN, see the editor plugins and fonts page.

-

All these websites run BQN (on your computer, except the CBQN ones):

+

All these websites run BQN, in your browser unless marked with "server-side" (JS is native Javascript; the Wasm engine is WebAssembly compiled from CBQN).

@@ -102,36 +102,25 @@ - +
week.golf Challenge CBQNCode golfCode golf, server-side
-

Further details in the sections below.

-

Self-hosted BQN

-

This version of BQN is implemented mainly in BQN itself, but a host language supplies basic functionality and can also replace primitives for better performance. This also allows embedding, where programs in the host language can include BQN code. It fully supports all functionality specified so far. System value support varies as it's implemented separately in each host.

-

Support in the following languages has been implemented (details in the subsections below):

+

Details about CBQN as well as the Javascript and other implementations follow.

+

Self-hosted BQN

+

Both CBQN and JS BQN are implemented using components written in BQN itself: the compiler, and primitive implementations. The host language provides a bytecode VM and basic functionality for the primitives, and can replace primitives with native implementations for better performance. It also provides system values, so that which ones are supported depends on the host. This setup allows embedding, where programs in the host language can evaluate BQN code.

+

Support in the following languages has been implemented:

-

Javascript

The file docs/bqn.js is zero-dependency Javascript, and can be loaded from HTML or Node.js. For command line use, call the Node.js script bqn.js, passing a file and •args, or -e to execute all remaining arguments directly and print the results.

-

CBQN

-

C sources are kept in the CBQN repository, but it also depends on bytecode from the BQN sources here. Running make gets a working copy right away with saved bytecode. Then to use the latest bytecode, call $ ./BQN genRuntime …/BQN, where …/BQN points to this repository, and run make again.

-

CBQN is developed on Linux, and as-is will only run on Unix-like systems (including macOS). To run on Windows, WSL has the best support but there are also native builds based on each of Cygwin and Mingw here.

-

genRuntime can also be run with another BQN implementation (the Node.js one works but takes up to a minute), and plain ./genRuntime uses your system's bqn executable. I symlink …/CBQN/BQN to ~/bin/bqn so I can easily use CBQN for scripting.

-

CBQN has native support for most primitive functionality and falls back to the self-hosted runtime to fill the gaps. The most important operations are fast, and it's almost always possible to write code that sticks to them. However, some cases, particularly those that deal with multiple axes, are much slower (although still fine for most use cases).

-

dzaima/BQN

+

dzaima/BQN

dzaima/BQN is an implementation in Java created by modifying the existing dzaima/APL, and should be easy to run on desktop Linux and Android. It was historically the main implementation, but is now updated only to stay up to date with language changes. Major missing functionality is dyadic Depth (⚇) and set functions ⊐⊒∊⍷ with rank >1, and there are various small differences from the BQN spec, mostly to do with rank, handling of atoms, fills, and headers. It uses UTF-16 instead of UTF-32, so that characters like 𝕩 don't behave correctly.

-

To get an executable that works like CBQN, make a script with the following contents. Scripts may use #! /usr/bin/env dbqn to run with dzaima/BQN specifically, but this is rare now (in this repository, only test/dzaima does it).

-
#! /bin/bash
-
-java -jar /path/to/dzaima/BQN/BQN.jar "$@"
-
-

If compiled with Native Image, nBQN can be used directly instead.

-

BQN2NGN

+

The only remaining dzaima/BQN script here is test/dzaima, which can be used to test the self-hosted primitives but has been superseded by test/unit.

+

BQN2NGN

BQN2NGN is a prototype implementation in Javascript built to experiment with the language. It's now abandoned.

-- cgit v1.2.3