Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Expand documentation with risks and status.
Include a local rebar3 build to include erlang/rebar3#2863.
Extend commands to use path environment variable to prevent erlang/otp header mismatch.
  • Loading branch information
cannadayr authored May 18, 2024
1 parent 191487d commit 44c2db6
Showing 1 changed file with 24 additions and 7 deletions.
31 changes: 24 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,36 @@
## BeamQN

An experiment in linking [CBQN](https://github.com/dzaima/CBQN) into the Erlang BEAM as a NIF.
An experiment in linking [CBQN](https://github.com/dzaima/CBQN) into the Erlang BEAM as a NIF.

### Status

BeamQN is experimental software and is **not ready for production use**. Use at your own risk!

The risks of using this library include, but are not limited to:
* Memory leaks
* Scheduler collapse
* Undefined behavior
* System crash

In order to rapidly identify bugs, it is recommended to develop BeamQN applications using a debug enabled Erlang runtime system.
A general guide for building a debug enabled Erlang runtime system and the latest Rebar3 build tool is below.

### Build (Development)

1. Download and extract the latest Erlang/OTP release tarball from the [downloads page](https://www.erlang.org/downloads).
2. Export `$ERL_TOP` to the path of the extracted source.
3. [Build Erlang/OTP from the release tarball.](https://www.erlang.org/doc/installation_guide/install#how-to-build-and-install-erlang-otp)
4. [Build the debug enabled runtime system.](https://www.erlang.org/doc/installation_guide/install#Advanced-configuration-and-build-of-ErlangOTP_Building_How-to-Build-a-Debug-Enabled-Erlang-RunTime-System)
5. Using the compiled runtime for development:
6. [Install Rebar3 from source using the latest Erlang/OTP release tarball.](https://rebar3.org/docs/getting-started/#installing-from-source)
```
env PATH=$ERL_TOP:$PATH ./bootstrap
```
7. Export `$REBAR_TOP` to the path of the rebar3 source.
8. Using the compiled runtime for development:

#### Debug

$ PATH="$ERL_TOP/bin:$PATH" rebar3 compile
$ PATH="$ERL_TOP/bin:$PATH" cerl -debug +pc unicode -pa ebin -pa ./_build/default/lib/*/ebin
$ env PATH=$ERL_TOP/bin:$PATH $REBAR_TOP/rebar3 compile
$ env PATH=$ERL_TOP/bin:$PATH cerl -debug +pc unicode -pa ebin -pa ./_build/default/lib/*/ebin

### Installation (Erlang)

Expand Down Expand Up @@ -41,13 +58,13 @@ end

Documentation can be generated with [EDoc](https://www.erlang.org/doc/man/edoc).
```
rebar3 edoc
env PATH=$ERL_TOP/bin:$PATH $REBAR_TOP/rebar3 edoc
```
Once generated, the docs can be found at `/doc/`.

### Testing

Tests can be ran with [EUnit](https://www.erlang.org/doc/apps/eunit/).
```
rebar3 eunit
env PATH=$ERL_TOP/bin:$PATH $REBAR_TOP/rebar3 eunit
```

0 comments on commit 44c2db6

Please sign in to comment.