Skip to content

Commit 3b843f9

Browse files
GuillaumeGomezGuillaumeGomez
committed
Split Readme even further
1 parent cb14f43 commit 3b843f9

File tree

5 files changed

+191
-171
lines changed

5 files changed

+191
-171
lines changed

‎Readme.md

+11-171
Original file line numberDiff line numberDiff line change
@@ -139,179 +139,19 @@ $ LIBRARY_PATH="[gcc-path value]" LD_LIBRARY_PATH="[gcc-path value]" rustc +$(ca
139139
<dd>Dump a C-like representation to /tmp/gccjit_dumps and enable debug info in order to debug this C-like representation.</dd>
140140
</dl>
141141

142-
## Licensing
143-
144-
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.
145-
146-
However, programs compiled with `rustc_codegen_gcc` do not need to be released under a GPL license.
147-
148-
## Debugging
149-
150-
Sometimes, libgccjit will crash and output an error like this:
151-
152-
```
153-
during RTL pass: expand
154-
libgccjit.so: error: in expmed_mode_index, at expmed.h:249
155-
0x7f0da2e61a35 expmed_mode_index
156-
../../../gcc/gcc/expmed.h:249
157-
0x7f0da2e61aa4 expmed_op_cost_ptr
158-
../../../gcc/gcc/expmed.h:271
159-
0x7f0da2e620dc sdiv_cost_ptr
160-
../../../gcc/gcc/expmed.h:540
161-
0x7f0da2e62129 sdiv_cost
162-
../../../gcc/gcc/expmed.h:558
163-
0x7f0da2e73c12 expand_divmod(int, tree_code, machine_mode, rtx_def*, rtx_def*, rtx_def*, int)
164-
../../../gcc/gcc/expmed.c:4335
165-
0x7f0da2ea1423 expand_expr_real_2(separate_ops*, rtx_def*, machine_mode, expand_modifier)
166-
../../../gcc/gcc/expr.c:9240
167-
0x7f0da2cd1a1e expand_gimple_stmt_1
168-
../../../gcc/gcc/cfgexpand.c:3796
169-
0x7f0da2cd1c30 expand_gimple_stmt
170-
../../../gcc/gcc/cfgexpand.c:3857
171-
0x7f0da2cd90a9 expand_gimple_basic_block
172-
../../../gcc/gcc/cfgexpand.c:5898
173-
0x7f0da2cdade8 execute
174-
../../../gcc/gcc/cfgexpand.c:6582
175-
```
176-
177-
To see the code which causes this error, call the following function:
178-
179-
```c
180-
gcc_jit_context_dump_to_file(ctxt, "/tmp/output.c", 1 /* update_locations */)
181-
```
182-
183-
This will create a C-like file and add the locations into the IR pointing to this C file.
184-
Then, rerun the program and it will output the location in the second line:
185-
186-
```
187-
libgccjit.so: /tmp/something.c:61322:0: error: in expmed_mode_index, at expmed.h:249
188-
```
189-
190-
Or add a breakpoint to `add_error` in gdb and print the line number using:
191-
192-
```
193-
p loc->m_line
194-
p loc->m_filename->m_buffer
195-
```
196-
197-
To print a debug representation of a tree:
198-
199-
```c
200-
debug_tree(expr);
201-
```
202-
203-
(defined in print-tree.h)
204-
205-
To print a debug representation of a gimple struct:
206-
207-
```c
208-
debug_gimple_stmt(gimple_struct)
209-
```
210-
211-
To get the `rustc` command to run in `gdb`, add the `--verbose` flag to `cargo build`.
212-
213-
To have the correct file paths in `gdb` instead of `/usr/src/debug/gcc/libstdc++-v3/libsupc++/eh_personality.cc`:
214-
215-
Maybe by calling the following at the beginning of gdb:
216-
217-
```
218-
set substitute-path /usr/src/debug/gcc /path/to/gcc-repo/gcc
219-
```
220-
221-
TODO(antoyo): but that's not what I remember I was doing.
222-
223-
### `failed to build archive` error
224-
225-
When you get this error:
226-
227-
```
228-
error: failed to build archive: failed to open object file: No such file or directory (os error 2)
229-
```
230-
231-
That can be caused by the fact that you try to compile with `lto = "fat"`, but you didn't compile the sysroot with LTO.
232-
(Not sure if that's the reason since I cannot reproduce anymore. Maybe it happened when forgetting setting `FAT_LTO`.)
142+
## Extra documentation
233143

234-
### ld: cannot find crtbegin.o
144+
More specific documentation is available in the [`doc`](./doc) folder:
235145

236-
When compiling an executable with libgccijt, if setting the `*LIBRARY_PATH` variables to the install directory, you will get the following errors:
146+
* [Common errors](./doc/errors.md)
147+
* [Debugging GCC LTO](./doc/debugging-gcc-lto.md)
148+
* [Debugging libgccjit](./doc/debugging-libgccjit.md)
149+
* [Git subtree sync](./doc/subtree.md)
150+
* [List of useful commands](./doc/tips.md)
151+
* [Send a patch to GCC](./doc/sending-gcc-patch.md)
237152

238-
```
239-
ld: cannot find crtbegin.o: No such file or directory
240-
ld: cannot find -lgcc: No such file or directory
241-
ld: cannot find -lgcc: No such file or directory
242-
libgccjit.so: error: error invoking gcc driver
243-
```
244-
245-
To fix this, set the variables to `gcc-build/build/gcc`.
246-
247-
### How to debug GCC LTO
248-
249-
Run do the command with `-v -save-temps` and then extract the `lto1` line from the output and run that under the debugger.
250-
251-
### How to send arguments to the GCC linker
252-
253-
```
254-
CG_RUSTFLAGS="-Clink-args=-save-temps -v" ../y.sh cargo build
255-
```
256-
257-
### How to see the personality functions in the asm dump
258-
259-
```
260-
CG_RUSTFLAGS="-Clink-arg=-save-temps -v -Clink-arg=-dA" ../y.sh cargo build
261-
```
262-
263-
### How to see the LLVM IR for a sysroot crate
264-
265-
```
266-
cargo build -v --target x86_64-unknown-linux-gnu -Zbuild-std
267-
# Take the command from the output and add --emit=llvm-ir
268-
```
269-
270-
### To prevent the linker from unmangling symbols
271-
272-
Run with:
273-
274-
```
275-
COLLECT_NO_DEMANGLE=1
276-
```
277-
278-
### How to use a custom-build rustc
279-
280-
* Build the stage2 compiler (`rustup toolchain link debug-current build/x86_64-unknown-linux-gnu/stage2`).
281-
* Clean and rebuild the codegen with `debug-current` in the file `rust-toolchain`.
282-
283-
### How to use [mem-trace](https://github.com/antoyo/mem-trace)
284-
285-
`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`.
286-
287-
### How to generate GIMPLE
288-
289-
If you need to check what gccjit is generating (GIMPLE), then take a look at how to
290-
generate it in [gimple.md](./doc/gimple.md).
291-
292-
### How to build a cross-compiling libgccjit
293-
294-
#### Building libgccjit
295-
296-
* Follow the instructions on [this repo](https://github.com/cross-cg-gcc-tools/cross-gcc).
297-
298-
#### Configuring rustc_codegen_gcc
299-
300-
* Run `./y.sh prepare --cross` so that the sysroot is patched for the cross-compiling case.
301-
* Set the path to the cross-compiling libgccjit in `gcc-path` (in `config.toml`).
302-
* 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`.
303-
* Build your project by specifying the target: `OVERWRITE_TARGET_TRIPLE=m68k-unknown-linux-gnu ../y.sh cargo build --target m68k-unknown-linux-gnu`.
304-
305-
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).
306-
Then, you can use it the following way:
307-
308-
* 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`
309-
* 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`.
310-
311-
If you get the following error:
153+
## Licensing
312154

313-
```
314-
/usr/bin/ld: unrecognised emulation mode: m68kelf
315-
```
155+
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.
316156

317-
Make sure you set `gcc-path` (in `config.toml`) to the install directory.
157+
However, programs compiled with `rustc_codegen_gcc` do not need to be released under a GPL license.

‎doc/debugging-gcc-lto.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# How to debug GCC LTO
2+
3+
Run do the command with `-v -save-temps` and then extract the `lto1` line from the output and run that under the debugger.

‎doc/debugging-libgccjit.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Debugging libgccjit
2+
3+
Sometimes, libgccjit will crash and output an error like this:
4+
5+
```
6+
during RTL pass: expand
7+
libgccjit.so: error: in expmed_mode_index, at expmed.h:249
8+
0x7f0da2e61a35 expmed_mode_index
9+
../../../gcc/gcc/expmed.h:249
10+
0x7f0da2e61aa4 expmed_op_cost_ptr
11+
../../../gcc/gcc/expmed.h:271
12+
0x7f0da2e620dc sdiv_cost_ptr
13+
../../../gcc/gcc/expmed.h:540
14+
0x7f0da2e62129 sdiv_cost
15+
../../../gcc/gcc/expmed.h:558
16+
0x7f0da2e73c12 expand_divmod(int, tree_code, machine_mode, rtx_def*, rtx_def*, rtx_def*, int)
17+
../../../gcc/gcc/expmed.c:4335
18+
0x7f0da2ea1423 expand_expr_real_2(separate_ops*, rtx_def*, machine_mode, expand_modifier)
19+
../../../gcc/gcc/expr.c:9240
20+
0x7f0da2cd1a1e expand_gimple_stmt_1
21+
../../../gcc/gcc/cfgexpand.c:3796
22+
0x7f0da2cd1c30 expand_gimple_stmt
23+
../../../gcc/gcc/cfgexpand.c:3857
24+
0x7f0da2cd90a9 expand_gimple_basic_block
25+
../../../gcc/gcc/cfgexpand.c:5898
26+
0x7f0da2cdade8 execute
27+
../../../gcc/gcc/cfgexpand.c:6582
28+
```
29+
30+
To see the code which causes this error, call the following function:
31+
32+
```c
33+
gcc_jit_context_dump_to_file(ctxt, "/tmp/output.c", 1 /* update_locations */)
34+
```
35+
36+
This will create a C-like file and add the locations into the IR pointing to this C file.
37+
Then, rerun the program and it will output the location in the second line:
38+
39+
```
40+
libgccjit.so: /tmp/something.c:61322:0: error: in expmed_mode_index, at expmed.h:249
41+
```
42+
43+
Or add a breakpoint to `add_error` in gdb and print the line number using:
44+
45+
```
46+
p loc->m_line
47+
p loc->m_filename->m_buffer
48+
```
49+
50+
To print a debug representation of a tree:
51+
52+
```c
53+
debug_tree(expr);
54+
```
55+
56+
(defined in print-tree.h)
57+
58+
To print a debug representation of a gimple struct:
59+
60+
```c
61+
debug_gimple_stmt(gimple_struct)
62+
```
63+
64+
To get the `rustc` command to run in `gdb`, add the `--verbose` flag to `cargo build`.
65+
66+
To have the correct file paths in `gdb` instead of `/usr/src/debug/gcc/libstdc++-v3/libsupc++/eh_personality.cc`:
67+
68+
Maybe by calling the following at the beginning of gdb:
69+
70+
```
71+
set substitute-path /usr/src/debug/gcc /path/to/gcc-repo/gcc
72+
```
73+
74+
TODO(antoyo): but that's not what I remember I was doing.
75+
76+
# How to debug GCC LTO
77+
78+
Run do the command with `-v -save-temps` and then extract the `lto1` line from the output and run that under the debugger.

‎doc/errors.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Common errors
2+
3+
This file lists errors that were encountered and how to fix them.
4+
5+
### `failed to build archive` error
6+
7+
When you get this error:
8+
9+
```
10+
error: failed to build archive: failed to open object file: No such file or directory (os error 2)
11+
```
12+
13+
That can be caused by the fact that you try to compile with `lto = "fat"`, but you didn't compile the sysroot with LTO.
14+
(Not sure if that's the reason since I cannot reproduce anymore. Maybe it happened when forgetting setting `FAT_LTO`.)
15+
16+
### ld: cannot find crtbegin.o
17+
18+
When compiling an executable with libgccijt, if setting the `*LIBRARY_PATH` variables to the install directory, you will get the following errors:
19+
20+
```
21+
ld: cannot find crtbegin.o: No such file or directory
22+
ld: cannot find -lgcc: No such file or directory
23+
ld: cannot find -lgcc: No such file or directory
24+
libgccjit.so: error: error invoking gcc driver
25+
```

‎doc/tips.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Tips
2+
3+
The following shows how to do different random small things we encountered and thought could
4+
be useful.
5+
6+
### How to send arguments to the GCC linker
7+
8+
```
9+
CG_RUSTFLAGS="-Clink-args=-save-temps -v" ../y.sh cargo build
10+
```
11+
12+
### How to see the personality functions in the asm dump
13+
14+
```
15+
CG_RUSTFLAGS="-Clink-arg=-save-temps -v -Clink-arg=-dA" ../y.sh cargo build
16+
```
17+
18+
### How to see the LLVM IR for a sysroot crate
19+
20+
```
21+
cargo build -v --target x86_64-unknown-linux-gnu -Zbuild-std
22+
# Take the command from the output and add --emit=llvm-ir
23+
```
24+
25+
### To prevent the linker from unmangling symbols
26+
27+
Run with:
28+
29+
```
30+
COLLECT_NO_DEMANGLE=1
31+
```
32+
33+
### How to use a custom-build rustc
34+
35+
* Build the stage2 compiler (`rustup toolchain link debug-current build/x86_64-unknown-linux-gnu/stage2`).
36+
* Clean and rebuild the codegen with `debug-current` in the file `rust-toolchain`.
37+
38+
### How to use [mem-trace](https://github.com/antoyo/mem-trace)
39+
40+
`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`.
41+
42+
### How to generate GIMPLE
43+
44+
If you need to check what gccjit is generating (GIMPLE), then take a look at how to
45+
generate it in [gimple.md](./doc/gimple.md).
46+
47+
### How to build a cross-compiling libgccjit
48+
49+
To fix this, set the variables to `gcc-build/build/gcc`.
50+
51+
#### Building libgccjit
52+
53+
* Follow the instructions on [this repo](https://github.com/cross-cg-gcc-tools/cross-gcc).
54+
55+
#### Configuring rustc_codegen_gcc
56+
57+
* Run `./y.sh prepare --cross` so that the sysroot is patched for the cross-compiling case.
58+
* Set the path to the cross-compiling libgccjit in `gcc-path` (in `config.toml`).
59+
* 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`.
60+
* Build your project by specifying the target: `OVERWRITE_TARGET_TRIPLE=m68k-unknown-linux-gnu ../y.sh cargo build --target m68k-unknown-linux-gnu`.
61+
62+
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).
63+
Then, you can use it the following way:
64+
65+
* 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`
66+
* 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`.
67+
68+
If you get the following error:
69+
70+
```
71+
/usr/bin/ld: unrecognised emulation mode: m68kelf
72+
```
73+
74+
Make sure you set `gcc-path` (in `config.toml`) to the install directory.

0 commit comments

Comments
 (0)