Skip to content

document combination of flags #756

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.

Sign up for GitHub

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

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

document combination of flags #756

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,45 @@ We encourage new contributors to join our communication channels and introduce t

## Understanding Core Concepts



### Sysroot & compilation flags

#### What *is* the sysroot?
The **sysroot** is the directory that stores the compiled standard
library (`core`, `alloc`, `std`, `test`, …) and compiler built-ins.
Rustup ships these libraries **pre-compiled with LLVM**.

Because **rustc_codegen_gcc** replaces LLVM with the GCC backend, the shipped
LLVM artefacts are **incompatible**.
Copy link
Contributor

Choose a reason for hiding this comment

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

They should be compatible. If they are not, this would be an ABI bug.

Therefore the standard library must be **rebuilt with GCC** before ordinary Rust crates can be compiled.

The freshly compiled sysroot ends up in
`build/build_sysroot/...`.

A rebuild of sysroot is needed when

* the backend changes in a way that affects code generation, or
* the user switches toolchains / updates submodules.

Both backend and sysroot can be built using different [profiles](https://doc.rust-lang.org/cargo/reference/profiles.html#default-profiles).
That is exactly what the `--sysroot`, `--release-sysroot` and `--release` flag supported by the frontend script `y.sh` take care of.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
That is exactly what the `--sysroot`, `--release-sysroot` and `--release` flag supported by the frontend script `y.sh` take care of.
That is exactly what the `--sysroot`, `--release-sysroot` and `--release` flag supported by the build system script `y.sh` take care of.



#### Typical flag combinations

| Command | Backend Profile | Sysroot Profile | Usage Scenario |
|--------------------------------------------|-------------------------------|----------------------------------|------------------------------------------------------------|
| `./y.sh build` |  dev (optimized + debuginfo) |  X |  Optimize backend with debug capabilities |
Copy link
Contributor

Choose a reason for hiding this comment

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

According to the Cargo.toml, only the dependencies are built with optimizations.

| `./y.sh build --release` |  release (optimized) |  X |  Optimize backend without rebuilding sysroot |
| `./y.sh build --release --release-sysroot`|  release (optimized) |  X |  Same as --release |
Copy link
Contributor

Choose a reason for hiding this comment

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

--release-sysroot should not be used without --sysroot, so I would remove this line and the other doing this from this table and perhaps specify that this outside the table.

| `./y.sh build --release --sysroot` |  release (optimized) |  dev (unoptimized + debuginfo) |  Optimize backend for release without full sysroot rebuild |
Copy link
Contributor

Choose a reason for hiding this comment

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

This should build the sysroot since the --sysroot flag is provided.

| `./y.sh build --sysroot` |  dev (optimized + debuginfo) |  dev (unoptimized + debuginfo) |  Full debug capabilities with optimized backend |
Copy link
Contributor

Choose a reason for hiding this comment

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

This should build the sysroot since the --sysroot flag is provided.

| `./y.sh build --release-sysroot` |  dev (optimized + debuginfo) |  X |  Build only optimized backend with debug capabilities |
| `./y.sh build --release-sysroot --sysroot`|  dev (optimized + debuginfo) |  release (optimized) |  Build optimized backend and sysroot for debugging and release, respectively |
Copy link
Contributor

Choose a reason for hiding this comment

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

This should only build a release sysroot, not a debug sysroot.
And this builds a "debug" (well, dependencies compiled with optimizations + backend not optimized) backend.




### Common Development Tasks

#### Running Specific Tests
Expand Down
4 changes: 1 addition & 3 deletions build_system/src/build.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,7 @@ impl BuildArg {
fn usage() {
println!(
r#"
`build` command help:

--sysroot : Build with sysroot"#
`build` command help:"#
);
ConfigInfo::show_usage();
println!(" --help : Show this help");
Expand Down
15 changes: 12 additions & 3 deletions build_system/src/config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -472,13 +472,22 @@ impl ConfigInfo {

pub fn show_usage() {
println!(
"\
"
--features [arg] : Add a new feature [arg]
--target-triple [arg] : Set the target triple to [arg]
--target [arg] : Set the target to [arg]
--out-dir : Location where the files will be generated
--release : Build in release mode
--release-sysroot : Build sysroot in release mode
--release : Build and optimize the backend in release mode
--sysroot : When used on its own, build both
sysroot and backend in dev. mode. Only the backend is optimized.
When used together with --release, build and optimize the backend
in release mode instead of in dev. mode.
When used together with --release-sysroot,
build and optimize the sysroot in release mode instead of in dev. mode
--release-sysroot : When used on its own, build and optimize only the backend in dev. mode.
When combined with --release, it has no effect.
When combined with --sysroot, additionally
build and optimize the sysroot in release mode
Comment on lines +480 to +490
Copy link
Contributor

Choose a reason for hiding this comment

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

I'll let you update this to reflect the above comments.
Also, most of these flags will only work with the build command, right?
If so, they should only be shown in the help of the build command.

--sysroot-panic-abort : Build the sysroot without unwinding support
--config-file : Location of the config file to be used
--gcc-path : Location of the GCC root folder
Expand Down