Define that package.order requires a package

[HansOlsson]

and that only packages should be stored as package.mo.
Closes #3921

Note: I generalized it to require that even package.mo should (so, there might be exceptions) be a package. We might revisit that, but I think it is a good general rule.
I agree that having package.order for a non-package would be really problematic - as there are non-constants, equations etc that must be ordered.

Having package.mo for a non-package would to me only make sense for a top-level class where you want to store resources as if it were a package, and in that case having sub-classes (and especially sub-classes stored externally) doesn't really make sense.

[henrikt-ma]

Having package.mo for a non-package would to me only make sense for a top-level class where you want to store resources as if it were a package, and in that case having sub-classes (and especially sub-classes stored externally) doesn't really make sense.

I can see that it would be an inconsistency to allow package.mo for a class where it is not allowed to have a corresponding package.order. However, I think there are good use cases also for storing non-packages in a directory with one or more .mo files inside:

• When a function is only intended to be used by a particular model, I like to place the function within the model's definition, and if the function definition is big it can be convenient to define it in a separate file.
• When creating stand-alone examples, it is often convenient to make the top-level class the model to be simulated, with all helper classes defined inside. In this case, the model acts as a kind of package with a predefined model to simulate, and not allowing it to be stored across multiple files would feel like an unnecessary restriction.
• I find it very useful to have external resources stored along with the class using them, and external resources are absolutely not something primarily of interest for packages. That is, if img.png belongs to P.A, I prefer to reference it as modelica:/P.A/img.png, but this means that P/A is a directory, and then I think P/A/package.mo is the more natural place for the class definition.

Edit: @maltelenz just pointed out that https://specification.modelica.org/master/packages.html#external-resources speaks of package name, so I am striking out the item about regarding external resources attached to non-packages.

[henrikt-ma]

Don't we want to be more restrictive and actually ban the presence of package.order for non-packages?

[gkurzbach]

If we allow a directory structure for non package classes, probably also a package.order file is needed for that.

[henrikt-ma]

The current support for package constants is of course easy to generalize to non-constant components, but the whole point of this PR is that the package.order idea is too difficult to apply to classes with equations.

[HansOlsson]

To me the relevant case other case is storing a top-level non-package in package.mo to have the Resources-directory as though it were a package; so we only want the directory structure for the Resources-directory not for storing local classes.

I would even say that there is no need to store any potential sub-classes separately for that case, and it's even a bit unusual to have a non-short local class inside a model; and if it is a short class it cannot be stored in a separate file.

[henrikt-ma]

To me the relevant case other case is storing a top-level non-package in package.mo to have the Resources-directory as though it were a package; so we only want the directory structure for the Resources-directory not for storing local classes.

This relates to the item I stroke out in #3928 (comment) above since the external resource text very clearly speaks of packages, not classes defined in a package.mo. I this something we should revisit as part of this PR?

[HansOlsson]

Yes, I'll add the minimal part.

[HansOlsson]

Now added

[henrikt-ma]

More discussion is needed regarding the status of package.mo for non-packages.

[HansOlsson]

Language meeting:

Goal:

• Allow package.mo for non-package class (for resources)
• Forbid package.order for non-package (as it defines location of child-classes that are stored in other files; and that is rare for a non-package).
• At least no need for a package.order if there's only package.mo; cannot be used to modify text-view of a model.
• Markus: Only allow sub-mo-files if non-package?

Agreement?: Most in favor, but Gerd thinks that package.order could work; so allow

Off-line poll->Hans

[HansOlsson]

Background:

• Packages stored as package.mo may (and are advised) to have package.order to give classes stored in separate files/directories a sensible order.
• There is some reasons to have a (top-level) model stored in a package.mo (in a directory with a name matching the model) - since that allows resources to be stored in a sensible way in the directory.
• The current text for package.order doesn't work well for non-packages (it assumes there are only classes and constants; we already have the issue with extends-clauses Clarification on matching relative order between package.mo and package.order #3438, it is more common here, and additionally we also have variables, equations, algorithms, and for functions external-clauses. Note that annotations aren't an issue (anymore) as they should be last.)

