Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refresh README documentation #533

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Conversation

darcagn
Copy link
Contributor

@darcagn darcagn commented Jun 19, 2024

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


## 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think https://rustup.rs/ is better for installing rustup.

```bash
--enable-languages=jit,c++
$ make -C gcc check-jit
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why adding -C gcc?

$ 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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same question.


### 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`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't recommend that.

Copy link
Contributor

@antoyo antoyo Jun 19, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please leave the comment.

$ ./y.sh build --sysroot --release
```

To run the tests:

You may also run the tests:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should remove all mentions to $CG_GCCJIT_DIR.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert.

```

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert.

@@ -1,2 +1,2 @@
#gcc-path = "gcc-build/gcc"
#gcc-path = "gcc-install/lib"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert. I never run make install and I'd like to keep it that way. You can mention the install folder too though.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe make install can be necessary for e.g. using LTO.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Instructions should use shell syntax
3 participants