osal-rs 1.0.3

Operating System Abstraction Layer for Rust with support for FreeRTOS and POSIX
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

/***************************************************************************
 *
 * osal-rs
 * Copyright (C) 2026 Antonio Salsi <passy.linux@zresa.it>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, see <https://www.gnu.org/licenses/>.
 *
 ***************************************************************************/

//! Build script for OSAL-RS library.
//!
//! Delegates to [`osal_rs_build::TypeGenerator`] to generate the `TickType`/
//! `UBaseType`/`BaseType`/`StackType` aliases the crate `include!`s from
//! `OUT_DIR/types_generated.rs`, and wire up `cargo:rerun-if-changed` for the
//! active backend's C porting sources. See `osal-rs-build`'s own docs for
//! exactly what each backend does at build time (POSIX probes the host
//! architecture and `SCHED_FIFO` support for real; the FreeRTOS path
//! currently always emits the common 32-bit type mapping rather than parsing
//! `FreeRTOSConfig.h`).
//!
//! # FreeRTOSConfig.h Location (freertos backend)
//!
//! Determined by `TypeGenerator` from:
//! 1. **Environment variable**: `FREERTOS_CONFIG_PATH` (if set)
//! 2. **Default location**: `<workspace_root>/inc/FreeRTOSConfig.h`
//!
//! ```bash
//! export FREERTOS_CONFIG_PATH=/path/to/FreeRTOSConfig.h
//! cargo build --features freertos
//! ```
//!
//! Or in `.cargo/config.toml`:
//!
//! ```toml
//! [env]
//! FREERTOS_CONFIG_PATH = { value = "/path/to/FreeRTOSConfig.h" }
//! ```
//!
//! # Rebuild Triggers
//!
//! Rebuilds on changes to `build.rs` itself and, for `freertos`, to its C
//! porting sources (`osal-rs-porting/freeretos/`); `posix` has no C porting
//! sources of its own to track.
//!
//! # Feature Requirements
//!
//! Exactly one of `freertos` / `posix` must be enabled: enabling neither or
//! both trips one of the two `compile_error!`s below.
//!
//! # Build Dependencies
//!
//! Requires the `osal-rs-build` crate (`TypeGenerator`) and, for `posix`,
//! `gcc` on `PATH` (used only to probe the host architecture).

use osal_rs_build::TypeGenerator;
use std::env;
use std::path::PathBuf;

/// Main entry point for the build script.
///
/// Builds a [`TypeGenerator`] from `CARGO_MANIFEST_DIR`, then - for whichever
/// of `freertos`/`posix` is active - registers rerun-if-changed triggers via
/// `TypeGenerator::add_rerun_if_changed()` and runs `generator.generate_all()`
/// to write `types_generated.rs` (and, for `posix`, compile and link the C
/// porting shim).
///
/// # Panics
///
/// - If `CARGO_MANIFEST_DIR` is not set (cargo always sets this)
/// - If neither or both of `freertos`/`posix` are enabled (`compile_error!`)
/// - If generation fails (handled by `TypeGenerator`, e.g. missing `gcc`)
///
/// # Environment Variables
///
/// - `CARGO_MANIFEST_DIR` - Set by cargo, points to the crate's directory
/// - `FREERTOS_CONFIG_PATH` - Optional, custom path to `FreeRTOSConfig.h` (freertos backend)
fn main() {
    // Tell cargo to rerun this build script if any of these files change.
    // This ensures the generated bindings stay synchronized with the FFI implementation.
    println!("cargo:rerun-if-changed=build.rs");

    // Get the workspace root directory by navigating up from the manifest directory.
    // Manifest dir is typically: <workspace>/osal-rs/osal-rs
    // Workspace root is: <workspace>
    let manifest_dir = env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR not set");
    

    let mut generator = TypeGenerator::new(&PathBuf::from(manifest_dir));

    #[cfg(all(not(feature = "posix"), feature = "freertos"))]
    {
        TypeGenerator::add_rerun_if_changed();

        // Generate all type mappings, configuration constants, and FFI bindings.
        // Generated files are written to the OUT_DIR and included by the main crate.
        generator.generate_all();
    }

    #[cfg(all(feature = "posix", not(feature = "freertos")))]
    {
        TypeGenerator::add_rerun_if_changed();
        
        // Generate all type mappings, configuration constants, and FFI bindings.
        // Generated files are written to the OUT_DIR and included by the main crate.
        generator.generate_all();
    }

    #[cfg(all(not(feature = "posix"), not(feature = "freertos")))]
    compile_error!("Either the \"posix\" or the \"freertos\" feature must be enabled");

    #[cfg(all(feature = "posix", feature = "freertos"))]
    compile_error!("Only one backend must be enabled");
}