site-www
site-www copied to clipboard
dart-lang
'Creating packages' page issue
Page URL: https://dart.dev/guides/libraries/create-library-packages Page source: https://github.com/dart-lang/site-www/tree/master/src/_guides/libraries/create-library-packages.md
Found a typo? You can fix it yourself by going to the page source and clicking the pencil icon. Or finish creating this issue.
Description of issue:
There are several tips on this page, but there are not explanations, for example:
Tip for web apps: For the best performance when developing with dartdevc, put implementation files under /lib/src, instead of elsewhere under /lib. Also, avoid imports of package:package_name/src/....
Why does using /lib/src increases performance? Why avoiding avoid imports of package:package_name/src/.... is desirable? Why is it better to avoid using part?
I think all the recommendations on this page should be revisited and a proper explanation added.
@jakemac53 can you help? I'm not sure we need to explain everything in this page, but maybe we can at least explain in this issue (and update the page if needed).
I can help selecting the questions, but since I don't do Dart for web (I am mostly a Flutter dev for Mobile Apps), I don't know many of the answers, but would like to know :)
Note: When the library directive isn’t specified, a unique tag is generated for each library based on its path and filename. Therefore, we suggest that you omit the library directive from your code unless you plan to generate library-level documentation.
The library directive is poorly documented. The Language Tour says it will be explained on this page, but it doesn't. As far as I understand library is mostly obsolete, but I don't know the edge cases were it still matter, and new project templates still add it to new libraries.
Beyond better documenting the library directive, I would also explain what a library is in Dart, as a unit of privacy.
Note: You may have heard of the part directive, which allows you to split a library into multiple Dart files. We recommend that you avoid using part and create mini libraries instead.
Why to avoid part? Is it because code becomes messy?
Also its very confusing that we creating a library package, where every dart file is a library (unit of privacy) on the Language Tour, and now the text calls it mini library as well.
The export is not explained, neither the mechanisms behind it. The Language Tour says it will be explained here.
Although its functionality might seem obvious, I think its important to explain it a bit, like:
exportexports files that are accessible for the current file, due to the folder structure, but private to others, like files undersrcare private to external code, but the main library can still access it. So when youimportany files with anexportdirective, you will be in fact also importing all the exported files.
That's kinda long a repeats a bit of text that's already on the website, I would polish it up a bit before using.
Tip for web apps: For the best performance when developing with dartdevc, put implementation files under /lib/src, instead of elsewhere under /lib. Also, avoid imports of package:package_name/src/....
Why? How this translates to poor performance on the web? Is it too much data to compile in real-time for development? Does the package instruction slow down dartdevc because it has to continuously look for packages? I am only guessing.
When importing a library file from your own package, use a relative path when both files are inside of lib, or when both files are outside of lib. Use package: when the imported file is in lib and the importer is outside.
Why?
Here the Dart package boundaries could be better explained so people understand why they have to add package and not just memorize it.
Also, due to IDE autocomplete, many put package on everything, if there are downsides of this it should be noted as well (before were mentions of downsides for dartdevc only, without explanations).
Note: To include any library-level documentation in the generated docs, you must specify the library directive. See issue 1082.
What are library-leve documentation and how it differs from regular docs?
Why? How this translates to poor performance on the web? Is it too much data to compile in real-time for development? Does the
packageinstruction slow downdartdevcbecause it has to continuously look for packages? I am only guessing.
This is based on the implementation - it is specifically a recommendation based on how we construct "compilation units" (we use the term modules in code/docs) for modular compilation. This recommendation applies to the build_web_compilers package specifically, and how it constructs those compilation units.
Dart does not have any built in notion of a compilation unit itself, so we use heuristics to try to come up with sensible ones. We do that by starting from the public entry points (files under lib/ but not lib/src of a package), and creating modules based on the assumption that people only ever actually import the public modules (any direct import to lib/src/* is already discouraged as it is not considered public).
We also have a guarantee that if you import a public dart file, we will not end up pulling in unnecessary dart files that are not transitively imported by that file. This means that almost all public dart files end up being in their own module (unless they are part of a cycle with another public import).
So having a bunch of files under lib (but not lib/src) creates more modules than you want - there is non-trivial overhead involved with tons of small modules due to dart compilation requiring all transitive modules not just immediate ones when compiling any given module.
Similarly, importing from lib/src ends up requiring whatever module that library is a part of - possibly including additional transitive deps that aren't actually imported by the app and causing unnecessary work.
See also the general recommendation which this is based upon https://dart.dev/tools/pub/package-layout#implementation-files
