Example projects window

[dbannon]

... a number of issues

> What about "examples" (pure examples, stored in the OE) that require a package?
I envisage only the Lazarus Examples stored in OE, examples belonging to external packages belong in external packages.

> -- 3) A package, unknown to the IDE (maybe removed, but example DB not yet updated) -> This would be an error, but needs handling.
The local Examples dbase could be updated daily (when user opens Example Window) or manually. If they remove a package and later that day expect to find the associated Example there, well, and error message is all we can do. But the point is, the Example has gone when the OPM has gone.

> IMHO we need at least the ability to specify "required packages" for the example.
While agree, I think it can be done with just FP defines in the project code and a mention in the Project Description, "This demo requires Lazarus 2.0.12 or later". We are not trying to make an unattended Build System, a new user using an old Lazarus will learn something from the experience.
 

> But the design of the meta file should allow to easily add them, including backward compatibilty.
Right now, due to its simplicity, the meta data is just plain text. If we intend to make it, the meta data, more complicated, then probably need to move to xml or json etc. My demo uses json for the master.meta file.

> 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...)
See earlier discussion with Trev about safety. Suppose I have an example in my own github repo, there is a link in the Lazarus Repo to it. It demonstrates how to read all files on disk into a TStringList.  Been there for years. I have too much to drink one night and add a two lines -

Code: Pascal  [Select][+][-]

1. for St in STL do
2.     deletefile(St);
3.  

Or an example that encrypts the user's disk until they find some bitcoin ....


> 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)
That side of it is all working now in the demo I mentioned yesterday. Its quite easy....

> 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.
With an appropriate warning / disclaimer.

(disregarding the next section because -
* I do not believe we should be automatically pointing to repositories out of our control
* required versions of FPC/Lazarus can be handled in project code

Martin, I suspect you see this facility as supporting large code base projects. I don't, its about small, self contained demonstrations of how to do one particular thing each. Nothing here should be an "application", just enough code to compile and demonstrate one useful trick. Most of the existing Examples are small, all thats lacking is a review and meta data.)

Davo

[dbannon]

And I get the impression from the discussion that the solution will somehow depend on features of GitLab.

Not intrinsically. I choose gitlab because FPC/Lazarus did. If gitlab closes down, several methods in https://gitlab.com/dbannon/fpexamples/-/blob/main/Utility/ExScanner/exampledata.pas would need to be changed to use github. Or some other service. Or a machine hosted in my back shed (just joking).

If gitlab no longer meets our needs, we have a lot more to worry about then OE (as Martin has named it).

Davo

[dbannon]

Just to labour the point a bit about keeping examples in the distro.

I believe if we keep some examples in the distro, we should keep all examples there. To make it work with just a handful of perhaps very basic ones is no harder than making it work for a whole lot.

Right now, we have lots of examples in the distro, they are generally speaking unusable for many users because -

1. Undocumented - all you get is a project name for most.
2. Unwriteable - (Linux package installs)
3. Unfindable - un-categorized as to target audience, applicability etc.
4. Inflexible - cannot, for example find installed OPM Package Examples.

So, something needs be done, please, lets not have two parallel models, its either in disto or online. I'm happy with either but I do consider an on-line model will provide a more manageable and flexible service. For much the same reason that so many other things are moving to on-line models.

Its all new and shiny !   

Davo

[Martin_fr]

> 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...)
See earlier discussion with Trev about safety. Suppose I have an example in my own github repo, there is a link in the Lazarus Repo to it. It demonstrates how to read all files on disk into a TStringList.  Been there for years. I have too much to drink one night and add a two lines -

Code: Pascal  [Select][+][-]

1. for St in STL do
2.     deletefile(St);
3.  

Or an example that encrypts the user's disk until they find some bitcoin ....

I do thing we will have a copy of their code. Just though things don't break if they have some downtime, or delete/move their repo.

But, a link is save too. As long as it is to a specific commit by sha1.
https://gitlab.com/freepascal.org/lazarus/lazarus/-/commit/c8feb2d0e8d72e8145c52b9a0b6055adbdc8344c

Unless you can deliberately generate content (different from the current), that will get the same sha. If you can do that, a lot of stuff on the net suddenly becomes a lot less secure.

[dbannon]

But, a link is safe too. As long as it is to a specific commit by sha1.
https://gitlab.com/freepascal.org/lazarus/lazarus/-/commit/c8feb2d0e8d72e8145c52b9a0b6055adbdc8344c

I think you mean (your link was to the commit) -
https://gitlab.com/freepascal.org/lazarus/lazarus/-/tree/c8feb2d0e8d72e8145c52b9a0b6055adbdc8344c

Yes, I agree, that's probably pretty safe !  But I come back to my question of we really here in the business of reviewing projects of the complexity that someone feels they even belong under revision control ? These are supposed the be small, simple examples of how to do some specific thing, not a full blown application.  Hmm, someone using a package may well have a directory containing Examples, based on their experiments perhaps, so its possible.  But its probably going to be rare ?  So we design our meta data model to support it "at some time in the future" ?

Now, talking of Delphi (someone was) has Delphi addressed this issue ? Do Delphi Examples have meta data ? (I have a legal copy of Delhi 2 somewhere).

Hmm, jumping around a bit. We'll have Examples that are OS specific, is it enough to say so in the Description, its free form text -

This application demonstrates reading the Windows Registery, its Windows Specific .....

Or rely on keywords saying "Registery Windows ..." ?

Or, more positive, we define some suggested keywords with specific meaning - Windows-Only, Unix-Only, BSD-on-PPC-64-Little-Endian-Tuesdays-Only (maybe not the last one). But having a keywords field does let us extend it easily.

