{"action":"created","comment":{"url":"https://api.github.com/repos/rust-lang/rust/pulls/comments/61936168","id":61936168,"diff_hunk":"@@ -108,3 +172,66 @@ build/\n     stage2/\n     stage3/\n ```\n+\n+## Cargo projects\n+\n+The current build is unfortunately not quite as simple as `cargo build` in a\n+directory, but rather the compiler is split into three different Cargo projects:\n+\n+* `src/rustc/std_shim` - a project which builds and compiles libstd\n+* `src/rustc/test_shim` - a project which builds and compiles libtest\n+* `src/rustc` - the actual compiler itself\n+\n+Each \"project\" has a corresponding Cargo.lock file with all dependencies, and\n+this means that building the compiler involves running Cargo three times. The\n+structure here serves two goals:\n+\n+1. Facilitating dependencies coming from crates.io. These dependencies don't\n+   depend on `std`, so libstd is a separate project compiled ahead of time\n+   before the actual compiler builds.\n+2. Splitting \"host artifacts\" from \"target artifacts\". That is, when building\n+   code for an arbitrary target you don't need the entire compiler, but you'll\n+   end up needing libraries like libtest that depend on std but also want to use\n+   crates.io dependencies. Hence, libtest is split out as its own project that\n+   is sequenced after `std` but before `rustc`. This project is built for all\n+   targets.\n+\n+There is some loss in build parallelism here because libtest can be compiled in\n+parallel with a number of rustc artifacts, but in theory the loss isn't too bad!\n+\n+## Build tools\n+\n+We've actually got quite a few tools that we use in the compiler's build system\n+and for testing. To organize these, each tool is a project in `src/tools` with a\n+corresponding `Cargo.toml`. All tools are compiled with Cargo (currently having\n+independent `Cargo.lock` files) and do not currently explicitly depend on the\n+compiler or standard library. Compiling each tool is sequenced after the\n+appropriate libstd/libtest/librustc compile above.\n+\n+## Extending rustbuild\n+\n+So you'd like to add a feature to the rustbuild build system or just fix a bug.\n+Great! One of the major motivational factors for moving away from `make` is that\n+Rust is in theory much easier to read, modify, and write. If you find anything\n+excessively confusing, please open an issue on this and we'll try to get it\n+documented or simplified pronto.\n+\n+First up, you'll probably want to read over the documentation above as that'll\n+give you a high level overview of what rustbuild is doing. You also probably\n+want to play around a bit yourself by just getting it up and running before you\n+dive too much into the actual build system itself.\n+\n+After that, each module in rustbuild should have enough documentation to keep\n+you up and running. Some general areas that you may be interested in modifying\n+are:\n+\n+* Adding a new build tool? Take a look at `build/step.rs` for examples of other\n+  tools, as well as `build/mod.rs`.\n+* Adding a new crate? Look no further! Adding crates can be done by just\n+  configuring all `Cargo.toml` files accordingly.","path":"src/bootstrap/README.md","position":194,"original_position":194,"commit_id":"5c4c35be84f6234eea789683f2fcde130e42ce31","original_commit_id":"5c4c35be84f6234eea789683f2fcde130e42ce31","user":{"login":"brson","id":147214,"avatar_url":"https://avatars.githubusercontent.com/u/147214?v=3","gravatar_id":"","url":"https://api.github.com/users/brson","html_url":"https://github.com/brson","followers_url":"https://api.github.com/users/brson/followers","following_url":"https://api.github.com/users/brson/following{/other_user}","gists_url":"https://api.github.com/users/brson/gists{/gist_id}","starred_url":"https://api.github.com/users/brson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/brson/subscriptions","organizations_url":"https://api.github.com/users/brson/orgs","repos_url":"https://api.github.com/users/brson/repos","events_url":"https://api.github.com/users/brson/events{/privacy}","received_events_url":"https://api.github.com/users/brson/received_events","type":"User","site_admin":false},"body":"This isn't clear to me. I'd guess that adding a crate means creating a new directory somewhere, writing a Cargo.toml file, and ensuring that it's mentioned in one other toml file. There's also the crates.io case. This document might say when it's appropriate to add a crates.io dependency.","created_at":"2016-05-03T18:57:39Z","updated_at":"2016-05-03T18:57:39Z","html_url":"https://github.com/rust-lang/rust/pull/33360#discussion_r61936168","pull_request_url":"https://api.github.com/repos/rust-lang/rust/pulls/33360","_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/comments/61936168"},"html":{"href":"https://github.com/rust-lang/rust/pull/33360#discussion_r61936168"},"pull_request":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/33360"}}},"pull_request":{"url":"https://api.github.com/repos/rust-lang/rust/pulls/33360","id":68630957,"html_url":"https://github.com/rust-lang/rust/pull/33360","diff_url":"https://github.com/rust-lang/rust/pull/33360.diff","patch_url":"https://github.com/rust-lang/rust/pull/33360.patch","issue_url":"https://api.github.com/repos/rust-lang/rust/issues/33360","number":33360,"state":"open","locked":false,"title":"rustbuild: Document many more parts of the build","user":{"login":"alexcrichton","id":64996,"avatar_url":"https://avatars.githubusercontent.com/u/64996?v=3","gravatar_id":"","url":"https://api.github.com/users/alexcrichton","html_url":"https://github.com/alexcrichton","followers_url":"https://api.github.com/users/alexcrichton/followers","following_url":"https://api.github.com/users/alexcrichton/following{/other_user}","gists_url":"https://api.github.com/users/alexcrichton/gists{/gist_id}","starred_url":"https://api.github.com/users/alexcrichton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alexcrichton/subscriptions","organizations_url":"https://api.github.com/users/alexcrichton/orgs","repos_url":"https://api.github.com/users/alexcrichton/repos","events_url":"https://api.github.com/users/alexcrichton/events{/privacy}","received_events_url":"https://api.github.com/users/alexcrichton/received_events","type":"User","site_admin":false},"body":"This commit expands the bootstrap build system's `README.md` as well as ensuring\r\nthat all API documentation is present and up-to-date. Additionally a new\r\n`config.toml.example` file is checked in with commented out versions of all\r\npossible configuration values.","created_at":"2016-05-02T22:18:47Z","updated_at":"2016-05-03T18:57:39Z","closed_at":null,"merged_at":null,"merge_commit_sha":"fea38d6774b22074b624ebba9d2d23a86dd50b67","assignee":{"login":"brson","id":147214,"avatar_url":"https://avatars.githubusercontent.com/u/147214?v=3","gravatar_id":"","url":"https://api.github.com/users/brson","html_url":"https://github.com/brson","followers_url":"https://api.github.com/users/brson/followers","following_url":"https://api.github.com/users/brson/following{/other_user}","gists_url":"https://api.github.com/users/brson/gists{/gist_id}","starred_url":"https://api.github.com/users/brson/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/brson/subscriptions","organizations_url":"https://api.github.com/users/brson/orgs","repos_url":"https://api.github.com/users/brson/repos","events_url":"https://api.github.com/users/brson/events{/privacy}","received_events_url":"https://api.github.com/users/brson/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/rust-lang/rust/pulls/33360/commits","review_comments_url":"https://api.github.com/repos/rust-lang/rust/pulls/33360/comments","review_comment_url":"https://api.github.com/repos/rust-lang/rust/pulls/comments{/number}","comments_url":"https://api.github.com/repos/rust-lang/rust/issues/33360/comments","statuses_url":"https://api.github.com/repos/rust-lang/rust/statuses/5c4c35be84f6234eea789683f2fcde130e42ce31","head":{"label":"alexcrichton:rustbuild-dox","ref":"rustbuild-dox","sha":"5c4c35be84f6234eea789683f2fcde130e42ce31","user":{"login":"alexcrichton","id":64996,"avatar_url":"https://avatars.githubusercontent.com/u/64996?v=3","gravatar_id":"","url":"https://api.github.com/users/alexcrichton","html_url":"https://github.com/alexcrichton","followers_url":"https://api.github.com/users/alexcrichton/followers","following_url":"https://api.github.com/users/alexcrichton/following{/other_user}","gists_url":"https://api.github.com/users/alexcrichton/gists{/gist_id}","starred_url":"https://api.github.com/users/alexcrichton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alexcrichton/subscriptions","organizations_url":"https://api.github.com/users/alexcrichton/orgs","repos_url":"https://api.github.com/users/alexcrichton/repos","events_url":"https://api.github.com/users/alexcrichton/events{/privacy}","received_events_url":"https://api.github.com/users/alexcrichton/received_events","type":"User","site_admin":false},"repo":{"id":7385331,"name":"rust","full_name":"alexcrichton/rust","owner":{"login":"alexcrichton","id":64996,"avatar_url":"https://avatars.githubusercontent.com/u/64996?v=3","gravatar_id":"","url":"https://api.github.com/users/alexcrichton","html_url":"https://github.com/alexcrichton","followers_url":"https://api.github.com/users/alexcrichton/followers","following_url":"https://api.github.com/users/alexcrichton/following{/other_user}","gists_url":"https://api.github.com/users/alexcrichton/gists{/gist_id}","starred_url":"https://api.github.com/users/alexcrichton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alexcrichton/subscriptions","organizations_url":"https://api.github.com/users/alexcrichton/orgs","repos_url":"https://api.github.com/users/alexcrichton/repos","events_url":"https://api.github.com/users/alexcrichton/events{/privacy}","received_events_url":"https://api.github.com/users/alexcrichton/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/alexcrichton/rust","description":"a safe, concurrent, practical language","fork":true,"url":"https://api.github.com/repos/alexcrichton/rust","forks_url":"https://api.github.com/repos/alexcrichton/rust/forks","keys_url":"https://api.github.com/repos/alexcrichton/rust/keys{/key_id}","collaborators_url":"https://api.github.com/repos/alexcrichton/rust/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/alexcrichton/rust/teams","hooks_url":"https://api.github.com/repos/alexcrichton/rust/hooks","issue_events_url":"https://api.github.com/repos/alexcrichton/rust/issues/events{/number}","events_url":"https://api.github.com/repos/alexcrichton/rust/events","assignees_url":"https://api.github.com/repos/alexcrichton/rust/assignees{/user}","branches_url":"https://api.github.com/repos/alexcrichton/rust/branches{/branch}","tags_url":"https://api.github.com/repos/alexcrichton/rust/tags","blobs_url":"https://api.github.com/repos/alexcrichton/rust/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/alexcrichton/rust/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/alexcrichton/rust/git/refs{/sha}","trees_url":"https://api.github.com/repos/alexcrichton/rust/git/trees{/sha}","statuses_url":"https://api.github.com/repos/alexcrichton/rust/statuses/{sha}","languages_url":"https://api.github.com/repos/alexcrichton/rust/languages","stargazers_url":"https://api.github.com/repos/alexcrichton/rust/stargazers","contributors_url":"https://api.github.com/repos/alexcrichton/rust/contributors","subscribers_url":"https://api.github.com/repos/alexcrichton/rust/subscribers","subscription_url":"https://api.github.com/repos/alexcrichton/rust/subscription","commits_url":"https://api.github.com/repos/alexcrichton/rust/commits{/sha}","git_commits_url":"https://api.github.com/repos/alexcrichton/rust/git/commits{/sha}","comments_url":"https://api.github.com/repos/alexcrichton/rust/comments{/number}","issue_comment_url":"https://api.github.com/repos/alexcrichton/rust/issues/comments{/number}","contents_url":"https://api.github.com/repos/alexcrichton/rust/contents/{+path}","compare_url":"https://api.github.com/repos/alexcrichton/rust/compare/{base}...{head}","merges_url":"https://api.github.com/repos/alexcrichton/rust/merges","archive_url":"https://api.github.com/repos/alexcrichton/rust/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/alexcrichton/rust/downloads","issues_url":"https://api.github.com/repos/alexcrichton/rust/issues{/number}","pulls_url":"https://api.github.com/repos/alexcrichton/rust/pulls{/number}","milestones_url":"https://api.github.com/repos/alexcrichton/rust/milestones{/number}","notifications_url":"https://api.github.com/repos/alexcrichton/rust/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/alexcrichton/rust/labels{/name}","releases_url":"https://api.github.com/repos/alexcrichton/rust/releases{/id}","deployments_url":"https://api.github.com/repos/alexcrichton/rust/deployments","created_at":"2012-12-31T08:59:51Z","updated_at":"2015-04-22T20:31:52Z","pushed_at":"2016-05-03T16:35:36Z","git_url":"git://github.com/alexcrichton/rust.git","ssh_url":"git@github.com:alexcrichton/rust.git","clone_url":"https://github.com/alexcrichton/rust.git","svn_url":"https://github.com/alexcrichton/rust","homepage":"http://www.rust-lang.org","size":291299,"stargazers_count":2,"watchers_count":2,"language":"Rust","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":2,"default_branch":"incoming"}},"base":{"label":"rust-lang:master","ref":"master","sha":"d80497e628945c3f11ff351030b4c62a8533e01e","user":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"repo":{"id":724712,"name":"rust","full_name":"rust-lang/rust","owner":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/rust-lang/rust","description":"A safe, concurrent, practical language.","fork":false,"url":"https://api.github.com/repos/rust-lang/rust","forks_url":"https://api.github.com/repos/rust-lang/rust/forks","keys_url":"https://api.github.com/repos/rust-lang/rust/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rust-lang/rust/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rust-lang/rust/teams","hooks_url":"https://api.github.com/repos/rust-lang/rust/hooks","issue_events_url":"https://api.github.com/repos/rust-lang/rust/issues/events{/number}","events_url":"https://api.github.com/repos/rust-lang/rust/events","assignees_url":"https://api.github.com/repos/rust-lang/rust/assignees{/user}","branches_url":"https://api.github.com/repos/rust-lang/rust/branches{/branch}","tags_url":"https://api.github.com/repos/rust-lang/rust/tags","blobs_url":"https://api.github.com/repos/rust-lang/rust/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rust-lang/rust/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rust-lang/rust/git/refs{/sha}","trees_url":"https://api.github.com/repos/rust-lang/rust/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rust-lang/rust/statuses/{sha}","languages_url":"https://api.github.com/repos/rust-lang/rust/languages","stargazers_url":"https://api.github.com/repos/rust-lang/rust/stargazers","contributors_url":"https://api.github.com/repos/rust-lang/rust/contributors","subscribers_url":"https://api.github.com/repos/rust-lang/rust/subscribers","subscription_url":"https://api.github.com/repos/rust-lang/rust/subscription","commits_url":"https://api.github.com/repos/rust-lang/rust/commits{/sha}","git_commits_url":"https://api.github.com/repos/rust-lang/rust/git/commits{/sha}","comments_url":"https://api.github.com/repos/rust-lang/rust/comments{/number}","issue_comment_url":"https://api.github.com/repos/rust-lang/rust/issues/comments{/number}","contents_url":"https://api.github.com/repos/rust-lang/rust/contents/{+path}","compare_url":"https://api.github.com/repos/rust-lang/rust/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rust-lang/rust/merges","archive_url":"https://api.github.com/repos/rust-lang/rust/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rust-lang/rust/downloads","issues_url":"https://api.github.com/repos/rust-lang/rust/issues{/number}","pulls_url":"https://api.github.com/repos/rust-lang/rust/pulls{/number}","milestones_url":"https://api.github.com/repos/rust-lang/rust/milestones{/number}","notifications_url":"https://api.github.com/repos/rust-lang/rust/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rust-lang/rust/labels{/name}","releases_url":"https://api.github.com/repos/rust-lang/rust/releases{/id}","deployments_url":"https://api.github.com/repos/rust-lang/rust/deployments","created_at":"2010-06-16T20:39:03Z","updated_at":"2016-05-03T17:53:30Z","pushed_at":"2016-05-03T18:47:17Z","git_url":"git://github.com/rust-lang/rust.git","ssh_url":"git@github.com:rust-lang/rust.git","clone_url":"https://github.com/rust-lang/rust.git","svn_url":"https://github.com/rust-lang/rust","homepage":"http://www.rust-lang.org","size":489036,"stargazers_count":16527,"watchers_count":16527,"language":"Rust","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":3153,"mirror_url":null,"open_issues_count":2508,"forks":3153,"open_issues":2508,"watchers":16527,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/33360"},"html":{"href":"https://github.com/rust-lang/rust/pull/33360"},"issue":{"href":"https://api.github.com/repos/rust-lang/rust/issues/33360"},"comments":{"href":"https://api.github.com/repos/rust-lang/rust/issues/33360/comments"},"review_comments":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/33360/comments"},"review_comment":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/rust-lang/rust/pulls/33360/commits"},"statuses":{"href":"https://api.github.com/repos/rust-lang/rust/statuses/5c4c35be84f6234eea789683f2fcde130e42ce31"}}}}