OE => "Online Examples", depending on context "Online Example Registry/Database"
It would NOT show OPM examples from packages not installed. And I think that makes sense.
Makes sense. In fact, showing examples for packages "not yet even downloaded" would be confusing. (There OPM could be extended, to allow filtering by "has example", but that is off-topic).
However:
- What about "examples" (pure examples, stored in the OE) that require a package?
-- 1) If that package is OPM ? (And not yet downloaded / or needs an update downloaded)
-- 2) If that package is avail on local storage (but maybe not installed in the IDE)
-- 3) A package, unknown to the IDE (maybe removed, but example DB not yet updated) -> This would be an error, but needs handling.
In case -2- examples could still be listed:
- "installation" (for design time packages) can be offered when opening the example.
- "installation" does not have to be mandatory. It is (usually) only needed to open the form in the designer. Installation is (usually) not needed to compile and run the example. (So once the user has been informed, it is their choice)
In case -1-:
I am sort of thinking, given that idea of the Example Unit scanning locally of OPM Examples, that OPM Examples belong in OPM Packages and 'should' comply with the Examples standard we come up with.
Well, ideally yes.
But, what if a person outside the "OPM package"-team provides examples? (I.e.: If I were to write examples for OPM-foo)
Ideally, I would submit them to the maintainer of that OPM package.
But if they do not want to add it? Maybe because their code is Laz&Delphi, but the example is Laz-only?
Then it could still be a good example...
-> Yes, this is a very special case.... Ok to worry later, if we don't have a good idea now.
As dbannon wrote, the example project system can search projects under the OPM install directory. No other integration is needed.
Depends, on how the above is handled.
IMHO we need at least the ability to specify "required packages" for the example.
And probably should at least prepare, to store some info on the packages
- min version (maybe max version too)
- Only required for design.
-- Some packages have separate *Dsgn packages, then the example can run without this (i.e. the package does not need to exist at all, example can be compiled/run without it)
But the user must be told what happens if he does not install it.
-- Other packages have IDE integration and runtime in one package. So even if the user skips installation, the package must exist for compilation.
- Origin of package: Laz-Installer, OPM, unknown
We may not need all of those right now, and hence not add them now.
But the design of the meta file should allow to easily add them, including backward compatibilty.
Translations:
As the meta files are by definition, quite short, maybe its just having a po directory in the project dir with translated files ? Can the same model support in project po behaviour too ?
Good start. Translated files, must not contain "version info", or any info at all, except translated strings. (Other elements could be allowed, but have to be ignored).
That depends a bit, on how well compatibility info "lazarus version" is represented.
Right now I am playing with a brief "technical feasibility" project, just to see if what I imagine works will (given my familiarity is with Github, not Gitlab).
What I am playing with is model where the client (ultimately built into Lazarus) dowloads a master.meta file, checked daily (?) and keeps a cached copy. Suppose when doing its daily checks (or a manual refresh) it also scans the area in .lazarus where OPM packages are and if it finds any recognisable example projects, adds them to its local list ?
A few notes:
1)
I would expect that contributors maintain their own GIT repo. (I guess we start with "git repo" as storage, probably keep it at this, but extension would be an issue for later...)
We would then have a central "OE" repo. Containing
* A list of all examples
* A copy of all meta files (and maybe translation)
* A copy of the current stable version of the example (actually not a must, but desirable in case the contributor's repo becomes unavailable.)
Ideally the meta files can keep info on:
- older versions
- Which example version to use with which IDE version
However, we do not need to have copies of older version. (Yet we probably will have).
==> IMHO we may find, that downloading data from our OE repo (and/or externals) will be very similar to what OPM already does.
So, it could be quite likely we can re-use some of the code from the OPM package. (just pass in our OE Url / some config/opts)
Like OPM, we could also allow the user, to get the latest example from the contributor. This would of course not have been reviewed by us.
(If the meta has a version map, this could be the "latest matching the IDE version" or the "latest on main branch")
2)
The meta file.
As long as we allow git only as storage for contributors, we can relay on references.
I.e. if the meta file would have:
"Compatibilty": {
"Laz-2-2": "1.3",
"Laz-2-0": "1.2"
};
"Versions": {
"1.3": "<sha1>123",
"1.2": "<sha1>234"
}
The "sha1" is a signature (and the meta with that sha1 is stored in our OE, under our control).
If we do not have the version for the sha1 in our OE, we can load it from the external git. If the contributor changes something, the sha1 no longer exists. But if it exists, it is the version that we know.
However, the copies in our OE repo have different sha1. So using the above, we need a "meta-sha1-map" file. This would contain a mapping from the external sha1 to our sha1.
Another options here is, to have a single global "meta-ide-version" file.
Lets say, our OE was updated for the 2.0 release.
The commit 987 has all the correct entries, for Laz-2.0.
Then "meta-ide-version" would contain
"VersionMap": {
"2.0": "987"
}
We can add new meta data, for the ongoing development versions of the IDE.
"987" can be on a branch. So if we need to add fix-updates, we can.
We would get commit "98A" on the branch.
And in the "main" branch we would change the info to: "2.0": "98A"
If we release Laz 2.2 we add:
"VersionMap": {
"2.0": "987",
"2.2": "ABC"
}
The example system can always download "meta-ide-version" from the "main" branch, and lookup the correct revision for the IDE version the user has installed.
Translations and versions:
Once the revision for the IDE-version has been found, all other data, including translation, is loaded from that revision.
Recent
