{"id":13395616,"url":"https://github.com/dart-archive/dart2js_info","last_synced_at":"2025-10-23T06:45:37.057Z","repository":{"id":36382907,"uuid":"40687781","full_name":"dart-archive/dart2js_info","owner":"dart-archive","description":"Model of the data produced by dart2js with --dump-info, and tools that process the information.","archived":true,"fork":false,"pushed_at":"2021-08-11T09:20:48.000Z","size":420,"stargazers_count":14,"open_issues_count":10,"forks_count":14,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-02-04T07:01:37.468Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/dart2js_info","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dart-archive.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-14T00:24:40.000Z","updated_at":"2023-01-28T07:17:48.000Z","dependencies_parsed_at":"2022-08-28T21:10:20.769Z","dependency_job_id":null,"html_url":"https://github.com/dart-archive/dart2js_info","commit_stats":null,"previous_names":["dart-lang/dart2js_info"],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dart-archive%2Fdart2js_info","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dart-archive%2Fdart2js_info/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dart-archive%2Fdart2js_info/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dart-archive%2Fdart2js_info/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dart-archive","download_url":"https://codeload.github.com/dart-archive/dart2js_info/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243493083,"owners_count":20299595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T18:00:26.447Z","updated_at":"2025-10-23T06:45:36.470Z","avatar_url":"https://github.com/dart-archive.png","language":"Dart","funding_links":[],"categories":["Development-Tools"],"sub_categories":[],"readme":"## Repo deprecation notice\n\n**NOTE**: This repository as been deprecated, as the source code now lives here:\n\nhttps://github.com/dart-lang/sdk/tree/master/pkg/dart2js_info\n\n# Dart2js Info\n\nThis package contains libraries and tools you can use to process info\nfiles produced when running dart2js with `--dump-info`.\n\nThe info files contain data about each element included in the output of your\nprogram. The data includes information such as:\n\n  * the size that each function adds to the `.dart.js` output,\n  * dependencies between functions,\n  * how the code is clustered when using deferred libraries, and\n  * the declared and inferred type of each function argument.\n\nAll of this information can help you understand why some piece of code is\nincluded in your compiled application, and how far was dart2js able to\nunderstand your code. This data can help you make changes to improve the quality\nand size of your framework or app.\n\nThis package focuses on gathering libraries and tools that summarize all of that\ninformation. Bear in mind that even with all these tools, it is not trivial to\nisolate code-size issues. We just hope that these tools make things a bit\neasier.\n\n## Status\n\n[![Build Status](https://github.com/dart-lang/dart2js_info/workflows/Dart%20CI/badge.svg)](https://github.com/dart-lang/dart2js_info/actions?query=workflow%3A\"Dart+CI\"+branch%3Amaster)\n\nCurrently, most tools available here can be used to analyze code-size and\nattribution of code-size to different parts of your app. With time, we hope to\nadd more data to the info files, and include better tools to help\nunderstand the results of type inference.\n\nThis package is still in flux and we might make breaking changes at any time.\nOur current goal is not to provide a stable API, we mainly want to expose the\nfunctionality and iterate on it.  We recommend that you pin a specific version\nof this package and update when needed.\n\n## Tools\n\nAll tools are provided as commands of a single command-line interface. To\ninstall:\n```console\npub global activate dart2js_info\n```\n\nTo run a tool, then run:\n```console\ndart2js_info \u003ccommand\u003e [arguments]\n```\n\nThere is a short help available on the tool, and more details are provided\nbelow.\n\n## Format\n\nThere are several formats of info files. Dart2js today produces a JSON format,\nbut very soon will switch to produce a binary format by default.\n\n## Info API\n\nThis package also exposes libraries to parse and represent the information from\nthe info files. If there is data that is stored in the info files but not\nexposed by one of our tools, you may be able to use the info APIs to quickly put\ntogether your own tool.\n\n[AllInfo][AllInfo] exposes a Dart representation of all of the collected\ninformation. There are deserialization libraries in this package to decode any\ninfo file produced by the `dart2js` `--dump-info` option. See\n`lib/binary_serialization.dart` and `lib/json_info_codec.dart` to find the\nbinary and JSON decoders respectively. For convenience,\n`package:dart2js_info/src/io.dart` also exposes a helper method that can choose,\ndepending on the extension of the info file, whether to deserialize it using the\nbinary or JSON decoder.  For example:\n\n```dart\nimport 'dart:convert';\nimport 'dart:io';\n\nimport 'package:dart2js_info/info.dart';\nimport 'package:dart2js_info/src/io.dart';\n\nmain(args) async {\n  var infoPath = args[0];\n  var info = await infoFromFile(infoPath);\n  ...\n}\n```\n\n## Available tools\n\nThe following tools are a available today:\n\n  * [`code_deps`][code_deps]: simple tool that can answer queries about the\n    dependency between functions and fields in your program. Currently it only\n    supports the `some_path` query, which shows a dependency path from one\n    function to another.\n    \n  * [`diff`][diff]: a tool that diffs two info files and reports which\n    program elements have been added, removed, or changed size. This also\n    tells which elements are no longer deferred or have become deferred.\n\n  * [`library_size`][library_size]: a tool that shows how much code was\n    attributed to each library. This tool is configurable so it can group data\n    in many ways (e.g. to tally together all libraries that belong to a package,\n    or all libraries that match certain name pattern).\n\n  * [`deferred_check`][deferred_check]: a tool that verifies that code\n    was split into deferred parts as expected. This tool takes a specification\n    of the expected layout of code into deferred parts, and checks that the\n    output from `dart2js` meets the specification.\n\n  * [`deferred_size`][deferred_size]: a tool that gives a breakdown of\n    the sizes of the deferred parts of the program. This can show how much of\n    your total code size can be loaded deferred.\n\n  * [`deferred_layout`][deferred_layout]: a tool that reports which\n    code is included on each output unit.\n\n  * [`function_size`][function_size]: a tool that shows how much\n    code was attributed to each function. This tool also uses dependency\n    information to compute dominance and reachability data. This information can\n    sometimes help determine how much savings could come if the function was not\n    included in the program.\n\n  * [`coverage_server`][coverage_server] and [`coverage_analysis`][coverage_analysis]:\n    dart2js has an experimental feature to gather coverage data of your\n    application. The `coverage_log_server` can record this data, and\n    `live_code_size_analysis` can correlate that with the info file, so you\n    determine why code that is not used is being included in your app.\n\n  * [`convert`][convert]: a tool that converts info files from one format to\n    another. Accepted inputs are JSON or the internal binary form, outputs can\n    be JSON, backward-compatible JSON, binary, or protobuf schema (as defined in\n    `info.proto`).\n\n  * [`show`][show]: a tool that dumps info files in a readable text format.\n\nNext we describe in detail how to use each of these tools.\n\n### Code deps tool\n\nThis command-line tool can be used to query for code dependencies. Currently\nthis tool only supports the `some_path` query, which gives you the shortest path\nfor how one function depends on another.\n\nRun this tool as follows:\n```console\n# activate is only needed once to install the dart2js_info tool\n$ pub global activate dart2js_info\n$ dart2js_info code_deps some_path out.js.info.data main foo\n```\n\nThe arguments to the query are regular expressions that can be used to\nselect a single element in your program. If your regular expression is too\ngeneral and has more than one match, this tool will pick\nthe first match and ignore the rest. Regular expressions are matched against\na fully qualified element name, which includes the library and class name\n(if any) that contains it. A typical qualified name is of this form:\n\n    libraryName::ClassName.elementName\n\nIf the name of a function your are looking for is unique enough, it might be\nsufficient to just write that name as your regular expression.\n\n### Diff tool\n\nThis command-line tool shows a diff between two info files. It can be run\nas follows:\n\n```console\n$ pub global activate dart2js_info # only needed once\n$ dart2js_info diff old.js.info.data new.js.info.data [--summary]\n```\n\nThe tool gives a breakdown of the difference between the two info files.\nHere's an example output:\n\n```\ntotal_size_difference -2688\ntotal_added 0\ntotal_removed 2321\ntotal_size_changed -203\ntotal_became_deferred 0\ntotal_no_longer_deferred 0\n\nADDED (0 bytes)\n========================================================================\n\nREMOVED (2321 bytes)\n========================================================================\ndart:_js_helper::getRuntimeTypeString: 488 bytes\ndart:_js_helper::substitute: 479 bytes\ndart:_js_helper::TypeImpl.toString: 421 bytes\ndart:_js_helper::computeSignature: 204 bytes\ndart:_js_helper::getRuntimeTypeArguments: 181 bytes\ndart:_js_helper::extractFunctionTypeObjectFrom: 171 bytes\ndart:_js_helper::getTypeArgumentByIndex: 147 bytes\ndart:_js_helper::runtimeTypeToString: 136 bytes\ndart:_js_helper::setRuntimeTypeInfo: 94 bytes\ndart:core::Object.runtimeType: 0 bytes\ndart:_js_helper::getRawRuntimeType: 0 bytes\ndart:_js_helper::invoke: 0 bytes\ndart:_js_helper::invokeOn: 0 bytes\ndart:_js_helper::getField: 0 bytes\ndart:_js_helper::getClassName: 0 bytes\ndart:_js_helper::getRuntimeType: 0 bytes\ndart:_js_helper::TypeImpl.TypeImpl: 0 bytes\n\nCHANGED SIZE (-203 bytes)\n========================================================================\ndart:_interceptors::JSUnmodifiableArray: -3 bytes\ndart:core::List: -3 bytes\ndart:_interceptors::ArrayIterator: -4 bytes\ndart:_js_helper::TypeImpl._typeName: -10 bytes\ndart:_js_helper::TypeImpl._unmangledName: -15 bytes\ndart:_js_names::: -30 bytes\ndart:_js_names::extractKeys: -30 bytes\ndart:core::StringBuffer: -40 bytes\ndart:core::StringBuffer._writeAll: -40 bytes\ndart:core::: -43 bytes\ndart:_interceptors::JSArray.+: -63 bytes\ndart:_interceptors::JSArray: -66 bytes\ndart:_interceptors::: -73 bytes\ndart:_js_helper::TypeImpl: -481 bytes\ndart:_js_helper::: -2445 bytes\n\nBECAME DEFERRED (0 bytes)\n========================================================================\n\nNO LONGER DEFERRED (0 bytes)\n========================================================================\n\n```\n\nYou can also pass `--summary` to only show the summary section.\n\n### Library size split tool\n\nThis command-line tool shows the size distribution of generated code among\nlibraries. It can be run as follows:\n\n```console\n$ pub global activate dart2js_info # only needed once\n$ dart2js_info library_size out.js.info.data\n```\n\n\nLibraries can be grouped using regular expressions. You can\nspecify what regular expressions to use by providing a `grouping.yaml` file\nwith the `--grouping` flag:\n\n```console\n$ dart2js_info library_size out.js.info.data --grouping grouping.yaml\n```\n\nThe format of the `grouping.yaml` file is as follows:\n\n```yaml\ngroups:\n- { regexp: \"package:(foo)/*.dart\", name: \"group name 1\", cluster: 2}\n- { regexp: \"dart:.*\",              name: \"group name 2\", cluster: 3}\n```\n\nThe file should include a single key `groups` containing a list of group\nspecifications.  Each group is specified by a map of 3 entries:\n\n  * `regexp` (required): a regexp used to match entries that belong to the\n  group.\n\n  * `name` (optional): the name given to this group in the output table. If\n  omitted, the name is derived from the regexp as the match's group(1) or\n  group(0) if no group was defined. When names are omitted the group\n  specification implicitly defines several groups, one per observed name.\n\n  * `cluster` (optional): a clustering index for how data is shown in a table.\n  Groups with higher cluster indices are shown later in the table after a\n  dividing line. If missing, the cluster index defaults to 0.\n\nHere is an example configuration, with comments about what each entry does:\n\n```yaml\ngroups:\n# This group shows the total size for all libraries that were loaded from\n# file:// urls, it is shown in cluster #2, which happens to be the last\n# cluster in this example before the totals are shown:\n- name: \"Loose files\"\n  regexp: \"file://.*\"\n  cluster: 2\n\n# This group shows the total size of all code loaded from packages:\n- { name: \"All packages\", regexp: \"package:.*\", cluster: 2}\n\n# This group shows the total size of all code loaded from core libraries:\n- { name: \"Core libs\", regexp: \"dart:.*\", cluster: 2}\n\n# This group shows the total size of all libraries in a single package. Here\n# we omitted the `name` entry, instead we extract it from the regexp\n# directly.  In this case, the name will be the package-name portion of the\n# package-url (determined by group(1) of the regexp).\n- { regexp: \"package:([^/]*)\", cluster: 1}\n\n# The next two groups match the entire library url as the name of the group.\n- regexp: \"package:.*\"\n- regexp: \"dart:.*\"\n\n# If your code lives under /my/project/dir, this will match any file loaded\nfrom a file:// url, and we use as a name the relative path to it.\n- regexp: \"file:///my/project/dir/(.*)\"\n```\n\nRegardless of the grouping configuration, the tool will display the total code\nsize attributed of all libraries, constants, and the program size.\n\n**Note**: eventually you should expect all numbers to add up to the program\nsize. Currently dart2js's `--dump-info` is not complete, so numbers for\nbootstrapping code and lazy static initializers are missing.\n\n### Deferred library verification\n\nThis tool checks that the output from dart2js meets a given specification,\ngiven in a YAML file. It can be run as follows:\n\n```console\n$ pub global activate dart2js_info # only needed once\n$ dart2js_info deferred_check out.js.info.data manifest.yaml\n```\n\nThe format of the YAML file is:\n\n```yaml\nmain:\n  include:\n    - some_package\n    - other_package\n  exclude:\n    - some_other_package\n\nfoo:\n  include:\n    - foo\n    - bar\n\nbaz:\n  include:\n    - baz\n    - quux\n  exclude:\n    - zardoz\n```\n\nThe YAML file consists of a list of declarations, one for each deferred\npart expected in the output. At least one of these parts must be named\n\"main\"; this is the main part that contains the program entrypoint. Each\ntop-level part contains a list of package names that are expected to be\ncontained in that part, a list of package names that are expected to be in\nanother part, or both. For instance, in the example YAML above the part named\n\"baz\" is expected to contain the packages \"baz\" and \"quux\" and exclude the\npackage \"zardoz\".\n\nThe names for parts given in the specification YAML file (besides \"main\")\nare the same as the name given to the deferred import in the dart file. For\ninstance, if you have `import 'package:foo/bar.dart' deferred as baz;` in your\ndart file, then the corresponding name in the specification file is 'baz'.\n\n### Deferred library size tool\n\nThis tool gives a breakdown of all of the deferred code in the program by size.\nIt can show how much of the total code size is deferred. It can be run as\nfollows:\n\n```console\npub global activate dart2js_info # only needed once\ndart2js_info deferred_size out.js.info.data\n```\n\nThe tool will output a table listing all of the deferred imports in the program\nas well as the \"main\" chunk, which is not deferred. The output looks like:\n\n```\nSize by library\n------------------------------------------------\nmain                                    12345678\nfoo                                      7654321\nbar                                      1234567\n------------------------------------------------\nMain chunk size                         12345678\nDeferred code size                       8888888\nPercent of code deferred                  41.86%\n```\n\n### Deferred library layout tool\n\nThis tool reports which code is included in each output unit.  It can be run as\nfollows:\n\n```console\n$ pub global activate dart2js_info # only needed once\n$ dart2js_info deferred_layout out.js.info.data\n```\n\nThe tool will output a table listing all of the deferred output units or chunks,\nfor each unit it will list the set of libraries that contribute code to this\nunit. If a library contributes to more than one output unit, the tool lists\nwhich elements are in one or another output unit. For example, the output might\nlook like this:\n\n```\nOutput unit main:\n  loaded by default\n  contains:\n     - hello_world.dart\n     - dart:core\n     ...\n\nOutput unit 2:\n  loaded by importing: [b]\n  contains:\n     - c.dart:\n       - function d\n     - b.dart\n\nOutput unit 1:\n  loaded by importing: [a]\n  contains:\n     - c.dart:\n       - function c\n     - a.dart\n```\n\nIn this example, all the code of `b.dart` after tree-shaking was included in the\noutput unit 2, but `c.dart` was split between output unit 1 and output unit 2.\n\n### Function size analysis tool\n\nThis command-line tool presents how much each function contributes to the total\ncode of your application.  We use dependency information to compute dominance\nand reachability data as well.\n\nWhen you run:\n```console\n$ pub global activate dart2js_info # only needed once\n$ dart2js_info function_size out.js.info.data\n```\n\nthe tool produces a table output with lots of entries. Here is an example entry\nwith the corresponding table header:\n```\n --- Results per element (field or function) ---\n    element size     dominated size     reachable size Element identifier\n    ...\n     275   0.01%     283426  13.97%    1506543  74.28% some.library.name::ClassName.myMethodName\n```\n\nSuch entry means that the function `myMethodName` uses 275 bytes, which is 0.01%\nof the application. That function however calls other functions, which\ntransitively can include up to 74.28% of the application size. Of all those\nreachable functions, some of them are reachable from other parts of the program,\nbut a subset are dominated by `myMethodName`, that is, other parts of the\nprogram starting from `main` would first go through `myMethodName` before\nreaching those functions. In this example, that subset is 13.97% of the\napplication size. This means that if you somehow can remove your dependency on\n`myMethodName`, you will save at least that 13.97%, and possibly some more from\nthe reachable size, but how much of that we are not certain.\n\n### Coverage tools\n\nCoverage information requires a bit more setup and work to get them running. The\nsteps are as follows:\n\n  * Compile an app with dart2js using `--dump-info` and\n    `--experiment-call-instrumentation`\n\n```console\n$ dart2js --dump-info --experiment-call-instrumentation main.dart\n```\n\n  The flag only works dart2js version 2.2.0 or newer.\n\n  * Launch the coverage server tool to serve up the JS code of your app:\n\n```console\n$ dart2js_info coverage_server main.dart.js\n```\n\n  * (optional) If you have a complex application setup, you may need to serve an\n    html file or integrate your application server to proxy to the log server\n    any GET request for the .dart.js file and /coverage POST requests that send\n    coverage data.\n\n  * Load your app and use it to exercise the entire code.\n\n  * Shut down the coverage server (Ctrl-C). This will emit a file named\n    `mail.dart.js.coverage.json`\n\n  * Finally, run the live code analysis tool given it both the info and\n    coverage json files:\n\n```console\n$ dart2js_info coverage_analysis main.dart.info.data main.dart.coverage.json\n```\n\n## Code location, features and bugs\n\nThis package is developed in [github][repo].  Please file feature requests and\nbugs at the [issue tracker][tracker].\n\n[repo]: https://github.com/dart-lang/dart2js_info/\n[tracker]: https://github.com/dart-lang/dart2js_info/issues\n[code_deps]: https://github.com/dart-lang/dart2js_info/blob/master/bin/code_deps.dart\n[diff]: https://github.com/dart-lang/dart2js_info/blob/master/bin/diff.dart\n[library_size]: https://github.com/dart-lang/dart2js_info/blob/master/bin/library_size_split.dart\n[deferred_check]: https://github.com/dart-lang/dart2js_info/blob/master/bin/deferred_library_check.dart\n[deferred_size]: https://github.com/dart-lang/dart2js_info/blob/master/bin/deferred_library_size.dart\n[deferred_layout]: https://github.com/dart-lang/dart2js_info/blob/master/bin/deferred_library_layout.dart\n[coverage_server]: https://github.com/dart-lang/dart2js_info/blob/master/bin/coverage_log_server.dart\n[coverage_analysis]: https://github.com/dart-lang/dart2js_info/blob/master/bin/live_code_size_analysis.dart\n[function_size]: https://github.com/dart-lang/dart2js_info/blob/master/bin/function_size_analysis.dart\n[AllInfo]: http://dart-lang.github.io/dart2js_info/doc/api/dart2js_info.info/AllInfo-class.html\n[convert]: https://github.com/dart-lang/dart2js_info/blob/master/bin/convert.dart\n[show]: https://github.com/dart-lang/dart2js_info/blob/master/bin/text_print.dart\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdart-archive%2Fdart2js_info","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdart-archive%2Fdart2js_info","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdart-archive%2Fdart2js_info/lists"}