Title: "Build mode" for TypeScript · Issue #22997 · microsoft/TypeScript · GitHub
Open Graph Title: "Build mode" for TypeScript · Issue #22997 · microsoft/TypeScript
X Title: "Build mode" for TypeScript · Issue #22997 · microsoft/TypeScript
Description: This is a follow-up to #3469. Most of this work is already done at https://github.com/RyanCavanaugh/tsbuild and just needs to be ported into the TypeScript code base. "Build Mode" for TypeScript TypeScript currently (soon...) supports pr...
Open Graph Description: This is a follow-up to #3469. Most of this work is already done at https://github.com/RyanCavanaugh/tsbuild and just needs to be ported into the TypeScript code base. "Build Mode" for TypeScript Ty...
X Description: This is a follow-up to #3469. Most of this work is already done at https://github.com/RyanCavanaugh/tsbuild and just needs to be ported into the TypeScript code base. "Build Mode" for Typ...
Opengraph URL: https://github.com/microsoft/TypeScript/issues/22997
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"\"Build mode\" for TypeScript","articleBody":"This is a follow-up to #3469. Most of this work is already done at https://github.com/RyanCavanaugh/tsbuild and just needs to be ported into the TypeScript code base.\r\n\r\n## \"Build Mode\" for TypeScript\r\n\r\nTypeScript currently (soon...) supports *project references*. However, if an upstream project is unbuilt, the developer will see an error telling them to build that project first.\r\n\r\nThere is a clear need for a build-scheduling mode for TypeScript that intelligently builds upstream projects.\r\n\r\nIn *build mode* (`tsc -b`), `tsc` will determine which other builds need to happen, order them correctly, and perform that build.\r\n\r\nOne way to think of it:\r\n```\r\n\"tsc -p\" : \"tsc -b\" :: \"csc\" : \"msbuild\"\r\n or\r\n\"tsc -p\" : \"tsc -b\" :: \"gcc\" : \"make\" \r\n```\r\n\r\n## Terminology\r\n\r\n * Project: A **project** is a single compilation unit, i.e. result of TypeScript's internal `createProgram` call, originating from a `tsconfig` file, with a defined set of inputs and outputs\r\n * Upstream/downstream: A project *depends* on **upstream** projects; projects *which depend on it* are **downstream**\r\n\r\n## Commandline Options\r\n\r\nThe following options are supported under `-b`:\r\n\r\n * `--clean`: Remove all output files from output folders and exit\r\n * `--force`: Force all projects to be rebuilt, even if they appear to be up-to-date\r\n * `--dry`: Do nothing, but display which projects *would* be built\r\n * Special case: `--dry --clean` displays which files would be deleted\r\n * `--verbose`: Include verbose logging\r\n * (What else do we need?)\r\n\r\nThe following regular `tsc` options are available when `-b` is specified.\r\nUsing any other non-`-b`-specific flag is an error.\r\n * `--help`\r\n * `--watch`\r\n\r\n## Input Specification\r\n\r\nThe `-b` switch takes any number of arguments:\r\n\r\n> `tsc -b [projectOrGlob1] [projectOrGlob2] [projectOrGlobN...]`\r\n\r\nEach argument can be:\r\n * A filename pointing to a `tsconfig.json` file (though it may have a different name, e.g. `mybuildcfg.json`)\r\n * A directory name, which is assumed to contain a `tsconfig.json` file\r\n * A glob that matches filenames\r\n\r\nWhat happens next?\r\n * If `tsc -b` is invoked with zero arguments, then\r\n * If a `tsconfig.json` file exists in the current directory, it is the only input\r\n * Otherwise, the current directory is recursively enumerated (excluding `node_modules`) and any `tsconfig.json` files found are added to the input\r\n * Otherwise, the input is the specified list of configs or globs\r\n\r\nAfter determining the set of inputs from the commandline, each input is opened and its references are added to the input list (if it wasn't already present). This repeats until no new inputs are found.\r\n\r\nIf any input cannot be found, an error is issued and nothing happens.\r\n\r\nInputs are then topologically sorted according to their dependencies and built in that order (upstream projects first).\r\n\r\n## Circular dependencies\r\n\r\nCircular dependencies are allowed as long as at least one dependency in the circularity-causing cycle is marked `\"circular\": true`.\r\n\r\nFor the purposes of the topological sorting of inputs, edges which would cause circularity are ignored. Note that this makes the final build order dependent on the initial ordering of inputs, which may be in turn dependent on file system enumeration order. Developers using circular dependencies should observe their build behavior carefully to ensure it's sufficiently deterministic.\r\n\r\n## Errors\r\n\r\nWhen a project has a configuration, syntactic, or semantic error, no files are emitted.\r\n\r\n**Sidebar: Why?** If an upstream project has errors but emits anyway, a downstream build will see the project as \"up to date\" and the errors will be hidden until a clean build or edit to the upstream project occurs. This is potentially fixable; we could write out the errors to disk and re-issue them on subsequent builds. It's not clear if this is desirable or not.\r\n\r\n## Why have two modes (-p and -b) ?\r\n\r\nUsers running `tsc -p` may sometimes see errors that basically amount to *\"You should run `tsc -b` instead\"*. So why not just make `-p` and `-b` the same?\r\n\r\nThe reason is to prevent an `O(n^2)` increase in build I/O for developers writing large solutions using `msbuild` or similar tools. If `msbuild` invokes `tsc -p` on each project in a deep graph, then the files of the every project will get checked once for *each* downstream project.\r\n\r\nFor example, in a linear graph of 3 projects with 10 files each, `tsc -p` on each project (in the correct order) will do 10 + 10 + 10 file checks, whereas `tsc -b` would check 10 + 20 + 30 files.\r\n\r\n## Faster Rebuilds\r\n\r\nDuring a build, `tsc -b` will detect if it's writing an output that is (bytewise) identical to an existing disk artifact. This is an *unchanged output*.\r\n\r\nWhen a downstream project would need to be rebuilt, but only depends on older or unchanged outputs, then it can be *fast rebuilt*.\r\n\r\nA fast rebuild of a module compilation simply increments the timestamps of all the output files to the current time.\r\n\r\nA fast rebuild of an `outFile` compilation with upstream-changed `prepend`s needs to break apart the `.js` file on disk, use the `bundleinfo` file to identify the correct offset, and re-output the JS file.\r\n\r\n > TODO: Consider cutting this feature? If all endpoints have small additions, this isn't a big perf hit\r\n\r\n-----\r\n\r\nMore to come...\r\n","author":{"url":"https://github.com/RyanCavanaugh","@type":"Person","name":"RyanCavanaugh"},"datePublished":"2018-03-29T19:39:11Z","url":"https://github.com/microsoft/TypeScript/issues/22997"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:5cff807a-4c7a-30d5-328e-fffa19ba6e4a |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 892E:1FE434:43D906:599F99:6B01975F |
| html-safe-nonce | c27da3f57b392bb9ba51a6ab10fc4ee6c7a0c0462df30fcf050e24af7e536c90 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4OTJFOjFGRTQzNDo0M0Q5MDY6NTk5Rjk5OjZCMDE5NzVGIiwidmlzaXRvcl9pZCI6IjkxMzA0NTQ0NjcwNjAyNzUwMzkiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | ef2953bf0630afb87a7c244a3a996f4860566d106265ed3d75c4e2183686dbe4 |
| hovercard-subject-tag | issue:309878813 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/microsoft/TypeScript/22997/issue_layout |
| twitter:image | https://opengraph.githubassets.com/d135f22eae74a5fea47ac9095e7c6b28fc9db40562978ab0d14bed8238dc2ec7/microsoft/TypeScript/issues/22997 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/d135f22eae74a5fea47ac9095e7c6b28fc9db40562978ab0d14bed8238dc2ec7/microsoft/TypeScript/issues/22997 |
| og:image:alt | This is a follow-up to #3469. Most of this work is already done at https://github.com/RyanCavanaugh/tsbuild and just needs to be ported into the TypeScript code base. "Build Mode" for TypeScript Ty... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | RyanCavanaugh |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/microsoft/TypeScript git https://github.com/microsoft/TypeScript.git |
| octolytics-dimension-user_id | 6154722 |
| octolytics-dimension-user_login | microsoft |
| octolytics-dimension-repository_id | 20929025 |
| octolytics-dimension-repository_nwo | microsoft/TypeScript |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 20929025 |
| octolytics-dimension-repository_network_root_nwo | microsoft/TypeScript |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width