|
| 1 | +# Bootstrapping Rust |
| 2 | + |
| 3 | +This is an in-progress README which is targeted at helping to explain how Rust |
| 4 | +is bootstrapped and in general some of the technical details of the build |
| 5 | +system. |
| 6 | + |
| 7 | +> **Note**: This build system is currently under active development and is not |
| 8 | +> intended to be the primarily used one just yet. The makefiles are currently |
| 9 | +> the ones that are still "guaranteed to work" as much as possible at least. |
| 10 | +
|
| 11 | +## Using the new build system |
| 12 | + |
| 13 | +When configuring Rust via `./configure`, pass the following to enable building |
| 14 | +via this build system: |
| 15 | + |
| 16 | +``` |
| 17 | +./configure --enable-rustbuild |
| 18 | +``` |
| 19 | + |
| 20 | +## ... |
| 21 | + |
| 22 | +## Directory Layout |
| 23 | + |
| 24 | +This build system houses all output under the `target` directory, which looks |
| 25 | +like this: |
| 26 | + |
| 27 | +``` |
| 28 | +# Root folder of all output. Everything is scoped underneath here |
| 29 | +build/ |
| 30 | +
|
| 31 | + # Location where the stage0 compiler downloads are all cached. This directory |
| 32 | + # only contains the tarballs themselves as they're extracted elsewhere. |
| 33 | + cache/ |
| 34 | + 2015-12-19/ |
| 35 | + 2016-01-15/ |
| 36 | + 2016-01-21/ |
| 37 | + ... |
| 38 | +
|
| 39 | + # Output directory for building this build system itself. The stage0 |
| 40 | + # cargo/rustc are used to build the build system into this location. |
| 41 | + bootstrap/ |
| 42 | + debug/ |
| 43 | + release/ |
| 44 | +
|
| 45 | + # Each remaining directory is scoped by the "host" triple of compilation at |
| 46 | + # hand. |
| 47 | + x86_64-unknown-linux-gnu/ |
| 48 | +
|
| 49 | + # The build artifacts for the `compiler-rt` library for the target this |
| 50 | + # folder is under. The exact layout here will likely depend on the platform, |
| 51 | + # and this is also built with CMake so the build system is also likely |
| 52 | + # different. |
| 53 | + compiler-rt/build/ |
| 54 | +
|
| 55 | + # Output folder for LLVM if it is compiled for this target |
| 56 | + llvm/ |
| 57 | +
|
| 58 | + # build folder (e.g. the platform-specific build system). Like with |
| 59 | + # compiler-rt this is compiled with CMake |
| 60 | + build/ |
| 61 | +
|
| 62 | + # Installation of LLVM. Note that we run the equivalent of 'make install' |
| 63 | + # for LLVM to setup these folders. |
| 64 | + bin/ |
| 65 | + lib/ |
| 66 | + include/ |
| 67 | + share/ |
| 68 | + ... |
| 69 | +
|
| 70 | + # Location where the stage0 Cargo and Rust compiler are unpacked. This |
| 71 | + # directory is purely an extracted and overlaid tarball of these two (done |
| 72 | + # by the bootstrapy python script). In theory the build system does not |
| 73 | + # modify anything under this directory afterwards. |
| 74 | + stage0/ |
| 75 | +
|
| 76 | + # These to build directories are the cargo output directories for builds of |
| 77 | + # the standard library and compiler, respectively. Internally these may also |
| 78 | + # have other target directories, which represent artifacts being compiled |
| 79 | + # from the host to the specified target. |
| 80 | + # |
| 81 | + # Essentially, each of these directories is filled in by one `cargo` |
| 82 | + # invocation. The build system instruments calling Cargo in the right order |
| 83 | + # with the right variables to ensure these are filled in correctly. |
| 84 | + stageN-std/ |
| 85 | + stageN-rustc/ |
| 86 | +
|
| 87 | + # This is a special case of the above directories, **not** filled in via |
| 88 | + # Cargo but rather the build system itself. The stage0 compiler already has |
| 89 | + # a set of target libraries for its own host triple (in its own sysroot) |
| 90 | + # inside of stage0/. When we run the stage0 compiler to bootstrap more |
| 91 | + # things, however, we don't want to use any of these libraries (as those are |
| 92 | + # the ones that we're building). So essentially, when the stage1 compiler is |
| 93 | + # being compiled (e.g. after libstd has been built), *this* is used as the |
| 94 | + # sysroot for the stage0 compiler being run. |
| 95 | + # |
| 96 | + # Basically this directory is just a temporary artifact use to configure the |
| 97 | + # stage0 compiler to ensure that the libstd we just built is used to |
| 98 | + # compile the stage1 compiler. |
| 99 | + stage0-rustc/lib/ |
| 100 | +
|
| 101 | + # These output directories are intended to be standalone working |
| 102 | + # implementations of the compiler (corresponding to each stage). The build |
| 103 | + # system will link (using hard links) output from stageN-{std,rustc} into |
| 104 | + # each of these directories. |
| 105 | + # |
| 106 | + # In theory there is no extra build output in these directories. |
| 107 | + stage1/ |
| 108 | + stage2/ |
| 109 | + stage3/ |
| 110 | +``` |
0 commit comments