Further improve general and native binaries build instructions

[HannesWell]

The main idea is to centralize the instructions how to build the native binaries and all relevant variations comprehensibly at the bundles/org.eclipse.swt/Readme.md but to improve the reference to it so that it can be discovered more easily (which is currently difficult, I have to admit).

@fedejeanne IIRC we also discussed about this some time ago, do you want to have a look too?

[vogella]

Lgtm

For windows I had to use ticks to make it work, maybe worth noting:

mvn clean install '-Dnative=win32.win32.x86_64' -DskipTests

[vogella]

For me I have to compile the natives on every commit I do even if I only affects the Java code. For example ecb78697fda3710ceefc3e4d914513509775cc8b
8b4c79055640729318db147cea5f0a4335279df0 forced me to compile natives. I would also suggest to mention that in the files.

[HeikoKlare]

For me I have to compile the natives on every commit I do even if I only affects the Java code.

Recompilation of binaries is only necessary when the native code (including Java classes from which native code is generated, such as OS.java) are modified. I guess you have properly checked out the binaries from LFS because otherwise you would not be able to start any application with just the master state checked out. So the only reason why you might need to recompile binaries is that you checked out a repository state with a commit that required rebuilt binaries without the subsequent commit containing those binaries. Unfortunately, after such a change there is a timeframe of around 10-15 minutes (the time it takes to perform a build) until the according binaries are pushed with another commit. In that state the code is basically in an inconsistent state. But it's unlikely that you accidentallly take such a state, but I don't see any other situation in which a rebuild of binaries is required. Can you share the error that shows up if you do not rebuild the binaries?

btw: I cannot find the mentioned commits in the repository. Are they just local to you?

[vogella]

@HeikoKlare I have to compile the natives all the time if I move in my Git history.

Initial state:

Run mvn clean verify -Dnative=gtk.linux.x86_64 -DskipTests -> works fine.

Now reset branch to eclipse/master and run another Snippet (before the Snippet from above does not exist in master).

[HeikoKlare]

@vogella okay, so you definitely have a broken setup. The binaries are properly committed into the repository, so there is no need to recompile them locally. You can just checkout whatever commit you want and everything should work fine. Maybe you did not properly set up LFS? Can you check the contents of the *.so files once you switched to a different commit? Do they contain actual binary code (hundrets of KB in size) or are they just small text documents that contain an (unresolved) reference to the LFS object?

[merks]

The Oomph setup ensures that this the lfs is installed and the lfs preference is set:

[vogella]

@vogella okay, so you definitely have a broken setup. The binaries are properly committed into the repository, so there is no need to recompile them locally. You can just checkout whatever commit you want and everything should work fine. Maybe you did not properly set up LFS? Can you check the contents of the *.so files once you switched to a different commit? Do they contain actual binary code (hundrets of KB in size) or are they just small text documents that contain an (unresolved) reference to the LFS object?

Good to know, I never used LFS actively before, so I need to set this up.

[HannesWell]

When git LFS is properly set up you should have entries like the following in either your (user) global .gitconfig or in the .git/config of your local SWT clone repository:

[filter "lfs"]
	useJGitBuiltin = true
	required = true
	clean = git-lfs clean -- %f
	smudge = git-lfs smudge -- %f
	process = git-lfs filter-process

If that's not present the automation through Oomph that Ed showed probably didn't work (do you use the Oomph setup?).
But you can activate it manually by following the install instructions from the doc linked above and run git lfs install.

Or within Eclipse in the Preferences under Version Control -> Git press the Enable LFS support globally button.

Of course the latter only works/require the o.e.jgit.lfs extension/bundle to be installed in your Eclipse, while running the former CLI command requires the git-lfs extension to be installed on your computer.
Either one from both should be sufficient, depending on how you work with git.

See also

• https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage

[HannesWell]

For windows I had to use ticks to make it work, maybe worth noting:

mvn clean install '-Dnative=win32.win32.x86_64' -DskipTests

Indeed, because PowerShell treats unquoted dots differently (not sure as what exactly, but it breaks the build).
But at the same time, if using single quotes on a Windows cmd shell the build also fails because cmd seems to keep the single quotes literally. A vague memory about the latter was also the reason why I wanted to skip the quotes, but PowerShell obviously requires it (and seems to be the default default in the Windows Terminal nowadays).

But double quotes seem to work on all kind of shells, UNIX sh, Windows PowerShell and CMD.
I'll update the doc to use that.
Thanks for pointing that out!

[vogella]

When git LFS is properly set up you should have entries like the following in either your (user) global .gitconfig or in the .git/config of your local SWT clone repository:

[filter "lfs"]
	useJGitBuiltin = true
	required = true
	clean = git-lfs clean -- %f
	smudge = git-lfs smudge -- %f
	process = git-lfs filter-process

If that's not present the automation through Oomph that Ed showed probably didn't work (do you use the Oomph setup?). But you can activate it manually by following the install instructions from the doc linked above and run git lfs install.

Or within Eclipse in the Preferences under Version Control -> Git press the Enable LFS support globally button.

Of course the latter only works/require the o.e.jgit.lfs extension/bundle to be installed in your Eclipse, while running the former CLI command requires the git-lfs extension to be installed on your computer. Either one from both should be sufficient, depending on how you work with git.

See also

• https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage

AFAICS the setup of Git LFS is not explicitly described in any human-oriented documentation within this repository (such as README.md, CONTRIBUTING.md, or AGENTS.md). I suggest to add to the readme. I do not use Oomph for setup (except for EGit which seems impossible to setup without it).