https://github.com/daniel-boll/beam-sys
🔦 Rust library designed for the creation and manipulation of BEAM (Erlang VM) bytecode
https://github.com/daniel-boll/beam-sys
beam codegen erlang erlang-beam erlang-vm rust
Last synced: 10 months ago
JSON representation
🔦 Rust library designed for the creation and manipulation of BEAM (Erlang VM) bytecode
- Host: GitHub
- URL: https://github.com/daniel-boll/beam-sys
- Owner: Daniel-Boll
- License: mit
- Created: 2023-12-30T23:19:41.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-12-30T23:34:47.000Z (over 2 years ago)
- Last Synced: 2025-04-10T04:07:27.456Z (about 1 year ago)
- Topics: beam, codegen, erlang, erlang-beam, erlang-vm, rust
- Language: Rust
- Homepage: https://beam-sys.org
- Size: 436 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
🔦 beam-sys
> A Rust library designed for the creation and manipulation of BEAM (Erlang VM) bytecode
The `beam_sys` project is a personal exploration and it try to provide an intuitive API to generate `.beam` files, abstracting the intricacies of lower-level details. This project is inspired by the [Tsoding](https://github.com/tsoding) [bada project](https://github.com/tsoding/bada) and incorporates ideas from the [`llvm-sys`](https://lib.rs/crates/llvm-sys) and [`cranelift`](https://lib.rs/crates/cranelift) crates.
## Features
- **Shared Context Management:** Uses a shared context (`beam_sys::context::Context`) for enhanced code generation.
- **High-Level Abstractions:** Offers high-level constructs to build functions, manage export tables, and handle bytecode encoding.
- **Erlang VM Compatibility:** Generated bytecode seamlessly integrates with Erlang systems.
## Usage Examples
### Basic Example
To create a `.beam` file:
```rust
use beam_sys;
fn main() {
let module = beam_sys::context::Context::create("sys".to_string());
module.add_basic_bif();
let code = module.code();
let mut function_block = code.build_function_block("empty".to_string(), 0);
{
function_block.build_return();
}
let function_metadata = function_block.function_metadata();
module.export_table_mut().export_function(function_metadata);
std::fs::write("sys.beam", module.encode()).unwrap();
}
```
Verify with Erlang shell:
```erl
1> beam_disasm:file(sys).
{beam_file,sys,
[{'-',0,2}],
[],[],
[{function,empty,0,2,
[{label,1},
{line,1},
{func_info,{atom,sys},{atom,empty},0},
{label,2},
return]}]}
```
### Context Reusability Example
Demonstrating the shared context's reusability across different functions:
```rust
use beam_sys;
fn main() {
initialize_module();
add_function();
// ... more operations
}
fn initialize_module() {
let module = beam_sys::context::Context::create("sys".to_string());
module.add_basic_bif();
// ... additional initializations
}
fn add_function() {
let module = beam_sys::context::Context::get("sys".to_string());
let code = module.code();
let mut function_block = code.build_function_block("test_func".to_string(), 0);
{
// ... build the function
function_block.build_return();
}
let function_metadata = function_block.function_metadata();
module.export_table_mut().export_function(function_metadata);
}
```
In this example, the shared context is created in `initialize_module` and reused in `add_function` without the need to pass the context around, simplifying the API usage.
## Development Status
`beam_sys` is in active development. The API is evolving and may undergo significant changes.
## Contributions
Contributions are welcome! Feel free to submit pull requests or open issues to propose features or discuss bugs.
## License
This project is under the [MIT License](LICENSE).