I'd really like to try and keep it as simple as possible. I work with Debian Packaging and its so (and needs to be so) specific about everything, people just won't bother to contribute if we let it get too regulated.

Davo

[dbannon]

OK, lest this topic go cold, I have established a (hopefully short lived) wiki page at

https://wiki.freepascal.org/Laz_Examples_Window

EDIT : https://wiki.freepascal.org/Lazarus_Examples_Window

I suggest anyone could add or remove proposals, content, make arguments either way there. But 'votes' for one model or another are perhaps better registered here ?

Davo

[howardpc]

For the metadata example you give

Keywords : Buttons Forms Hello

I would suggest rather

Keywords: button TButton form TForm memo TMemo Hello

although I thought most "Hello World" programs used a label rather than a memo?

[dbannon]

Thanks Howard, I guess the example there is more about the format rather than content of the metadata right now.  But if we go ahead, some "guidelines" would be a good idea.  I'd also like to see multi word words too -

'Hello World', 'Windows Only' etc, single quotes to stay readable in json ....

I think we MUST keep the metadata format simple but its also important it do the job, sigh ...

Davo

[Martin_fr]

About the meta data. I would strongly suggest to use either json or xml.
There is pro and contra for both.

Pro "json": Even if we keep Examples separate from OPM, there is a good chance that some OPM code may be re-used. After all there are similar tasks to be achieved.

Pro "xml": It is more or less the IDE's default format for data.

[dbannon]

About the meta data. I would strongly suggest to use either json or xml.
There is pro and contra for both.

OK Martin, if thats the call, done. Personally I would prefer json because its easier to read using human eyes. That important if we go for an on-line solution, being able to browse through the repo content sensibly would be useful. OTOH, if its an in-distro solution, really does not matter, maybe conforming to an existing Lazarus precedent is worthwhile so xml.

So, we really need a decision, on-line or in-distro ?  My vote is on-line repo and json meta data.

Davo

Browsing ? Please see - https://gitlab.com/dbannon/fpexamples

[dbannon]

I now have a reasonable demonstration of the On-Line version at -

https://gitlab.com/dbannon/fpexamples/-/tree/main/Utility/ExScanner

Its a stand alone application, has one window that might eventually evolve into a replacement for the Lazarus Examples Window. In the mean time, it serves to demonstrate the second, headless  unit that transports files from gitlab, builds a master meta file, searches for local Example meta data and, finally manages a (fplist) list of metadata allowing it to be poked into a listview and optionally filtered by category.

The App windows has a "drop down" extension showing some setup information, obviously not needed in the real thing. Similarly, there are some "Source" radiobuttons used, here, to exercise the unit.

I have tested on Linux and Windows (Mac will need some directory issues sorted out) and apart from some scalling issues, works OK.

I note to my surprise that GetEnvironmentVariable('HOMEPATH') on windows does not seem to prepend the "c:" thingo to users home path, should it ?   And TListView, in windows,you have to click in the leftmost column to get its attention, why is that ?

Summary
I have demonstrated that the on-line system is feasible and it does have some advantages over the in-distro model. Not much more I can do now unless I get some feedback as to which way we are proceeding.

See also

https://wiki.freepascal.org/Lazarus_Examples_Window - note this is a new address, someone renamed it (Laz -> Lazarus)

https://gitlab.com/dbannon/fpexamples - my badly named demo repository.

Davo

[Edit: Fixed Wiki link + explained]

[dbannon]

OK, a week after my last post here, apparently no interest so I abandone the proposal.

I have removed the gitlab demo page, marked the wiki page as abandoned (Trev tells me it cannot be deleted).

I think its a wasted opportunity, we need to make it easier for (especially new) users and easy access to examples would, IMHO, make a big difference.

Thanks folks to those who contributed early on !

Davo

[JuhaManninen]

OK, a week after my last post here, apparently no interest so I abandone the proposal.
I have removed the gitlab demo page, marked the wiki page as abandoned (Trev tells me it cannot be deleted).
I think its a wasted opportunity, we need to make it easier for (especially new) users and easy access to examples would, IMHO, make a big difference.

I planned to study it but then other things came up. Have you really deleted the whole thing now? No way to test?

A branch in GitLab Lazarus sources would be a good fit for such experiment. You could replace the examples window in Tools menu right away there and then fine tune without hurry.

[dbannon]

I planned to study it but then other things came up. Have you really deleted the whole thing now? No way to test?

Sorry, I was too impatient !

I saved the demo app because I plan to use the gitlab code in my own app, it already works with github.  And the few demo projects I built are still in my trash bin here. So I will recreate it.

A branch in GitLab Lazarus sources would be a good fit for such experiment. You could replace the examples window in Tools menu right away there and then fine tune without hurry.

If you think the idea has some merit, then I will continue (I do have time on my hands, heat wave, C19 lockdown, watching cricket on TV) to develop it, initially as a standalone thing so we can get the existing example projects under control. From what I have seen, there is a fair bit of work to be done there. My standalone app can easily be turned into a replacement for the existing window but no point in doing that until it has a reasonable number of projects ready.

I'd rather manage the updating of existing projects in a standalone app and a standalone repository for now, the devs don't want me continuously sending pull requests in. I'll call for volunteers to help with the projects, its a big task but one that needs to be done no matter which path we take.

Davo

 

[dbannon]

OK, its all back.
The temp Gitlab repo has a more reasonable name now, its -
https://gitlab.com/dbannon/laz_examples

I will proceed on the basis that -

• We'll be using a json metadata file, as defined in the wiki page.
• most of the examples will eventually live in a branch of the real Lazarus gitlab tree.
  
• I'll copy a user selected project into a dir tree under 'examples' in the Lazarus config dir.
• We'll scan the Lazarus config dir looking for any additional Examples

If anyone is unhappy with that, please speak up now !

Davo