QUICKSTART.md updates

Author: FractalFir

QUICKSTART.md

@@ -19,13 +19,13 @@ rustup update
 
 If this does not solve the problem, open an issue. The project is only compatible with a narrow set of `rustc` versions, and tries to always use the newest nigthly build.
 ## Install the .NET runtime
-
+**Note: This is only relevant if you want to use this project in its .NET mode**
 This project requires the .NET runtime to be used. You can find [instalation instructions here](https://dotnet.microsoft.com/en-us/download).
 
 After installing .NET, run ` dotnet --info` to confoirm it is installed propely.
 
 ## Install `ilasm`
-
+**Note: This is only relevant if you want to use this project in its .NET mode**
 ### Windows
 
 `ilasm` comes [installed with Visual Studio](https://learn.microsoft.com/en-us/dotnet/framework/tools/ilasm-exe-il-assembler). So, you propably already have it. If not, install visual stuido. 
@@ -36,7 +36,11 @@ This tool supports both the "Core" and "Mono" flavours of ILASM. While you *can*
 
 ### Checking the dependencies 
 
-After you installed `dotnet` and `ilasm`, run `./bin/rustflags.rs` to check if you installed `ilasm` and `dotnet` correctly. 
+After you installed `dotnet` and `ilasm`(, run `./bin/rustflags.rs` to check if you installed `ilasm` and `dotnet` correctly. 
+If you want to use the project to generate C code, set `C_MODE` to `1`.
+```
+export C_MODE=1
+```
 
 This script uses the experimental `cargo-script` feaure to will check your enviroment, build the project, and print the flags you need to use it.
 
@@ -57,9 +61,9 @@ target = "x86_64-unknown-linux-gnu" # Change to the host target.
 build-std = ["core","alloc","std","panic_abort"]
 ```
 
-Then, run the codegen utility `rustflags` again, by running `cargo --bin rustflags --release` **in the directory `rustc_codegen_clr`**.
+Then, run the codegen utility `rustflags` again, by running `./bin/rustflags.rs` **in the directory `rustc_codegen_clr`**.
 
-It should provide you with the commands necesary for enabling the codegen. They should look something like this:
+It should provide you with the commands necesarry for enabling the codegen. They should look something like this:
 
 On Linux:
 ```bash
@@ -75,4 +79,26 @@ The project makes **no pernament changes** to your instaltation, and simply clos
 
 After this, simply run `cargo run` to compile & run your app inside the .NET runtime. Other cargo commands should work to. There may be quite a few error / warning messages dispalyed, but they will not stop compilation.
 
-NOTE: the project currently does not support any `proc-macros`, due to techincal liminations. Supporting them is possible, but it is currently more effort than it is worth.
+NOTE: the project currently does not properly support `proc-macros`, due to technical liminations. Fully supporting them is possible, but it is currently more effort than it is worth.
+# Additional information on C support
+
+## Required features
+Currently, the generated code will, by default, depend on some features of C that may not always be present. 
+
+Those features are:
+1. malloc and aligned allocators - certain static/constant variables require alignments higher than the ones guaranteed by the C standard. As a workaround, `cg_clr` will use malloc & aligned allocators
+to ensure sufficient alignment of static variables. This is something I am actively working on resolving, and this should not be an issue in the near future. 
+2. POSIX threading APIs. The header files generated by `cg_clr` will override certain POSIX APIs in order to track new threads. This is needed to ensure proper initialization of thread-local data.
+
+## Odd function names
+Additionally, you might notice that the generated code sometimes calls "wierd" functions, like `System_Numerics_BitOperations_LeadingZeroCountu64i32`. 
+This is a limitation of the current abstractions over .NET and C. Most of the time, those functions simply call / emulate a C builtin. This is also something that will not be an issue in the future:
+I am actively working on better abstractions.
+
+## Non-alphabetic identifiers.
+
+By default, `cg_clr` will keep symbol(function) names more-or-less intact. However, those names may contain characters accepted by *most*, but not *all* compilers. 
+```
+_ZN54_$LT$$LP$A$C$B$RP$$u20$as$u20$fuzz100__PrintFDebug$GT$12printf_debug17h769fc7ecbdc54ca9E
+```
+In those cases, simply set `ASCI_IDENT` enviroment variable to ensure correct symbol names.

bin/build_backend.rs

@@ -93,9 +93,9 @@ pub static ILASM_PATH: std::sync::LazyLock<String> = std::sync::LazyLock::new(||
 pub fn absolute_backend_path() -> PathBuf {
     if cfg!(debug_assertions) {
         if cfg!(target_os = "linux") {
-            std::fs::canonicalize("../target/debug/librustc_codegen_clr.so").unwrap()
+            std::fs::canonicalize("target/debug/librustc_codegen_clr.so").unwrap()
         } else if cfg!(target_os = "windows") {
-            std::fs::canonicalize("../target/debug/rustc_codegen_clr.dll").unwrap()
+            std::fs::canonicalize("target/debug/rustc_codegen_clr.dll").unwrap()
         } else if cfg!(target_os = "macos") {
             let current_dir = std::env::current_dir().unwrap();
             let dylib_path = current_dir.join("target/debug/librustc_codegen_clr.dylib");

bin/rustflags.rs

@@ -19,8 +19,11 @@ fn main() {
     println!("Welcome to the `rustc_codegen_clr` environment setup helper!");
     println!("This tool will help you use the codegen to compile Rust projects.");
     println!();
+    println!("NOTE: if you are only interested in the C side of the project, set the enviroment variable C_MODE to 1, and run this tool again.");
     println!("Doing dependency checks...");
-    ilasm_check();
+    if !std::env::var("C_MODE").is_ok() {
+        ilasm_check();
+    }
     println!("Dependency checks succeeded.");
     println!();
     println!("WARNING: Please note, the project is currently in the early stages of development.  Bugs, crashes and miscompilations will occur.");
@@ -31,6 +34,9 @@ fn main() {
     println!();
     println!("\"{build_env}\"");
     println!();
+    if std::env::var("C_MODE").is_ok() {
+        println!("Additonally, set `C_MODE` to 1");
+    }
     println!();
     #[cfg(target_family = "unix")]
     {
@@ -40,6 +46,9 @@ fn main() {
         println!();
         println!();
         println!("export RUSTFLAGS=\"{build_env}\"");
+        if std::env::var("C_MODE").is_ok() {
+            println!("export C_MODE=1");
+        }
         println!();
         println!();
     }
@@ -78,5 +87,19 @@ fn main() {
         "  In 99.999% of the cases, the bug is within this project and not the Rust compiler."
     );
     println!();
-    // std::env::set_var("RUSTFLAGS", build_env);
+    #[cfg(target_family = "unix")]
+    {
+        println!("############# Testing with the Rust compiler #####################");
+        println!("Testing with the Rust compiler requires:");
+        println!("1. running `cargo test ::stable`(builds & tests the backend)");
+        println!("2. running ./setup_rustc_fork.sh to download rustc.");
+        println!("3. Setting the following environment variables:");
+        println!("# For .NET");
+        println!("export RUSTFLAGS_NOT_BOOTSTRAP=\"{build_env} -C link-args=--cargo-support\"");
+        println!("# For C");
+        println!("export C_MODE=1");
+        println!("export RUSTFLAGS_NOT_BOOTSTRAP=\"{build_env} -Cpanic=abort -Zpanic_abort_tests -C link-args=--cargo-support\"");
+        println!("Go to the `rustc` directory, run `./configure` to setup the compiler.");
+        println!("./x test core --stage 0 -j 10");
+    }
 }

src/assembly.rs

@@ -731,9 +731,10 @@ pub fn add_allocation(alloc_id: u64, asm: &mut cilly::Assembly, tcx: TyCtxt<'_>)
             CILNode::AddressOfStaticField(Box::new(field_desc))
         }
         _ => {
+            let tl = if thread_local { "t" } else { "g" };
             let alloc_name: IString = if let Some(krate) = krate {
                 format!(
-                    "al_{}_{}_{}_{thread_local}_{}",
+                    "al_{}_{}_{}_{tl}_{}",
                     encode(alloc_id),
                     encode(byte_hash),
                     const_allocation.len(),
@@ -742,7 +743,7 @@ pub fn add_allocation(alloc_id: u64, asm: &mut cilly::Assembly, tcx: TyCtxt<'_>)
                 .into()
             } else {
                 format!(
-                    "al_{}_{}_{}_{thread_local}",
+                    "al_{}_{}_{}_{tl}",
                     encode(alloc_id),
                     encode(byte_hash),
                     const_allocation.len()