Set up

Three steps. Ten minutes, most of it waiting for a download.

star-burxt is written in Burxt, so Burxt is the one thing you install — the way you install PHP before Laravel, or Node before React. After that, star-burxt is a line in your project file.

1. Install Burxt

Follow burxt-lang.org/install. Then check it worked:

burxt --version

Burxt 1.3.0 or newer. Earlier releases refuse two things every component does — an update function returning a record that holds a list, and a pure function calling the JSON encoder — so a component will not compile against 1.2.0 or below. A released version is all you need; there is nothing to build from source.

That floor is verified rather than remembered, which it had not been: the 1.3.0 tarball is downloaded, the three commands below are built with its binary and its library, a component is generated and compiled, and the two things the sentence names are compiled directly. A floor nothing builds against is a capability claim, and this one had gone two minor versions unchecked — the suggestion to test it by downloading the old release rather than by raising the number is the language session’s, and it took ten minutes.

Then check the standard library, because the version alone does not. Every component star generates opens with use "std/html.bx", and a compiler that cannot resolve that checks nothing — every document you write reports an error and none of the errors are about your document.

printf 'use "std/html.bx";\n' > /tmp/probe.bx && burxt check /tmp/probe.bx
#  /tmp/probe.bx: no errors     ← ready

burxt --version will not tell you this. It prints a number a broken install prints just as happily, and the number does not move until Burxt tags a release — so it cannot even distinguish two builds. The probe asks the only question that matters.

If it fails, the usual cause is a second Burxt earlier in your PATH. The library is found by the compiler’s own installation — BURXT_LIB, or ../lib/burxt beside the binary — never by proximity to your program, so an old binary that shadows a good install takes its missing library with it. Run which -a burxt: if there is more than one, the first is the one you are using.

2. Make a project

A project is a folder with a file called burxt.package in it:

name        my-app
version     0.1.0

dependency  star  https://github.com/andrecorugda/star-burxt  v0.2.0
dependency  bmx   https://github.com/andrecorugda/bmx         burxt-0.12.1

Then:

burxt fetch

That downloads both and writes burxt.lock. Keep burxt.lock — it is what makes your teammate’s build match yours.

Why two lines and not one. star-burxt uses BMX to read your documents, and a Burxt project names everything it uses, including what its own libraries use. If you forget the second line you will see this, and it is not a mistake in your code:

error: cannot read .../bmx/burxt/bmx.bx: No such file or directory

Add the line and it goes away.

burxt-0.12.1 is not a typo for the format’s version. BMX the format has its own number; that tag names the Burxt implementation of it, which is a separate thing released on its own schedule.

3. Build the three commands

They are Burxt programs, and you build them once:

git clone https://github.com/andrecorugda/star-burxt && cd star-burxt
burxt build examples/generate.bx -o star-generate
burxt build examples/check.bx    -o star-check
burxt build examples/build.bx    -o star-build

star-generate prints the component it made, and you are meant to read that output. Nothing is hidden in it, and watching your document turn into ordinary code is the quickest way to see what star-burxt does for you.

That’s it

Chapter 1: Your first component →

If something goes wrong

pure function view may not call html_element… — your Burxt is too old. Step 1.

cannot read .../bmx/burxt/bmx.bx — the second dependency line is missing. Step 2.

main is a name the language owns — a Burxt program is just statements, top to bottom. Delete the function main() { wrapper and un-indent what was inside it.