diff --git a/Readme.md b/Readme.md index 2c6d21b3f96..da6e91587fd 100644 --- a/Readme.md +++ b/Readme.md @@ -139,179 +139,19 @@ $ LIBRARY_PATH="[gcc-path value]" LD_LIBRARY_PATH="[gcc-path value]" rustc +$(ca
Dump a C-like representation to /tmp/gccjit_dumps and enable debug info in order to debug this C-like representation.
+## Extra documentation + +More specific documentation is available in the [`doc`](./doc) folder: + + * [Common errors](./doc/errors.md) + * [Debugging GCC LTO](./doc/debugging-gcc-lto.md) + * [Debugging libgccjit](./doc/debugging-libgccjit.md) + * [Git subtree sync](./doc/subtree.md) + * [List of useful commands](./doc/tips.md) + * [Send a patch to GCC](./doc/sending-gcc-patch.md) + ## 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. - -## Debugging - -Sometimes, libgccjit will crash and output an error like this: - -``` -during RTL pass: expand -libgccjit.so: error: in expmed_mode_index, at expmed.h:249 -0x7f0da2e61a35 expmed_mode_index - ../../../gcc/gcc/expmed.h:249 -0x7f0da2e61aa4 expmed_op_cost_ptr - ../../../gcc/gcc/expmed.h:271 -0x7f0da2e620dc sdiv_cost_ptr - ../../../gcc/gcc/expmed.h:540 -0x7f0da2e62129 sdiv_cost - ../../../gcc/gcc/expmed.h:558 -0x7f0da2e73c12 expand_divmod(int, tree_code, machine_mode, rtx_def*, rtx_def*, rtx_def*, int) - ../../../gcc/gcc/expmed.c:4335 -0x7f0da2ea1423 expand_expr_real_2(separate_ops*, rtx_def*, machine_mode, expand_modifier) - ../../../gcc/gcc/expr.c:9240 -0x7f0da2cd1a1e expand_gimple_stmt_1 - ../../../gcc/gcc/cfgexpand.c:3796 -0x7f0da2cd1c30 expand_gimple_stmt - ../../../gcc/gcc/cfgexpand.c:3857 -0x7f0da2cd90a9 expand_gimple_basic_block - ../../../gcc/gcc/cfgexpand.c:5898 -0x7f0da2cdade8 execute - ../../../gcc/gcc/cfgexpand.c:6582 -``` - -To see the code which causes this error, call the following function: - -```c -gcc_jit_context_dump_to_file(ctxt, "/tmp/output.c", 1 /* update_locations */) -``` - -This will create a C-like file and add the locations into the IR pointing to this C file. -Then, rerun the program and it will output the location in the second line: - -``` -libgccjit.so: /tmp/something.c:61322:0: error: in expmed_mode_index, at expmed.h:249 -``` - -Or add a breakpoint to `add_error` in gdb and print the line number using: - -``` -p loc->m_line -p loc->m_filename->m_buffer -``` - -To print a debug representation of a tree: - -```c -debug_tree(expr); -``` - -(defined in print-tree.h) - -To print a debug representation of a gimple struct: - -```c -debug_gimple_stmt(gimple_struct) -``` - -To get the `rustc` command to run in `gdb`, add the `--verbose` flag to `cargo build`. - -To have the correct file paths in `gdb` instead of `/usr/src/debug/gcc/libstdc++-v3/libsupc++/eh_personality.cc`: - -Maybe by calling the following at the beginning of gdb: - -``` -set substitute-path /usr/src/debug/gcc /path/to/gcc-repo/gcc -``` - -TODO(antoyo): but that's not what I remember I was doing. - -### `failed to build archive` error - -When you get this error: - -``` -error: failed to build archive: failed to open object file: No such file or directory (os error 2) -``` - -That can be caused by the fact that you try to compile with `lto = "fat"`, but you didn't compile the sysroot with LTO. -(Not sure if that's the reason since I cannot reproduce anymore. Maybe it happened when forgetting setting `FAT_LTO`.) - -### ld: cannot find crtbegin.o - -When compiling an executable with libgccijt, if setting the `*LIBRARY_PATH` variables to the install directory, you will get the following errors: - -``` -ld: cannot find crtbegin.o: No such file or directory -ld: cannot find -lgcc: No such file or directory -ld: cannot find -lgcc: No such file or directory -libgccjit.so: error: error invoking gcc driver -``` - -To fix this, set the variables to `gcc-build/build/gcc`. - -### How to debug GCC LTO - -Run do the command with `-v -save-temps` and then extract the `lto1` line from the output and run that under the debugger. - -### How to send arguments to the GCC linker - -``` -CG_RUSTFLAGS="-Clink-args=-save-temps -v" ../y.sh cargo build -``` - -### How to see the personality functions in the asm dump - -``` -CG_RUSTFLAGS="-Clink-arg=-save-temps -v -Clink-arg=-dA" ../y.sh cargo build -``` - -### How to see the LLVM IR for a sysroot crate - -``` -cargo build -v --target x86_64-unknown-linux-gnu -Zbuild-std -# Take the command from the output and add --emit=llvm-ir -``` - -### To prevent the linker from unmangling symbols - -Run with: - -``` -COLLECT_NO_DEMANGLE=1 -``` - -### How to use a custom-build rustc - - * Build the stage2 compiler (`rustup toolchain link debug-current build/x86_64-unknown-linux-gnu/stage2`). - * Clean and rebuild the codegen with `debug-current` in the file `rust-toolchain`. - -### How to use [mem-trace](https://github.com/antoyo/mem-trace) - -`rustc` needs to be built without `jemalloc` so that `mem-trace` can overload `malloc` since `jemalloc` is linked statically, so a `LD_PRELOAD`-ed library won't a chance to intercept the calls to `malloc`. - -### How to generate GIMPLE - -If you need to check what gccjit is generating (GIMPLE), then take a look at how to -generate it in [gimple.md](./doc/gimple.md). - -### How to build a cross-compiling libgccjit - -#### Building libgccjit - - * Follow the instructions on [this repo](https://github.com/cross-cg-gcc-tools/cross-gcc). - -#### Configuring rustc_codegen_gcc - - * Run `./y.sh prepare --cross` so that the sysroot is patched for the cross-compiling case. - * Set the path to the cross-compiling libgccjit in `gcc-path` (in `config.toml`). - * Make sure you have the linker for your target (for instance `m68k-unknown-linux-gnu-gcc`) in your `$PATH`. Currently, the linker name is hardcoded as being `$TARGET-gcc`. Specify the target when building the sysroot: `./y.sh build --target-triple m68k-unknown-linux-gnu`. - * Build your project by specifying the target: `OVERWRITE_TARGET_TRIPLE=m68k-unknown-linux-gnu ../y.sh cargo build --target m68k-unknown-linux-gnu`. - -If the target is not yet supported by the Rust compiler, create a [target specification file](https://docs.rust-embedded.org/embedonomicon/custom-target.html) (note that the `arch` specified in this file must be supported by the rust compiler). -Then, you can use it the following way: - - * Add the target specification file using `--target` as an **absolute** path to build the sysroot: `./y.sh build --target-triple m68k-unknown-linux-gnu --target $(pwd)/m68k-unknown-linux-gnu.json` - * Build your project by specifying the target specification file: `OVERWRITE_TARGET_TRIPLE=m68k-unknown-linux-gnu ../y.sh cargo build --target path/to/m68k-unknown-linux-gnu.json`. - -If you get the following error: - -``` -/usr/bin/ld: unrecognised emulation mode: m68kelf -``` - -Make sure you set `gcc-path` (in `config.toml`) to the install directory. diff --git a/doc/debugging-gcc-lto.md b/doc/debugging-gcc-lto.md new file mode 100644 index 00000000000..93b150d7686 --- /dev/null +++ b/doc/debugging-gcc-lto.md @@ -0,0 +1,3 @@ +# How to debug GCC LTO + +Run do the command with `-v -save-temps` and then extract the `lto1` line from the output and run that under the debugger. diff --git a/doc/debugging-libgccjit.md b/doc/debugging-libgccjit.md new file mode 100644 index 00000000000..be0ec83f7cd --- /dev/null +++ b/doc/debugging-libgccjit.md @@ -0,0 +1,74 @@ +# Debugging libgccjit + +Sometimes, libgccjit will crash and output an error like this: + +``` +during RTL pass: expand +libgccjit.so: error: in expmed_mode_index, at expmed.h:249 +0x7f0da2e61a35 expmed_mode_index + ../../../gcc/gcc/expmed.h:249 +0x7f0da2e61aa4 expmed_op_cost_ptr + ../../../gcc/gcc/expmed.h:271 +0x7f0da2e620dc sdiv_cost_ptr + ../../../gcc/gcc/expmed.h:540 +0x7f0da2e62129 sdiv_cost + ../../../gcc/gcc/expmed.h:558 +0x7f0da2e73c12 expand_divmod(int, tree_code, machine_mode, rtx_def*, rtx_def*, rtx_def*, int) + ../../../gcc/gcc/expmed.c:4335 +0x7f0da2ea1423 expand_expr_real_2(separate_ops*, rtx_def*, machine_mode, expand_modifier) + ../../../gcc/gcc/expr.c:9240 +0x7f0da2cd1a1e expand_gimple_stmt_1 + ../../../gcc/gcc/cfgexpand.c:3796 +0x7f0da2cd1c30 expand_gimple_stmt + ../../../gcc/gcc/cfgexpand.c:3857 +0x7f0da2cd90a9 expand_gimple_basic_block + ../../../gcc/gcc/cfgexpand.c:5898 +0x7f0da2cdade8 execute + ../../../gcc/gcc/cfgexpand.c:6582 +``` + +To see the code which causes this error, call the following function: + +```c +gcc_jit_context_dump_to_file(ctxt, "/tmp/output.c", 1 /* update_locations */) +``` + +This will create a C-like file and add the locations into the IR pointing to this C file. +Then, rerun the program and it will output the location in the second line: + +``` +libgccjit.so: /tmp/something.c:61322:0: error: in expmed_mode_index, at expmed.h:249 +``` + +Or add a breakpoint to `add_error` in gdb and print the line number using: + +``` +p loc->m_line +p loc->m_filename->m_buffer +``` + +To print a debug representation of a tree: + +```c +debug_tree(expr); +``` + +(defined in print-tree.h) + +To print a debug representation of a gimple struct: + +```c +debug_gimple_stmt(gimple_struct) +``` + +To get the `rustc` command to run in `gdb`, add the `--verbose` flag to `cargo build`. + +To have the correct file paths in `gdb` instead of `/usr/src/debug/gcc/libstdc++-v3/libsupc++/eh_personality.cc`: + +Maybe by calling the following at the beginning of gdb: + +``` +set substitute-path /usr/src/debug/gcc /path/to/gcc-repo/gcc +``` + +TODO(antoyo): but that's not what I remember I was doing. diff --git a/doc/errors.md b/doc/errors.md new file mode 100644 index 00000000000..5727b0ff7c8 --- /dev/null +++ b/doc/errors.md @@ -0,0 +1,27 @@ +# Common errors + +This file lists errors that were encountered and how to fix them. + +### `failed to build archive` error + +When you get this error: + +``` +error: failed to build archive: failed to open object file: No such file or directory (os error 2) +``` + +That can be caused by the fact that you try to compile with `lto = "fat"`, but you didn't compile the sysroot with LTO. +(Not sure if that's the reason since I cannot reproduce anymore. Maybe it happened when forgetting setting `FAT_LTO`.) + +### ld: cannot find crtbegin.o + +When compiling an executable with libgccijt, if setting the `*LIBRARY_PATH` variables to the install directory, you will get the following errors: + +``` +ld: cannot find crtbegin.o: No such file or directory +ld: cannot find -lgcc: No such file or directory +ld: cannot find -lgcc: No such file or directory +libgccjit.so: error: error invoking gcc driver +``` + +To fix this, set the variables to `gcc-build/build/gcc`. diff --git a/doc/tips.md b/doc/tips.md new file mode 100644 index 00000000000..1379f5130be --- /dev/null +++ b/doc/tips.md @@ -0,0 +1,72 @@ +# Tips + +The following shows how to do different random small things we encountered and thought could +be useful. + +### How to send arguments to the GCC linker + +``` +CG_RUSTFLAGS="-Clink-args=-save-temps -v" ../y.sh cargo build +``` + +### How to see the personality functions in the asm dump + +``` +CG_RUSTFLAGS="-Clink-arg=-save-temps -v -Clink-arg=-dA" ../y.sh cargo build +``` + +### How to see the LLVM IR for a sysroot crate + +``` +cargo build -v --target x86_64-unknown-linux-gnu -Zbuild-std +# Take the command from the output and add --emit=llvm-ir +``` + +### To prevent the linker from unmangling symbols + +Run with: + +``` +COLLECT_NO_DEMANGLE=1 +``` + +### How to use a custom-build rustc + + * Build the stage2 compiler (`rustup toolchain link debug-current build/x86_64-unknown-linux-gnu/stage2`). + * Clean and rebuild the codegen with `debug-current` in the file `rust-toolchain`. + +### How to use [mem-trace](https://github.com/antoyo/mem-trace) + +`rustc` needs to be built without `jemalloc` so that `mem-trace` can overload `malloc` since `jemalloc` is linked statically, so a `LD_PRELOAD`-ed library won't a chance to intercept the calls to `malloc`. + +### How to generate GIMPLE + +If you need to check what gccjit is generating (GIMPLE), then take a look at how to +generate it in [gimple.md](./doc/gimple.md). + +### How to build a cross-compiling libgccjit + +#### Building libgccjit + + * Follow the instructions on [this repo](https://github.com/cross-cg-gcc-tools/cross-gcc). + +#### Configuring rustc_codegen_gcc + + * Run `./y.sh prepare --cross` so that the sysroot is patched for the cross-compiling case. + * Set the path to the cross-compiling libgccjit in `gcc-path` (in `config.toml`). + * Make sure you have the linker for your target (for instance `m68k-unknown-linux-gnu-gcc`) in your `$PATH`. Currently, the linker name is hardcoded as being `$TARGET-gcc`. Specify the target when building the sysroot: `./y.sh build --target-triple m68k-unknown-linux-gnu`. + * Build your project by specifying the target: `OVERWRITE_TARGET_TRIPLE=m68k-unknown-linux-gnu ../y.sh cargo build --target m68k-unknown-linux-gnu`. + +If the target is not yet supported by the Rust compiler, create a [target specification file](https://docs.rust-embedded.org/embedonomicon/custom-target.html) (note that the `arch` specified in this file must be supported by the rust compiler). +Then, you can use it the following way: + + * Add the target specification file using `--target` as an **absolute** path to build the sysroot: `./y.sh build --target-triple m68k-unknown-linux-gnu --target $(pwd)/m68k-unknown-linux-gnu.json` + * Build your project by specifying the target specification file: `OVERWRITE_TARGET_TRIPLE=m68k-unknown-linux-gnu ../y.sh cargo build --target path/to/m68k-unknown-linux-gnu.json`. + +If you get the following error: + +``` +/usr/bin/ld: unrecognised emulation mode: m68kelf +``` + +Make sure you set `gcc-path` (in `config.toml`) to the install directory.