Refresh README documentation #533
Conversation
|
|
||
| ## Building | ||
| ### Dependencies | ||
| * **[rustup](https://www.rust-lang.org/tools/install)**: The rustup tool is required to build this project using the following instructions; do not rely on a Rust toolchain that may have been provided by your operating system's package manager. |
There was a problem hiding this comment.
I think https://rustup.rs/ is better for installing rustup.
| ```bash | ||
| --enable-languages=jit,c++ | ||
| $ make -C gcc check-jit |
| $ make check-jit | ||
| # To run one specific test: | ||
| $ make check-jit RUNTESTFLAGS="-v -v -v jit.exp=jit.dg/test-asm.cc" | ||
| $ make -C gcc check-jit RUNTESTFLAGS="-v -v -v jit.exp=jit.dg/test-asm.cc" |
|
|
||
| ### Building GCC with libgccjit.so | ||
| #### On Linux x86-64 | ||
| When using an x86-64 Linux host to target x86-64 Linux, building `libgccjit.so` is unnecessary -- in that case, a precompiled version may be downloaded automatically. Simply copy the provided `config.example.toml` file to `config.toml` to enable the automatic downloading of `libgccjit.so`. |
There was a problem hiding this comment.
| When using an x86-64 Linux host to target x86-64 Linux, building `libgccjit.so` is unnecessary -- in that case, a precompiled version may be downloaded automatically. Simply copy the provided `config.example.toml` file to `config.toml` to enable the automatic downloading of `libgccjit.so`. | |
| When using an x86-64 Linux host to target x86-64 Linux, building `libgccjit.so` is unnecessary (unless you patched it) -- in that case, a precompiled version may be downloaded automatically. Simply copy the provided `config.example.toml` file to `config.toml` to enable the automatic downloading of `libgccjit.so`. |
| ``` | ||
|
|
||
| and to comment the `download-gccjit` setting: | ||
| If desired, you may now delete the `gcc-source` and `gcc-build` directories to reclaim disk space, but keep the `gcc-install` directory. |
There was a problem hiding this comment.
I wouldn't recommend that.
There was a problem hiding this comment.
I guess that may be useful for people wanting the use the project, but not contribute on it. So, perhaps we should move this to the Tips document?
|
|
||
| ```bash | ||
| $ ./y.sh prepare # download and patch sysroot src and install hyperfine for benchmarking | ||
| $ ./y.sh prepare |
There was a problem hiding this comment.
Please leave the comment.
| $ ./y.sh build --sysroot --release | ||
| ``` | ||
|
|
||
| To run the tests: | ||
|
|
||
| You may also run the tests: |
There was a problem hiding this comment.
Please leave the original sentence.
|
|
||
| You have to run these commands, in the corresponding order: | ||
|
|
||
| The following example commands are run with `$CG_GCCJIT_DIR` representing the path to your rustc_codegen_gcc directory. |
There was a problem hiding this comment.
I think we should remove all mentions to $CG_GCCJIT_DIR.
There was a problem hiding this comment.
Since it seems like a recurring wish to be able to run y.sh from anywhere (@darcagn: is this why you mention this variable?), perhaps we could have a section explaining what I did to alleviate this issue, which is I created an alias y = /path/to/rustc_codegen_gcc/y.sh?
| ```bash | ||
| $ ./y.sh prepare | ||
| $ ./y.sh build --sysroot | ||
| $ CHANNEL="release" $CG_GCCJIT_DIR/y.sh cargo run |
There was a problem hiding this comment.
No need for CHANNEL="release".
|
|
||
| ```bash | ||
| $ CHANNEL="release" $CG_GCCJIT_DIR/y.sh cargo run | ||
| $ CHANNEL="release" $CG_GCCJIT_DIR/y.sh cargo build --manifest-path $CG_GCCJIT_DIR/tests/hello-world/Cargo.toml |
| ``` | ||
|
|
||
| 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. | ||
| Note: If you compiled rustc_codegen_gcc in debug mode (i.e., you didn't pass `--release` to `./y.sh` above), you should use `CHANNEL="debug"` or omit `CHANNEL="release"` completely. |
There was a problem hiding this comment.
Would be interesting to instead explain here that the CHANNEL environment variable can be used.
|
|
||
| ```bash | ||
| $ ./y.sh rustc my_crate.rs | ||
| $ $CG_GCCJIT_DIR/y.sh rustc my_crate.rs |
| @@ -1,2 +1,2 @@ | |||
| #gcc-path = "gcc-build/gcc" | |||
| #gcc-path = "gcc-install/lib" | |||
There was a problem hiding this comment.
Please revert. I never run make install and I'd like to keep it that way. You can mention the install folder too though.
There was a problem hiding this comment.
I believe make install can be necessary for e.g. using LTO.
In the 6 months or so I've been using this project to target SuperH and integrate it with the toolchain targeting the Sega Dreamcast (KallistiOS), I've had a few issues and pain points with the documentation that I'd like to address. I've also spent a lot of time troubleshooting, figuring things out with cross-compilation, listening to feedback from interested users, etc. so I'd like to pass on what I've learned by fixing up and refreshing the documentation here. Some of the changes are slightly opinionated or adjust the original steps so feel free to ask questions or for clarification, but nothing should be too bad. 😄
Thanks for all the hard work you all have done on rustc_codegen_gcc.
This should also address and fix #501