Struct Version 

pub struct Version {
    pub major: i32,
    pub minor: i32,
    pub bugfix: i32,
}

A Bela version: major, minor and bugfix.

Ordered the way version numbers are — major first, then minor, then bugfix — so a program can ask whether the library it found is new enough for what it is about to use:

use bela::Version;

assert!(Version::new(1, 18, 0) >= Version::new(1, 17, 0));
assert_eq!(Version::new(1, 18, 0).to_string(), "1.18.0");

The three numbers are C ints in the API that fills them, and they are kept as they arrived: deciding what a negative version number means is not this crate’s to do, and a saturated one would be a number nobody reported.

Why the fields are public

Because there is nothing to keep them consistent with. Every combination of three ints is a version this type is willing to hold — that is the paragraph above — and new already builds any of them, so private fields would add three getters without narrowing what can exist.

Board and DetectMode are closed differently, and for a reason that does not reach here: they are C enums whose set of values moves with the board image, so they are #[non_exhaustive] and Board::Unrecognised is unforgeable — a hand-built one could carry a number a named variant already has and then compare unequal to it. A version has no such variant to contradict, and its shape is fixed by Bela_getVersion, which fills in exactly three numbers.

Fields

major: i32

The major version.

minor: i32

The minor version.

bugfix: i32

The bugfix version.

Implementations

impl Version

pub const HEADERS: Self

What the headers this crate was built against said.

BELA_MAJOR_VERSION and its siblings, as vendored in bela-sys. Compared with running it says whether the board’s image is the one the bindings describe; they differ when a binary is run on a board other than the one its sysroot came from.

pub const fn new(major: i32, minor: i32, bugfix: i32) -> Self

A version from its three numbers.

pub fn running() -> Self

Asks the libbela this program is linked against which version it is.

The library’s own answer, not the headers’: a binary built against one image and run on another reports the version it found there. No audio system is involved.

Only available on the device target (aarch64-unknown-linux-gnu).

Examples found in repository

examples/board_info.rs (line 89)

fn main() -> ExitCode {
    use core::iter::once;
    use std::env::args;

    use bela::{Board, DetectMode, Version};

    let arguments: Vec<String> = args().skip(1).collect();
    let all_modes = match arguments.as_slice() {
        [] => false,
        [flag] if flag == "--all-modes" => true,
        _ => {
            eprintln!(
                "usage: board_info [--all-modes]\n\
                 \x20 --all-modes  ask every detect mode, including the scan that writes\n\
                 \x20              /run/bela/belaconfig"
            );
            return ExitCode::FAILURE;
        }
    };

    if all_modes {
        // Named per line, because the interesting result is the one
        // that disagrees with the others.
        //
        // `Scan` goes last however `DetectMode::ALL` is ordered: it
        // writes `/run/bela/belaconfig`, which `Cache`, `CacheOnly` and
        // `User` read. Asking it first would leave those three
        // reporting what this same run had just written, and four
        // modes agreeing would say nothing about the board. Last, they
        // report what was already on the board and the scan is a fresh
        // answer to compare with it.
        let scan_last = DetectMode::ALL
            .iter()
            .filter(|mode| **mode != DetectMode::Scan)
            .chain(once(&DetectMode::Scan));
        for mode in scan_last {
            println!("board[{mode}]: {}", Board::detect(*mode));
        }
    } else {
        // `Cache` rather than `Scan`: on a running board the daemon has
        // already written the file, so this is a file read. It is not
        // free of side effects — with no file to read it falls back to
        // scanning, which writes one — but it is the mode that leaves
        // a working board alone, and `CacheOnly` would answer `NoHw`
        // on a board that simply had not been scanned yet.
        println!("board: {}", Board::detect(DetectMode::Cache));
    }

    // Both versions on one line. They agree on a board whose image is
    // the one the bindings were vendored from, and the whole point of
    // printing them together is the run where they do not.
    let running = Version::running();
    if running == Version::HEADERS {
        println!("version: {running}");
    } else {
        println!(
            "version: {running} (this binary was built against {headers})",
            headers = Version::HEADERS
        );
    }

    ExitCode::SUCCESS
}

examples/io_config.rs (line 256)

    pub(crate) fn hardware() {
        let board = Board::detect(DETECT_CACHED);
        report("detect-hw", &hardware_name(board));
        // The library that answered, which is not necessarily the one
        // this was built against: every number below is a claim about a
        // particular libbela, and this is which one.
        report("version", &Version::running().to_string());
        let hw = board.to_sys();

        // The configuration libbela associates with that hardware,
        // which is where a Gem's channel counts come from before any
        // settings are applied. Null is an answer too: it is what a
        // hardware libbela has no configuration for looks like.
        let config = unsafe { Bela_HwConfig_new(hw) };
        if config.is_null() {
            report("hw-config", "null");
        } else {
            let config_ref = unsafe { &*config };
            report(
                "hw-config",
                &format!(
                    "rate:{},audio-in:{},audio-out:{},analog-in:{},analog-out:{},digital:{}",
                    config_ref.audioSampleRate,
                    config_ref.audioInChannels,
                    config_ref.audioOutChannels,
                    config_ref.analogInChannels,
                    config_ref.analogOutChannels,
                    config_ref.digitalChannels
                ),
            );
            unsafe { Bela_HwConfig_delete(config) };
        }

        // The defaults an application inherits by setting nothing,
        // which is what `Settings`'s "unset fields keep the values
        // produced by `Bela_defaultSettings()`" means in practice.
        let raw = unsafe { Bela_InitSettings_alloc() };
        if raw.is_null() {
            report("defaults", "alloc-failed");
            return;
        }
        unsafe { Bela_defaultSettings(raw) };
        let defaults = unsafe { &*raw };
        report(
            "defaults-analog",
            &format!(
                "use:{},in:{},out:{},uniform:{}",
                defaults.useAnalog,
                defaults.numAnalogInChannels,
                defaults.numAnalogOutChannels,
                defaults.uniformSampleRate
            ),
        );
        report(
            "defaults-digital",
            &format!(
                "use:{},channels:{}",
                defaults.useDigital, defaults.numDigitalChannels
            ),
        );
        report(
            "defaults-audio",
            &format!(
                "period:{},rate:{},threads:{}",
                defaults.periodSize, defaults.audioSampleRate, defaults.threadCount
            ),
        );
        unsafe { Bela_InitSettings_free(raw) };
    }

Trait Implementations

impl Clone for Version

fn clone(&self) -> Version

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Version

impl Debug for Version

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Version

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Version

impl Hash for Version

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Version

fn cmp(&self, other: &Version) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Version

fn eq(&self, other: &Version) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Version

fn partial_cmp(&self, other: &Version) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for Version