docs/running.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

<head>
  <link href="favicon.ico" rel="shortcut icon" type="image/x-icon"/>
  <link href="style.css" rel="stylesheet"/>
  <title>How to run BQN</title>
</head>
<div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="index.html">BQN</a></div>
<h1 id="how-to-run-bqn"><a class="header" href="#how-to-run-bqn">How to run BQN</a></h1>
<p><a href="https://github.com/dzaima/CBQN">CBQN</a> is the primary offline implementation. Scripts in this repository start with <code><span class='Comment'>#! /usr/bin/env bqn</span></code> in order to look up the user's <code><span class='Value'>bqn</span></code> executable, which is expected to be CBQN.</p>
<p>Third-party packages to build some BQN implementations are available for both Nix and Arch Linux. For general use I recommend <code><span class='Value'>cbqn</span></code> from nixpkgs (Nix) and <code><span class='Value'>cbqn</span><span class='Function'>-</span><span class='Value'>git</span></code> from the AUR (Arch).</p>
<h3 id="self-hosted-bqn"><a class="header" href="#self-hosted-bqn">Self-hosted BQN</a></h3>
<p>See the subsections below for instructions on specific implementations.</p>
<p>This version of BQN is <a href="implementation/index.html">implemented</a> mainly in BQN itself, but a host language supplies basic functionality and can also replace primitives for better performance. This also allows <a href="doc/embed.html">embedding</a>, where programs in the host language can include BQN code. It fully supports all syntax specified so far, and all primitives except a few cases of structural Under (<code><span class='Modifier2'>⌾</span></code>). System value support varies at it's implemented separately in each host.</p>
<p>Support in the following languages has been implemented:</p>
<ul>
<li><a href="https://github.com/dzaima/CBQN">C</a>, targetting high performance. Usually fairly fast.</li>
<li>Javascript, in this repository. Slow (compiles at ~5kB/s) but usable.</li>
<li>BQN (<a href="https://github.com/mlochbaum/BQN/blob/master/bqn.bqn">bqn.bqn</a>), for testing without a build step.</li>
<li><a href="https://github.com/ashermancinelli/cxbqn">C++</a>, planning to enable GPU use. Still slow; some cool features.</li>
<li><a href="https://github.com/cannadayr/rsbqn/">Rust</a>, motivated by web use (an <a href="https://github.com/cannadayr/ebqn">Erlang</a> version is abandoned as too slow).</li>
<li><a href="https://git.sr.ht/~andreypopp/BQN.jl">Julia</a> embedding, with common primitives implemented natively. Slow startup.</li>
</ul>
<h4 id="javascript"><a class="header" href="#javascript">Javascript</a></h4>
<p>The file <a href="https://github.com/mlochbaum/BQN/blob/master/docs/bqn.js">docs/bqn.js</a> is zero-dependency Javascript, and can be loaded from HTML or Node.js. For command line use, call the Node.js script <a href="https://github.com/mlochbaum/BQN/blob/master/bqn.js">bqn.js</a>, passing a file and <code><span class='Value'>•args</span></code>, or <code><span class='Function'>-</span><span class='Value'>e</span></code> to execute all remaining arguments directly and print the results.</p>
<p>Several sites run using JS-based BQN:</p>
<ul>
<li><a href="https://mlochbaum.github.io/BQN/try.html">The main online REPL</a>.</li>
<li>Razetime's <a href="https://razetime.github.io/bqn-repl/">alternative</a> runs as a continuous session so you can save results.</li>
<li><a href="https://dso.surge.sh/">Do Stuff Online</a> considers BQN to be a stuff (it's like Try It Online).</li>
<li>This <a href="https://observablehq.com/@lsh/bqn">Observable notebook</a> can be imported into other notebooks.</li>
<li><a href="https://dancek.github.io/bqn-80">BQN-80</a>: make animations with BQN.</li>
</ul>
<h4 id="cbqn"><a class="header" href="#cbqn">CBQN</a></h4>
<p>C sources are kept in the <a href="https://github.com/dzaima/CBQN">CBQN</a> repository, but it also depends on bytecode from the BQN sources here. Running <code><span class='Value'>make</span></code> gets a working copy right away with saved bytecode. Then to use the latest bytecode, call <code><span class='Value'>$</span> <span class='Value'>.</span><span class='Function'>/BQN</span> <span class='Value'>genRuntime</span> <span class='Value'>…</span><span class='Function'>/BQN</span></code>, where <code><span class='Value'>…</span><span class='Function'>/BQN</span></code> points to this repository, and run <code><span class='Value'>make</span></code> again.</p>
<p><code><span class='Value'>genRuntime</span></code> can also be run with another BQN implementation (the Node.js one works but takes up to a minute), and plain <code><span class='Value'>.</span><span class='Function'>/</span><span class='Value'>genRuntime</span></code> uses your system's <code><span class='Value'>bqn</span></code> executable. I symlink <code><span class='Value'>…</span><span class='Function'>/CBQN/BQN</span></code> to <code><span class='Value'>~</span><span class='Function'>/</span><span class='Value'>bin</span><span class='Function'>/</span><span class='Value'>bqn</span></code> so I can easily use CBQN for scripting.</p>
<p>CBQN uses the self-hosted runtime to achieve full primitive coverage, and implements specific primitives or parts of primitives natively to speed them up. This means primitives with native support—including everything used by the compiler—are fairly fast while others are much slower.</p>
<h3 id="dzaimabqn"><a class="header" href="#dzaimabqn">dzaima/BQN</a></h3>
<p><a href="https://github.com/dzaima/BQN/">dzaima/BQN</a> 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. It has almost complete syntax support but incomplete primitive support: major missing functionality is dyadic Depth (<code><span class='Modifier2'>⚇</span></code>), Windows (<code><span class='Function'>↕</span></code>), and many cases of set functions (<code><span class='Function'>⊐⊒∊⍷</span></code>, mostly with rank &gt;1).</p>
<p>To get an executable that works like CBQN, make a script with the following contents. Scripts may use <code><span class='Comment'>#! /usr/bin/env dbqn</span></code> to run with dzaima/BQN specifically, but this is rare now (in this repository, only <code><span class='Value'>test</span><span class='Function'>/</span><span class='Value'>dzaima</span></code> does it).</p>
<pre><span class='Comment'>#! /bin/bash
</span>
<span class='Value'>java</span> <span class='Function'>-</span><span class='Value'>jar</span> <span class='Function'>/</span><span class='Value'>path</span><span class='Function'>/</span><span class='Value'>to</span><span class='Function'>/</span><span class='Value'>dzaima</span><span class='Function'>/BQN/BQN</span><span class='Value'>.jar</span> <span class='String'>&quot;$@&quot;</span>
</pre>
<p>If compiled with Native Image, <code><span class='Value'>nBQN</span></code> can be used directly instead.</p>
<h3 id="bqn2ngn"><a class="header" href="#bqn2ngn">BQN2NGN</a></h3>
<p><a href="https://github.com/mlochbaum/BQN2NGN">BQN2NGN</a> is a prototype implementation in Javascript built to experiment with the langauge. It's now abandoned.</p>