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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

<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>CBQN is the primary offline implementation, and has <a href="https://github.com/dzaima/CBQN">build instructions in its own repository</a>. Here and elsewhere it's expected to be installed as <code><span class='Value'>bqn</span></code>. For Windows, build in <a href="https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux">WSL</a> or see WinBQN below.</p>
<p>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.</p>
<table>
<thead>
<tr>
<th>OS/distro</th>
<th>Package</th>
<th>Type</th>
</tr>
</thead>
<tbody>
<tr>
<td>Windows download</td>
<td><a href="https://github.com/actalley/WinBQN">WinBQN</a></td>
<td>Binary</td>
</tr>
<tr>
<td>Arch AUR</td>
<td><code><span class='Value'>cbqn</span><span class='Function'>-</span><span class='Value'>git</span></code></td>
<td>Source</td>
</tr>
<tr>
<td>Nix</td>
<td><code><span class='Value'>cbqn</span></code></td>
<td>Source/Binary</td>
</tr>
<tr>
<td>Guix</td>
<td><code><span class='Value'>cbqn</span></code></td>
<td>Source/Binary</td>
</tr>
</tbody>
</table>
<p>For tools related to running BQN, see the <a href="editors/index.html">editor plugins</a> and <a href="https://mlochbaum.github.io/BQN/fonts.html">fonts page</a>.</p>
<p>All these websites run BQN, in your browser unless marked with &quot;server-side&quot; (JS is native Javascript; the Wasm engine is WebAssembly compiled from CBQN).</p>
<table>
<thead>
<tr>
<th>Link</th>
<th>Style</th>
<th>Engine</th>
<th>Comments</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://mlochbaum.github.io/BQN/try.html">Online REPL</a></td>
<td>One-shot</td>
<td>JS</td>
<td>&quot;Explain&quot;, error marker</td>
</tr>
<tr>
<td><a href="https://bqnpad.mechanize.systems/">BQNPAD</a></td>
<td>Session</td>
<td>JS, Wasm</td>
<td>Preview, syntax coloring</td>
</tr>
<tr>
<td><a href="https://ato.pxeger.com/run?1=m704qTBvwYKlpSVpuhZoFJQGAA">Attempt This Online</a></td>
<td>TIO</td>
<td>CBQN</td>
<td>Server-side</td>
</tr>
<tr>
<td><a href="https://dso.surge.sh/#bqn">Do Stuff Online</a></td>
<td>TIO</td>
<td>JS</td>
<td></td>
</tr>
<tr>
<td><a href="https://razetime.github.io/bqn-repl/">Razetime</a></td>
<td>Session</td>
<td>JS</td>
<td></td>
</tr>
<tr>
<td><a href="https://ktye.github.io/zoo/index.html#bqn">ktye/zoo</a></td>
<td>Session</td>
<td>JS</td>
<td>Many array languages</td>
</tr>
<tr>
<td><a href="https://observablehq.com/@lsh/bqn">Observable</a></td>
<td>Notebook</td>
<td>JS</td>
<td>For import in Observable</td>
</tr>
<tr>
<td><a href="https://dancek.github.io/bqn-80">BQN-80</a></td>
<td>One-shot</td>
<td>JS</td>
<td>Create animations</td>
</tr>
<tr>
<td><a href="https://week.golf">week.golf</a></td>
<td>Challenge</td>
<td>CBQN</td>
<td>Code golf, server-side</td>
</tr>
</tbody>
</table>
<p>Details about CBQN as well as the Javascript and other implementations follow.</p>
<h2 id="self-hosted-bqn"><a class="header" href="#self-hosted-bqn">Self-hosted BQN</a></h2>
<p>Both CBQN and JS BQN are <a href="implementation/index.html">implemented</a> 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 <a href="doc/embed.html">embedding</a>, where programs in the host language can evaluate BQN code.</p>
<p>Support in the following languages has been implemented:</p>
<ul>
<li><a href="https://github.com/dzaima/CBQN">CBQN</a> in C, targeting high <a href="implementation/perf.html">performance</a> with mostly native primitives.</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/andreypopp/BQN.jl">Julia</a> embedding, with common primitives implemented natively. Slow startup.</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). Note that CBQN <a href="https://detegr.github.io/cbqn-rs/cbqn/">can run from Rust</a> as well.</li>
</ul>
<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>
<h2 id="dzaimabqn"><a class="header" href="#dzaimabqn">dzaima/BQN</a></h2>
<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. Major missing functionality is dyadic Depth (<code><span class='Modifier2'>⚇</span></code>) and set functions <code><span class='Function'>⊐⊒∊⍷</span></code> with rank &gt;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 <code><span class='Value'>𝕩</span></code> don't behave correctly.</p>
<p>The only remaining dzaima/BQN script here is <code><span class='Value'>test</span><span class='Function'>/</span><span class='Value'>dzaima</span></code>, which can be used to test the self-hosted primitives but has been superseded by <code><span class='Value'>test</span><span class='Function'>/</span><span class='Value'>unit</span></code>.</p>
<h2 id="bqn2ngn"><a class="header" href="#bqn2ngn">BQN2NGN</a></h2>
<p><a href="https://github.com/mlochbaum/BQN2NGN">BQN2NGN</a> is a prototype implementation in Javascript built to experiment with the language. It's now abandoned.</p>