Generate an _all.dart

[mahesh-hegde]

Should we generate a src/third_party/_all.dart from jnigen?

That way we don't have to deal with manually adding extra exports here when we add classes.

Originally posted by @dcharkes in dart-archive/jnigen#87 .

---

Some thoughts

current design maps the package names to file names using logic similar to

filename = "${packagename.split('.').join('/') }.dart"

So in a hierarchy

com
|____ a.dart
|____ a
    |____ b.dart
    |____ c.dart
    |____ _all.dart

If outer a is not an empty package and has some classes, a.dart is also created.

Ideally we want com/a/_all.dart to export recursively all of com.a, and not just b.dart and c.dart.

It can write

export '../a.dart';
export 'b.dart';
export 'c.dart';

But I am not convinced about this is the neatest solution possible.

Is it a better solution to map 1 class -> 1 dart file vs 1 package -> 1 dart file?

[dcharkes]

Ideally we want com/a/_all.dart to export recursively all of com.a, and not just b.dart and c.dart.

It can write

export '../a.dart';
export 'b.dart';
export 'c.dart';

But I am not convinced about this is the neatest solution possible.

I think it's quite neat. 😅

When using the generated bindings within a package, users can chose how many imports they want (e.g. per class, or whole packages). Similar for a standard library package if everything is generated to lib/ (instead of lib/src/). And for packages with a public api it's relatively common to export many things from a central file.

Is it a better solution to map 1 class -> 1 dart file vs 1 package -> 1 dart file?

Cross-link single file issue:

• v0.2: Pure dart, single file bindings #773

As discussed on the other issue, both have their pros and cons. Why not support both?

output:
  dart:
    output_structure: single_file || package_structure

[mahesh-hegde]

Sorry I was not clear.

Currently output_structure: single_file is not implemented. That will put all classes into 1 file renaming when necessary.

package_structure mimics java package structure. (Renaming is not an issue since in a package, class names are unique).

But it currently maps 1 java package to 1 dart file, which can still get pretty large (eg: pdfbox.pdmodel), and the ambiguity above. Ambiguity is because, in java, package is always folder and class is always java file. In current dart mapping, package may be dart file if we are accessing the package, but it will be folder if we are accessing a subpackage.

Should it map the same way java files are? That's one dart file per class?

Which one is better?

The question is on how to implement package_structure.

I don't like to support both per-class and per-package because it's just maintainence burden. Seems better to pick one tradeoff and stick with it.

With class mapping we have an advantage of doing this

com
  - a
    - class_x.dart
    - class_y.dart
    - b/
      ...
      _all.dart
   - c/
     ...
     _all.dart
  _all.dart

will result in a/_all.dart which is

export 'class_x.dart';
export 'class_y.dart';
export 'b/_all.dart';
export 'c/_all.dart';

But has the disadvantage of too many files and having to write import 'my_package/_all.dart' instead of import 'my_package.dart'.

[dcharkes]

Ah you're saying we have three options:

1. 1 file with everything (proposed in v0.2: Pure dart, single file bindings #773)
2. 1 file per package with all classes in that package (current)
3. 1 file per class (my proposal)

That will put all classes into 1 file renaming when necessary.

This is also an issue with _all.dart with name collisions. (Not sure how to solve that one. Because we probably don't want to rename there.)

Should it map the same way java files are? That's one dart file per class?

Yes.

With class mapping we have an advantage of doing this

com
  - a
    - class_x.dart
    - class_y.dart
    - b/
      ...
      _all.dart
   - c/
     ...
     _all.dart
  _all.dart

will result in a/_all.dart which is

export 'class_x.dart';
export 'class_y.dart';
export 'b/_all.dart';
export 'c/_all.dart';

Yes, that is what I was thinking.

But has the disadvantage of too many files and having to write import 'my_package/_all.dart' instead of import 'my_package.dart'.

Wild idea, how about instead of a/_all.dart we put a.dart in the folder above? (Oh no, we get com.dart at the top... but it's nice otherwise.)

I think users should probably add the lib/package.dart themselves which exports lib/src/third_party/com/a.dart for users of their package.

[mahesh-hegde]

Exactly.

Now we want either {1, 2} or {1, 3} but not {1,2,3} for maintenance reasons.

1. How about _all.dart exporting only the files directly under current package, and not recursively? This is what wildcard import does in java.

[dcharkes]

1. How about _all.dart exporting only the files directly under current package, and not recursively? This is what wildcard import does in java.

I like your thinking. Lets just look at Java itself. :)

Maybe for the naming we should also look at java. But _wildcard.dart is a bit strange. Maybe _package.dart. Though maybe _all.dart is fine.

That does raise the question what to do if you generate all bindings in lib/src/ and you want to export them in lib/my_package.dart. But maybe we leave that as a TODO for when someone needs it.

Now we want either {1, 2} or {1, 3} but not {1,2,3} for maintenance reasons.

Agreed. I say {1,3} then.

(P.S. You could try to set up your code in such a way, that supporting all of them would be trivial. E.g. some internal abstraction for where bindings are generated and for importing required files. If your abstraction is right, it could support arbitrary file structures and still do the imports right. 😆 Your abstraction could have something like a definition Uri pathForClass(String uniqueJavaClassName).)

[mahesh-hegde]

That does raise the question what to do if you generate all bindings in lib/src/ and you want to export them in lib/my_package.dart. But maybe we leave that as a TODO for when someone needs it.

Maybe: _package.dart export all files under the package, _all.dart exports recursively?

What will happen if 2 elements have same name in such a case? Is this a compile time error for the package, or will the error only appear when you try to use the ambiguous element?

(P.S. You could try to set up your code in such a way, that supporting all of them would be trivial. E.g. some internal abstraction for where bindings are generated and for importing required files. If your abstraction is right, it could support arbitrary file structures and still do the imports right. 😆 Your abstraction could have something like a definition Uri pathForClass(String uniqueJavaClassName).)

I have a similar abstraction in a WIP branch. basically 2 implementations of BindingsWriter, one for single file and one for multiple file. 2 implementations of BindingsGenerator, one for pure dart and one for C based. It's still not perfect abstraction but works.

[dcharkes]

What will happen if 2 elements have same name in such a case? Is this a compile time error for the package, or will the error only appear when you try to use the ambiguous element?

The name 'Architecture' is defined in the libraries 'package:native/src/target.dart' and 'package:native/src/toolchain.dart'. Try removing the export of one of the libraries, or explicitly hiding the name in one of the export directives.dart[ambiguous_export](https://dart.dev/diagnostics/ambiguous_export)

And as far as I know, Dart does not support renaming things in exports.

So we would need a sanity check for both _package.dart and _all.dart and give an warning if there is a name conflict and hide one of the duplicate name.

1. If users really want to re-export all symbols, they should use some kind of renaming so that all can live in the same namespace.
2. If users don't want to re-export all symbols, they can use the more specific import to import the symbol that we removed from _package.dart and _all.dart.