# Objective
Running `cargo ci` on Fedora 40 causes a system crash due to many `ld`
processes consuming all available memory when performing doc tests.
## Solution
This PR extends #13553.
- Add reference to #12207 in the CI sections of `CONTRIBUTING.md` and
`config_fast_builds.toml`.
- Add sample `rustdocflags` configurations for `lld` and `mold` to
`config_fast_builds.toml` for Linux.
## Testing
Crashing configuration
- config.toml
```
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-Clink-arg=-fuse-ld=lld"]
[alias]
ci = "run --package ci --"
```
- Test command
`cargo ci`
Working configuration
- config.toml
```
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-Clink-arg=-fuse-ld=lld"]
rustdocflags = ["-Clink-arg=-fuse-ld=lld"]
[alias]
ci = "run --package ci --"
```
- Test command
`cargo ci`
# Objective
- Rustdoc doesn't seem to follow cargo's `linker` setting
- Improves the situation in #12207
## Solution
- Explicitly set the linker in rustdoc flags
## Testing
- I tested this change on Windows and it significantly improves testing
performances (can't give an exact estimate since they got stuck before
this change)
---
Note: I avoided changing the settings on Linux and MacOS because I can't
test on those platforms. It would be nice if someone could test similar
changes there and report so they can be done on all major platforms.
# Objective
- https://github.com/bevyengine/bevy/pull/13136 changed the default
value of `-Zshare-generics=n` to `-Zshare-generics=y` on Windows
- New users are encouraged to use dynamic builds and LLD when setting up
Bevy
- New users are also encouraged to check out `fast_config.toml`
- https://github.com/bevyengine/bevy/issues/1126 means that running
dynamic builds, using LLD and sharing generics on Windows results in a
cryptic error message
As a result, a new Windows user following all recommendations for better
compiles is actually not able to compile Bevy at all.
## Solution
- Set `-Zshare-generics=n` on Windows with a comment saying this is for
dynamic linking
## Testing
I verified that https://github.com/bevyengine/bevy/issues/1126 is still
in place on the current nightly (1.80)
## Additional Info
Maybe the website should mention this as well? The relevant snippet
there looks like this:
```toml
# /path/to/project/.cargo/config.toml
[target.x86_64-unknown-linux-gnu]
rustflags = [
# (Nightly) Make the current crate share its generic instantiations
"-Zshare-generics=y",
]
```
so it kinda implies it's only for Linux? Which is not quite true, this
setting works on macOS as well AFAIK
# Objective
- Running `cargo run --package ci -- ...` is lengthy, and `cargo r -p ci
-- ...` isn't much better.
- Closes#13197.
## Solution
- Add an opt-in alias to the `ci` tool with `cargo ci ...`.
- You need to copy `config_fast_builds.toml` to `config.toml` to enable
this functionality.
## Testing
- Copy `config_fast_builds.toml` to `config.toml`, then run `cargo ci
--help`.
---
## Changelog
- Added `cargo ci` alias for internal `ci` tool.
# Objective
- `config_fast_builds.toml` could use some general improvements and
additions.
- [Mold](https://github.com/rui314/mold) is a modern linker with serious
performance improvements that provides a good alternative to LLD.
- This is exactly the same as #12949; I accidentally deleted the branch.
😅
## Solution
- Majorly improve `config_fast_builds.toml`.
- Add further documentation.
- Add a section for the alternative Mold linker, which is **much**
faster.
- Disable nightly options by default so that developers running stable
can copy the file without having to edit it. (Nightly is still
recommended, but this is following suite with `rustfmt.toml`.)
---
## Changelog
- Majorly improved `config_fast_builds.toml` documentation and added
Mold linker.
# Objective
- The build on Windows currently fails on stable when using the
`config.toml` as described but commenting out all lines that say
"Nightly"
## Solution
- Add a missing nightly specifier for a flag that won't run on stable
# Objective
Improve compile times.
## Solution
The `-Z threads=0` option has been introduced into nightly rust somewhat
recently, and was showcased in this [rust-lang
article](https://blog.rust-lang.org/2023/11/09/parallel-rustc.html).
This option improves multithreading in rust and speeds up compilation. I
added this option to `config_fast_builds.toml` so others can also use
this option to improve compile times.
`-Z threads=0` automatically uses the same amount of threads as the
amount of threads in your system (See [rustc source
code](6b4f1c5e78/compiler/rustc_session/src/options.rs (L617))).
### Benchmarks
> **Disclaimer:** This section was written before I knew of `-Z
threads=0`, so it uses `-Z threads=8` instead.
I compiled bevy with/without the `-Z threads=8` and saw about a 7%
improvement in compliation times on my Kubuntu system with a 13th Gen
Intel® Core™ i5-13400.
Also the compile times go down over time, probably because I had other
things running in the background.
#### Without `-Z threads=8`
- 42.33s
- 40.90s
- 38.27s
- 38.07s
- 37.17s
- 37.67s
- 36.63s
- 37.24s
**Average**: 38.535
#### With `-Z threads=8`
- 36.77s
- 39.50s
- 38.86s
- 35.61s
- 34.37s
- 34.32s
- 34.44s
- 33.74s
**Average**: 35.95125
# Objective
Theres no explaination for what the compiler flags
`config_fast_builds.toml` do
## Solution
Explain what the flags in `config_fast_builds.toml` do.
# Objective
Fixes#4751, zld link error.
## Solution
- Change the `zld` file path in the example to the one homebrew installs to by default, `/usr/local/bin/zld`.
Not sure if this is the new format, but quickly looking I couldn't wind a easy way to update it in the book
# Objective
* For sample project to compile after first pages of book
got:
```
= note: clang: error: invalid linker name in argument '-fuse-ld=/usr/local/bin/zld'
error: linking with `cc` failed: exit status: 1
```
## Solution
FIx to correct zld path
# Objective
The description of NixOS dependencies is extremely long and spends entire paragraphs just for simple line changes.
With this PR it should be much simpler.
## Solution
- Linking Vulkan in `build.rs` is less effective than adding it in LD_LIBRARY_PATH, so I removed the former (related to #1992);
- I put a simple comment explaining the line in the list of dependencies, instead of making entire paragraphs;
- Clang is not in an absolute path in `.cargo/config_fast_builds` anymore, so that there is no need to specify it in `docs/linux_dependencies.md` (didn't test if this breaks other distros, though I doubt it. Also, maybe it could also be done on Darwin for consistency?);
- Also added optional wayland dependencies.
A few notes:
- The x11 libraries will be linked only during the compilation phase. This means that if you use the `x11` feature without these libraries in the environment (for example because you forget to enter the nix shell before compiling), the program will still compile successfully but won't run. You'll have to `cargo clean` and recompile with the x11 libraries in the environment. I don't know if this is important enough to be added to the documentation, but it's not specified anywhere, though I don't think it's specific to NixOS;
- The wayland dependencies need to be put in LD_LIBRARY_PATH only in certain conditions (IIRC, only if using the `dynamic` feature) and the text doesn't specify it. Because putting them there doesn't increase the number of dependencies (they are already in buildInputs) or alter the performance, I doubt anyone will care;
- Should I comment out what isn't needed by default?
- ~I removed `cargo` from buildInputs. Ignoring the fact that it should be in nativeBuildInputs, having it in `shell.nix` allows to use stable Rust in case it's not in the system environment, but maybe the user wanted to use the version that was already in the system environment and will be caught by surprise. In my opinion, if someone is looking at a Bevy's documentation on NixOS, that user will either have Rust already in the system environment (eg. via rustup) or is capable to add the toolchain they want on shell.nix by themselves. This isn't exactly the place to explain how this works.~ ~EDIT: I replaced `cargo` with Rust from the [Oxalica overlay](https://github.com/oxalica/rust-overlay) in order to have the latest nightly.~ EDIT: Removed `cargo` from dependencies. See comments for details.
# Objective
M1 Macs / Apple Silicon / simply aarch64 needs to be specified for it to compile with zld, so users might be surprised to find that they aren't getting the benefits and see the fast compiles they might be seeing on other platforms.
## Solution
- Add it? :)
This PR is easiest to review commit by commit.
Followup on https://github.com/bevyengine/bevy/pull/1309#issuecomment-767310084
- [x] Switch from a bash script to an xtask rust workspace member.
- Results in ~30s longer CI due to compilation of the xtask itself
- Enables Bevy contributors on any platform to run `cargo ci` to run linting -- if the default available Rust is the same version as on CI, then the command should give an identical result.
- [x] Use the xtask from official CI so there's only one place to update.
- [x] Bonus: Run clippy on the _entire_ workspace (existing CI setup was missing the `--workspace` flag
- [x] Clean up newly-exposed clippy errors
~#1388 builds on this to clean up newly discovered clippy errors -- I thought it might be nicer as a separate PR.~ Nope, merged it into this one so CI would pass.
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
