Introduction to Onyx

What is Onyx?

It is a new programming language with wasm as its primary compilation target.

It officially provides a compiler, package manager, LSP, editor support like VSCode Extension, and more.

Syntactically, it is influenced by languages like Go, Jai, and Odin. Its base is a C-like syntax. Personally, features like custom allocators and data-oriented memory layout look distinctive. Also, you can write functional-like processing chains using the pipe operator |>.

It compiles directly to wasm binaries without using LLVM or Binaryen. The compiler is written in C.

Installation

There don't seem to be Homebrew or npm packages yet, so running an installation script seems to be the only way for now.
First, it asks whether to install a runtime. You have three options: wasmer, OVM (Onyx VM?), or None.

$ sh <(curl https://get.onyxlang.io -sSfL)
                   ######
               ####++++++###
            ###+++++++++++++###
         ###+++++++++++++++++++###
      ###++++++++++++++++++++++++++###
  ###+++++++++++++++++++++++++++++++++###
  #++++++++++++++++++++++++++++++++++++#-#
  #--------------------------------++#####
  #-----------------------------+##+++####
  #--------------------------+##+++++#####      The Onyx Programming Language
  #-----------------------+##+++++++######
  #--------------------##++++++++++#######             Brendan Hansen
  #----------------+##+++++++++++#########
  #-------------+##+++++++++++++##########
  #----------##++++++++++++++++###########
  #------+##++++++++++++++++++############
  #---+##++++++++++++++++++++#############
  ####++++++++++++++++++++++##############
  ###++++++++++++++++++++++##############
     ####+++++++++++++++++############
         ###+++++++++++++##########
            ###+++++++++########
               ####++++######
                   ######


Please choose a WebAssembly runtime to use with your Onyx installation.
1) Wasmer: An industry standard WebAssembly runtime. Very fast. (default)
2) OVM: A custom, lightweight runtime made for Onyx. Supports debugging. Slower than Wasmer.
3) None: Omit using a runtime and only use Onyx as a compiler to WebAssembly.
Which runtime would you like to use? [1/2/3] 1
downloading: onyx-darwin-wasmer-arm64
Latest release: v0.1.8-beta
Downloading archive from https://github.com/onyx-lang/onyx/releases/download/v0.1.8-beta/onyx-darwin-wasmer-arm64.tar.gz

100.0%
installing: /Users/****/.onyx
Updating bash profile /Users/****/.zshrc
we've added the following to your /Users/****/.zshrc
If you have a different profile please add the following:
# Onyx config
export ONYX_PATH="/Users/****/.onyx"
export PATH="$ONYX_PATH/bin:$PATH"
check: Error: ONYX_PATH environment variable is not set. Please set this to the location of your Onyx installation. installed successfully ✓
onyx will be available the next time you open the terminal.

If you choose 2 for Which runtime would you like to use? [1/2/3], it might not support Apple Silicon as it crashed with the following message. Unfortunate. So, I specified 1 (wasmer) as the runtime above.

downloading: onyx-darwin-ovm-arm64
Latest release: v0.1.8-beta
Downloading archive from https://github.com/onyx-lang/onyx/releases/download/v0.1.8-beta/onyx-darwin-ovm-arm64.tar.gz

100.0%
error: Your platform is not yet supported (darwin-ovm-arm64).
Please open an issue on the Onyx repository if you want to use Onyx in your project: https://github.com/onyx-lang/onyx

Verifying Installation

The path was set automatically; in my environment, it seems the path settings or something were written to .zshrc.

$ tail -3 ~/.zshrc
# Onyx config
export ONYX_PATH="~/.onyx"
export PATH="$ONYX_PATH/bin:$PATH"

I moved this description to an appropriate place myself. Keeping it as is should also be fine.

Looking at the installation directory, it contained many sample code files.

$ ls ~/.onyx
LICENSE  bin      core     examples include  lib      misc     tests    tools

$ ls ~/.onyx/bin
onyx

$ ls ~/.onyx/examples
01_hello_world.onyx       04_fixed_arrays.onyx      07_structs.onyx           10_switch_statements.onyx 13_use_keyword.onyx       16_pipe_operator.onyx     19_do_blocks.onyx         22_interfaces.onyx
02_variables.onyx         05_slices.onyx            08_enums.onyx             11_map.onyx               14_overloaded_procs.onyx  17_operator_overload.onyx 20_auto_return.onyx       50_misc.onyx
03_basics.onyx            06_dynamic_arrays.onyx    09_for_loops.onyx         12_varargs.onyx           15_polymorphic_procs.onyx 18_macros.onyx            21_quick_functions.onyx

However, there were no samples that seemed to run in the browser among these examples.

Let's try running the onyx command.

$ onyx
zsh: command not found: onyx

As suggested by the message during installation, I reopened the shell and tried again.

$ onyx
Onyx toolchain version v0.1.8
Built on Wed Nov 29 01:49:45 2023
Runtime: wasmer-custom

The toolchain for the Onyx programming language, created by Brendan Hansen.

Usage:
	onyx <subcommand>

Subcommands:
	help      Shows this help message. Use "onyx help <subcommand>".
	build     Compiles an Onyx program into an executable.
	run       Compiles and runs an Onyx program, all at once.
	check     Checks syntax and types of an Onyx program.
	package   Package manager
	version   Prints version information

It ran without issues.

Hello, World

Create a file named hello.onyx and write the following code:

use core {*}

main :: () {
    println("Hello, World!");
}

The run subcommand handles compilation and execution all at once.

$ onyx run hello.onyx
Hello, World!

Next, let's compile it into a wasm binary. The run command does not generate a binary file; you need to use the build command for that.

$ onyx build hello.onyx -o hello.wasm

$ onyx run hello.wasm
Hello, World!

It doesn't seem to generate a .wat file, so let's take a look at the binary.

The first bytes are 4F 4E 59 58, which spells O N Y X. Wait, shouldn't the first bytes of a standard wasm binary be the magic number 00 61 73 6D (\0 a s m)^[1]?

(Update 2024-01-08) In a Discord exchange, the creator Brendan Hansen mentioned that this behavior of Onyx creating wasm binaries in a non-standard way has already been fixed in nightly and will be included in v0.19.

From https://discord.com/channels/1180961614984388683/1181249331630719036/1190788434378358956

👋 To compile Onyx to be able to be run in the browser, you need to specify the -r js flag. This tell it to use the javascript platform layer. The error you are hitting is that in the 0.1.8 and previous versions, Onyx made WASM binaries in a non-standard way when compiling for Onyx's runtime (not WASI or JS). The magic bytes were changed from \x00asm to ONYX, hence the bytes being 4f 4e 59 58. This was deemed a very bad decision and in the nightly release of the compiler, this is fixed. The nightly version will become version 0.1.9 soon, there are just a couple of outstanding thing I am working on first

Development Environment

An official VSCode Extension is available.

https://marketplace.visualstudio.com/items?itemName=onyxlang.onyxlang

Installing it enables syntax highlighting.

There isn't a README, so the exact features aren't very clear, but it does mention that a debugger is included. The repository is part of a monorepo within Onyx itself → https://github.com/onyx-lang/onyx/tree/master/misc/vscode

Next Steps

I have also written a follow-up article.
https://zenn.dev/hatappo/articles/09ff4f8546f805

脚注

1. I assume this is related to the history from the days of asm.js and such.