Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/newcomb-luke/kerbalobjects.rs

KerbalObjects is a Rust crate that allows anyone to read or write a Kerbal Machine Code or Kerbal Object file.
https://github.com/newcomb-luke/kerbalobjects.rs

compiler kasm kerbal kerbal-space-program klinker krisc linker rust

Last synced: about 1 month ago
JSON representation

KerbalObjects is a Rust crate that allows anyone to read or write a Kerbal Machine Code or Kerbal Object file.

Host: GitHub
URL: https://github.com/newcomb-luke/kerbalobjects.rs
Owner: newcomb-luke
License: gpl-3.0
Created: 2020-11-12T00:47:21.000Z (about 4 years ago)
Default Branch: main
Last Pushed: 2023-06-21T00:13:11.000Z (over 1 year ago)
Last Synced: 2024-11-18T19:48:39.889Z (about 2 months ago)
Topics: compiler, kasm, kerbal, kerbal-space-program, klinker, krisc, linker, rust
Language: Rust
Homepage:
Size: 927 KB
Stars: 4
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        # KerbalObjects

[](https://github.com/newcomb-luke/kerbalobjects.rs)

[](https://crates.io/crates/kerbalobjects)

[](https://docs.rs/kerbalobjects/latest/kerbalobjects/)

[]()

[]()

[]()

[](https://deps.rs/repo/github/newcomb-luke/kerbalobjects.rs)

A Rust crate that allows anyone to read or write a Kerbal Machine Code file or Kerbal Object file.

```toml

[dependencies]

kerbalobjects = "4.0"

```

## Examples

### Example for Kerbal Machine Code hello world program

```rust

use std::io::Write;

use kerbalobjects::ksm::sections::{ArgumentSection, CodeSection, CodeType, DebugEntry, DebugRange, DebugSection};

use kerbalobjects::ksm::{Instr, KSMFile};

use kerbalobjects::{Opcode, KOSValue, ToBytes};

let mut arg_section = ArgumentSection::new();

let mut main_code = CodeSection::new(CodeType::Main);

let one = arg_section.add_checked(KOSValue::Int16(1));

// Corresponds to the KerbalScript code:

// PRINT("Hello, world!").

main_code.add(Instr::OneOp(Opcode::Push, arg_section.add_checked(KOSValue::String("@0001".into()))));

main_code.add(Instr::TwoOp(Opcode::Bscp, one, arg_section.add_checked(KOSValue::Int16(0))));

main_code.add(Instr::ZeroOp(Opcode::Argb));

main_code.add(Instr::OneOp(Opcode::Push, arg_section.add_checked(KOSValue::ArgMarker)));

main_code.add(Instr::OneOp(Opcode::Push, arg_section.add_checked(KOSValue::StringValue("Hello, world!".into()))));

main_code.add(Instr::TwoOp(Opcode::Call, arg_section.add_checked(KOSValue::String("".into())), arg_section.add_checked(KOSValue::String("print()".into()))));

main_code.add(Instr::ZeroOp(Opcode::Pop));

main_code.add(Instr::OneOp(Opcode::Escp, one));

let code_sections = vec![

    CodeSection::new(CodeType::Function),

    CodeSection::new(CodeType::Initialization),

    main_code

];

// A completely wrong and useless debug section, but we NEED to have one

let mut debug_entry =  DebugEntry::new(1).with_range(DebugRange::new(0x06, 0x13));

let debug_section = DebugSection::new(debug_entry);

let mut file_buffer = Vec::with_capacity(2048);

let ksm_file = KSMFile::new_from_parts(arg_section, code_sections, debug_section);

ksm_file.write(&mut file_buffer);

let mut file = std::fs::File::create("hello.ksm").expect("Couldn't open output file");

file.write_all(file_buffer.as_slice()).expect("Failed to write to output file");

```

### Example for Kerbal Object hello world program

```rust

use kerbalobjects::ko::symbols::{KOSymbol, SymBind, SymType};

use kerbalobjects::ko::{Instr, KOFile};

use kerbalobjects::{KOSValue, Opcode};

use kerbalobjects::ko::SectionIdx;

use kerbalobjects::ko::sections::DataIdx;

use std::io::Write;

use std::path::PathBuf;

let mut ko = KOFile::new();

let mut data_section = ko.new_data_section(".data");

let mut start = ko.new_func_section("_start");

let mut symtab = ko.new_symtab(".symtab");

let mut symstrtab = ko.new_strtab(".symstrtab");

// Set up the main code function section

let one = data_section.add_checked(KOSValue::Int16(1));

start.add(Instr::TwoOp(

    Opcode::Bscp,

    one,

    data_section.add_checked(KOSValue::Int16(0)),

));

start.add(Instr::ZeroOp(Opcode::Argb));

start.add(Instr::OneOp(

    Opcode::Push,

    data_section.add_checked(KOSValue::ArgMarker),

));

start.add(Instr::OneOp(

    Opcode::Push,

    data_section.add_checked(KOSValue::StringValue("Hello, world!".into())),

));

start.add(Instr::TwoOp(

    Opcode::Call,

    data_section.add_checked(KOSValue::String("".into())),

    data_section.add_checked(KOSValue::String("print()".into())),

));

start.add(Instr::ZeroOp(Opcode::Pop));

start.add(Instr::OneOp(Opcode::Escp, one));

// Set up our symbols

let file_symbol = KOSymbol::new(

    symstrtab.add("test.kasm"),

    DataIdx::PLACEHOLDER,

    0,

    SymBind::Global,

    SymType::File,

    SectionIdx::NULL,

);

let start_symbol = KOSymbol::new(

    symstrtab.add("_start"),

    DataIdx::PLACEHOLDER,

    start.size() as u16,

    SymBind::Global,

    SymType::Func,

    start.section_index(),

);

symtab.add(file_symbol);

symtab.add(start_symbol);

ko.add_data_section(data_section);

ko.add_func_section(start);

ko.add_str_tab(symstrtab);

ko.add_sym_tab(symtab);

// Write the file out to disk

let mut file_buffer = Vec::with_capacity(2048);

let ko = ko.validate().expect("Could not update KO headers properly");

ko.write(&mut file_buffer);

let file_path = PathBuf::from("test.ko");

let mut file =

    std::fs::File::create(file_path).expect("Output file could not be created: test.ko");

file.write_all(file_buffer.as_slice())

    .expect("File test.ko could not be written to.");

```

## Documentation

See the kerbalobjects [docs.rs](https://docs.rs/kerbalobjects/latest/kerbalobjects/) for information on how to use this library.

Documentation on kOS [instructions](https://github.com/newcomb-luke/kerbalobjects.rs/blob/main/docs/Instruction-docs.md) and what they do. 

## Support

Besides the documentation, support can be found by the library author in this [Discord server](https://discord.gg/APETM2ceVZ).

## If this doesn't fit your use case

If this library doesn't implement a specific feature that your program needs, then please create a new issue or contact the developer.

If that cannot be resolved, see docs/ for examples and explanations of the [KSM](https://github.com/newcomb-luke/kerbalobjects.rs/blob/main/docs/KSM-file-format.md) and [KO](https://github.com/newcomb-luke/kerbalobjects.rs/blob/main/docs/KO-file-format.md) file formats and how to create or read them.