update book

Author: mhasel

book/src/libraries/api_lib_guide.md

@@ -142,8 +142,6 @@ void Count(CountStruct* countInst) {
 }
 ```
 
-
-
 #### 2.2.3 Return values
 
 A `FUNCTION` defines a return value in the signature, while a `FUNCTION_BLOCK` relies on `VAR_OUTPUT` definitions.
@@ -334,6 +332,67 @@ pub struct myStruct {
 ```
 
 ### 2.5 `FUNCTION_BLOCK` initialization
-Not yet implemented.
+
+When creating a library with `FUNCTION_BLOCK`s, you can implement initialization logic that runs when an instance is created. 
+
+For more details on `FB_INIT` in IEC61131-3, refer to the [Program Organization Units (POUs)](../pous.md#function_block-initialization) documentation.
+
+#### Interoperability with libraries written in other languages
+
+When implementing a `FUNCTION_BLOCK` with initialization in C or other languages, you need to follow a specific naming convention for the initialization function.
+
+For a C implementation:
+
+1. Define a struct that matches your `FUNCTION_BLOCK` variables:
+
+```c
+typedef struct {
+    int a;
+    int b;
+    // Other members as needed
+} myFunctionBlock;
+```
+
+2. ruSTy expects a default-initializer to be present to initialize instances on the stack
+(`VAR_TEMP` blocks or `VAR` blocks in functions or methods)
+
+This global instance follows the naming scheme of `__<FunctionBlockName>__init`, below is an example of a zero-initializer:
+
+```c
+myFunctionBlock __myFunctionBlock__init = { 0 };
+```
+
+3. Optionally create an initialization function following the naming pattern `<FunctionBlockName>_FB_INIT`:
+
+```c
+void myFunctionBlock_FB_INIT(myFunctionBlock* fb_instance) {
+    // Initialize members here
+    fb_instance->a = 1;
+    fb_instance->b = 2;
+    
+    // ...perform any other needed initialization
+}
+```
+
+4. In your IEC61131-3 declaration (e.g., in a header file [`*.pli`]), ensure your `FUNCTION_BLOCK` includes the `FB_INIT` method (if present):
+
+```
+{external}
+FUNCTION_BLOCK myFunctionBlock
+VAR
+    a : DINT;
+    b : DINT;
+END_VAR
+    METHOD FB_INIT
+    END_METHOD
+END_FUNCTION_BLOCK
+```
+
+Note that the `FB_INIT` method doesn't need implementation details in the IEC61131-3 declaration when using an external implementation - the declaration just signals that initialization is available.
+
+#### Project-wide initialization
+
+See [Project-wide initialization](../using_rusty.md#project-wide-initialization)
+
 
 

book/src/pous.md

@@ -147,6 +147,28 @@ END_VAR
 END_FUNCTION_BLOCK
 ```
 
+#### `FUNCTION_BLOCK` initialization
+Function blocks can define a special method called `FB_INIT` that is automatically called when an instance is created. This is analogous to a constructor in object-oriented programming.
+
+The `FB_INIT` method allows you to initialize the function block's variables to specific values. It is called during program initialization before any other code runs.
+
+`FB_INIT` methods can neither have parameters nor a return type in their current implementation - violating this contract will lead to undefined behaviour at runtime.
+
+```iecst
+FUNCTION_BLOCK MyFB
+VAR
+    x : INT;
+    y : INT;
+END_VAR
+    METHOD FB_INIT
+        x := 1;
+        y := 2;
+    END_METHOD
+
+    // Other methods and code...
+END_FUNCTION_BLOCK
+```
+
 ### Action
 
 An action is represented by a parent struct, and does not define its own interface (VAR blocks).

book/src/using_rusty.md

@@ -136,3 +136,29 @@ Outputs the json schema used for the validation of the `plc.json` file
 Ouputs a json file with the default error severity configuration for the project.
 See [Error Configuration](./error_configuration.md) for more information.
 
+## Project-wide initialization
+
+When your code is compiled, the compiler creates a special initialization function with the naming pattern `__init___<projectname>`. This function is responsible for calling all implicit and user-defined initialization code, including all [`FB_INIT`](../pous.md#function_block-initialization) methods.
+
+`<projectname>` is either taken directly from the `plc.json`'s `name` field or derived from the first input file (replacing `.`/`-` with `_`) when compiling without a `plc.json` (e.g. `plc prog.st ...` would yield `__init___prog_st`).
+
+This function is added to the global constructor list, therefore loading the binary will automatically call the `__init___<projectname>` function (and therefore your `<FunctionBlockName>_FB_INIT` function) when an instance of your function block is created, before any other methods are called. This allows you to set default values or perform required setup for your function block.
+
+> **IMPORTANT:** The global constructor initialization is currently only supported for `x86` ISAs. To make sure initialization code runs reliably regardless of target-architecture, ensure your runtime calls this function before starting main task execution.
+If you're using the executable without a runtime, you **must** ensure that `__init___<projectname>` is called before any other code runs. Failure to do so will result in uninitialized function blocks and pointers, which can lead to undefined behavior and/or crashes.
+
+Example of ensuring initialization when using C (crt0):
+
+```c
+int main() {
+    // Call the project initialization function first
+    __init___myproject();
+    
+    // Now it's safe to start cyclic execution
+    for (;;) {
+        mainProg();
+    }
+    
+    return 0;
+}
+```

compiler/plc_project/src/project.rs

@@ -302,7 +302,7 @@ impl<S: SourceContainer> Project<S> {
     /// Returns the symbol name of this projects main initializer function
     pub fn get_init_symbol_name(&self) -> &'static str {
         //Converts into static because this will live forever
-        format!("__init___{}", self.get_name().replace('.', "_")).leak()
+        format!("__init___{}", self.get_name().replace(['.', '-'], "_")).leak()
     }
 }
 

src/codegen/generators/llvm.rs

@@ -12,7 +12,7 @@ use inkwell::{
     values::{BasicValue, BasicValueEnum, GlobalValue, IntValue, PointerValue},
     AddressSpace,
 };
-use plc_ast::ast::{AstNode, LinkageType};
+use plc_ast::ast::AstNode;
 use plc_diagnostics::diagnostics::Diagnostic;
 use plc_source::source_location::SourceLocation;
 
@@ -318,9 +318,6 @@ impl<'a> Llvm<'a> {
         exp_gen: &ExpressionCodeGenerator,
     ) -> Result<(), Diagnostic> {
         let (qualified_name, type_name, location) = variable;
-        if index.find_pou(type_name).is_some_and(|it| it.get_linkage() == &LinkageType::External) {
-            return Ok(());
-        }
         let variable_llvm_type =
             llvm_index.get_associated_type(type_name).map_err(|err| err.with_location(location))?;
 

src/codegen/generators/pou_generator.rs

@@ -38,7 +38,7 @@ use inkwell::{
     types::{BasicType, StructType},
     values::PointerValue,
 };
-use plc_ast::ast::{AstNode, Implementation, LinkageType, PouType};
+use plc_ast::ast::{AstNode, Implementation, PouType};
 use plc_diagnostics::diagnostics::{Diagnostic, INTERNAL_LLVM_ERROR};
 use plc_source::source_location::SourceLocation;
 use rustc_hash::FxHashMap;
@@ -110,10 +110,8 @@ pub fn generate_global_constants_for_pou_members<'ink>(
         .filter(|it| it.is_in_unit(location));
     for implementation in implementations {
         let type_name = implementation.get_type_name();
-        if implementation.is_init()
-            || index.find_pou(type_name).is_some_and(|it| it.get_linkage() == &LinkageType::External)
-        {
-            // initializer functions and externals don't need global constants to initialize members
+        if implementation.is_init() {
+            // initializer functions don't need global constants to initialize members
             continue;
         }
         let pou_members = index.get_pou_members(type_name);

src/lowering.rs

@@ -37,7 +37,6 @@ impl InitVisitor {
         let mut visitor = Self::new(index, unresolvables, id_provider);
         // before visiting, we need to collect all candidates for user-defined init functions
         units.iter().for_each(|unit| {
-            // TODO: probably also need to consider structs here
             visitor.collect_user_init_candidates(unit);
         });
         // visit all units
@@ -72,14 +71,22 @@ impl InitVisitor {
     }
 
     fn collect_user_init_candidates(&mut self, unit: &CompilationUnit) {
-        // TODO: probably also need to consider structs here
         // collect all candidates for user-defined init functions
         for pou in unit.pous.iter().filter(|it| matches!(it.kind, PouType::FunctionBlock | PouType::Program))
         {
             // add the POU to potential `FB_INIT` candidates
             self.user_inits
                 .insert(pou.name.to_owned(), self.index.find_method(&pou.name, "FB_INIT").is_some());
         }
+
+        for user_type in
+            unit.user_types.iter().filter(|it| matches!(it.data_type, DataType::StructType { .. }))
+        {
+            // add the struct to potential `STRUCT_INIT` candidates
+            if let Some(name) = user_type.data_type.get_name() {
+                self.user_inits.insert(name.to_string(), false);
+            };
+        }
     }
 
     fn update_initializer(&mut self, variable: &mut plc_ast::ast::Variable) {
@@ -358,9 +365,6 @@ impl AstVisitorMut for InitVisitor {
 
     fn visit_data_type(&mut self, data_type: &mut DataType) {
         if matches!(data_type, plc_ast::ast::DataType::StructType { .. }) {
-            if let Some(name) = data_type.get_name() {
-                self.user_inits.insert(name.to_string(), false);
-            };
             self.walk_with_scope(data_type, data_type.get_name().map(ToOwned::to_owned))
         } else {
             data_type.walk(self)

tests/lit/multi/extern_C_fb_init/foo.c

@@ -5,7 +5,7 @@ typedef struct {
     int b;
 } myFunctionBlock;
 
-// myFunctionBlock __myFunctionBlock__init;
+myFunctionBlock __myFunctionBlock__init = { 0 };
 
 void myFunctionBlock_FB_INIT(myFunctionBlock* fb_instance) {
     fb_instance->a = 1;

tests/lit/multi/extern_C_fb_init/libfoo.so

@@ -1,27 +1,44 @@
 # Override the compile command to include the custom library
 import os.path
+import subprocess
 
 # Access the same parameters that the main configuration uses
 stdlibLocation = lit_config.params["LIB"]
 compilerLocation = lit_config.params["COMPILER"]
 rustyRootDirectory = "/home/michael/dev/rusty"
 
 test_dir = os.path.dirname(__file__)
-lib_path = os.path.abspath(test_dir)
+source_path = os.path.abspath(test_dir)
+
+# Use tmp directory for compiled library
+tmp_lib_path = "/tmp"
+tmp_lib_file = f"{tmp_lib_path}/libfoo.so"
+
+# Compile foo.c to libfoo.so in the tmp directory
+try:
+    lit_config.note(f"Compiling foo.c into {tmp_lib_file}...")
+    gcc_cmd = f"gcc -shared -fPIC -o {tmp_lib_file} {source_path}/foo.c"
+    lit_config.note(f"Running: {gcc_cmd}")
+    result = subprocess.run(gcc_cmd, shell=True, check=True, 
+                           stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    lit_config.note(f"Successfully compiled {tmp_lib_file}")
+except subprocess.CalledProcessError as e:
+    lit_config.error(f"Failed to compile foo.c: {e.stderr.decode()}")
+    raise
 
 # Build on the existing compile command but add our custom library
 compile = f'{compilerLocation}'
 compile = f'{compile} -o /tmp/%basename_t.out'
 compile = f'{compile} -liec61131std -L{stdlibLocation}/lib -i "{stdlibLocation}/include/*.st"'
 compile = f'{compile} -i "{rustyRootDirectory}/tests/lit/util/*.pli"'
-compile = f'{compile} -L{lib_path} -lfoo -i {lib_path}/header.pli'
+compile = f'{compile} -L{tmp_lib_path} -lfoo -i {source_path}/header.pli'
 compile = f'{compile} --linker=cc'
 
 # Log the compile command
 lit_config.note(f"Compile command: {compile}")
 
 # Update the run command to include the custom library path
-run_cmd = f'LD_LIBRARY_PATH="{stdlibLocation}/lib:{lib_path}" /tmp/%basename_t.out'
+run_cmd = f'LD_LIBRARY_PATH="{stdlibLocation}/lib:{tmp_lib_path}" /tmp/%basename_t.out'
 
 # Override the substitutions
 config.substitutions = [s for s in config.substitutions if s[0] not in ['%COMPILE', '%RUN']]