|
| 1 | +# Supplemental Tool Policy |
| 2 | +T-compiler's mandate is to do what is necessary to ship a functioning Rust compiler (`rustc`), but `rustc` has never worked in isolation. |
| 3 | +It has always required additional tools to use, whether provided with the compiler toolchain or expected in the environment. |
| 4 | +The following is an attempt to clarify some of the expectations around `rustc` and the tools it may be used with or require, |
| 5 | +and make explicit some expectations that are already implicit. |
| 6 | + |
| 7 | + |
| 8 | +## Definitions |
| 9 | +- **compilation environment** - the host system that a **provided tool** is invoked on, |
| 10 | + including its transient state like the filesystem and environment variables. |
| 11 | +- **invoke** - running the code of any artifact, whether via process spawning, library loading, or |
| 12 | + other means that the **compilation environment** may support. |
| 13 | +- **intermediates** - artifacts output by **invoking** a **compiler tool** that will be |
| 14 | + provided as inputs to compiler tools. |
| 15 | +- **compiler tool** - an artifact, especially one shipped as part of the Rust toolchain, that is |
| 16 | + **invoke**d as part of the process of compiling and linking code into binary code objects. |
| 17 | +- **binary tool** - a **compiler tool** that is used to emit or edit binary code objects. |
| 18 | +- **provided tool** - a **binary tool** or **compiler tool** shipped as part of the Rust toolchain, |
| 19 | + with the support of T-compiler and T-release. |
| 20 | + This especially includes **binary tools** like `rustc`, `rust-lld`, and `rust-objcopy`. |
| 21 | +- **supplemental tool** - a **compiler tool** that is not shipped by T-compiler and T-release, |
| 22 | + but that may be used alongside the **provided tool**s. |
| 23 | + This especially includes **binary tools** like `ld.bfd`, `link.exe`, `llvm-bolt`, and "linker scripts" |
| 24 | + (programs written in the Link Editor Command Language). |
| 25 | + |
| 26 | + |
| 27 | +## Our Use of Supplemental Tools |
| 28 | + |
| 29 | +Any provided tool, including `rustc`, may *implicitly* invoke a supplemental tool, |
| 30 | +**without** requiring explicit user input. |
| 31 | +A provided tool may examine the compilation environment to determine what tools to invoke.[^10] |
| 32 | +The compilation environment may be expected to be configured in a customary and/or idiosyncratic |
| 33 | +way when a supplemental tool is invoked. |
| 34 | + |
| 35 | +Examples of customary expectations include |
| 36 | +- an executable named `link.exe` being expected to perform the task of linking binary code objects |
| 37 | + located at paths given as arguments to it, or |
| 38 | +- a Unix tool may be expected to obey arguments in a way specified by POSIX, or |
| 39 | +- an environment variable such as `$CC` may be expected to contain a path to a C compiler. |
| 40 | + |
| 41 | +Idiosyncratic expectations may resemble a customary expectation but apply it unreasonably, |
| 42 | +such as assuming a Unix system, even macOS, resembles a Linux system with a GNU userland. |
| 43 | +Alternately they may be purely invented, such as assuming data in the compilation environment |
| 44 | +was created or modified by another provided tool in the Rust toolchain. |
| 45 | + |
| 46 | +These expectations extend to not being required to determine whether the contents of the |
| 47 | +compilation environment are safe to use, correctly functioning, or correctly named. |
| 48 | +The filesystem may be expected to be organized in a certain way, and |
| 49 | +any names provided for files may be trusted implicitly as correct labels. |
| 50 | +Reasonable attempts *should* be made to find supplemental tools at their expected paths, |
| 51 | +to document what tools we may rely on, and in what ways, but this is not *required*. |
| 52 | +It is not even required to continue to invoke a supplemental tool from the environment, |
| 53 | +as the provided tools may be expanded at the discretion of T-release and T-compiler and |
| 54 | +used for the explicit purpose of replacing supplemental tools found in the environment. |
| 55 | + |
| 56 | +If a provided tool determines a supplemental tool must be invoked and its outputs |
| 57 | +used as intermediates for any other part of the compilation process, then |
| 58 | +the resulting output may be expected to be strictly adherent to the format output by that tool. |
| 59 | +They may also be expected to fulfill other requirements, such as specifically being |
| 60 | +linkable, loadable, or even executable binary code objects, or simply |
| 61 | +retaining additional metadata sections the Rust toolchain expects. |
| 62 | + |
| 63 | +Assuming that no expectations of the provided tools have been violated, then |
| 64 | +provided tools **shall**, when emitting executable or dynamically loadable binary code objects, |
| 65 | +emit objects that at least minimally adhere to the object's binary format specification. |
| 66 | +Intermediates may not be correctly formatted, even if they usually adhere to a binary format. |
| 67 | +Adherence may be interpreted as T-compiler pleases for underdocumented binary formats. |
| 68 | + |
| 69 | +For the compiler team, this mostly means to invoke things from the environment as you like. |
| 70 | +Just try to get outputs right assuming, for example, there's no undefined behavior in the source. |
| 71 | +Ideally, we adhere enough that the "native" toolchain, including debuggers and the like, |
| 72 | +works well with our code, but there is an infinite list of possible tools one can want to use. |
| 73 | + |
| 74 | +## Triaging Supplemental Tool Issues |
| 75 | + |
| 76 | +Before resolving an issue concerning supplemental tools, expectations our toolchain depends on |
| 77 | +should be documented if they are not "obvious". For example, dependence on a minimum tool version, |
| 78 | +especially if it is higher than the one shipped with the operating system by default. |
| 79 | +The reason to only document non-obvious expectations is the verbose definition-of-definitions |
| 80 | +at the start of this document: it can take a long time to define sufficient vocabulary to |
| 81 | +describe how compilers work if you assume absolutely nothing. |
| 82 | + |
| 83 | +If someone actively includes a supplemental tool via compiler flags or configuration, then |
| 84 | +files a bug, try to determine if the object is correctly-formatted without the supplemental tool. |
| 85 | +If that is the case, then we should usually close the issue without trying to fix it |
| 86 | + |
| 87 | +Sometimes a supplemental tool is involved because it was invoked implicitly by `rustc`. |
| 88 | +If the toolchain features a provided tool that could functionally replace it, |
| 89 | +then preferably that should be done before resolving the issue. |
| 90 | + |
| 91 | +If the matter is about conformance to the local customs of a given operating system, then |
| 92 | +as long as we have a distinct target for it, some effort can be made to respond to that. |
| 93 | +We should usually try to participate, assuming the resources are open and available for doing so. |
| 94 | + |
| 95 | +[^10]: This is a functional consequence from the OS-provided execution of any tool by name |
| 96 | +being possible or preferable, as that means implicitly or explicitly rummaging through `$PATH`. |
0 commit comments