rust/Readme.md

WIP libgccjit codegen backend for rust

This is a GCC codegen for rustc, which means it can be loaded by the existing rustc frontend, but benefits from GCC: more architectures are supported and GCC's optimizations are used.

Despite its name, libgccjit can be used for ahead-of-time compilation, as is used here.

Motivation

The primary goal of this project is to be able to compile Rust code on platforms unsupported by LLVM. A secondary goal is to check if using the gcc backend will provide any run-time speed improvement for the programs compiled using rustc.

Dependencies

rustup: Follow the instructions on the official website

DejaGnu: Consider to install DejaGnu which is necessary for running the libgccjit test suite. website

Building

This requires a patched libgccjit in order to work. You need to use my fork of gcc which already includes these patches.

$ cp config.example.toml config.toml

If don't need to test GCC patches you wrote in our GCC fork, then the default configuration should be all you need. You can update the rustc_codegen_gcc without worrying about GCC.

Building with your own GCC version

If you wrote a patch for GCC and want to test it without this backend, you will need to do a few more things.

To build it (most of these instructions come from here, so don't hesitate to take a look there if you encounter an issue):

$ git clone https://github.com/antoyo/gcc
$ sudo apt install flex libmpfr-dev libgmp-dev libmpc3 libmpc-dev
$ mkdir gcc-build gcc-install
$ cd gcc-build
$ ../gcc/configure \
    --enable-host-shared \
    --enable-languages=jit \
    --enable-checking=release \ # it enables extra checks which allow to find bugs
    --disable-bootstrap \
    --disable-multilib \
    --prefix=$(pwd)/../gcc-install
$ make -j4 # You can replace `4` with another number depending on how many cores you have.

If you want to run libgccjit tests, you will need to also enable the C++ language in the configure:

--enable-languages=jit,c++

Then to run libgccjit tests:

$ cd gcc # from the `gcc-build` folder
$ make check-jit
# To run one specific test:
$ make check-jit RUNTESTFLAGS="-v -v -v jit.exp=jit.dg/test-asm.cc"

Put the path to your custom build of libgccjit in the file config.toml.

You now need to set the gcc-path value in config.toml with the result of this command:

$ dirname $(readlink -f `find . -name libgccjit.so`)

and to comment the download-gccjit setting:

gcc-path = "[MY PATH]"
# download-gccjit = true

Then you can run commands like this:

$ ./y.sh prepare # download and patch sysroot src and install hyperfine for benchmarking
$ ./y.sh build --sysroot --release

To run the tests:

$ ./y.sh test --release

Usage

You have to run these commands, in the corresponding order:

$ ./y.sh prepare
$ ./y.sh build --sysroot

To check if all is working correctly, run:

$ ./y.sh cargo build --manifest-path tests/hello-world/Cargo.toml

Cargo

$ CHANNEL="release" $CG_GCCJIT_DIR/y.sh cargo run

If you compiled cg_gccjit in debug mode (aka you didn't pass --release to ./y.sh test) you should use CHANNEL="debug" instead or omit CHANNEL="release" completely.

Rustc

If you want to run rustc directly, you can do so with:

$ ./y.sh rustc my_crate.rs

You can do the same manually (although we don't recommend it):

$ LIBRARY_PATH="[gcc-path value]" LD_LIBRARY_PATH="[gcc-path value]" rustc +$(cat $CG_GCCJIT_DIR/rust-toolchain | grep 'channel' | cut -d '=' -f 2 | sed 's/"//g' | sed 's/ //g') -Cpanic=abort -Zcodegen-backend=$CG_GCCJIT_DIR/target/release/librustc_codegen_gcc.so --sysroot $CG_GCCJIT_DIR/build_sysroot/sysroot my_crate.rs

Env vars

• CG_GCCJIT_DUMP_ALL_MODULES: Enables dumping of all compilation modules. When set to "1", a dump is created for each module during compilation and stored in /tmp/reproducers/.
• CG_GCCJIT_DUMP_MODULE: Enables dumping of a specific module. When set with the module name, e.g., CG_GCCJIT_DUMP_MODULE=module_name, a dump of that specific module is created in /tmp/reproducers/.
• CG_RUSTFLAGS: Send additional flags to rustc. Can be used to build the sysroot without unwinding by setting CG_RUSTFLAGS=-Cpanic=abort.
• CG_GCCJIT_DUMP_TO_FILE: Dump a C-like representation to /tmp/gccjit_dumps and enable debug info in order to debug this C-like representation.
• CG_GCCJIT_DUMP_RTL: Dumps RTL (Register Transfer Language) for virtual registers.
• CG_GCCJIT_DUMP_RTL_ALL: Dumps all RTL passes.
• CG_GCCJIT_DUMP_TREE_ALL: Dumps all tree (GIMPLE) passes.
• CG_GCCJIT_DUMP_IPA_ALL: Dumps all Interprocedural Analysis (IPA) passes.
• CG_GCCJIT_DUMP_CODE: Dumps the final generated code.
• CG_GCCJIT_DUMP_GIMPLE: Dumps the initial GIMPLE representation.
• CG_GCCJIT_DUMP_EVERYTHING: Enables dumping of all intermediate representations and passes.
• CG_GCCJIT_KEEP_INTERMEDIATES: Keeps intermediate files generated during the compilation process.
• CG_GCCJIT_VERBOSE: Enables verbose output from the GCC driver.

Extra documentation

More specific documentation is available in the doc folder:

• Common errors
• Debugging GCC LTO
• Debugging libgccjit
• Git subtree sync
• List of useful commands
• Send a patch to GCC

Licensing

While this crate is licensed under a dual Apache/MIT license, it links to libgccjit which is under the GPLv3+ and thus, the resulting toolchain (rustc + GCC codegen) will need to be released under the GPL license.

However, programs compiled with rustc_codegen_gcc do not need to be released under a GPL license.