diff --git a/_config.yml b/_config.yml index 57748320f9..75a393ffc6 100644 --- a/_config.yml +++ b/_config.yml @@ -42,7 +42,8 @@ gh: https://github.com gh-dart: org: https://github.com/dart-lang sdk: https://github.com/dart-lang/sdk - site: https://github.com/dart-lang/website + lang: https://github.com/dart-lang/language + site: https://github.com/dart-lang/site-www show_banner: true diff --git a/src/_data/side-nav.yml b/src/_data/side-nav.yml index c0a3bea10d..af00b4c1eb 100644 --- a/src/_data/side-nav.yml +++ b/src/_data/side-nav.yml @@ -336,8 +336,6 @@ - title: Resources expanded: false children: - - title: FAQ - permalink: /resources/faq - title: Breaking changes permalink: /resources/breaking-changes - title: Language evolution @@ -353,6 +351,8 @@ permalink: /guides/language/coming-from/js-to-dart - title: Swift to Dart permalink: /guides/language/coming-from/swift-to-dart + - title: FAQ + permalink: /resources/faq - title: Glossary permalink: /resources/glossary - title: Books diff --git a/src/_sass/site.scss b/src/_sass/site.scss index 07eb178c3b..c266573d6f 100644 --- a/src/_sass/site.scss +++ b/src/_sass/site.scss @@ -884,3 +884,7 @@ body.obsolete { } } } + +dd { + margin-left: 1rem; +} \ No newline at end of file diff --git a/src/guides/whats-new.md b/src/guides/whats-new.md index 5f24f2f689..4d2d54abbc 100644 --- a/src/guides/whats-new.md +++ b/src/guides/whats-new.md @@ -285,9 +285,6 @@ we made the following changes to this site: * New library directive section in [The language tour][] * Improved clarity surrounding Dart's single-threaded or multi-threaded status: * Removed the outdated `dart:io` page. - * Added two sections to the FAQ: - * [Is Dart single-threaded?][] - * [Is Dart single-threaded on the web?][] * Expanded on [Dart's web concurrency capabilities][]. * Rearranged and clarified [discussion][] of default values for optional and positional parameters. * Updated [Concurrency in Dart][] to default to new `Isolate.run()` function. @@ -307,7 +304,6 @@ we made the following changes to this site: [Automated publishing of packages to pub.dev]: /tools/pub/automated-publishing [community resources section]: /community#additional-community-resources [migration guide]: /null-safety/migration-guide -[Sound null safety]: /null-safety#dart-3-and-null-safety [unsound null safety]: /null-safety/unsound-null-safety [Learning Dart as a Swift developer]: /guides/language/coming-from/swift-to-dart [booleans and equality operators]: /effective-dart/usage#dont-use-true-or-false-in-equality-operations diff --git a/src/resources/faq.md b/src/resources/faq.md index 9a2a514bec..ae76759405 100644 --- a/src/resources/faq.md +++ b/src/resources/faq.md @@ -4,26 +4,53 @@ short-title: FAQ description: You have questions about Dart, we have answers. --- -This page collects some of the top questions we've heard from the community -since Dart was open sourced. +{% assign pdf = 'picture_as_pdf' %} +{% assign site-repo = site.gh-dart.site %} +{% assign sdk-repo = site.gh-dart.sdk %} +{% assign lang-repo = site.gh-dart.lang %} +{% assign ecma-pdf = 'https://ecma-international.org/wp-content/uploads' %} +This page collects some of the top questions from the community. ## General ### Q. Is there a specification for Dart? -Yes. Dart 1 has a formal specification owned by [Ecma TC52][tc52]. +Yes. [EMCA-408][emca408] covers the Dart Programming Language Specification. -Dart 2.x is currently being specified; the specification is available from the -[Dart language specification](/guides/language/spec) page. +Five versions have been published. +The latest in-progress version covers to Dart 2.13-dev. + +| Edition | Published | Approved | Covers to version | +|-----------------------|-------------------|---------------|-------------------| +| [6th][6th-ed] {{pdf}} | January 24, 2024 | | 2.13-dev | +| [5th][5th-ed] {{pdf}} | April 9, 2021 | | 2.10 | +| [4th][4th-ed] {{pdf}} | August 19, 2015 | December 2015 | 1.11 | +| [3rd][3rd-ed] {{pdf}} | April 15, 2015 | June 2015 | 1.9 | +| [2nd][2nd-ed] {{pdf}} | November 21, 2014 | December 2014 | 1.6 | +| [1st][1st-ed] {{pdf}} | March 27, 2014 | June 2014 | 1.3 | +{:.table .table-striped} + +To learn more about the specification, +review the [Dart language specification](/guides/language/spec) page. ### Q. How are you taking input on changes to Dart? -We listen to feedback and [issues,][SDK issues] and we review patches from contributors. -A contributor with a good track record can become a committer to the repository. -Google engineers will also be working in the public repository, making visible -changes. The project is lucky to have received many external patches and has -welcomed distributed committers. +The team listens to feedback, reads [issues][SDK issues], +and reviews patches from contributors. +A contributor with a good track record can be granted +write permission to the repository. +Google engineers also work in the public repository, making visible changes. +The project has received many external patches +and welcomes distributed committers. + +[emca408]: https://ecma-international.org/publications-and-standards/standards/ecma-408/ +[1st-ed]: {{ecma-pdf}}/ECMA-408_1st_edition_june_2014.pdf +[2nd-ed]: {{ecma-pdf}}/ECMA-408_2nd_edition_december_2014.pdf +[3rd-ed]: {{ecma-pdf}}/ECMA-408_3rd_edition_june_2015.pdf +[4th-ed]: {{ecma-pdf}}/ECMA-408_4th_edition_december_2015.pdf +[5th-ed]: https://dart.dev/guides/language/specifications/DartLangSpec-v2.10.pdf +[6th-ed]: https://spec.dart.dev/DartLangSpecDraft.pdf --- @@ -32,88 +59,96 @@ welcomed distributed committers. ### Q. Isn't Dart a lot like Java? Dart has some similarities with Java. -Check out the code samples in the [Introduction to Dart](/language) -for brief examples with familiar syntax. +To review brief examples with familiar syntax, +reviewed the code samples in the [Introduction to Dart](/language). ### Q. How does Dart relate to Go? -Dart and Go are both language projects started at Google, but they -are independent and have different goals. As a result, -they make different choices, and the languages have very different -natures, even while we all try to learn from each others' work. +Google started the Dart and Go language projects. +These independent projects have different goals. +As a result, they make different choices. +The languages have very different natures, +but team members learn from each others' work. ### Q. Why isn't Dart more like Haskell / Smalltalk / Python / Scala / other language? -Various reasons, depending on the language being asked about. +Various reasons that depend on the comparison language. -For languages that are quite different from JavaScript: it's important for Dart -to compile to efficient JavaScript. Our experience in GWT is that if the source -language is too different from JavaScript, it creates some cases where complex -output code is needed to emulate the source language's behavior. This can cause -performance to vary in ways that are not transparent to the programmer. +**Languages differ from JavaScript** +: Dart must compile to efficient JavaScript. +Source languages that differ too much from JavaScript can generate complex +output code to emulate the source language's behavior. +This can cause performance to vary in non-obvious ways to the programmer. -For languages that are compiled to native code: it's important that Dart -compiles efficiently to machine code, and thus it shares a number of aspects -with other compiled languages. +**Languages that compile to native code** +: Dart prioritizes efficient compliation to machine code. + Therefore, it shares some aspects with other compiled languages. -For languages that are "more dynamic" than Dart: Dart deliberately trades off -some of this arbitrary runtime modification for the goal of better performance -and more productive tools. +**Languages that are considered "more dynamic" than Dart** +: Dart chooses to trade off some of this arbitrary runtime modification + to achieve better performance and more productive tools. ### Q. Why isn't Dart syntax more exciting? -We did throw in some nice syntactic features such as `this.` constructor args -and `=>` for one-line functions, but we'd agree that Dart chooses -familiarity over excitement. One team member's personal testimonial: -"I wish it had a little more razzle dazzle but I can't deny that -literally on my first day of writing Dart code, I was productive in it." +Some nice syntactic features exist, like the `this.` constructor args and `=>` +for one-line functions. +Dart chooses _familiarity_ over _excitement_. ### Q. Does Dart have reflection capabilities? -For servers and command-line scripts, we have reflection support from the -[mirrors API.]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-mirrors) -There is no support for mirrors when using Dart to write web or -Flutter apps ([more info][Flutter no mirrors]). - -### Q. Can Dart add tuples, pattern matching, partial evaluation, optional semicolons, ...? - -Future releases might be able to include (some of) those features, although -we can't include everything. Some features don't fit the basic nature of the -language, and some don't play well with other features. Simplicity is the single -most important gift we can give to future programmers. - -Please look at the [language funnel][language funnel] and -[language issues list][language issues] to see if your request is already there. -If it is, let us know that you care and give it a thumbs up. Otherwise, go ahead -and add a new request issue (see the [language evolution process][language process] -for details). Make a thoughtful argument for your feature. Sample code with and -without your feature is good evidence; a sizeable codebase that shows the need -is even better evidence. - -Don't be surprised if the Dart language team says "no" by default. -It's far more painful to remove a language feature than to add it, so -Dart is likely to add the most obvious features first, and then revisit the next -tier later. And there simply are more possible language features in the world -that can fit into any single language without making a total hash of it. But -we do very much appreciate suggestions and evidence. We hope you'll see our -appreciation through careful design choices and fair communication about them. +**Servers and command-line scripts** +: Yes, Dart supports reflection from the [mirrors API][dart-mirror]. + +**Web or Flutter apps** +: No, Dart doesn't support write to [web or Flutter apps][Flutter no mirrors]. + +### Q. Can Dart add tuples, partial evaluation, ...? + +Future releases might include a feature you want. +Some features don't fit the nature of the language. +Some don't play well with other features. +Simplicity is the most important gift to give to future programmers. + +To check if someone has filed your request, +review the [language funnel][lang-funnel] and +[language issues list][lang-issues]. + +* If an issue exists, add your thumbs up. +* If an issue doesn't exist, request a [new issue][new-issue]. + + Make a thoughtful argument for your feature. + Add evidence to your argument. Include sample code with and without your + feature or a sizeable codebase. + +To learn more, consult the [language evolution process][lang-process]. + +Don't be surprised if the Dart language team turns down your request. +Removing a language feature inflicts more pain than adding one. +The Dart language team adds the most obvious features first, +and revisits the next tier later. + +The community will request more features than any single language +can meet without making a total hash of it. +The Dart language team does appreciate suggestions and evidence. +This appreciation should become apparent through careful design choices +and fair communication about them. --- -## Types +## Typing -### Q. Is Dart a statically typed language? +### Q. Does Dart use static typing? -Yes, Dart 2 is statically typed. For more information, -read about [Dart's type system][]. +Yes, Dart uses static typing. To learn more, consult [Dart's type system][]. -With its combination of static and runtime checks, Dart has a sound type system, -which guarantees that an expression of one type cannot produce a value of another type. -No surprises! +Combining static and runtime checks, Dart has a sound type system. +This guarantees that an expression of one type cannot produce a value +of another type. -Even with type-safe Dart, you can annotate any variable with `dynamic` if you need the flexibility of a dynamic language. -The `dynamic` type itself is static, but can contain any type at runtime. -Of course, that removes many of the benefits of a type-safe language for that variable. +if you need the flexibility of a dynamic typing, +you can annotate any variable with `dynamic`. +This `dynamic` type is static, but can contain any type at _runtime_. +That removes many benefits of a type-safe language from that variable. ### Q. Why are generics covariant? @@ -139,61 +174,54 @@ Again, we're trying to be pragmatic, and we think the outcome is reasonable. ### Q. Does Dart support JSON? -Yes. See the [JSON] converters in the dart:convert library. +Yes. To learn more, consult the [JSON] converters in the [dart:convert][] library. ### Q. Can Dart run on the server? -Yes. See [Dart on the Server] for details. +Yes. To learn more, consult [Dart on the Server]. ### Q. How do I use third party code, or share code? -You can find many packages on the [pub.dev site][pub] a service for hosting -packages of Dart code. Use the `pub` command to package your code and upload -to the site. +Search for packages on the [pub.dev site][pub], +the package-hosting service for Dart and Flutter. +Use the [`pub` command][pub-cmd] to package your code and upload to the site. ### Q. Do I need to use a particular editor or IDE to write Dart code? -Nope. You can try out Dart code with [DartPad,][DartPad] and then use your favorite +No. You can try out Dart code with [DartPad,][DartPad] and then use your favorite editor or IDE for development. Some full-featured IDEs such as IntelliJ IDEA, WebStorm, and Visual Studio Code have Dart plugins. Open source Dart plugins also exist for a number of editors. For more information, see the [Dart tools][]. ### Q. Can I build an Android app with Dart? -Yes! You can build an Android app that also works on iOS from a single codebase -using [Flutter][Flutter], which is powered by the Dart platform. +Yes! You can build an Android app using the [Flutter][Flutter] framework +and the Dart language. +Any Flutter app you write will also work on iOS, the web, and desktop platforms. ### Q. What are some real-world production deployments of Dart? -Google Ads, AdSense, AdMob, and the Google Assistant all use Dart. +Google Ads, AdSense, AdMob, and the Google Assistant use Dart. A significant portion of Google's revenue flows through these apps. Inside or outside of Google, [every Flutter app][FlutterShowcase] uses Dart. - -[dartisnotjava]: http://programming.oreilly.com/2013/05/dart-is-not-the-language-you-think-it-is.html -[pnacl]: https://developer.chrome.com/native-client/overview -[SDK issues]: https://github.com/dart-lang/sdk/issues -[language issues]: https://github.com/dart-lang/language/issues -[language funnel]: https://github.com/dart-lang/language/projects/1 -[language process]: https://github.com/dart-lang/language/blob/main/doc/life_of_a_language_feature.md +[dart:convert]: {{site.dart-api}}/stable/dart-convert/dart-convert-library.html +[SDK issues]: {{sdk-repo}}/issues +[lang-issues]: {{lang-repo}}/issues +[lang-funnel]: {{lang-repo}}/projects/1 +[lang-process]: {{lang-repo}}/blob/main/doc/life_of_a_language_feature.md [pub]: {{site.pub}} -[announcement]: https://blog.chromium.org/2013/11/dart-10-stable-sdk-for-structured-web.html -[lang]: /language -[JSON]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-convert/JsonCodec-class.html -[tc52]: {{site.news}}/2013/12/ecma-forms-tc52-for-dart-standardization.html +[JSON]: {{site.dart-api}}/stable/dart-convert/JsonCodec-class.html [Dart on the Server]: /server [Dart tools]: /tools/ -[Dart and Google Cloud Platform]: /server/google-cloud -[Who Uses Dart]: /community/who-uses-dart -[spec]: https://www.ecma-international.org/publications/standards/Ecma-408.htm -[DEP]: https://github.com/dart-lang/dart_enhancement_proposals [DartPad]: {{site.dartpad}} [Flutter]: {{site.flutter}} -[DDC]: https://github.com/dart-lang/sdk/tree/main/pkg/dev_compiler#dev_compiler -[strong mode]: /language/type-system [Dart's type system]: /language/type-system [Flutter no mirrors]: {{site.flutter-docs}}/resources/faq#does-flutter-come-with-a-reflection--mirrors-system [FlutterShowcase]: {{site.flutter}}/showcase +[new-issue]: {{site-repo}}/issues/new/choose + +[isolate]: {{site.dart-api}}/stable/dart-isolate/dart-isolate-library.html --- @@ -201,239 +229,93 @@ Inside or outside of Google, [every Flutter app][FlutterShowcase] uses Dart. ### Q. Is Dart single-threaded? -No. On native targets, Dart's isolate API can -enable multiple threads of execution at any given time. -The Dart VM uses multiple processor cores -to run those threads concurrently. +No. On native targets, +[Dart's isolate API][isolate] can start multiple execution threads when needed. +The Dart VM uses multiple CPU cores to run those threads at the same time. -[Dart's concurrency architecture](/language/concurrency) -abstracts the complex, error-prone code of typical shared-memory threading, -which might explain the misconception that Dart is single-threaded. +[Dart's concurrency architecture](/language/concurrency) abstracts the complex, +error-prone code of typical shared-memory threading. +This might explain the misconception that Dart is single-threaded. -Note that concurrency works differently in Dart web apps. -To learn more, see +Concurrency works differently in Dart web apps. +To learn more, consult [Is Dart single-threaded on the web?](#q-is-dart-single-threaded-on-the-web) ### Q. Can I compile Dart code to native code? -Yes. For programs targeting devices (mobile, desktop, server, and more), [Dart -Native](/overview#native-platform) includes both a Dart VM with JIT -(just-in-time) compilation and an AOT (ahead-of-time) compiler for producing -machine code. +Yes. When compiling apps that target devices like desktops or mobile, +[Dart Native](/overview#native-platform) +includes both a Dart VM with a just-in-time (JIT) compiler and an +ahead-of-time (AOT) compiler to produce native code. -[Flutter][] is a sample framework that uses Dart's native compilation capability -to produce fast native apps. +The [Flutter][] framework uses Dart's native compilation capability to produce +fast native apps. ### Q. Can I compile a Dart program for running in a terminal? -Yes. Dart programs can be compiled to native x64 machine code for running in a -Terminal/Command Prompt on desktop operating systems such as Windows, macOS, and -Linux. For more details, see the [dart compile][] documentation. +Yes. Dart programs can be compiled to native code for running in a +macOS Terminal, Windows command prompt, or a Linux shell. + +Consult the [dart compile][] documentation. ### Q. Which is faster: AOT- or JIT-compiled code? -Code that's compiled ahead-of-time (_AOT_) with -a tool such as [dart compile][] -has different performance characteristics from -code that's compiled just-in-time (_JIT_) in the Dart VM. -AOT-compiled code is guaranteed to have fast startup and consistent runtime -performance, with no latency during early runs. JIT-compiled code is slower at -startup, but it can have better peak performance after it runs -long enough for runtime optimizations to be applied. +It depends. +How Dart compiles code produces apps with different performance characteristics. ---- +* AOT-compiled code starts fast with consistent runtime performance, + with no latency during early runs. +* JIT-compiled code starts slower, but reaches peak performance after it runs + long enough to apply runtime optimizations. -## Web: general +--- + +## Web execution ### Q. What browsers do you support as JavaScript compilation targets? The _production_ web compiler supports the last two major releases of the following browsers: - * Chrome - * Edge - * Firefox - * Safari - -The [_development_ JavaScript compiler](/tools/webdev#serve) supports Chrome only. -You _might_ be able to use other modern browsers: Microsoft Edge, Mozilla Firefox, and Apple Safari). - -### Q. Is Dart supported by my browser? - -Although no production browsers can execute Dart code directly, -all modern browsers can execute Dart code that's been compiled to JavaScript. - -### Q. How do I debug an app? - -For setup details and a walkthrough, see [Debugging Dart Web Apps](/web/debugging). - -### Q. What web frameworks can I use with Dart? - -You can use the low-level HTML API that core libraries define like `dart:html`, or you can choose from many [web packages](/web/libraries#web-packages). -You can also use the [Flutter framework]({{site.flutter}}), which has [web support]({{site.flutter}}/web) +* Google Chrome +* Microsoft Edge +* Firefox +* Apple Safari -### Q. Will the Dart VM get into Chrome? - -[No.]({{site.news}}/2015/03/dart-for-entire-web.html) -Dart is designed to compile to JavaScript to run across the modern web. +The [_development_ JavaScript compiler](/tools/webdev#serve) only +supports Chrome for debugging. ### Q. Is Dart single-threaded on the web? -Dart is *mostly* single-threaded on the web, -since web apps cannot use isolates. -To run code concurrently, web apps use [web workers][] instead. +Somewhat. +Dart web apps can't use isolates. +To achieve code concurrency, web apps use [web workers][]. Web workers lack the ease and efficiency of isolates, and have different capabilities and restrictions. -To learn more, see +To learn more, consult [Concurrency on the web](/language/concurrency#concurrency-on-the-web). [web workers]: https://developer.mozilla.org/docs/Web/API/Web_Workers_API/Using_web_workers ---- - -## Web: JavaScript and other technologies - -### Q. How does Dart code interoperate with JavaScript libraries? - -Although Dart and JavaScript are completely separate languages with -separate VMs, they can interoperate. For more information, see -[JavaScript and TypeScript interop](/interop/js-interop). - -### Q. I have a large JavaScript codebase. How can I migrate it to Dart? - -Try migrating one major feature at a time, and use the -[JavaScript interoperability library][package:js] -only when necessary. +### Q. Will any valid Dart code compile to JavaScript? -### Q. How does Dart compare with using the Closure compiler on JavaScript? - -The idea of optional type annotations is similar. -Dart's are nicer syntactically. - -Compare the following Closure compiler code: - -```js -// Closure compiler code - -/** - * @param {String} name - * @return {String} - */ -makeGreeting = function(name) { - /** @type {String} */ - var greeting = 'Hello ' + name; - return greeting; -} -``` - -With the following Dart code: - - -```dart -// Dart code - -String makeGreeting(String name) { - var greeting = 'Hello $name'; - return greeting; -} -``` - -### Q. How does Dart compare with CoffeeScript? - -Both Dart and CoffeeScript are inspired by JavaScript, and both can be -translated back to it. They make different choices, particularly in the flavor -of their syntax. As a language we think it's fair to say that Dart differs -semantically from JavaScript more than CoffeeScript does; that may result in a -less line-for-line translation, but we believe Dart-generated JavaScript can -have excellent size and speed. - -Dart introduces new semantics, while CoffeeScript retains the semantics -of JavaScript. - -If you like CoffeeScript for its more structured feel than raw JavaScript, you -may like Dart's static type annotations. - -### Q. What does Google think of TypeScript? - -TypeScript and Dart have similar goals; they make building large-scale web -apps easier. However, their approaches are fairly different. TypeScript -maintains backwards compatability with JavaScript, whereas Dart purposely made a -break from certain parts of JavaScript's syntax and semantics in order to -eradicate large classes of bugs and to improve performance. The web has suffered -from too little choice for too long, and we think that both Dart and TypeScript -are pointing to a brighter future for web developers. You can read a -[more complete response][typescript] on our blog. - -### Q. I have a large app written in GWT. How do I port it to Dart? - -Java and Dart are syntactically similar, -so this might be easier than you think. -You can rely on the [Dart analyzer][dart analyze] -to flag any syntax problems. Alternatively, you may -consider porting one feature at a time to Dart and using the -[JavaScript interoperability library][package:js] as the common middle -ground. Be sure to watch [Dart-JavaScript -interoperability,](https://www.youtube.com/watch?v=aIonwL-8hdE) -a talk from Dart Developer Summit 2016. - ---- - -## Web: JavaScript compilation - -### Q. Will any valid Dart code compile to JavaScript, or are there limitations? - -We intend for any valid Dart code to compile to JavaScript. Of course, -some libraries only run on the server or in Flutter. -For example, the `dart:io` library -provides access to operating system files and directories with APIs not -available to the browser. +Any valid Dart code should compile to JavaScript. +Some libraries run only on the server or in Flutter. +Consider the `dart:io` library. +It provides access to operating system files +and directories with APIs not available to the browser. ### Q. Why does Dart have two ways to compile to JavaScript? -Each developer journey has different requirements. How Dart generates -JavaScript code depends on what you need to do. You should not need to -worry about which compiler you use. The [`webdev`][webdev] tool chooses the -right compiler for your use case. - -* When you're developing your app, `webdev` uses Dart's development - compiler. This compiler creates modular JavaScript code and supports - incremental compilation. This allows you to see the results of your - edits quickly. -* When you're deploying your app, `webdev` chooses the production web - compiler (which work the same as `dart compile js`). This compiler - uses techniques such as tree shaking to produce optimized code. - -### Q. How can `dart compile js` produce JavaScript that runs faster than handwritten JavaScript? - -The production JavaScript compiler analyzes your entire program and optimizes -code in ways you might not be able to or want to do. Just like `gcc` -moves code around to produce efficient code, the production web -compiler takes advantage of Dart's structured nature to implement -global optimizations. - -We don't claim that all Dart code will run faster -than handwritten JavaScript, when compiled to JavaScript, -but we're working to make the common cases fast. +Both ways use the `webdev` command. +The `webdev build` command produces minified JavaScript optimized for +production. +The `webdev serve` command produces modulized JavaScript optimized for +debugging. -### Q. How can I write Dart code that compiles to performant JavaScript? - -See [Improving production web compilation](/tools/dart-compile#helping-generate-efficient-code). -This information might change as the implementation of -`dart compile js` changes. - -### Q. Why is the code for "Hello, World" so big, compared to the original Dart code after compilation to JavaScript? - -We believe that it's important to create small and efficient JavaScript -from Dart, but most developers don't write "Hello, World" apps. It's all -relative, and with tree shaking (dead code elimination), minification, and -compression, Dart apps can be compiled to JavaScript fairly efficiently. - -Kevin Moore [saw improvements][ppwsize] in the size of the generated -JavaScript from his real-world HTML5 game. - -The web compiler team strives to reduce output code, but focuses more on -real-world apps instead of trivial examples. +To learn more, +consult the [Dart JavaScript compiler reference](/tools/dart-compile#js) ### Q. How are floating point numbers handled when compiled to JavaScript? @@ -442,29 +324,32 @@ floating-point number. This means that any number—integer or floating point—is represented as a double. JavaScript has typed data arrays, and the mapping from native Dart typed lists to JavaScript typed arrays is trivial. -### Q. How are integers handled when compiled to JavaScript? +### Q. How does Dart handle integers when compiling to JavaScript? -Because all numbers are stored as doubles, -integers are restricted to a 53-bit precision. -Integer values in the range of -253 to 253 can be stored -without loss of accuracy. -Because JavaScript VMs play tricks -with the internal representation of numbers -(similar to those described above), -staying within smi range is still good practice. +JavaScript stores all [numbers as doubles][number-js]. +This limits integers to 53-bit precision +with values ranging from -253 to 253 +JavaScript can store integers in this range without loss of accuracy. +As JavaScript VMs manipulates the internal representation of numbers, +stay within the small integer (SMI) range. +In JavaScript, that range falls between -231 to 231 +(-2,147,483,647 to 2,147,483,648 including 0). ### Q. How are typed lists handled when compiled to JavaScript? -JavaScript offers typed arrays compatible with Dart's typed lists. -The mapping is trivial: `Float32List` becomes a `Float32Array`. -One exception exists: the production JavaScript compiler does not support -64-bit integers: `Int64List` or `Uint64List`. Compiling Dart code with +JavaScript offers 32-bit typed arrays compatible with Dart's typed lists. +This maps as `Float32List` becoming a `Float32Array`. +The production JavaScript compiler doesn't support 64-bit integers: +`Int64List` or `Uint64List`. Compiling Dart code with either of those lists results in a runtime exception. - +[number-js]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type [ppwsize]: https://work.j832.com/2012/11/excited-to-see-dart2js-minified-output.html [package:js]: {{site.pub-pkg}}/js [dart compile]: /tools/dart-compile [dart analyze]: /tools/dart-analyze [typescript]: {{site.news}}/2012/10/the-dart-team-welcomes-typescript.html [webdev]: /tools/webdev + +[dart-mirror]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-mirrors +[pub-cmd]: https://dart.dev/tools/pub/cmd diff --git a/src/resources/index.md b/src/resources/index.md index ca43a3e508..92f3fb6f95 100644 --- a/src/resources/index.md +++ b/src/resources/index.md @@ -18,11 +18,6 @@ Check out the following Dart language resources:

Keeping community spaces safe and respectful.

-
-

Dart FAQ

-

Answers to questions from the Dart community.

-
-

Videos

Videos aimed at Dart developers.

diff --git a/src/tools/dartpad/troubleshoot.md b/src/tools/dartpad/troubleshoot.md index acb00f635f..12287e4aa9 100644 --- a/src/tools/dartpad/troubleshoot.md +++ b/src/tools/dartpad/troubleshoot.md @@ -16,7 +16,8 @@ The dart.dev homepage and many codelabs have embedded DartPads. If these DartPads don't appear at all, then try the following: -* Make sure you're using a [supported browser][browser]. +* Make sure you're using one of the latest two versions of Chrome, + Edge, Firefox, or Safari. DartPad might not work in other browsers, and is known not to work in the default configuration of the Brave browser. diff --git a/src/tools/webdev.md b/src/tools/webdev.md index b942974f83..900fd8b291 100644 --- a/src/tools/webdev.md +++ b/src/tools/webdev.md @@ -112,7 +112,8 @@ assets on disk. This makes later builds compile faster. The development compiler supports **only Chrome.** To view your app in another browser, use the production compiler. - For a list of supported browsers, [see the FAQ][supported browsers]. + The production compiler supports the latest two versions of Chrome, + Edge, Firefox, and Safari. {{site.alert.end}} To enable [Dart DevTools][], add the `--debug` flag: @@ -188,7 +189,6 @@ test package runner, use this command: $ dart test -h ``` - ## More information For a complete list of `webdev` options, run `webdev --help` or see the @@ -205,11 +205,8 @@ Also see the following pages: [compiler options](/tools/dart-compile#js). [build_runner]: /tools/build_runner -[build_runner test]: #test [build_web_compilers]: {{site.pub-pkg}}/build_web_compilers [Dart DevTools]: /tools/dart-devtools [dev_dependencies]: /tools/pub/dependencies#dev-dependencies -[PATH]: /tools/pub/cmd/pub-global#running-a-script-from-your-path -[supported browsers]: /resources/faq#q-what-browsers-do-you-support-as-javascript-compilation-targets [test package]: {{site.pub-pkg}}/test [webdev]: {{site.pub-pkg}}/webdev