Allow library declarations with no name.

[lrhn]

Dart has library declarations of the form library some.name; which are no longer commonly used.
The name used to be required for having part files, but is now not necessary.
Giving a library a name is only really useful for avoiding duplicate imports with different paths, so most libraries do not use the declaration.

However, it's still useful to have a library declaration for a number of reasons:

• Adding annotations/metadata to the library.
• Writing documentation for the library.

The latter is "fixed" by the dartdoc tool assuming that a dartdoc occurring before the first import is really documenting the library, and not the import. (Edit: No, it actually doesn't. The culprit is the @TestOn annotation.)
The former is not fixed, so when you want to annotate your library with metadata, you need to give it an otherwise completely useless name.

The obvious solution would be to allow a declaration of the form library;, which gives the library the empty name (same as no library declaration). It's just a hook to hang your annotations from.

Feature specification

https://github.com/dart-lang/language/blob/master/accepted/future-releases/unnamed-libraries/feature-specification.md

Experiment flag

--unnamed-libraries

Implementation Tasks

• language tests written (https://dart-review.googlesource.com/c/sdk/+/262580).
• core library updates.
• implementation in CFE
  (https://dart-review.googlesource.com/c/sdk/+/257490).
• implementation in Analyzer
  (https://dart-review.googlesource.com/c/sdk/+/257490).
• implementation in Dartfmt (Support unnamed libraries dart_style#1141).
• implementation in build systems and Angular compiler.
• support in linter (Support unnamed libraries linter#3730).
• implementation in Dartdoc (Unnamed libraries support dartdoc#3188).
• implementation in DDC.
• implementation in the VM.
• VM Service support.
• implementation in syntax highlighters
• Github syntax highlighting.
• highlight.js support (api.dart.dev, api.pub.dev, Dartdoc):
• CodeMirror support (DartPad).
• implementation in IntelliJ.
• implementation in Cider.
• web debugging support.
• implementation in dart2js.
• implementation in Kythe.
• documentation. - [2.19] Update documentation on Dart library directive to include non-name libraries site-www#4314

[kevmoo]

FYI: there is special handling in pkg:test for this as well. Would be great to have this feature!

[jcollins-g]

However, it's still useful to have a library declaration for a number of reasons:

• Adding annotations/metadata to the library.
• Writing documentation for the library.

The latter is "fixed" by the dartdoc tool assuming that a dartdoc occurring before the first import is really documenting the library, and not the import.

AFAIK this is not the case, see dart-lang/dartdoc#1082.

[lrhn]

It does indeed seem like that feature never made it into DartDoc. All the more reason to introduce the library; declaration.

[Silentdoer]

library name is useful for mirror, such as:
await currentMirrorSystem().isolate.loadUri(Uri.parse('./testaa.dart'));
await currentMirrorSystem().isolate.loadUri(Uri.parse('./testbb.dart'));

but testaa's library name is aa and testbb's library name is aa, the code will throw exception:
currentMirrorSystem().findLibrary(#aa);

[lrhn]

@Silentdoer Not sure what point you are making. You can add names to libraries if you want to, and you can choose not to if you want to. The one thing you can't currently do is not have a library name and have metadata or documentation on the library.
That's what this feature request tries to address.

People choose not to give libraries names for a reason.

Letting libraries define their own name means that you risk conflicts. Dart disallows such conflicts, but there is no way to resolve them other than to not include one of the libraries in the program. Generally in Dart, a declaration with a name is included in a scope which limits that name's reach (and risk of conflict). You can't have two top-level declarations in the same library, but a library is also a unit of editing, so the person adding the conflict is also able to resolve it again.
You can't import (and use) two declarations with the same name into the same library, but the person doing the import is also the one using the names, and the able to add an import with a prefix if necessary.

The scope of library names is the program. That means that any library name you declare can potentially conflict with any other library. The solution to that is to use structured library names based on the package name and library name, like pkg.mypackage.src.foo_bar for package:mypackage/src/foo_bar.dart. At that point, there really isn't much advantage over just using the URI directly, having a library name is a liability, not an advantage.

The solution to that is to not give libraries names. That's what people are already doing. Whether library names are useful for mirrors or not isn't really important, because you can still choose to give libraries a name if you want to, and most people choose not to do that. This request is to allow those people to still attach metadata (including documentation) to the library.

[eernstg]

Dart disallows such conflicts

We actually removed that error in 14fcda2, July 2020. Of course, this means that library names are only useful for code using mirrors, which makes it even more natural to use a bare library; in a library which needs to have metadata (aka annotations) on the library per se, especially on platforms where mirrors are not supported.

[rakudrama]

This would be very useful to me right now.
I am about to recommend that a customer place a certain @pragma annotation on their many thousands of libraries.
But they don't use the library declaration, so they will have to invent a whole system of names.

[lrhn]

Just do it!

(My biggest obstacle to having already done this was that it required changes to the analyzer AST model. Parsing is trivial. Libraries having empty names is already possible. Some code will not expect a library with a library declaration to have an empty name, though.)

[kevmoo]

Just do it!

Yes please!!!

[jcollins-g]

@bwilkerson @srawlins Is there something in the analyzer blocking this?

[srawlins]

No, there shouldn't be. We'd be game to implement.

[srawlins]

I believe I've more-or-less implemented this in https://dart-review.googlesource.com/c/sdk/+/257490.

@leafpetersen should I still spell out the feature real quick in a language repo spec?

[leafpetersen]

It's nice to have something around as a record, so if you don't mind, maybe a 1 paragraph spec would be great? You could land it directly in accepted/future_releases I think?

[srawlins]

Specification mailed in: #2490

[kevmoo]

@srawlins – leave it open until we have a plan to ship it in a specific release? (CC @mit-mit @leafpetersen )

[srawlins]

Yeah I think leaving it open for now is good.

[kevmoo]

@srawlins – can we close this as "done"? 😺

[srawlins]

I want to check off the last box there for vm_service support. I hoped to work on it today, but... tomorrow!

[srawlins]

Debugging a library without a name seems to work perfectly :D. Checked off vm_service.