Poll for variants among MAP-Lang members:

• Storing sub-classes in separate files and/or directories (together with package.mo) is only allowed for packages. Using package.order to order them is only allowed for packages. ❤️
• Storing sub-classes in separate files and/or directories (together with package.mo) is only allowed for packages. Having a package.order is allowed, but it has no practical effect for non-packages. 🚀
• Storing sub-classes in separate files and/or directories is allowed also for non-packages stored as package.mo. For the description of package.order change constants to components, and in case of ambiguity equations/algorithms are after sub-classes. 🎉
• Storing sub-classes in separate files and/or directories is allowed also for non-packages stored as package.mo. The package.order only includes child classes and package constants (not constant components declared in non-packages), and is only intended for ordering items in a tree view of the class tree. (Added) 👀

Select one (or possibly more) reaction(s) from "Add or Remove Reaction" (below to the left).
Poll ends September 18th.

[henrikt-ma]

The poll above does not include the following liberal and backward compatible alternative discussed at the meeting:

• Storing sub-classes in separate files and/or directories is allowed also for non-packages stored as package.mo. The package.order only covers child classes and package constants (not constant components declared in non-packages), and is only intended for ordering items in a tree view of the class tree.

[HansOlsson]

The poll above does not include the following liberal and backward compatible alternative discussed at the meeting:

• Storing sub-classes in separate files and/or directories is allowed also for non-packages stored as package.mo. The package.order only covers child classes and package constants (not constant components declared in non-packages), and is only intended for ordering items in a tree view of the class tree.

I must have missed that idea, but added it.

However, note that:

• The normal package.order for packages allows a consistent textual view of the entire package - that is not possible for this case, and in this case the order between sub-classes and other elements will vary between tools.
• Unless the child classes are encapsulated they are not accessible from the outside; and even if encapsulated it is not clear whether tools will show them in the class view.

[henrikt-ma]

With ❤️ and 🚀, imagine that FMU_A and FMU_B are imported FMUs. When organized in a package, resources can be placed next to the wrapper models:

- MyLib
  - package.mo
  - ImportedFMUs
    - package.mo
    - FMU_A.mo
    - FMU_A
      - Resources
        - modelDescription.xml
        - binaries
        - documentation
        - LICENSE.md
        - …
    - FMU_B.mo
    - FMU_B
      - Resources
        - …

However, the same pattern doesn't work when an FMU is imported as a top-level class, because then the directory corresponding to, say, FMU_A would be the top-level directory of the package, meaning that FMU_A.mo will sitt side by with with Resources:

FMU_A
- FMU_A.mo
- Resources
  - …

Hence, it gets a bit messy to move an imported FMU from the original top-level location into a package like ImportedFMUs, because the shape in the file system needs to change.

With 🎉 and 👀, the same pattern can be used both at the top-level and inside packages. Top-level:

FMU_A
- package.mo
- Resources
  - modelDescription.xml
  - …

Inside package:

ImportedFMUs
- FMU_A
  - package.mo
  - Resources
    - ...

[HansOlsson]

Was there a misunderstanding of "Storing sub-classes in separate files and/or directories (together with package.mo) is only allowed for packages."? The parenthesis can be skipped and the idea was:

• A non-package class can be stored in package.mo (even if not a good idea).
• However, sub-classes cannot be stored separately for a non-class.

Added: I know that there were a discussion on restricting non-package package.mo to the top-level, originally I favored that - but there was some push-back, and since non-package package.mo is already a bit odd I think it was concluded to not add that restriction.

[henrikt-ma]

Was there a misunderstanding of "Storing sub-classes in separate files and/or directories (together with package.mo) is only allowed for packages."? The parenthesis can be skipped and the idea was:

Don't know if anybody misunderstood, but skipping it sounds like a good idea.

• A non-package class can be stored in package.mo (even if not a good idea).

I think the imported FMU example shows clearly that it can be a good idea.