|
|
||
|---|---|---|
| build | ||
| docs | ||
| include | ||
| licenses | ||
| src | ||
| test | ||
| .gitignore | ||
| .gitmodules | ||
| makefile | ||
| README.md | ||
A BQN implementation in C
CBQN-specific documentation • source code overview
Running
make- Third-party packages and other ways to run BQN are listed here
make REPLXX=1to enable replxx (syntax highlighting & some system/variable name completion)make CC=ccifclangisn't installed- Use
gmakeon BSD (aNO_LDL=1make arg may be useful if the linker complains about-ldl) make FFI=0if your system doesn't have libffi (ifpkg-configdoesn't exist, extra configuration may be necessary to allow CBQN to find libffi)- Run
sudo make installafterwards to install into/usr/local/bin/bqn(aPREFIX=/some/pathargument will install to/some/path/bin/bqn);sudo make uninstallto uninstall make cleanif anything breaks and you want a clean build slate
./BQN somefile.bqnto execute a file, orrlwrap ./BQNfor a REPL (or just./BQNif replxx is enabled)
Configuration options
-
Builds with more performance:
make o3n-singeli- native for the current processor (i.e.-march=native); on x86-64 this assumes & uses AVX2 (and, if available, also uses BMI2)make o3-singeli- generic build for the current architecture; on x86-64 or unknown architectures this doesn't do much, but on aarch64 it uses NEON
Therefore, on x86-64,o3n-singeliis highly recommended, but, on aarch64,o3-singeliis enoughmake o3-singeli has=avx2- generic build for any x86-64 CPU that supports AVX2 (won't utilize BMI2 though;has='avx2 bmi2'to assume both AVX2 & BMI2)make o3n-singeli has=slow-pdep- build tuned for AMD Zen 1/Zen 2 CPUs, which have BMI2, but their pdep/pext instructions are extremely slow- Target architecture is decided by
uname -sm- override withtarget_arch=x86-64/target_arch=aarch64; and extensions by/proc/cpuinfo(orsysctl machdep.cpuon macOS), and C macro checks, for native builds
-
Build flags:
CC=cc- choose a different C compiler (default isclang)CXX=c++- choose a different C++ compiler (default isc++)f=...- add extra C compiler flags for CBQN file compilationlf=...- add extra linker flagsCCFLAGS=...- add flags for all CC/CXX/linker invocationsREPLXX=1- enable/disable replxx (default depends on target and may change in the future)REPLXX_FLAGS=...- override replxx build flags (default is-std=c++11 -Os)FFI=0- disable libffi usagej=8to override the default parallel job countOUTPUT=path/to/somewhere- change output location; foremcc-o3it will be the destination folder ofBQN.jsandBQN.wasm, for everything else - the filename- For build targets which use build.bqn (currently all the
-singeli&shared-ones),target_archandtarget_osoptions can be added, specifying the target architecture/OS (mostly just changing library loading defaults/Singeli configuration; if cross-compiling, further manual configuration will be necessary)
-
More build types:
make o3--O3; currently the default buildmake shared-o3- produce a shared librarylibcbqn.so/libcbqn.dylib/cbqn.dllmake o3g--O3 -gmake o3g-singeli/make o3ng-singeli- Singeli builds with-gmake debug- unoptimized build with extra assertion checks (also includes-g)make debug1- debug build without parallel compilation. Useful if everything errors, and you don't want error messages from multiple threads to be printed at the same time.make c- a build with minimal default settings, for manual customizingmake shared-c- likemake cbut for a shared librarymake single-(o3|o3g|debug|c)- compile everything as a single translation unit. Won't have incremental/parallel compilation, and isn't supported for many configurationsmake emcc-o3- build with Emscriptenemccmake wasi-o3- build targeting WASI
-
Git submodules are used for Singeli, replxx, and bytecode. It's possible to override those by linking/copying a local version to, respectively,
build/singeliLocal,build/replxxLocal, andbuild/bytecodeLocal.
Precompiled bytecode
CBQN uses the self-hosted BQN compiler & some parts of the runtime, and therefore needs to be bootstrapped. By default, the CBQN will use precompiled bytecode.
In order to build everything from source, you can:
option 1: use another BQN implementation
- dzaima/BQN is a BQN implementation that is completely implemented in Java (clone it & run
./build) - clone mlochbaum/BQN
mkdir -p build/bytecodeLocal/genother-bqn-impl ./build/genRuntime path/to/mlochbaum/BQN build/bytecodeLocal
In the case of the Java impl,java -jar path/to/dzaima/BQN/BQN.jar ./build/genRuntime path/to/mlochbaum/BQN build/bytecodeLocal
option 2: use the bootstrap compilers
- clone mlochbaum/BQN
mkdir -p build/bytecodeLocal/gen && make for-bootstrap && ./BQN build/bootstrap.bqn path/to/mlochbaum/BQN
Note that, after either of those, the compiled bytecode may become desynchronized if you later update CBQN without also rebuilding the bytecode. Usage of the submodule can be restored by removing build/bytecodeLocal.
Requirements
CBQN requires either gcc or clang as the C compiler (it defaults to clang as optimizations are written based on whether or not clang needs them, but a CC=cc make arg can be added to use the default system compiler), and, optionally, libffi for •FFI, and C++ (requires ≥C++11; defaults to c++, override with CXX=your-c++) for replxx.
There aren't hard requirements for versions of any of those, but nevertheless here are some configurations that CBQN is tested on by dzaima:
x86-64 (Linux):
gcc 9.5; gcc 11.3; clang 10.0.0; clang 14.0.0
libffi 3.4.2
cpu microarchitecture: Haswell
replxx: g++ 11.3.0
x86 (Linux):
clang 14.0.0; known to break on gcc - https://gcc.gnu.org/bugzilla/show_bug.cgi?id=58416
running on the above x86-64 system, compiled with CCFLAGS=-m32
AArch64 ARMv8-A (within Termux on Android 8):
using a `lf=-landroid-spawn` make arg after `pkg install libandroid-spawn` to get •SH to work
clang 15.0.7
libffi 3.4.4 (structs were broken as of 3.4.3)
replxx: clang++ 15.0.4
Additionally, CBQN is known to compile as-is on macOS, but Windows builds need WinBQN to set up an appropriate Windows build environment, or be built from Linux by cross-compilation.
License
Most files here are copyright (c) 2021-2023 dzaima & others, GNU GPLv3 only. Exceptions are:
- timsort implementation -
src/builtins/sortTemplate.h: MIT; original repo - Ryu -
src/utils/ryu.c& files insrc/utils/ryu/: Apache 2.0 or Boost 1.0; original repo