47

I know that this keyword should be used in some custom library, but when I dropped it, nothing happened (at least I didn't notice anything), imports still worked fine, private members remained private.

Could somebody explain what the "library" keyword in Dart does?

Johannes Fahrenkrug
  • 42,912
  • 19
  • 126
  • 165
romanos
  • 1,288
  • 2
  • 11
  • 20

2 Answers2

27

update 2018-03-05

For a while now, part of accepts a URI, which reduces the need of library to a few edge cases.

update 2015-11-27

With a recent change, two imported nameless libraries don't produce a warning anymore. The plan is to make the library declaration entirely optional.

The library declaration is optional. If it is omitted the library name defaults to "".
There are some situations (pub build) where you get an error if two libraries have the same name, so it's usually good practice to set proper library names.

In a simple command line app consisting of one library it's usually fine to omit the library declaration.

From the Dart language spec

An implicitly named library has the empty string as its name.

The name of a library is used to tie it to separately compiled parts of the library (called parts) and can be used for printing and, more generally, reflection. The name may be relevant for further language evolution.

Libraries intended for widespread use should avoid name collisions. Dart's pub package management system provides a mechanism for doing so. Each pub package is guaranteed a unique name, effectively enforcing a global namespace.

Pi Da
  • 359
  • 2
  • 8
Günter Zöchbauer
  • 623,577
  • 216
  • 2,003
  • 1,567
  • 1
    What edge cases? – Michel Feinstein Sep 08 '20 at 03:11
  • Not sure if there are any still valid today. There were times where there were required for library-level annotations. Without reflection support on most platforms this is hardly relevant. There was a discussion once that a part file can be part of more than one library, where this might be relevant. – Günter Zöchbauer Sep 08 '20 at 04:19
  • I can't find many information on the `library` keyword, it looks like it's kinda deprecated, but when I create a new package, the template adds it, so I am not sure if it's irrelevant, or if the templates weren't updated. – Michel Feinstein Sep 08 '20 at 05:19
  • It should still be valid but I assume nobody uses it anymore since it became optional a few years ago, because it's cumbersome to maintain for example on file moves/renames. We were all happy to be freed of that burden. Just update the template and forget about it. – Günter Zöchbauer Sep 08 '20 at 12:58
8

The library keyword is not well documented in the language tour (libraries and visibility section). However, in the creating packages documentation:

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.

And

Note: To include any library-level documentation in the generated docs, you must specify the library directive. See issue 1082.

So this is automatically generated, but it doesn't work for library-level documentation, the documentation does not get generated for libraries without library directive.

Ben Butterworth
  • 22,056
  • 10
  • 114
  • 167
  • 1
    This particular bit of information now in the docs really clarifies whether or not to use the library directive and should be the current (as of May 2022) correct answer. – Jeff Neet May 18 '22 at 20:32