Request for a quick start docs

[Xuanwo]

Hello, I'm excited about this project! However, I'm not sure how to get it up and running.

Could you provide a quick guide or walkthrough for getting started, such as compiling a hello_world example? Specifically, with everything set up for rustc already in place, how do I integrate it with rustc_codegen_clr?

[FractalFir]

The process is currently a bit tedious - I plan on simplifying it in the future, and/or making an installer.
Currently, you should:

Installing dependencies, building the project, building and running examples

1. Ensure you have all the necessary dependencies - a .NET runtime (preferably the newest version), and ilasm(.NET tool used for creating assemblies).

2. Ensure you are on the newest nightly rust. Run rustup default nightly to switch to nightly, and then run rustup update to ensure you are on the newest version. There are frequent breaking changes in rustc internals, so this is quite important.

3. Clone the repository to get the newest development version. Cloning is preferred, due to frequent changes in the compiler. Run git clone --depth 1 https://github.com/FractalFir/rustc_codegen_clr to get the newest version.

4. Run cargo test - this will both build the project, and run some tests (this will help you ensure everything works as expected). Currently, 50 tests should pass, and 25 should fail. This should also build a hello_world interop example.

Adding examples / building arbitrary code

The "proper" installation (integrating it with the rest of the system) process is currently quite brittle and tedious. It involves a bit of manual setup (moving files around, passing some arguments to cargo). In the future, this will be automated, but it currently is not. However, there is an easier way.

The test harness does those things automatically, but it is an internal testing tool. Still, you can modify the examples provided and insert a small bit of code to make the tester build anything. This way of building things works and is very reliable, but is not the ideal solution.

In src/compile_test.rs, there are some macros which can be used to build any rust code. If you add a line like this:
crago_test!{CRATE_NAME}
to that file, the tester will automatically build a crate named CRATE_NAME in the cargo_tests directory. You can use that to try and compile any code you want.

Then go to the root directory of the project (not the crate you are building!), and run cargo test CRATE_NAME - this will attempt to build a release and debug version of CRATE_NAME. Release builds tend to succeed far more often and contain fewer bugs.

Building the standard library

In order to use the standard library in your crate, you will have to create a file named config.toml at
cargo_tests/CRATE_NAME/.cargo/config.toml
In that file, insert the following text:

[build]
target = "x86_64-unknown-linux-gnu"
[unstable]
build-std = ["core","alloc","std","panic_abort"]

This will tell cargo to rebuild the standard library. The x86_64-unknown-linux-gnu is there because I have not yet defined a custom target triple for .NET. It should not be changed, because changing it from Linux to windows will make the compiler use different names for certain external functions(e.g. malloc, functions related to opening files).

The build process should take at most a couple of minutes (it may finish much faster, depends on your CPU and version of ILASM). If any error messages show up on the screen, that is OK. Some parts of Rust are not supported, and the codegen will print an error when encountering them. After the build finishes, you should have an executable file within cargo_test/CRATE_NAME/target/x86_64-unknown-linux-gnu/release.

I know this is probably quite convoluted, so fell free to ask any questions.

[Xuanwo]

Thank you for the guide—it worked! I've also submitted a PR at #26 to enhance the experience, hoping it will be useful.

[FractalFir]

I have made an updated quick-start guide.

[siwatanejo]

The project will ONLY work with the newest, nightly rustc

Why is this? Any plans to change it to depend on stable version at some point?

[FractalFir]

This is sadly not something I have control over. The internal Rust APIs constantly change, and the project needs to be updated every time this happens.

For example, NullOp::DebugAssertions was present for one version(and needed to be handled properly), and then got removed in the very next one.

TyKind::RawPtr was also recently changed to store mutability info separately from the pointed type - which would cause a compilation error.

I could try to stick to a specific nightly version, but that would still require me to update at some point.

Also, GitHub actions only have the newest nightly version, so in order to use them, the project needs to be kept up to date.

[siwatanejo]

You seem to be describing the difference or challenge about some nightly from the next day breaking compatibility with the nightly of the previous day, but I was talking about stable vs nightly.

[FractalFir]

The compiler-internal APIs I use are nightly-only, and will never be stable.

If the project ever gets included in the Rust compiler repo, then it might work on stable(since it will be a part of the compiler). Until then - it sadly can't run stable Rust :(.

[siwatanejo]

Ah, now I understood, thanks.